How sciphi-ai/r2r works
Purpose and Entry Points
R2R is a self-hostable, REST-oriented AI retrieval platform: multimodal document ingestion, hybrid/vector retrieval, RAG and research agents, knowledge graphs, and multi-user document/collection management. The Python server starts through py/r2r/serve.py and assembles the application in py/core/main/app_entry.py / py/core/main/app.py. Consumers use Python and TypeScript SDKs via py/sdk/sync_client.py, py/sdk/async_client.py, and js/sdk/src/r2rClient.ts.
API and Application Assembly
Versioned HTTP endpoints are separated by resource domain—documents, chunks, collections, retrieval, graphs, conversations, users, prompts, indices, and system. Routers should remain thin API boundaries over services:
• py/core/main/api/v3/documents_router.py
• py/core/main/api/v3/retrieval_router.py
• py/core/main/api/v3/graph_router.py
py/core/main/assembly/builder.py and py/core/main/assembly/factory.py select and wire provider implementations from runtime configuration, allowing light/local versus full/deployed installations without changing service callers.
Service Layer and Core Flows
Services contain use-case orchestration between routers, providers, and background workflows:
• py/core/main/services/ingestion_service.py
• py/core/main/services/retrieval_service.py
• py/core/main/services/graph_service.py
Primary ingestion flow is API/SDK request → ingestion service → file/ingestion provider and format parser → chunking/embedding → PostgreSQL-backed document/chunk/vector persistence; graph extraction can be scheduled from ingested content. Retrieval flows are API → retrieval service → database hybrid search and LLM/agent generation, returning search results or cited RAG output. Authorization, ownership, collections, limits, and prompts constrain these operations.
Ingestion and Knowledge Construction
The parser layer supports media, structured, and text inputs, while provider interfaces isolate parser/ingestion implementations:
• py/core/parsers/media/pdf_parser.py
• py/core/providers/ingestion/r2r/base.py
• py/core/providers/ingestion/unstructured/base.py
Document text is split through shared abstractions, embedded through configured models, and stored as searchable chunks. Graph workflows perform entity/relationship extraction and community-oriented graph processing:
• py/core/main/orchestration/hatchet/ingestion_workflow.py
• py/core/main/orchestration/hatchet/graph_workflow.py
• py/shared/abstractions/graph.py
Retrieval, RAG, and Agents
Retrieval combines semantic/vector and keyword-oriented database capabilities, with prompt-driven RAG and tool-using agents:
• py/core/agent/rag.py
• py/core/agent/research.py
• py/core/providers/database/postgres.py
Agent tools include knowledge/file search and web acquisition, creating an explicit boundary between tenant knowledge-base retrieval and internet-backed research:
• py/core/base/agent/tools/built_in/search_file_knowledge.py
• py/core/base/agent/tools/built_in/web_search.py
• py/core/base/agent/tools/built_in/tavily_search.py
Provider and Persistence Boundaries
Abstract provider contracts in py/core/base/providers/ decouple application logic from concrete integrations. Implementations cover PostgreSQL/pgvector data, S3 or PostgreSQL file storage, OpenAI/LiteLLM/Ollama/Anthropic/Azure model access, OCR, auth, email, and scheduling. Key implementations:
• py/core/providers/database/postgres.py
• py/core/providers/embeddings/openai.py
• py/core/providers/llm/litellm.py
PostgreSQL schema evolution is managed under py/migrations/. Authentication supports internal JWT/R2R auth and external Clerk/Supabase alternatives.
Deployment and Runtime Topology
Light mode runs the Python service with local/simple providers. Full Docker and Kubernetes deployments provision R2R alongside PostgreSQL/pgvector, Hatchet orchestration with RabbitMQ, MinIO-compatible object storage, optional Unstructured parsing, and a separate graph-clustering service:
• docker/compose.full.yaml
• deployment/k8s/kustomizations/kustomization.yaml
• services/clustering/main.py
Hatchet is the durable asynchronous-workflow boundary for long-running ingestion and graph jobs; simple orchestration offers an in-process alternative. Production observability includes Fluent Bit configuration and optional Sentry integration.
Main entry points: compose.full.yaml Full Docker/Kubernetes topology · base.py Ingestion pipeline · postgres.py PostgreSQL + pgvector · ingestion_service.py Application services
Components 20
Clients
- Python SDKs
py/sdk/sync_client.py - TypeScript SDK
js/sdk/src/r2rClient.ts
Python application
- R2R server
py/r2r/serve.py - Application assembly · Builds the REST application and selected runtime components.
py/core/main/app_entry.py - Versioned API routers · Resource routers remain thin boundaries over services.
py/core/main/api/v3/documents_router.py - Application services · Applies authorization, ownership, collections, limits, and prompts.
py/core/main/services/ingestion_service.py - Ingestion pipeline · Parses inputs, chunks text, and creates embeddings.
py/core/providers/ingestion/r2r/base.py - Format parsers · Handles media, structured, and text inputs.
py/core/parsers/media/pdf_parser.py - RAG and research agents · Produces cited RAG responses and tool-using research.
py/core/agent/rag.py - Knowledge search tool
py/core/base/agent/tools/built_in/search_file_knowledge.py - Web research tools · Explicit internet acquisition boundary.
py/core/base/agent/tools/built_in/web_search.py
Providers and data
- Provider builder · Selects implementations for light or deployed installations.
py/core/main/assembly/builder.py - Provider contracts · Decouple services from database, model, storage, auth, and scheduler integrations.
- LLM and embedding providers
py/core/providers/llm/litellm.py - PostgreSQL + pgvector · Stores documents, chunks, vectors, metadata, and supports hybrid search.
py/core/providers/database/postgres.py - Object storage · S3- or PostgreSQL-backed file storage.
Async knowledge workflows
- Hatchet workflows · Runs long-lived ingestion and graph extraction jobs.
py/core/main/orchestration/hatchet/ingestion_workflow.py - Knowledge graph processing · Extracts entities and relationships and performs community processing.
py/core/main/orchestration/hatchet/graph_workflow.py
Full deployment services
- Graph clustering service
services/clustering/main.py - Full Docker/Kubernetes topology · Provisions R2R with PostgreSQL, Hatchet/RabbitMQ, storage, and optional parsing.
docker/compose.full.yaml
Connections 28
- Python SDKs → Versioned API routers: REST requests
- TypeScript SDK → Versioned API routers: REST requests
- R2R server → Application assembly: starts
- Application assembly → Versioned API routers: mounts
- Application assembly → Provider builder: configures
- Versioned API routers → Application services: delegates
- Application services → Ingestion pipeline: ingests documents
- Ingestion pipeline → Format parsers: parses content
- Ingestion pipeline → LLM and embedding providers: embeds chunks
- Ingestion pipeline → PostgreSQL + pgvector: persists chunks and vectors
- Ingestion pipeline → Object storage: stores files
- Application services → RAG and research agents: runs retrieval and RAG
- RAG and research agents → Knowledge search tool: tenant knowledge
- Knowledge search tool → PostgreSQL + pgvector: hybrid search
- RAG and research agents → Web research tools: internet research
- RAG and research agents → LLM and embedding providers: generation
- Provider builder → Provider contracts: binds implementations
- Provider contracts → LLM and embedding providers: model contracts
- Provider contracts → PostgreSQL + pgvector: database contract
- Application services → Hatchet workflows: schedules long jobs
- Hatchet workflows → Knowledge graph processing: runs graph jobs
- Knowledge graph processing → PostgreSQL + pgvector: stores graph data
- Knowledge graph processing → Graph clustering service: community clustering
- Full Docker/Kubernetes topology → R2R server: deploys
- Full Docker/Kubernetes topology → Hatchet workflows: provisions
- Full Docker/Kubernetes topology → PostgreSQL + pgvector: provisions
- Full Docker/Kubernetes topology → Object storage: provisions
- Full Docker/Kubernetes topology → Graph clustering service: provisions