# Understanding Internals of R2R Library

## Table of Contents

1. [Introduction](#introduction)

2. [Installation](#installation)

- [Prerequisites](#prerequisites)

- [Docker Installation](#docker-installation)

- [Install the R2R CLI & Python SDK](#install-the-r2r-cli--python-sdk)

- [Start R2R with Docker](#start-r2r-with-docker)

- [Google Cloud Platform Deployment](#google-cloud-platform-deployment)

- [Overview](#overview)

- [Creating a Google Compute Engine Instance](#creating-a-google-compute-engine-instance)

- [Installing Dependencies](#installing-dependencies)

- [Setting up R2R](#setting-up-r2r)

- [Configuring Port Forwarding for Local Access](#configuring-port-forwarding-for-local-access)

- [Exposing Ports for Public Access (Optional)](#exposing-ports-for-public-access-optional)

- [Conclusion](#conclusion-1)

3. [R2R Application Lifecycle](#r2r-application-lifecycle)

- [Developer Workflow](#developer-workflow)

- [User Interaction](#user-interaction)

- [Hello R2R (Code Example)](#hello-r2r-code-example)

4. [Configuration](#configuration)

- [Configuration Overview](#configuration-overview)

- [Server-Side Configuration (`r2r.toml`)](#server-side-configuration-r2rtoml)

- [Example: `r2r.toml`](#example-r2rtoml)

- [Runtime Overrides](#runtime-overrides)

- [Postgres Configuration](#postgres-configuration)

- [Example Configuration](#example-configuration-1)

- [Key Features](#key-features)

- [Embedding Configuration](#embedding-configuration)

- [Example Configuration](#example-configuration-2)

- [Auth & Users Configuration](#auth--users-configuration)

- [Example Configuration](#example-configuration-3)

- [Key Features](#key-features-1)

- [Data Ingestion Configuration](#data-ingestion-configuration)

- [Example Configuration](#example-configuration-4)

- [Retrieval Configuration](#retrieval-configuration)

- [Example Configuration](#example-configuration-5)

- [RAG Configuration](#rag-configuration)

- [Example Configuration](#example-configuration-6)

- [Graphs Configuration](#graphs-configuration)

- [Example Configuration](#example-configuration-7)

- [Prompts Configuration](#prompts-configuration)

- [Example Configuration](#example-configuration-8)

5. [Data Ingestion](#data-ingestion)

- [Introduction](#introduction-1)

- [Ingestion Modes](#ingestion-modes)

- [Ingesting Documents](#ingesting-documents)

- [Example Response](#example-response)

- [Ingesting Pre-Processed Chunks](#ingesting-pre-processed-chunks)

- [Example](#example-1)

- [Deleting Documents and Chunks](#deleting-documents-and-chunks)

- [Delete a Document](#delete-a-document)

- [Sample Output](#sample-output)

- [Key Features of Deletion](#key-features-of-deletion)

- [Additional Configuration & Concepts](#additional-configuration--concepts)

- [Light vs. Full Deployments](#light-vs-full-deployments)

- [Provider Configuration](#provider-configuration)

- [Conclusion](#conclusion-2)

6. [Contextual Enrichment](#contextual-enrichment)

- [The Challenge of Context Loss](#the-challenge-of-context-loss)

- [Introducing Contextual Enrichment](#introducing-contextual-enrichment)

- [Enabling Enrichment](#enabling-enrichment)

- [Enrichment Strategies Explained](#enrichment-strategies-explained)

- [Neighborhood Strategy](#neighborhood-strategy)

- [Semantic Strategy](#semantic-strategy)

- [The Enrichment Process](#the-enrichment-process)

- [Implementation and Results](#implementation-and-results)

- [Viewing Enriched Results](#viewing-enriched-results)

- [Metadata and Storage](#metadata-and-storage)

- [Best Practices](#best-practices-1)

- [Conclusion](#conclusion-3)

7. [AI Powered Search](#ai-powered-search)

- [Introduction](#introduction-2)

- [Understanding Search Modes](#understanding-search-modes)

- [How R2R Hybrid Search Works](#how-r2r-hybrid-search-works)

- [Vector Search](#vector-search)

- [Example](#example-2)

- [Hybrid Search](#hybrid-search)

- [Example](#example-3)

- [Knowledge Graph Search](#knowledge-graph-search)

- [Example](#example-4)

- [Reciprocal Rank Fusion (RRF)](#reciprocal-rank-fusion-rrf)

- [Result Ranking](#result-ranking)

- [Configuration](#configuration-1)

- [Choosing a Search Mode](#choosing-a-search-mode)

- [Best Practices](#best-practices-2)

- [Conclusion](#conclusion-4)

8. [Retrieval-Augmented Generation (RAG)](#retrieval-augmented-generation-rag)

- [Basic RAG](#basic-rag)

- [Example](#example-5)

- [Sample Output](#sample-output-1)

- [RAG with Hybrid Search](#rag-w-hybrid-search)

- [Example](#example-6)

- [Streaming RAG](#streaming-rag)

- [Example](#example-7)

- [Customizing RAG](#customizing-rag)

- [Example](#example-8)

- [Advanced RAG Techniques](#advanced-rag-techniques)

- [HyDE (Hypothetical Document Embeddings)](#hyde-hypothetical-document-embeddings)

- [Workflow](#workflow)

- [Python Example](#python-example-1)

- [Sample Output](#sample-output-2)

- [RAG-Fusion](#rag-fusion)

- [Workflow](#workflow-1)

- [Python Example](#python-example-2)

- [Sample Output](#sample-output-3)

- [Combining with Other Settings](#combining-with-other-settings)

- [Example](#example-9)

- [Customization and Server-Side Defaults](#customization-and-server-side-defaults)

- [Example](#example-10)

- [Conclusion](#conclusion-5)

9. [Knowledge Graphs in R2R](#knowledge-graphs-in-r2r)

- [Overview](#overview-2)

- [System Architecture](#system-architecture)

- [Getting Started](#getting-started)

- [Document-Level Extraction](#document-level-extraction)

- [Python Example](#python-example-3)

- [Creating Collection Graphs](#creating-collection-graphs)

- [Python Example](#python-example-4)

- [Managing Collection Graphs](#managing-collection-graphs)

- [Python Example](#python-example-5)

- [Example Output](#example-output-4)

- [Graph-Collection Relationship](#graph-collection-relationship)

- [Knowledge Graph Workflow](#knowledge-graph-workflow)

- [Step 1: Extract Document Knowledge](#step-1-extract-document-knowledge)

- [Step 2: Initialize and Populate Graph](#step-2-initialize-and-populate-graph)

- [Step 3: View Entities and Relationships](#step-3-view-entities-and-relationships)

- [Step 4: Build Graph Communities](#step-4-build-graph-communities)

- [Step 5: KG-Enhanced Search](#step-5-kg-enhanced-search)

- [Step 6: Reset Graph](#step-6-reset-graph)

- [Graph Synchronization](#graph-synchronization)

- [Document Updates](#document-updates)

- [Cross-Collection Updates](#cross-collection-updates)

- [Access Control](#access-control)

- [Python Example](#python-example-6)

- [Using Knowledge Graphs](#using-knowledge-graphs)

- [Search Integration](#search-integration)

- [Curl Example](#curl-example-1)

- [RAG Integration](#rag-integration)

- [Python Example](#python-example-7)

- [Best Practices](#best-practices-3)

- [Document Management](#document-management)

- [Collection Management](#collection-management)

- [Performance Optimization](#performance-optimization)

- [Access Control](#access-control-1)

- [Troubleshooting](#troubleshooting-1)

- [Conclusion](#conclusion-6)

- [Next Steps](#next-steps-1)

10. [GraphRAG in R2R](#graphrag-in-r2r)

- [Overview](#overview-1)

- [Architecture](#architecture)

- [Understanding Communities](#understanding-communities)

- [Example Communities](#example-communities)

- [Implementation Guide](#implementation-guide)

- [Prerequisites](#prerequisites-1)

- [Python Example](#python-example-8)

- [Building Communities](#building-communities)

- [Python Example](#python-example-9)

- [Build Process Includes](#build-process-includes)

- [Using GraphRAG](#using-graphrag)

- [Python Example](#python-example-10)

- [Understanding Results](#understanding-results)

- [Document Chunks](#document-chunks)

- [Graph Elements](#graph-elements)

- [Communities](#communities-1)

- [Scaling GraphRAG](#scaling-graphrag)

- [Using Orchestration](#using-orchestration)

- [Access Hatchet UI](#access-hatchet-ui)

- [Features](#features-1)

- [Example Diagram](#example-diagram)

- [Best Practices](#best-practices-4)

- [Development](#development)

- [Performance](#performance-1)

- [Quality](#quality)

- [Troubleshooting](#troubleshooting-2)

- [Next Steps](#next-steps-2)

- [Conclusion](#conclusion-7)

- [Security Considerations](#security-considerations-1)

11. [Agent](#agent)

- [Understanding R2R’s RAG Agent](#understanding-r2rs-rag-agent)

- [Planned Extensions](#planned-extensions)

- [Configuration](#configuration-2)

- [Default Configuration](#default-configuration)

- [Enable Web Search](#enable-web-search)

- [Using the RAG Agent](#using-the-rag-agent)

- [Python Example](#python-example-11)

- [Streaming Responses](#streaming-responses)

- [Context-Aware Responses](#context-aware-responses)

- [Working with Files](#working-with-files)

- [Python Example](#python-example-12)

- [Advanced Features](#advanced-features)

- [Combined Search Capabilities](#combined-search-capabilities)

- [Example](#example-11)

- [Custom Search Settings](#custom-search-settings)

- [Example](#example-12)

- [Best Practices](#best-practices-5)

- [Conversation Management](#conversation-management)

- [Search Optimization](#search-optimization)

- [Response Handling](#response-handling)

- [Error Handling](#error-handling-1)

- [Python Example](#python-example-13)

- [Limitations](#limitations)

- [Future Developments](#future-developments)

- [Conclusion](#conclusion-8)

- [Security Considerations](#security-considerations-2)

12. [Orchestration](#orchestration)

- [Key Concepts](#key-concepts)

- [Orchestration in R2R](#orchestration-in-r2r)

- [Benefits of Orchestration](#benefits-of-orchestration)

- [Workflows in R2R](#workflows-in-r2r)

- [List of Workflows](#list-of-workflows)

- [Orchestration GUI](#orchestration-gui)

- [Access GUI](#access-gui)

- [Login](#login-1)

- [Credentials](#credentials-1)

- [Logging into Hatchet](#logging-into-hatchet)

- [Running Tasks](#running-tasks)

- [Running Tasks Screenshot](#running-tasks-screenshot)

- [Inspecting a Workflow](#inspecting-a-workflow)

- [Inspecting a Workflow Screenshot](#inspecting-a-workflow-screenshot)

- [Long Running Tasks](#long-running-tasks)

- [Long Running Tasks Screenshot](#long-running-tasks-screenshot)

- [Coming Soon](#coming-soon)

- [Best Practices](#best-practices-6)

- [Development](#development-1)

- [Performance](#performance-2)

- [Quality](#quality-1)

- [Troubleshooting](#troubleshooting-3)

- [Conclusion](#conclusion-9)

13. [Maintenance & Scaling](#maintenance--scaling)

- [Vector Indices](#vector-indices)

- [Do You Need Vector Indices?](#do-you-need-vector-indices)

- [Vector Index Management](#vector-index-management)

- [Python Example: Creating and Deleting a Vector Index](#python-example-14)

- [Important Considerations](#important-considerations-1)

- [System Updates and Maintenance](#system-updates-and-maintenance)

- [Version Management](#version-management)

- [Check Current R2R Version](#check-current-r2r-version)

- [Update Process](#update-process)

- [Steps with Commands](#steps-with-commands)

- [Database Migration Management](#database-migration-management)

- [Check Current Migration](#check-current-migration)

- [Apply Migrations](#apply-migrations)

- [Managing Multiple Environments](#managing-multiple-environments)

- [Example with Environment Variables](#example-with-environment-variables)

- [Troubleshooting](#troubleshooting-4)

- [Steps](#steps-1)

- [Scaling Strategies](#scaling-strategies)

- [Horizontal Scaling](#horizontal-scaling)

- [Load Balancing](#load-balancing)

- [Sharding](#sharding)

- [Vertical Scaling](#vertical-scaling)

- [Cloud Provider Solutions](#cloud-provider-solutions)

- [Memory Optimization](#memory-optimization)

- [Multi-User Considerations](#multi-user-considerations)

- [Filtering Optimization](#filtering-optimization)

- [Collection Management](#collection-management-1)

- [Resource Allocation](#resource-allocation)

- [Performance Monitoring](#performance-monitoring)

- [Metrics](#metrics)

- [Performance Considerations](#performance-considerations-1)

- [Strategies](#strategies)

- [Additional Resources](#additional-resources-1)

- [Best Practices](#best-practices-7)

- [Optimize Indexing](#optimize-indexing)

- [Monitor Resources](#monitor-resources)

- [Regular Maintenance](#regular-maintenance)

- [Plan Scaling Ahead](#plan-scaling-ahead)

- [Conclusion](#conclusion-10)

14. [Web Development](#web-development)

- [Hello R2R—JavaScript](#hello-r2rjavascript)

- [Example: `r2r-js/examples/hello_r2r.js`](#example-r2r-jsexampleshello_r2rjs)

- [r2r-js Client](#r2r-js-client)

- [Installing](#installing-1)

- [Creating the Client](#creating-the-client)

- [Log into the Server](#log-into-the-server)

- [Ingesting Files](#ingesting-files-1)

- [Example and Sample Output](#example-and-sample-output-1)

- [Performing RAG](#performing-rag-1)

- [Example and Sample Output](#example-and-sample-output-2)

- [Connecting to a Web App](#connecting-to-a-web-app)

- [Setting up an API Route](#setting-up-an-api-route)

- [Frontend: React Component](#frontend-react-component)

- [Template Repository](#template-repository)

- [Usage Steps](#usage-steps-1)

- [Best Practices](#best-practices-8)

- [Secure API Routes](#secure-api-routes)

- [Optimize Frontend Performance](#optimize-frontend-performance)

- [Handle Errors Gracefully](#handle-errors-gracefully)

- [Implement Caching](#implement-caching)

- [Maintain Consistent State](#maintain-consistent-state)

- [Conclusion](#conclusion-11)

15. [User Management](#user-management)

- [Introduction](#introduction-3)

- [Basic Usage](#basic-usage-2)

- [User Registration and Login](#user-registration-and-login-1)

- [Python Example](#python-example-15)

- [Email Verification (Optional)](#email-verification-optional-1)

- [Token Refresh](#token-refresh-1)

- [User-Specific Search](#user-specific-search-1)

- [Curl Example](#curl-example-2)

- [User Logout](#user-logout-1)

- [Curl Example](#curl-example-3)

- [Advanced Authentication Features](#advanced-authentication-features-1)

- [Password Management](#password-management-1)

- [Python Example](#python-example-16)

- [User Profile Management](#user-profile-management-1)

- [Python Example](#python-example-17)

- [Account Deletion](#account-deletion-1)

- [Python Example](#python-example-18)

- [Logout](#logout-2)

- [Python Example](#python-example-19)

- [Superuser Capabilities and Default Admin Creation](#superuser-capabilities-and-default-admin-creation)

- [Superuser Capabilities](#superuser-capabilities-1)

- [Default Admin Creation](#default-admin-creation-1)

- [Configuration](#configuration-3)

- [Accessing Superuser Features](#accessing-superuser-features-1)

- [Python Example](#python-example-20)

- [Security Considerations for Superusers](#security-considerations-for-superusers)

- [Security Considerations](#security-considerations-3)

- [Customizing Authentication](#customizing-authentication)

- [Troubleshooting](#troubleshooting-5)

- [Conclusion](#conclusion-12)

16. [Collections](#collections)

- [Introduction](#introduction-4)

- [Basic Usage](#basic-usage-3)

- [Collection CRUD Operations](#collection-crud-operations-1)

- [Creating a Collection](#creating-a-collection)

- [Python Example](#python-example-21)

- [Retrieving Collection Details](#retrieving-collection-details)

- [Python Example](#python-example-22)

- [Updating a Collection](#updating-a-collection-1)

- [Python Example](#python-example-23)

- [Deleting a Collection](#deleting-a-collection-1)

- [Example](#example-13)

- [User Management in Collections](#user-management-in-collections)

- [Adding a User to a Collection](#adding-a-user-to-a-collection)

- [Example](#example-14)

- [Removing a User from a Collection](#removing-a-user-from-a-collection)

- [Example](#example-15)

- [Listing Users in a Collection](#listing-users-in-a-collection)

- [Example](#example-16)

- [Getting Collections for a User](#getting-collections-for-a-user)

- [Example](#example-17)

- [Document Management in Collections](#document-management-in-collections)

- [Assigning a Document to a Collection](#assigning-a-document-to-a-collection)

- [Example](#example-18)

- [Removing a Document from a Collection](#removing-a-document-from-a-collection)

- [Example](#example-19)

- [Listing Documents in a Collection](#listing-documents-in-a-collection)

- [Example](#example-20)

- [Getting Collections for a Document](#getting-collections-for-a-document)

- [Example](#example-21)

- [Advanced Collection Management](#advanced-collection-management)

- [Generating Synthetic Descriptions](#generating-synthetic-descriptions)

- [Example](#example-22)

- [Collection Overview](#collection-overview-1)

- [Example](#example-23)

- [Pagination and Filtering](#pagination-and-filtering-1)

- [Examples](#examples-1)

- [Security Considerations](#security-considerations-4)

- [Customizing Collection Permissions](#customizing-collection-permissions)

- [Troubleshooting](#troubleshooting-6)

- [Conclusion](#conclusion-13)

- [Next Steps](#next-steps-3)

17. [Telemetry](#telemetry)

- [Introduction](#introduction-5)

- [Disabling Telemetry](#disabling-telemetry)

- [Example](#example-24)

- [Collected Information](#collected-information)

- [Telemetry Data Storage](#telemetry-data-storage)

- [Note](#note)

- [Why We Collect Telemetry](#why-we-collect-telemetry)

- [Conclusion](#conclusion-14)

18. [Embedding](#embedding)

- [Embedding System](#embedding-system)

- [Embedding Configuration](#embedding-configuration-1)

- [Example: `r2r.toml`](#example-r2rtoml-1)

- [Advanced Embedding Features in R2R](#advanced-embedding-features-in-r2r)

- [Batched Processing](#batched-processing)

- [Python Example](#python-example-24)

- [Concurrent Request Management](#concurrent-request-management-1)

- [Performance Considerations](#performance-considerations-2)

- [Strategies](#strategies-1)

- [Supported LiteLLM Providers](#supported-litellm-providers)

- [Example Configuration](#example-configuration-9)

- [Supported Models](#supported-models)

- [Performance Considerations](#performance-considerations-3)

- [Conclusion](#conclusion-15)

19. [Prompts](#prompts)

- [Prompt Management in R2R](#prompt-management-in-r2r)

- [Default Prompts](#default-prompts)

- [Example: `rag.yaml`](#example-default_ragyaml)

- [Prompt Files](#prompt-files)

- [Prompt Provider](#prompt-provider)

- [Prompt Structure](#prompt-structure)

- [Managing Prompts](#managing-prompts)

- [Adding a Prompt](#adding-a-prompt)

- [Example](#example-25)

- [Updating a Prompt](#updating-a-prompt)

- [Example](#example-26)

- [Retrieving a Prompt](#retrieving-a-prompt)

- [Example](#example-27)

- [Security Considerations](#security-considerations-5)

- [Conclusion](#conclusion-16)

20. [RAG](#rag)

- [RAG Customization](#rag-customization)

- [Components](#components)

- [LLM Provider Configuration](#llm-provider-configuration)

- [Retrieval Configuration](#retrieval-configuration-1)

- [Combining LLM and Retrieval Configuration for RAG](#combining-llm-and-retrieval-configuration-for-rag)

- [Example](#example-28)

- [RAG Prompt Override](#rag-prompt-override)

- [Example](#example-29)

- [Agent-based Interaction](#agent-based-interaction)

- [Example](#example-30)

- [Conclusion](#conclusion-17)

21. [Graphs](#graphs)

- [Graphs](#graphs-1)

- [Knowledge Graph Operations](#knowledge-graph-operations)

- [Entity Management](#entity-management-1)

- [Relationship Management](#relationship-management-1)

- [Batch Import](#batch-import)

- [Vector Search](#vector-search-1)

- [Community Detection](#community-detection)

- [Customization](#customization-1)

- [Conclusion](#conclusion-18)

22. [Conclusion](#conclusion-19)

---

## Introduction

**R2R** (Retrieval to Riches) is an engine for building user-facing **Retrieval-Augmented Generation (RAG)** applications. It provides core services through an architecture of providers, services, and an integrated RESTful API. This documentation offers a detailed walkthrough of interacting with R2R, including installation, configuration, and leveraging its advanced features such as data ingestion, search, RAG, and knowledge graphs.

For a deeper dive into the R2R system architecture, refer to the [R2R System Architecture](https://r2r-docs.sciphi.ai/introduction/system).

---

## Installation

Before diving into R2R's features, ensure that you have completed the [installation instructions](https://r2r-docs.sciphi.ai/documentation/installation/overview).

### Prerequisites

- **Python 3.8+**: Ensure Python is installed on your system.

- **Docker**: Required for Docker-based installations. Install Docker from the [official Docker installation guide](https://docs.docker.com/engine/install/).

- **pip**: Python package installer.

### Docker Installation

This installation guide is for the **Full R2R**. For solo developers or teams prototyping, start with [R2R Light](https://r2r-docs.sciphi.ai/documentation/installation/light/local-system).

#### Install the R2R CLI & Python SDK

```bash

pip install r2r

```

> **Note**: A distinct CLI binary for R2R is under active development. For specific needs or feature requests, reach out to the R2R team.

#### Start R2R with Docker

The Full R2R installation uses a custom configuration (`full.toml`). Launch R2R with Docker:

```bash

r2r serve --docker --config-path=full.toml

```

> This command pulls necessary Docker images and starts required containers, including R2R, Hatchet, and Postgres+pgvector. Access the live server at [http://localhost:7272](http://localhost:7272/).

### Google Cloud Platform Deployment

Deploying R2R on Google Cloud Platform (GCP) involves setting up a Compute Engine instance, installing dependencies, and configuring port forwarding.

#### Overview

1. **Creating a Google Compute Engine Instance**

2. **Installing Dependencies**

3. **Setting up R2R**

4. **Configuring Port Forwarding for Local Access**

5. **Exposing Ports for Public Access (Optional)**

6. **Security Considerations**

#### Creating a Google Compute Engine Instance

1. **Log in** to the Google Cloud Console.

2. Navigate to **Compute Engine** > **VM instances**.

3. Click **Create Instance**.

4. Configure the instance:

- **Name**: Choose a name.

- **Region and Zone**: Select based on preference.

- **Machine Configuration**:

- **Series**: N1

- **Machine type**: `n1-standard-4` (4 vCPU, 15 GB memory) or higher.

- **Boot Disk**:

- **OS**: Ubuntu 22.04 LTS

- **Size**: 500 GB

- **Firewall**: Allow HTTP and HTTPS traffic.

5. Click **Create** to launch the instance.

#### Installing Dependencies

SSH into your instance and run the following commands:

```bash

# Update package list and install Python and pip

sudo apt update

sudo apt install python3-pip -y

# Install R2R

pip install r2r

# Add R2R to PATH

echo 'export PATH=$PATH:$HOME/.local/bin' >> ~/.bashrc

source ~/.bashrc

# Install Docker

sudo apt-get update

sudo apt-get install ca-certificates curl gnupg -y

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \

"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \

$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \

sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Add your user to the Docker group

sudo usermod -aG docker $USER

newgrp docker

# Verify Docker installation

docker run hello-world

```

#### Setting up R2R

```bash

# Set required remote providers

export OPENAI_API_KEY=sk-...

# Optional - pass in a custom configuration

r2r serve --docker --full

```

#### Configuring Port Forwarding for Local Access

Use SSH port forwarding to access R2R locally:

```bash

gcloud compute ssh --zone "your-zone" "your-instance-name" -- -L 7273:localhost:7273 -L 7274:localhost:7274

```

#### Exposing Ports for Public Access (Optional)

To make R2R publicly accessible:

1. **Create a Firewall Rule**:

- Navigate to **VPC network** > **Firewall**.

- Click **Create Firewall Rule**.

- **Name**: Allow-R2R

- **Target tags**: `r2r-server`

- **Source IP ranges**: `0.0.0.0/0`

- **Protocols and ports**: `tcp:7272`

2. **Add Network Tag to Instance**:

- Go to **Compute Engine** > **VM instances**.

- Click on your instance.

- Click **Edit**.

- Under **Network tags**, add `r2r-server`.

- Click **Save**.

3. **Ensure R2R Listens on All Interfaces**.

After starting R2R, access it at:

```

http://<your-instance-external-ip>:7272

```

> **Security Considerations**:

> - Use HTTPS with a valid SSL certificate.

> - Restrict source IP addresses in firewall rules.

> - Regularly update and patch your system.

#### Conclusion

You have successfully deployed R2R on Google Cloud Platform. The application is accessible locally via SSH tunneling and optionally publicly. Ensure proper security measures are in place before exposing R2R to the internet.

For more details, refer to the [R2R Configuration Documentation](https://r2r-docs.sciphi.ai/documentation/configuration/overview).

---

## R2R Application Lifecycle

R2R's application lifecycle encompasses customization, configuration, deployment, implementation, and interaction. The lifecycle is designed to provide flexibility and scalability for various use cases.

### Developer Workflow

- **Customize**: Developers tailor R2R applications using R2RConfig and the R2R SDK.

- **Configure**: Adjust settings via configuration files (`r2r.toml`) or runtime overrides.

- **Deploy**: Launch R2R using Docker, cloud platforms, or local installations.

- **Implement**: Integrate R2R into applications using provided APIs and SDKs.

- **Interact**: Users engage with the R2R application through interfaces like dashboards or APIs to perform RAG queries or search documents.

### User Interaction

- **Users** interact with the R2R application, typically over an HTTP interface, to run RAG queries or search documents.

- Access the **R2R Dashboard** for managing documents, collections, and performing searches.

### Hello R2R (Code Example)

**Python Example** at `core/examples/hello_r2r.py`:

```python

from r2r import R2RClient

client = R2RClient("http://localhost:7272")

# Create a test document

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-4.1-mini", "temperature": 0.0},

)

results = rag_response["results"]

print(f"Search Results:\n{results['search_results']}")

print(f"Completion:\n{results['completion']}")

```

**Sample Output:**

```json

{

"results": {

"search_results": {

"chunk_search_results": [

{

"chunk_id": "b9f40dbd-2c8e-5c0a-8454-027ac45cb0ed",

"document_id": "7c319fbe-ca61-5770-bae2-c3d0eaa8f45c",

"score": 0.6847735847465275,

"text": "John is a person that works at Google.",

"metadata": {

"version": "v0",

"chunk_order": 0,

"document_type": "txt",

"associated_query": "Who is John"

}

}

],

"kg_search_results": []

},

"completion": {

"id": "chatcmpl-AV1Sc9DORfHvq7yrmukxfJPDV5dCB",

"choices": [

{

"finish_reason": "stop",

"index": 0,

"message": {

"content": "John is a person that works at Google [1].",

"role": "assistant"

}

}

],

"created": 1731957146,

"model": "gpt-4.1-mini",

"object": "chat.completion",

"usage": {

"completion_tokens": 11,

"prompt_tokens": 145,

"total_tokens": 156

}

}

}

}

```

This snippet:

1. Creates a file with simple text.

2. Ingests it to R2R.

3. Runs a **Retrieval-Augmented Generation** query.

4. Prints the context matched (“search_results”) and the generated answer (“completion”).

---

## Configuration

R2R is highly configurable, allowing you to tailor its behavior to your specific needs. Configuration can be done at the server-side using configuration files (`r2r.toml`) or at runtime via API calls.

### Configuration Overview

R2R configurations are divided into two primary levels:

1. **Server-Side Configuration**: Managed through the `r2r.toml` file and environment variables.

2. **Runtime Overrides**: Passed directly in API calls to adjust settings dynamically.

### Server-Side Configuration (`r2r.toml`)

The `r2r.toml` file allows you to define server-side settings that govern the behavior of R2R. Below are the main configuration sections:

#### Example: `r2r.toml`

```toml

[completion]

provider = "litellm"

concurrent_request_limit = 16

[completion.generation_config]

model = "openai/gpt-4.1"

temperature = 0.5

[ingestion]

provider = "r2r"

chunking_strategy = "recursive"

chunk_size = 1024

chunk_overlap = 512

excluded_parsers = []

[database]

provider = "postgres"

user = "your_postgres_user"

password = "your_postgres_password"

host = "your_postgres_host"

port = "your_postgres_port"

db_name = "your_database_name"

project_name = "your_project_name"

[embedding]

provider = "litellm"

base_model = "openai/text-embedding-3-small"

base_dimension = 512

batch_size = 512

rerank_model = "BAAI/bge-reranker-v2-m3"

concurrent_request_limit = 256

[auth]

provider = "r2r"

require_authentication = true

require_email_verification = false

default_admin_email = "admin@example.com"

default_admin_password = "change_me_immediately"

access_token_lifetime_in_minutes = 60

refresh_token_lifetime_in_days = 7

secret_key = "your-secret-key"

[ingestion.chunk_enrichment_settings]

enable_chunk_enrichment = true

strategies = ["semantic", "neighborhood"]

forward_chunks = 3

backward_chunks = 3

semantic_neighbors = 10

semantic_similarity_threshold = 0.7

generation_config = { model = "openai/gpt-4.1-mini" }

[agent]

rag_agent_static_prompt = "rag_agent"

tools = ["search_file_knowledge", "web_search"]

[database.graph_creation_settings]

entity_types = []

relation_types = []

max_knowledge_triples = 100

fragment_merge_count = 4

generation_config = { model = "openai/gpt-4.1-mini" }

[database.graph_enrichment_settings]

max_description_input_length = 65536

max_summary_input_length = 65536

generation_config = { model = "openai/gpt-4.1-mini" }

leiden_params = {}

[database.graph_settings]

generation_config = { model = "openai/gpt-4.1-mini" }

```

### Runtime Overrides

Runtime overrides allow you to adjust configurations dynamically without modifying the `r2r.toml` file. This is useful for temporary changes or testing different settings on the fly.

**Example: Customizing RAG Query at Runtime**

```python

rag_response = client.retrieval.rag(

query="Who is Jon Snow?",

rag_generation_config={

"model": "anthropic/claude-3-haiku-20240307",

"temperature": 0.7

},

search_settings={

"use_semantic_search": True,

"limit": 20,

"use_hybrid_search": True

}

)

```

### Postgres Configuration

R2R uses Postgres for relational and vector data storage, leveraging the `pgvector` extension for vector indexing.

#### Example Configuration

```toml

[database]

provider = "postgres"

user = "your_postgres_user"

password = "your_postgres_password"

host = "your_postgres_host"

port = "your_postgres_port"

db_name = "your_database_name"

project_name = "your_project_name"

```

**Key Features:**

- **pgvector**: Enables efficient vector operations.

- **Full-Text Indexing**: Utilizes Postgres’s `ts_rank` for full-text search.

- **JSONB**: Stores flexible metadata.

### Embedding Configuration

R2R uses **LiteLLM** to manage embedding providers, allowing flexibility in selecting different LLM providers.

#### Example Configuration

```toml

[embedding]

provider = "litellm"

base_model = "openai/text-embedding-3-small"

base_dimension = 512

batch_size = 512

rerank_model = "BAAI/bge-reranker-v2-m3"

concurrent_request_limit = 256

```

**Environment Variables:**

- `OPENAI_API_KEY`

- `HUGGINGFACE_API_KEY`

- `ANTHROPIC_API_KEY`

- `COHERE_API_KEY`

- `OLLAMA_API_KEY`

- etc.

**Supported Providers:**

- OpenAI

- Azure

- Anthropic

- Cohere

- Ollama

- HuggingFace

- Bedrock

- Vertex AI

- Voyage AI

### Auth & Users Configuration

R2R’s authentication system supports secure user registration, login, session management, and access control.

#### Example Configuration

```toml

[auth]

provider = "r2r"

require_authentication = true

require_email_verification = false

default_admin_email = "admin@example.com"

default_admin_password = "change_me_immediately"

access_token_lifetime_in_minutes = 60

refresh_token_lifetime_in_days = 7

secret_key = "your-secret-key"

```

**Key Features:**

- **JWT-Based Authentication**: Utilizes access and refresh tokens.

- **Email Verification**: Optional, recommended for production.

- **Superuser Management**: Default admin creation and superuser capabilities.

### Data Ingestion Configuration

Configure how R2R ingests documents, including parsing, chunking, and embedding strategies.

#### Example Configuration

```toml

[ingestion]

provider = "r2r"

chunking_strategy = "recursive"

chunk_size = 1024

chunk_overlap = 512

excluded_parsers = []

[ingestion.chunk_enrichment_settings]

enable_chunk_enrichment = true

strategies = ["semantic", "neighborhood"]

forward_chunks = 3

backward_chunks = 3

semantic_neighbors = 10

semantic_similarity_threshold = 0.7

generation_config = { model = "openai/gpt-4.1-mini" }

```

**Modes:**

- `fast`: Speed-oriented ingestion.

- `hi-res`: Comprehensive, high-quality ingestion.

- `custom`: Fine-grained control with a full `ingestion_config` dictionary.

### Retrieval Configuration

Focuses on search settings, combining vector and knowledge-graph search capabilities.

#### Example Configuration

```json

{

"search_settings": {

"use_semantic_search": true,

"limit": 20,

"use_hybrid_search": true,

"graph_search_settings": {

"use_graph_search": true,

"kg_search_type": "local"

}

}

}

```

### RAG Configuration

Customize RAG (Retrieval-Augmented Generation) settings, including the language model's behavior.

#### Example Configuration

```python

rag_generation_config = {

"model": "anthropic/claude-3-haiku-20240307",

"temperature": 0.7,

"top_p": 0.95,

"max_tokens_to_sample": 1500,

"stream": True

}

```

### Graphs Configuration

Defines settings related to knowledge graph creation and enrichment.

#### Example Configuration

```toml

[database.graph_creation_settings]

entity_types = []

relation_types = []

max_knowledge_triples = 100

fragment_merge_count = 4

generation_config = { model = "openai/gpt-4.1-mini" }

[database.graph_enrichment_settings]

max_description_input_length = 65536

max_summary_input_length = 65536

generation_config = { model = "openai/gpt-4.1-mini" }

leiden_params = {}

[database.graph_settings]

generation_config = { model = "openai/gpt-4.1-mini" }

```

### Prompts Configuration

Manages prompt templates used for various tasks within R2R.

#### Example Configuration

Prompts are stored in Postgres and can be managed via the SDK.

**Example: Adding a Prompt**

```python

response = client.prompts.add_prompt(

name="my_new_prompt",

template="Hello, {name}! Welcome to {service}.",

input_types={"name": "str", "service": "str"}

)

```

---

## Data Ingestion

### Introduction

R2R provides a powerful and flexible ingestion pipeline to process and manage various types of documents. It supports a wide range of file formats—text, documents, PDFs, images, audio, and video—and transforms them into searchable, analyzable content. The ingestion process includes parsing, chunking, embedding, and optionally extracting entities and relationships for knowledge graph construction.