R2R is an MIT-licensed, Python-based retrieval system from SciPhi-AI that gives developers a RESTful API for agentic Retrieval-Augmented Generation over their own documents, with official Python and JavaScript clients.

What it is

R2R is an advanced AI retrieval system that supports Retrieval-Augmented Generation as a production service rather than as a library fragment. It is built around a RESTful API and ships with several capabilities that usually get stitched together by hand: multimodal content ingestion, hybrid search, knowledge graphs, agentic reasoning, and document management. The project lives in the Python ecosystem and publishes two client SDKs — r2r for Python and r2r-js for JavaScript — both of which talk to the same server, exposed by default at http://localhost:7272.

The concrete problem it solves is the assembly work behind a document question-answering product. Instead of wiring ingestion, chunking, search, reasoning, and access control into separate internal services, a team runs one R2R server and calls client.retrieval.search, client.retrieval.rag, and client.retrieval.agent against it. It replaces the custom retrieval layer a team would otherwise build and maintain per project, and it does so across both the retrieval-systems and retrieval-augmented-generation topic areas listed for the repository.

Key capabilities

• Multimodal ingestion that parses .txt, .pdf, .json, .png, .mp3, and more through client.documents.create(file_path="/path/to/file"), with client.documents.list() for enumeration.
• Hybrid search combining semantic and keyword retrieval with reciprocal rank fusion, reached through client.retrieval.search(query="...").
• RAG responses with citations through client.retrieval.rag(query="...").
• A Deep Research API and agentic RAG mode through client.retrieval.agent(...), a multi-step reasoning system that fetches relevant data from the knowledgebase, the internet, or both.
• Knowledge graphs with automatic entity and relationship extraction.
• User and access management covering complete authentication and a collection system.
• Tunable generation through rag_generation_config, which accepts model, extended_thinking, thinking_budget, temperature, top_p, and max_tokens_to_sample; the README example uses anthropic/claude-3-7-sonnet-20250219 with thinking_budget set to 4096.

Who uses it and how

• Teams answering questions over mixed document sets, since ingestion covers text, PDF, JSON, images, and audio in one pipeline.
• Multi-tenant applications that need authentication and collections before exposing retrieval to end users.
• Research and analysis workflows that call the Deep Research agent for multi-step questions, such as asking what a model release implies across market and societal dimensions.
• JavaScript and TypeScript front ends, which consume the same server through npm i r2r-js and r2rClient.
• Self-hosters running the full profile on Docker with a Postgres backend.

Getting started

Light mode is three commands: pip install r2r, export OPENAI_API_KEY=sk-..., then python -m r2r.serve. Full mode runs docker compose -f compose.full.yaml --profile postgres up -d after cloning the repository and setting R2R_CONFIG_NAME=full.

How it compares

The facts provided name no paid products and no comparable tools, so this page offers no substitution comparison. R2R stands alone in this registry on the evidence given.

When to use it — and when not to

Choose R2R when a team is willing to operate a service: full mode expects Docker Compose with the postgres profile, and both modes expect an OPENAI_API_KEY, so self-hosting means owning the process, the database, and the model credentials. Teams that want a managed endpoint rather than an operated deployment will not find one in what the README describes, and the repository carries 126 open issues alongside roughly 8,000 stars, which is a normal signal for an actively developed project rather than a settled one. The README excerpt also documents quick-start paths more thoroughly than operational concerns, so a prospective self-hoster should read the linked self-hosting docs before committing.

# Basic search
results = client.retrieval.search(query="What is DeepSeek R1?")

# RAG with citations
response = client.retrieval.rag(query="What is DeepSeek R1?")

# Deep Research RAG Agent
response = client.retrieval.agent(
  message={"role":"user", "content": "What does deepseek r1 imply? Think about market, societal implications, and more."},
  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,
  },
)

# Quick install and run in light mode
pip install r2r
export OPENAI_API_KEY=sk-...
python -m r2r.serve

# Or run in full mode with Docker
# git clone [email protected]:SciPhi-AI/R2R.git && cd R2R
# export R2R_CONFIG_NAME=full OPENAI_API_KEY=sk-...
# docker compose -f compose.full.yaml --profile postgres up -d

# Install SDK
pip install r2r  # Python
# or
npm i r2r-js    # JavaScript

from r2r import R2RClient
client = R2RClient(base_url="http://localhost:7272")

const { r2rClient } = require('r2r-js');
const client = new r2rClient("http://localhost:7272");

# Ingest sample or your own document
client.documents.create(file_path="/path/to/file")

# List documents
client.documents.list()