R2R

https://r2r-docs.sciphi.ai/documentation/
Admin
R2R is a framework for building and deploying Retrieval-Augmented Generation (RAG) applications,...
Tokens:24,867
Snippets:115
Trust Score:6.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install R2R SDK

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Installs the R2R SDK for Python. Ensure you have pip installed.

```bash
pip install r2r
```

--------------------------------

### Configuration Examples

Source: https://r2r-docs.sciphi.ai/documentation/hybrid-search

Examples of how to configure different search modes.

```APIDOC
## Configuration

**Choosing a Search Mode:**

*   `basic`: Semantic-only.
```json
{
  "search_mode": "basic"
}
```
  * Semantic search only, no full-text matching

*   `advanced`: Hybrid by default.
```json
{
  "search_mode": "advanced"
}
```
  * Hybrid search is automatically enabled with well-tuned defaults

*   `custom`: Manually configure hybrid search.
```json
{
  "search_mode": "custom",
  "search_settings": {
    "use_semantic_search": true,
    "use_fulltext_search": true,
    "use_hybrid_search": true,
    "hybrid_settings": {
      "full_text_weight": 1.0,
      "semantic_weight": 5.0,
      "full_text_limit": 200,
      "rrf_k": 50
    }
  }
}
```
  * Enable both semantic and full-text search and set weights as needed:
    * `use_semantic_search`: Set to `true` to enable semantic search.
    * `use_fulltext_search`: Set to `true` to enable full-text search.
    * `use_hybrid_search`: Set to `true` to enable hybrid search.
    * `hybrid_settings`: Object for tuning hybrid search parameters:
      * `full_text_weight`: Weight for full-text search results.
      * `semantic_weight`: Weight for semantic search results.
      * `full_text_limit`: Maximum number of full-text results to consider.
      * `rrf_k`: Parameter for Reciprocal Rank Fusion.
```

--------------------------------

### Streaming RAG - Python

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Provides a Python example for initiating a streaming RAG process.

```python
def stream_rag_response():
    # Placeholder for streaming RAG logic in Python
    pass
```

--------------------------------

### Register a New User

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Creates a new user account with provided email and password. Includes example output showing user details.

```Python
from r2r import R2RClient

client.users.create("test@example.com", "password123")
```

--------------------------------

### Streaming RAG - JavaScript

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Provides a JavaScript example for initiating a streaming RAG process.

```javascript
async function streamRAGResponse() {
  // Placeholder for streaming RAG logic in JavaScript
}
```

--------------------------------

### R2R Agent: Optimizing for Fast Responses

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

Provides an example of configuring the R2R agent for time-sensitive applications by using a smaller `max_tokens_to_sample`, a faster model like Claude 3 Haiku, minimal tools, and streaming output.

```python
# For time-sensitive applications, consider:
# 1. Using a smaller max_tokens value
# 2. Selecting faster models like claude-3-haiku
# 3. Avoiding unnecessary tools

fast_response = client.retrieval.agent(
    message={"role": "user", "content": "Give me a quick overview of DeepSeek R1"},
    rag_generation_config={
        "model": "anthropic/claude-3-haiku-20240307",  # Faster model
        "max_tokens_to_sample": 200,                   # Limited output
        "stream": True                                 # Stream for perceived responsiveness
    },
    rag_tools=["search_file_knowledge"],              # Minimal tools
    mode="rag"
)
```

--------------------------------

### R2R Agent: Tool Selection for RAG and Research Modes

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

Demonstrates configuring the R2R agent with different tool sets for RAG (Retrieval Augmented Generation) and research modes. RAG mode example includes web capabilities, while research mode focuses on reasoning and code execution.

```python
response = client.retrieval.agent(
    message={"role": "user", "content": "What are the latest developments in AI safety?"},
    rag_tools=["search_file_knowledge", "get_file_content", "web_search", "web_scrape"],
    mode="rag"
)

response = client.retrieval.agent(
    message={"role": "user", "content": "Analyze the complexity of this algorithm"},
    research_tools=["reasoning", "python_executor"],  # Only reasoning and code execution
    mode="research"
)
```

--------------------------------

### Python R2R Basic RAG Query

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Shows a basic example of using the R2R client to perform a Retrieval-Augmented Generation (RAG) query to get an answer based on ingested documents.

```Python
client.retrieval.rag(query="What is DeepSeek R1?")
```

--------------------------------

### Python RAG Query Example

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Demonstrates a basic RAG query in Python, specifying the query parameter for retrieval.

```python
client.retrieval.rag(
  query="What is DeepSeek R1?",
)
```

--------------------------------

### Streaming RAG Response Example

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Illustrates a streaming RAG response structure, showing generated answers, search results, citations, and metadata.

```python
RAGResponse(
  generated_answer='DeepSeek-R1 is a model that demonstrates impressive performance across various tasks, leveraging reinforcement learning (RL) and supervised fine-tuning (SFT) to enhance its capabilities. It excels in writing tasks, open-domain question answering, and benchmarks like IF-Eval, AlpacaEval2.0, and ArenaHard [1], [2]. DeepSeek-R1 outperforms its predecessor, DeepSeek-V3, in several areas, showcasing its strengths in reasoning and generalization across diverse domains [1]. It also achieves competitive results on factual benchmarks like SimpleQA, although it performs worse on the Chinese SimpleQA benchmark due to safety RL constraints [2]. Additionally, DeepSeek-R1 is involved in distillation processes to transfer its reasoning capabilities to smaller models, which perform exceptionally well on benchmarks [4], [6]. The model is optimized for English and Chinese, with plans to address language mixing issues in future updates [8].',
  search_results=AggregateSearchResult(
    chunk_search_results=[ChunkSearchResult(score=0.643, text=Document Title: DeepSeek_R1.pdf ...)]
  ),
  citations=[Citation(id='cit_3a35e39', object='citation', payload=ChunkSearchResult(score=0.676, text=Document Title: DeepSeek_R1.pdf\n\nText: However, DeepSeek-R1-Zero encounters challenges such as poor readability, and language mixing. To address these issues and further enhance reasoning performance, we introduce DeepSeek-R1, which incorporates a small amount of cold-start data and a multi-stage training pipeline. Specifically, we begin by collecting thousands of cold-start data to fine-tune the DeepSeek-V3-Base model. Following this, we perform reasoning-oriented RL like DeepSeek-R1-Zero. Upon nearing convergence in the RL process, we create new SFT data through rejection sampling on the RL checkpoint, combined with supervised data from DeepSeek-V3 in domains such as writing, factual QA, and self-cognition, and then retrain the DeepSeek-V3-Base model. After fine-tuning with the new data, the checkpoint undergoes an additional RL process, taking into account prompts from all scenarios. After these steps, we obtained a checkpoint referred to as DeepSeek-R1, which achieves performance on par with OpenAI-o1-1217.)), Citation(id='cit_ec89403', object='citation', payload=ChunkSearchResult(score=0.664, text=Document Title: DeepSeek_R1.pdf\n\nText: - We introduce our pipeline to develop DeepSeek-R1. The pipeline incorporates two RL stages aimed at discovering improved reasoning patterns and aligning with human preferences, as well as two SFT stages that serve as the seed for the model's reasoning and non-reasoning capabilities. We believe the pipeline will benefit the industry by creating better models.)), ...],
  metadata={'id': 'chatcmpl-B0BaZ0vwIa58deI0k8NIuH6pBhngw', 'choices': [{'finish_reason': 'stop', 'index': 0, 'logprobs': None, 'message': {'refusal': None, 'role': 'assistant', 'audio': None, 'function_call': None, 'tool_calls': None}}], 'created': 1739384247, 'model': 'gpt-4o-2024-08-06', 'object': 'chat.completion', 'service_tier': 'default', 'system_fingerprint': 'fp_4691090a87', ...}
)

```

--------------------------------

### Using a Prompt Template with Inputs

Source: https://r2r-docs.sciphi.ai/documentation/prompts

This code example shows how to retrieve and render a prompt template using provided input values for the defined placeholders.

```python
greeting = prompts.get(  
    name="welcome_template",  
    inputs={  
        "name": "John",  
        "company": "Acme Inc"  
    }  
)  
# -> "Hello John, welcome to Acme Inc!"
```

--------------------------------

### Hello R2R: Basic Client Interaction and RAG

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Demonstrates basic interaction with the R2R client, including document ingestion from a local file and performing a RAG query. It shows how to get search results, generated answers, and citations.

```python
from r2r import R2RClient

client = R2RClient() # optional, pass in "http://localhost:7272" or "https://api.sciphi.ai"

with open("test.txt", "w") as file:
    file.write("John is a person that works at Google.")

client.documents.create(file_path="test.txt")

# Call RAG directly
rag_response = client.retrieval.rag(
    query="Who is john",
    rag_generation_config={"model": "openai/gpt-4o-mini", "temperature": 0.0},
)

print(f"Search Results:\n{rag_response.results.search_results}")
# AggregateSearchResult(chunk_search_results=[ChunkSearchResult(score=0.685, text=John is a person that works at Google.)], graph_search_results=[], web_search_results=[], context_document_results=[])

print(f"Completion:\n{rag_response.results.generated_answer}")
# John is a person that works at Google [e123456].

print(f"Citations:\n{rag_response.results.citations}")
# [Citation(id='e123456', object='citation', payload=ChunkSearchResult(...))]
```

--------------------------------

### R2R Agent: Propagating Search Settings

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

Illustrates how search settings, including semantic search, filters, and result limits, configured at the agent level are propagated to downstream searches.

```python
response = client.retrieval.agent(
    message={"role": "user", "content": "Summarize our Q1 financial results"},
    search_settings={
        "use_semantic_search": True,
        "filters": {"collection_ids": {"$overlap": ["e43864f5-..."]}},
        "limit": 25
    },
    rag_tools=["search_file_knowledge", "get_file_content"],
    mode="rag"
)
```

--------------------------------

### R2R Agent: Multi-Turn Conversation Management

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

Demonstrates how to maintain context across multiple turns in a conversation using `conversation_id`. It includes creating a conversation, performing the first turn, and a follow-up query.

```python
# Create a new conversation
conversation = client.conversations.create()
conversation_id = conversation.results.id

# First turn
first_response = client.retrieval.agent(
    message={"role": "user", "content": "What does DeepSeek R1 imply for the future of AI?"},
    rag_generation_config={
        "model": "anthropic/claude-3-7-sonnet-20250219",
        "temperature": 0.7,
        "max_tokens_to_sample": 1000,
        "stream": False
    },
    conversation_id=conversation_id,
    mode="rag"
)
print(f"First response: {first_response.results.messages[-1].content[:100]}...")

# Follow-up query in the same conversation
follow_up_response = client.retrieval.agent(
    message={"role": "user", "content": "How does it compare to other reasoning models?"},
    rag_generation_config={
        "model": "anthropic/claude-3-7-sonnet-20250219",
        "temperature": 0.7,
        "max_tokens_to_sample": 1000,
        "stream": False
    },
    conversation_id=conversation_id,
    mode="rag"
)
print(f"Follow-up response: {follow_up_response.results.messages[-1].content[:100]}...")

# The agent maintains context, so it knows "it" refers to DeepSeek R1
```

--------------------------------

### R2R Agent: Model Selection and Generation Parameters

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

Shows how to customize agent behavior by selecting a specific model (e.g., Anthropic Claude 3 Haiku) and adjusting generation parameters like temperature, max tokens, and streaming.

```python
response = client.retrieval.agent(
    message={"role": "user", "content": "Write a concise summary of DeepSeek R1's capabilities"},
    rag_generation_config={
        "model": "anthropic/claude-3-haiku-20240307",  # Faster model for simpler tasks
        "temperature": 0.3,                           # Lower temperature for more deterministic output
        "max_tokens_to_sample": 500,                  # Limit response length
        "stream": False                               # Non-streaming for simpler use cases
    },
    mode="rag"
)
```

--------------------------------

### Hybrid Search Example

Source: https://r2r-docs.sciphi.ai/documentation/search-and-rag

Demonstrates how to use hybrid search by combining keyword-based (full-text) search with vector search for potentially broader results.

```APIDOC
## POST /retrieval/search (Hybrid Search Example)

### Description
Combine keyword-based (full-text) search with vector search for potentially broader results.

### Method
POST

### Endpoint
`/retrieval/search`

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
- **search_mode** (string) - Set to `custom` to leverage detailed `search_settings`.
- **search_settings** (object) - Required for detailed hybrid configuration.
  * **`use_hybrid_search`** (boolean) - Set to `true`.
  * **`hybrid_settings`** (object) - Configure hybrid search parameters.
    * **`semantic_weight`** (number) - Weight for semantic search results.
    * **`full_text_weight`** (number) - Weight for full-text search results.
    * **`rrf_k`** (number) - Parameter for Reciprocal Rank Fusion.

#### Request Body
(Not applicable for this endpoint, parameters are in query string or assumed context)

### Request Example
###### Python
```python
results_hybrid = client.retrieval.search(
  query="Explain the Transformer architecture",
  search_mode="custom",
  search_settings={
    "use_hybrid_search": True,
    "hybrid_settings": {
      "semantic_weight": 0.6,
      "full_text_weight": 0.4,
      "rrf_k": 16
    },
    "use_semantic_search": True,
    "use_fulltext_search": True,
    "include_scores": True,
    "limit": 10
  }
)
```

###### JavaScript
```javascript
// JavaScript example would follow a similar structure using the R2R SDK for JavaScript
// const results = await r2rClient.retrieval.search({
//   query: "Explain the Transformer architecture",
//   searchMode: "custom",
//   searchSettings: {
//     useHybridSearch: true,
//     hybridSettings: {
//       semanticWeight: 0.6,
//       fullTextWeight: 0.4,
//       rrfK: 16
//     },
//     useSemanticSearch: true,
//     useFulltextSearch: true,
//     includeScores: true,
//     limit: 10
//   }
// });
```

### Response
(Similar to the general search response, but results reflect hybrid search configuration)
```

--------------------------------

### Local Deployment Configuration

Source: https://r2r-docs.sciphi.ai/documentation/limits

Illustrates how to override default limits for local R2R deployments using the `r2r.toml` configuration file, including examples for general limits and route-specific limits.

```APIDOC
## Local Deployment Configuration

### Description
For local R2R deployments, default limits can be customized by modifying the `r2r.toml` configuration file. The examples below show how to set general limits and route-specific rate limits.

### General Limits Configuration Example:
```toml
[app]
default_max_documents_per_user = 200
default_max_chunks_per_user = 50_000
default_max_collections_per_user = 20
default_max_upload_size = 10_000_000  # 10 MB
```

### Route-Specific Limits Configuration Example:
```toml
[database.route_limits]
"/v3/retrieval/search" = { route_per_min = 50, monthly_limit = 10_000 }
```
```

--------------------------------

### R2R Client Agent Interaction and Event Processing in JavaScript

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

This snippet shows how to initialize an R2R client, send a message to an agent with specific rag generation configurations, and iterate through the streaming results, handling different event types like Thinking, ToolCall, ToolResult, Citation, Message, and FinalAnswer. It also includes an example of processing the output from these events.

```javascript
from r2r import (
    ThinkingEvent,
    ToolCallEvent,
    ToolResultEvent,
    CitationEvent,
    FinalAnswerEvent,
    MessageEvent,
    R2RClient,
)

results = client.retrieval.agent(
    message={"role": "user", "content": "What does deepseek r1 imply for the future of AI?"},
    rag_generation_config={
        "model": "anthropic/claude-3-7-sonnet-20250219",
        "extended_thinking": True,
        "thinking_budget": 4096,
        "temperature": 1,
        "top_p": None,
        "max_tokens_to_sample": 16000,
        "stream": True
    },
)

# Process the streaming events
for event in results:
    if isinstance(event, ThinkingEvent):
        print(f"🧠 Thinking: {event.data.delta.content[0].payload.value}")
    elif isinstance(event, ToolCallEvent):
        print(f"🔧 Tool call: {event.data.name}({event.data.arguments})")
    elif isinstance(event, ToolResultEvent):
        print(f"📊 Tool result: {event.data.content[:60]}...")
    elif isinstance(event, CitationEvent):
        print(f"📑 Citation: {event.data}")
    elif isinstance(event, MessageEvent):
        print(f"💬 Message: {event.data.delta.content[0].payload.value}")
    elif isinstance(event, FinalAnswerEvent):
        print(f"✅ Final answer: {event.data.generated_answer[:100]}...")
        print(f"   Citations: {len(event.data.citations)} sources referenced")
```

--------------------------------

### R2R Agent Research Mode with Tools

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

This Python code showcases the R2R agent in 'research' mode, designed for more complex reasoning. The first part uses multiple research tools including 'rag', 'reasoning', 'critique', and 'python_executor' for a broad analysis. The second part focuses on a computational task, using only the 'python_executor' tool to calculate a factorial, demonstrating how to configure generation settings and retrieve the final answer.

```python
# Research mode with all available tools
response = client.retrieval.agent(
    message={
        "role": "user", 
        "content": "Analyze the philosophical implications of DeepSeek R1 for the future of AI reasoning"
    },
    research_generation_config={
        "model": "anthropic/claude-3-opus-20240229",
        "extended_thinking": True,
        "thinking_budget": 8192,
        "temperature": 0.2,
        "max_tokens_to_sample": 32000,
        "stream": True
    },
    research_tools=["rag", "reasoning", "critique", "python_executor"],
    mode="research"
)

# Process streaming events as shown in the previous example
# ...

# Research mode with computational focus
# This example solves a mathematical problem using the python_executor tool
compute_response = client.retrieval.agent(
    message={
        "role": "user", 
        "content": "Calculate the factorial of 15 multiplied by 32. Show your work."
    },
    research_generation_config={
        "model": "anthropic/claude-3-opus-20240229",
        "max_tokens_to_sample": 1000,
        "stream": False
    },
    research_tools=["python_executor"],
    mode="research"
)

print(f"Final answer: {compute_response.results.messages[-1].content}")
```

--------------------------------

### R2R Agent Basic RAG Mode with Streaming

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

This Python code snippet demonstrates how to use the R2R client in basic Retrieval-Augmented Generation (RAG) mode with streaming. It sends a user message and configures generation parameters, including the model, extended thinking, thinking budget, temperature, top_p, max tokens, and stream settings. It also specifies the RAG tools to be used and iterates through the streaming response, handling different event types like ThinkingEvent, ToolCallEvent, ToolResultEvent, CitationEvent, MessageEvent, and FinalAnswerEvent.

```python
from r2r import R2RClient
from r2r import (
    ThinkingEvent,
    ToolCallEvent,
    ToolResultEvent,
    CitationEvent,
    MessageEvent,
    FinalAnswerEvent,
)

# when using auth, do client.users.login(...)

# Basic RAG mode with streaming
response = client.retrieval.agent(
    message={
        "role": "user",
        "content": "What does DeepSeek R1 imply for the future of AI?"
    },
    rag_generation_config={
        "model": "anthropic/claude-3-7-sonnet-20250219",
        "extended_thinking": True,
        "thinking_budget": 4096,
        "temperature": 1,
        "top_p": None,
        "max_tokens_to_sample": 16000,
        "stream": True
    },
    rag_tools=["search_file_knowledge", "get_file_content"],
    mode="rag"
)

# Improved streaming event handling
current_event_type = None
for event in response:
    # Check if the event type has changed
    event_type = type(event)
    if event_type != current_event_type:
        current_event_type = event_type
        print() # Add newline before new event type

        # Print emoji based on the new event type
        if isinstance(event, ThinkingEvent):
            print(f"\n🧠 Thinking: ", end="", flush=True)
        elif isinstance(event, ToolCallEvent):
            print(f"\n🔧 Tool call: ", end="", flush=True)
        elif isinstance(event, ToolResultEvent):
            print(f"\n📊 Tool result: ", end="", flush=True)
        elif isinstance(event, CitationEvent):
            print(f"\n📑 Citation: ", end="", flush=True)
        elif isinstance(event, MessageEvent):
            print(f"\n💬 Message: ", end="", flush=True)
        elif isinstance(event, FinalAnswerEvent):
            print(f"\n✅ Final answer: ", end="", flush=True)

    # Print the content without the emoji
    if isinstance(event, ThinkingEvent):
        print(f"{event.data.delta.content[0].payload.value}", end="", flush=True)
    elif isinstance(event, ToolCallEvent):
        print(f"{event.data.name}({event.data.arguments})")
    elif isinstance(event, ToolResultEvent):
        print(f"{event.data.content[:60]}...")
    elif isinstance(event, CitationEvent):
        print(f"{event.data}")
    elif isinstance(event, MessageEvent):
        print(f"{event.data.delta.content[0].payload.value}", end="", flush=True)
    elif isinstance(event, FinalAnswerEvent):
        print(f"{event.data.generated_answer[:100]}...")
        print(f"   Citations: {len(event.data.citations)} sources referenced")
```

--------------------------------

### Initialize R2R Client

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Initializes the R2R client in Python, optionally setting a custom base URL. Alternatively, users can log in directly using email and password.

```python
from r2r import R2RClient

client = R2RClient() # can set remote w/ R2RClient(base_url=...)

# or, alternatively, client.users.login("my@email.com", "my_strong_password")
```

--------------------------------

### User Registration

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Register a new user with the system.

```APIDOC
## POST /users

### Description
Register a new user. This endpoint creates a new user account in the system with the provided email and password.

### Method
POST

### Endpoint
`/users`

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.

### Response
#### Success Response (201)
- **User** (object) - Details of the newly created user, including ID, email, and account status.
```

--------------------------------

### Ingest Sample Document with R2R

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Ingests a sample document into R2R. For custom documents, use the `create` method with a file path.

```python
client.documents.create_sample(hi_res=True)
# to ingest your own document, client.documents.create(file_path="/path/to/file")
```

--------------------------------

### Reset Graph to Clean State

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Resets the graph to an initial clean state, removing all existing data. This is useful for starting fresh or experimenting.

```Python
client.graphs.reset(collection_id)
```

--------------------------------

### Execute Search Query in R2R

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Demonstrates how to perform a search query using the R2R client.

```python
client.search("your search query")
```

--------------------------------

### Configuring Distance Measures for Vector Search in Python

Source: https://r2r-docs.sciphi.ai/documentation/search-and-rag

Shows how to specify a distance measure for vector search in R2R. This example sets the index measure to 'l2_distance' (Euclidean distance) instead of the default 'cosine_distance'.

```python
results = client.retrieval.search(
  query="What are the key features of quantum computing?",
  search_settings={
    "chunk_settings": {
      "index_measure": "l2_distance"  # Use Euclidean distance instead of default
    }
  }
)
```

--------------------------------

### Initialize and Populate Graph

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Synchronizes the graph with a collection and allows viewing extracted knowledge like entities and relationships. Requires a collection ID.

```Python
collection_id="122fdf6a-e116-546b-a8f6-e4cb2e2c0a09" # default collection_id for admin

# Sync graph with collection
pull_response = client.graphs.pull(collection_id)

# View extracted knowledge
entities = client.graphs.list_entities(collection_id)
relationships = client.graphs.list_relationships(collection_id)
```

--------------------------------

### Advanced Filtering with AND/OR Operators in Python

Source: https://r2r-docs.sciphi.ai/documentation/search-and-rag

Illustrates advanced filtering capabilities in R2R searches using logical operators like $and. This example filters results to include only PDFs with a publication year greater than 2020.

```python
filtered_results = client.retrieval.search(
    query="What are the effects of climate change?",
    search_settings={
        "filters": {
            "$and":[
                {"document_type": {"$eq": "pdf"}}, # Assuming 'document_type' is stored
                {"metadata.year": {"$gt": 2020}} # Access nested metadata fields
            ]
        },
        "limit": 10
    }
)
```

--------------------------------

### Starter Tier Overrides

Source: https://r2r-docs.sciphi.ai/documentation/limits

Details the increased default limits for users who have upgraded to the Starter Tier in SciPhi Cloud.

```APIDOC
## Starter Tier Overrides

### Description
When upgrading to the Starter Tier, the following default limits are increased. Other limits, such as file size and request rates, remain the same unless explicitly specified by the plan.

### Increased Limits for Starter Tier:
- **Documents**: Increased to 1,000 documents per user.
- **Chunks**: Increased to 100,000 chunks per user.
- **Collections**: Increased to 50 collections per user.
```

--------------------------------

### Python R2R Search with Hybrid Settings

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Demonstrates how to perform a search using R2R's Python client, configuring hybrid search with specific weights and limits for full-text and semantic search.

```Python
client.retrieval.search(
    "What was Uber's profit in 2020?",
    search_settings={
        "index_measure": "l2_distance",
        "use_hybrid_search": True,
        "hybrid_settings": {
            "full_text_weight": 1.0,
            "semantic_weight": 5.0,
            "full_text_limit": 200,
            "rrf_k": 50,
        }
    },
)
```

--------------------------------

### Create Document using R2R Synchronous Client

Source: https://r2r-docs.sciphi.ai/documentation/documents

Demonstrates how to create a document using the R2R synchronous client by providing a file path and metadata. This operation blocks until the document creation is complete.

```python
from r2r import R2RClient

client = R2RClient()
# when using auth, do client.login(...)

response = client.documents.create(
    file_path="document.pdf",
    metadata={"source": "research paper"},
    id=None
)

# Code here runs after document creation completes
print(response)
```

--------------------------------

### Filter Documents for Agent Retrieval

Source: https://r2r-docs.sciphi.ai/documentation/retrieval/agentic-rag

This Python code snippet shows how to use filters to narrow down search results when querying an agent. It specifies criteria such as document type, metadata category, and publication year to retrieve only relevant chunks from a large document collection.

```python
# When working with large document collections, use filters to narrow results  
filtered_response = client.retrieval.agent(
    message={"role": "user", "content": "Summarize key points from our AI ethics documentation"},
    search_settings={
        "filters": {
            "$and": [
                {"document_type": {"$eq": "pdf"}},
                {"metadata.category": {"$eq": "ethics"}},
                {"metadata.year": {"$gt": 2023}}
            ]
        },
        "limit": 10  # Limit number of chunks returned  
    },
    rag_generation_config={
        "max_tokens_to_sample": 500,
        "stream": True
    },
    mode="rag"
)
```

--------------------------------

### Streaming Agent for Deep Research (Python)

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Shows how to use the R2R client's agent mode for deep research, which iteratively researches and reasons using various tools. This example queries about 'DeepSeek R1' and processes different event types like Thinking, ToolCall, ToolResult, Citation, Message, and FinalAnswer. It utilizes Anthropic Claude 3.5 Sonnet with extended thinking capabilities.

```python
from r2r import (
    ThinkingEvent,
    ToolCallEvent,
    ToolResultEvent,
    CitationEvent,
    FinalAnswerEvent,
    MessageEvent,
    R2RClient,
)
client = R2RClient("http://localhost:7272")

results = client.retrieval.agent(
    message={"role": "user", "content": "What does deepseek r1 imply for the future of AI?"},
    rag_generation_config={
        "model": "anthropic/claude-3-7-sonnet-20250219",
        "extended_thinking": True,
        "thinking_budget": 4096,
        "temperature": 1,
        "top_p": None,
        "max_tokens_to_sample": 16000,
        "stream": True
    },
    mode="research" # for `deep research`, otherwise omit
)

# Process the streaming events
for event in results:
    if isinstance(event, ThinkingEvent):
        print(f"🧠 Thinking: {event.data.delta.content[0].payload.value}")
    elif isinstance(event, ToolCallEvent):
        print(f"🔧 Tool call: {event.data.name}({event.data.arguments})")
    elif isinstance(event, ToolResultEvent):
        print(f"📊 Tool result: {event.data.content[:60]}...")
    elif isinstance(event, CitationEvent):
        print(f"📑 Citation: {event.data}")
    elif isinstance(event, MessageEvent):
        print(f"💬 Message: {event.data.delta.content[0].payload.value}")
    elif isinstance(event, FinalAnswerEvent):
        print(f"✅ Final answer: {event.data.generated_answer[:100]}...")
        print(f"   Citations: {len(event.data.citations)} sources referenced")
```

--------------------------------

### Search Documents using R2R Client (Python)

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Demonstrates how to perform a basic similarity search using the R2R client. It takes a query string as input and returns relevant documents. Advanced search methods can be utilized based on specific use cases.

```python
client.retrieval.search(
  query="What is DeepSeek R1?",
)
```

--------------------------------

### Overview of Default Limits

Source: https://r2r-docs.sciphi.ai/documentation/limits

Provides a summary of the default per-user limits for R2R Cloud deployments, including maximums for documents, chunks, collections, and global file upload size, along with rate limits.

```APIDOC
## Overview of Default Limits

### Description
This section outlines the default limits imposed by SciPhi Cloud on various resources and actions per user.

### Limits:
- **Documents**: Maximum 100 documents per user.
- **Chunks**: Maximum 10,000 chunks per user.
- **Collections**: Maximum 5 collections per user.
- **File Upload (global)**: Maximum 2 MB (2,000,000 bytes) for file uploads, unless an extension-specific limit applies.
- **Rate Limit (global)**: 60 requests per minute per user.

**Note**: An additional Nginx ingress layer enforces a 60 requests/minute limit per IP address, regardless of the user account.
```

--------------------------------

### Graph Community Management

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Build and list communities within the graph.

```APIDOC
## POST /collections/{collection_id}/graphs/build

### Description
Build communities within the graph. This process analyzes the graph structure to identify and group related entities.

### Method
POST

### Endpoint
`/collections/{collection_id}/graphs/build`

### Parameters
#### Path Parameters
- **collection_id** (string) - Required - The ID of the collection.
#### Request Body
- **settings** (object) - Optional - Configuration settings for building communities.

## GET /collections/{collection_id}/graphs/communities

### Description
List the communities identified within the graph. Each community represents a cluster of related knowledge.

### Method
GET

### Endpoint
`/collections/{collection_id}/graphs/communities`

### Parameters
#### Path Parameters
- **collection_id** (string) - Required - The ID of the collection.
```

--------------------------------

### R2R Document Ingestion

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Shows how to ingest a sample document or a custom file using the R2R client. It highlights the process of creating documents which are then parsed, chunked, embedded, and stored.

```python
# export R2R_API_KEY=...
from r2r import R2RClient

client = R2RClient() # or set base_url=...
# when using auth, do client.users.login(...)

client.documents.create_sample(hi_res=True)
# to ingest your own document, client.documents.create(file_path="/path/to/file")
```

--------------------------------

### Basic Search with R2R Client

Source: https://r2r-docs.sciphi.ai/documentation/search-and-rag

Demonstrates how to perform a basic search using the R2R client in Python, showing both default settings and explicit 'basic' mode usage.

```python
# Uses default settings (likely semantic search in 'custom' mode)  
results = client.retrieval.search(  
  query="What is DeepSeek R1?",  
)  
  
# Explicitly using 'basic' mode  
results_basic = client.retrieval.search(  
  query="What is DeepSeek R1?",  
  search_mode="basic",  
)
```

--------------------------------

### Set R2R API Key Environment Variable

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Sets the R2R API key as an environment variable for authentication.

```bash
# export R2R_API_KEY=...
```

--------------------------------

### Define a Prompt Template with Input Types

Source: https://r2r-docs.sciphi.ai/documentation/prompts

This snippet demonstrates how to define a reusable prompt template with placeholders for variables and specifies the expected input types for those variables.

```python
template = "Hello {name}, welcome to {company}!"  
input_types = {  
    "name": "string",  
    "company": "string"  
}
```

--------------------------------

### User Login and Obtain Access Tokens

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Logs a user into the system and retrieves access and refresh tokens. These tokens are necessary for subsequent authenticated API requests. It requires the user's email and password as input.

```python
client.users.login("test@example.com", "password123")
```

```python
LoginResponse(access_token=Token(token='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0QGV4YW1wbGUuY29tIiwidG9rZW5fdHlwZSI6ImFjY2VzcyIsImV4cCI6MTc0MjU5MTQ0Ni43MTY2MzcsImlhdCI6MTczODk5MTQ0Ni43MTY3MDUsIm5iZiI6MTczODk5MTQ0Ni43MTY3MDUsImp0aSI6IkhkWWVfeWxOSm9Yc2tvaU5ZVkdoNHc9PSIsIm5vbmNlIjoiMkhOOUs3bU40QVNfVnkzOTdXR2Vpdz09In0.gG_9oa-7_ZHqfHHo-bE1ooynCm7YCQFCYbJoiEgGmTg', token_type='access'), refresh_token=Token(token='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZXN0QGV4YW1wbGUuY29tIiwidG9rZW5fdHlwZSI6InJlZnJlc2giLCJleHAiOjE3Mzk1OTYyNDYuNzE3MzQxLCJpYXQiOjE3Mzg5OTE0NDYuNzE3MzQ5LCJuYmYiOjE3Mzg5OTE0NDYuNzE3MzQ5LCJqdGkiOiJybXltZTk5bGNtZklOWDZLQWNaTmpBPT0iLCJub25jZSI6InExRGdqZm96YkpjYXpDbzdTcE5XcWc9PSJ9.Zn-2pncsEdvyuig36N4APO_U9AWDQcJi6E5EjglN16U', token_type='refresh'))
```

--------------------------------

### RAG Retrieval with Anthropic Claude 3 Haiku (Python)

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Demonstrates how to perform a Retrieval Augmented Generation (RAG) query using the R2R client, specifically with the Anthropic Claude 3 Haiku model. It requires the ANTHROPIC_API_KEY environment variable to be set. The response is streamed and printed chunk by chunk.

```python
# requires ANTHROPIC_API_KEY is set  
response = client.retrieval.rag(  
  "Who was Aristotle?",  
  rag_generation_config={"model":"anthropic/claude-3-haiku-20240307", "stream": True}  
)  
for chunk in response:  
    print(chunk, flush=False)
```

--------------------------------

### Stream RAG Results with Python

Source: https://r2r-docs.sciphi.ai/documentation/quickstart

Demonstrates streaming results from a RAG query using the R2R client. It shows how to handle different event types like search results, partial messages, citations, and the final answer. Requires the R2R library.

```python
from r2r import (
    CitationEvent,
    FinalAnswerEvent,
    MessageEvent,
    SearchResultsEvent,
    R2RClient,
)

# Assuming 'client' is an initialized R2RClient instance
# client = R2RClient(...)

result_stream = client.retrieval.rag(
    query="What is DeepSeek R1?",
    search_settings={"limit": 25},
    rag_generation_config={"stream": True},
)

# can also do a switch on `type` field
for event in result_stream:
    if isinstance(event, SearchResultsEvent):
        print("Search results:", event.data)
    elif isinstance(event, MessageEvent):
        print("Partial message:", event.data.delta)
    elif isinstance(event, CitationEvent):
        print("New citation detected:", event.data)
    elif isinstance(event, FinalAnswerEvent):
        print("Final answer:", event.data.generated_answer)

```

--------------------------------

### List Documents

Source: https://r2r-docs.sciphi.ai/documentation/walkthrough

Retrieves a list of documents with their metadata, allowing for pagination using limit and offset.

```APIDOC
## GET /documents

### Description
Retrieves a list of documents with their metadata, including ID, collection IDs, owner ID, document type, metadata, version, size, and ingestion/extraction statuses.

### Method
GET

### Endpoint
/documents

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of documents to return.
- **offset** (integer) - Optional - The number of documents to skip before starting to collect the result set.

### Response
#### Success Response (200)
- **id** (UUID) - The unique identifier for the document.
- **collection_ids** (array of UUID) - A list of collection IDs the document belongs to.
- **owner_id** (UUID) - The identifier of the owner of the document.
- **document_type** (string) - The type of the document (e.g., 'pdf', 'txt').
- **metadata** (object) - Additional metadata associated with the document, such as 'title' and 'version'.
- **version** (string) - The version of the document.
- **size_in_bytes** (integer) - The size of the document in bytes.
- **ingestion_status** (string) - The status of the document ingestion process.
- **extraction_status** (string) - The status of the graph extraction process.
- **created_at** (datetime) - The timestamp when the document was created.
- **updated_at** (datetime) - The timestamp when the document was last updated.

#### Response Example
```json
{
  "results": [
    {
      "id": "e43864f5-a36f-548e-aacd-6f8d48b30c7f",
      "collection_ids": ["122fdf6a-e116-546b-a8f6-e4cb2e2c0a09"],
      "owner_id": "2acb499e-8428-543b-bd85-0d9098718220",
      "document_type": "pdf",
      "metadata": {"title": "DeepSeek_R1.pdf", "version": "v0"},
      "version": "v0",
      "size_in_bytes": 1768572,
      "ingestion_status": "success",
      "extraction_status": "pending",
      "created_at": "2025-02-08T03:31:39.126759Z",
      "updated_at": "2025-02-08T03:31:39.160114Z",
      "ingestion_attempt_number": null,
      "summary": "The document contains a comprehensive overview of DeepSeek-R1...",
      "summary_embedding": null,
      "total_tokens": 29673
    }
  ],
  "total_entries": 1
}
```
```
Tokens:
Raw