docs: update documentation

Author: cjumel

README.md

@@ -3,17 +3,19 @@
 [![PyPI version](https://badge.fury.io/py/linkup-sdk.svg)](https://pypi.org/project/linkup-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-A Python SDK for the [Linkup API](https://linkup-api.readme.io/reference/getting-started), allowing easy integration with Linkup's services. 🐍
+A Python SDK for the [Linkup API](https://linkup-api.readme.io/reference/getting-started), allowing
+easy integration with Linkup's services. 🐍
 
 ## 🌟 Features
 
 - ✅ **Simple and intuitive API client.**
 - 🔍 **Supports both standard and deep search queries.**
+- ⚡ **Supports synchronous and asynchronous requests.**
 - 🔒 **Handles authentication and request management.**
 
 ## 📦 Installation
 
-Install the SDK using `pip`:
+Simply install the Linkup Python SDK using `pip`:
 
 ```bash
 pip install linkup-sdk
@@ -25,11 +27,11 @@ pip install linkup-sdk
 
 1. **🔑 Obtain an API Key:**
 
-	Sign up on Linkup to get your API key.
+   Sign up on Linkup to get your API key.
 
-2. **⚙️ Set the API Key as an Environment Variable:**
+2. **⚙️ Set-up the API Key:**
 
-   Option 1: Export the LINKUP_API_KEY environment variable in your shell before using the Python
+   Option 1: Export the `LINKUP_API_KEY` environment variable in your shell before using the Python
    SDK.
 
    ```bash
@@ -38,7 +40,7 @@ pip install linkup-sdk
 
    Option 2: Set the `LINKUP_API_KEY` environment variable directly within Python, using for
    instance `os.environ` or [python-dotenv](https://github.com/theskumar/python-dotenv) with a
-   `.env` file (python-dotenv needs to be installed separately in this case), before creating the
+   `.env` file (`python-dotenv` needs to be installed separately in this case), before creating the
    Linkup Client.
 
    ```python
@@ -62,6 +64,16 @@ pip install linkup-sdk
 
 ## 📋 Example
 
+All search queries can be used with two very different modes:
+
+- with `depth="standard"`, the search will be straightforward and fast, suited for relatively simple
+  queries (e.g. "What's the weather in Paris today?")
+- with `depth="deep"`, the search will use an agentic workflow, which makes it in general slower,
+  but it will be able to solve more complex queries (e.g. "What is the company profile of LangChain
+  accross the last few years, and how does it compare to its concurrents?")
+
+### 📝 Standard Search Query
+
 ```python
 from linkup import LinkupClient
 
@@ -71,11 +83,20 @@ client = LinkupClient()
 # Perform a search query
 search_response = client.search(
     query="What are the 3 major events in the life of Abraham Lincoln?",
-    depth="standard",  # or "deep"
-    output_type="searchResults",  # or "sourcedAnswer" or "structured"
+    depth="deep",  # "standard" or "deep"
+    output_type="sourcedAnswer",  # "searchResults" or "sourcedAnswer" or "structured"
     structured_output_schema=None,  # must be filled if output_type is "structured"
 )
 print(search_response)
+```
+
+### 📰 Content Access
+
+```python
+from linkup import LinkupClient
+
+# Initialize the client (API key can be read from the environment variable or passed as an argument)
+client = LinkupClient()
 
 # Get access to our Premium Sources Partners content
 content_response = client.content(
@@ -85,5 +106,7 @@ content_response = client.content(
 print(content_response)
 ```
 
+### 📚 More Examples
+
 See the `examples/` directory for more examples and documentation, for instance on how to use Linkup
 entrypoints using asynchronous functions.

examples/1_default_search.py renamed to examples/1_direct_search_results.py

@@ -1,7 +1,6 @@
 """
-By default, the Linkup search outputs a raw search results, which can then be re-used in different
-use-cases, for instance in a RAG system. This is controlled by the output_type parameter, which
-defaults to "searchResults".
+The Linkup search can output raw search results which can then be re-used in different use-cases,
+for instance in a RAG system, with the output_type parameter set to "searchResults".
 """
 
 from linkup import LinkupClient