R2R

Processes diverse document formats (PDF, DOCX, images, code files, web content) through a pluggable IngestionService that routes each format to specialized parsers (pypdf for PDFs, python-docx for Word docs, unstructured-client for mixed media). The system extracts text, metadata, and structural information, then chunks documents into semantically meaningful segments before vectorization. Supports streaming ingestion for large document batches.

Combines dense vector search (pgvector embeddings) with sparse full-text search (PostgreSQL FTS) using Reciprocal Rank Fusion (RRF) to merge results from both modalities. Queries are embedded and matched against vector index, while simultaneously executed as full-text queries on indexed text columns. RRF algorithm normalizes and combines rankings, allowing semantic and keyword-based relevance to influence final ordering. Supports filtering by metadata, date ranges, and document tags.

Provides Docker configuration for containerized R2R deployment, including Dockerfile for building images and docker-compose for multi-container orchestration (R2R API, PostgreSQL, optional Redis for caching). Supports environment variable configuration for all settings, enabling deployment across different environments (dev, staging, production) without code changes. Includes health checks and graceful shutdown handling.

Implements Model Context Protocol support, allowing R2R to expose its capabilities (document retrieval, search, entity lookup) as MCP tools that can be called by LLM clients (Claude, other MCP-compatible models). Tools are defined with JSON schemas and can be invoked by LLMs with automatic parameter validation. Enables seamless integration of R2R into LLM-native workflows without custom API wrappers.

Supports multiple document chunking strategies (fixed-size windows, semantic chunking, code-aware chunking) that can be selected via configuration. Semantic chunking uses embeddings to identify natural breakpoints in text, preserving semantic units. Code-aware chunking respects syntax boundaries (functions, classes) to avoid splitting logical units. Chunk size, overlap, and strategy are configurable per document type.

Supports multiple embedding models (OpenAI, Hugging Face, local models via Ollama) through a pluggable EmbeddingProvider interface. Processes documents in batches to maximize throughput and reduce API costs. Embeddings are stored in PostgreSQL with pgvector extension, enabling efficient similarity search. Supports re-embedding documents with different models without data loss.

Implements a Deep Research API that enables agents to iteratively fetch information from local knowledge bases and external web sources, synthesizing results through LLM-driven reasoning. Agents decompose complex queries into sub-tasks, call retrieval tools with refined prompts, and aggregate findings. The system supports tool calling via schema-based function registries compatible with OpenAI and Anthropic function-calling APIs. Streaming responses allow real-time visibility into agent reasoning steps.

Automatically extracts entities and relationships from ingested documents using LLM-based extraction or rule-based patterns, then constructs a knowledge graph stored as nodes and edges. Applies community detection algorithms (networkx-based) to identify clusters of related entities, enabling hierarchical knowledge organization. Supports querying the graph to find entity relationships, traverse paths between concepts, and retrieve context-rich information for RAG augmentation.

Exposes R2R functionality through a FastAPI application with versioned endpoints (v1, v2, v3) supporting document management, retrieval, search, and administrative operations. Provides Python (R2RClient, R2RAsyncClient) and JavaScript (r2rClient) SDKs that abstract HTTP communication and handle request/response serialization. Supports both synchronous and asynchronous operations, enabling non-blocking integration into async frameworks.

Implements a pluggable provider architecture where LLM, embedding, database, and ingestion providers are swappable via TOML configuration without code changes. Supports multiple LLM backends (OpenAI, Anthropic, Ollama, LM Studio), embedding models (OpenAI, Hugging Face, local), and databases (PostgreSQL, in-memory). Providers implement standard interfaces (e.g., LLMProvider, EmbeddingProvider) enabling runtime selection and fallback strategies.

Implements multi-user support with role-based access control (RBAC) where users have roles (admin, user, viewer) with different permissions for document management, search, and administrative operations. User authentication is API-key based; each user has a unique key for API requests. Permissions are enforced at the API endpoint level, preventing unauthorized access to documents or operations.

Stores and indexes document metadata (title, source, creation date, custom tags, document type) in PostgreSQL alongside document chunks. Metadata is extracted during ingestion or provided by users. Supports filtering search results by metadata using SQL WHERE clauses, enabling queries like 'find documents from 2024 with tag=legal'. Metadata can be updated without re-ingesting documents.

Supports asynchronous document ingestion via streaming APIs, allowing large batches to be processed without blocking the main API thread. Uses async/await patterns throughout the ingestion pipeline (IngestionService, parsers, embedding). Clients can poll for ingestion status or receive webhooks when processing completes. Streaming responses enable real-time visibility into ingestion progress.

Integrates with Hatchet workflow orchestration platform to manage complex, multi-step document processing pipelines. Workflows are defined as DAGs (directed acyclic graphs) where each node is a processing step (ingestion, embedding, entity extraction, graph construction). Hatchet handles task scheduling, retries, error handling, and distributed execution across worker nodes. R2R provides SimpleOrchestrationProvider for basic workflows and HatchetOrchestrationProvider for advanced scenarios.