jb-r2r

The ultimate open source RAG answer engine

About

R2R was designed to bridge the gap between local LLM experimentation and scalable, production-ready Retrieval-Augmented Generation (RAG). R2R provides a comprehensive and SOTA RAG system for developers, built around a RESTful API for ease of use.

For a more complete view of R2R, check out the full documentation.

Key Features

• 📁 Multimodal Support: Ingest files ranging from .txt, .pdf, .json to .png, .mp3, and more.
• 🔍 Hybrid Search: Combine semantic and keyword search with reciprocal rank fusion for enhanced relevancy.
• 🔗 Graph RAG: Automatically extract relationships and build knowledge graphs.
• 🗂️ App Management: Efficiently manage documents and users with rich observability and analytics.
• 🌐 Client-Server: RESTful API support out of the box.
• 🧩 Configurable: Provision your application using intuitive configuration files.
• 🔌 Extensible: Develop your application further with easy builder + factory pattern.
• 🖥️ Dashboard: Use the R2R Dashboard, an open-source React+Next.js app for a user-friendly interaction with R2R.

Table of Contents

• Install
• R2R Quickstart
• R2R Dashboard
• Community and Support
• Contributing

Install

[!NOTE] Windows users are advised to use Docker to run R2R.

Installing with Pip 🐍

pip install r2r

# setup env, can freely replace `demo_vecs`
export OPENAI_API_KEY=sk-...
export POSTGRES_USER=YOUR_POSTGRES_USER
export POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD
export POSTGRES_HOST=YOUR_POSTGRES_HOST
export POSTGRES_PORT=YOUR_POSTGRES_PORT
export POSTGRES_DBNAME=YOUR_POSTGRES_DBNAME
export POSTGRES_VECS_COLLECTION=demo_vecs

Installing with Docker 🐳

Note: The R2R client must still be installed, even when running with Docker. Download the Python client with pip install r2r.

To run R2R using Docker:

# Setting up the environment. The right side is where you should put the value of your variable.
# Note - you can freely replace `demo_vecs`
export OPENAI_API_KEY=sk-...
export POSTGRES_USER=YOUR_POSTGRES_USER
export POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD
export POSTGRES_HOST=YOUR_POSTGRES_HOST
export POSTGRES_PORT=YOUR_POSTGRES_PORT
export POSTGRES_DBNAME=YOUR_POSTGRES_DBNAME
export POSTGRES_VECS_COLLECTION=demo_vecs

# Optional on first pull. Advised when fetching the main updates.
docker pull emrgntcmplxty/r2r:main

# Runs the image. If you set up the environment you don't need to modify anything.
# Otherwise, add your values on the right side of the -e commands.
# For Windows, remove the "\" from your command.
docker run -d \
   --name r2r \
   -p 8000:8000 \
   -e POSTGRES_USER=$POSTGRES_USER \
   -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
   -e POSTGRES_HOST=$POSTGRES_HOST \
   -e POSTGRES_PORT=$POSTGRES_PORT \
   -e POSTGRES_DBNAME=$POSTGRES_DBNAME \
   -e OPENAI_API_KEY=$OPENAI_API_KEY \
   emrgntcmplxty/r2r:main

Important: The Docker image of r2r operates in server and client mode, with the server being the Docker container and the client being your PC. This means you need to append --client_server_mode to all your queries.

Additionally, your PC (acting as the client) needs to have Python, Pip, and the dependencies listed in the r2r folder of the repository. Therefore, you need to have the repository cloned on your computer and run pip install r2r in the root folder of the cloned repository.

You have the option to run the client inside the terminal of the Docker container (to have everything in one place), but the use of pip install r2r and --client_server_mode is necessary.

For local LLMs:

docker run -d \
   --name r2r \
   --add-host=host.docker.internal:host-gateway \
   -p 8000:8000 \
   -e POSTGRES_USER=$POSTGRES_USER \
   -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
   -e POSTGRES_HOST=$POSTGRES_HOST \
   -e POSTGRES_PORT=$POSTGRES_PORT \
   -e POSTGRES_DBNAME=$POSTGRES_DBNAME \
   -e OLLAMA_API_BASE=http://host.docker.internal:11434 \
   -e CONFIG_OPTION=local_ollama \
  emrgntcmplxty/r2r:main

Updates

Star R2R on GitHub by clicking "Star" in the upper right hand corner of the page to be instantly notified of new releases.

R2R Quickstart

Start the R2R server

Serving with Python 🐍

python -m r2r.examples.quickstart serve --port=8000

2024-06-26 16:54:46,998 - INFO - r2r.core.providers.vector_db_provider - Initializing VectorDBProvider with config extra_fields={} provider='pgvector' collection_name='demo_vecs'.
2024-06-26 16:54:48,054 - INFO - r2r.core.providers.embedding_provider - Initializing EmbeddingProvider with config extra_fields={'text_splitter': {'type': 'recursive_character', 'chunk_size': 512, 'chunk_overlap': 20}} provider='openai' base_model='text-embedding-3-small' base_dimension=512 rerank_model=None rerank_dimension=None rerank_transformer_type=None batch_size=128.
2024-06-26 16:54:48,639 - INFO - r2r.core.providers.llm_provider - Initializing LLM provider with config: extra_fields={} provider='litellm'

Serving with Docker 🐳

Successfully completing the installation steps above results in an R2R application being served over port 8000.

Ingest a file

python -m r2r.examples.quickstart ingest --client-server-mode
# can be called with additional argument,
# e.g. `python -m r2r...  --client-server-mode /path/to/your_file`

{'results': {'processed_documents': ["File '.../aristotle.txt' processed successfully."], 'skipped_documents': []}}

Perform a search

python -m r2r.examples.quickstart search --query="who was aristotle?" --client-server-mode

{'results': {'vector_search_results': [
    {
        'id': '7ed3a01c-88dc-5a58-a68b-6e5d9f292df2',
        'score': 0.780314067545999,
        'metadata': {
            'text': 'Aristotle[A] (Greek: Ἀριστοτέλης Aristotélēs, pronounced [aristotélɛːs]; 384–322 BC) was an Ancient Greek philosopher and polymath. His writings cover a broad range of subjects spanning the natural sciences, philosophy, linguistics, economics, politics, psychology, and the arts. As the founder of the Peripatetic school of philosophy in the Lyceum in Athens, he began the wider Aristotelian tradition that followed, which set the groundwork for the development of modern science.',
            'title': 'aristotle.txt',
            'version': 'v0',
            'chunk_order': 0,
            'document_id': 'c9bdbac7-0ea3-5c9e-b590-018bd09b127b',
            'extraction_id': '472d6921-b4cd-5514-bf62-90b05c9102cb',
            ...

Perform RAG

python -m r2r.examples.quickstart rag --query="who was aristotle?" --client-server-mode

Search Results:
{'vector_search_results': [
    {'id': '7ed3a01c-88dc-5a58-a68b-6e5d9f292df2',
    'score': 0.7802911996841491,
    'metadata': {'text': 'Aristotle[A] (Greek: Ἀριστοτέλης Aristotélēs, pronounced [aristotélɛːs]; 384–322 BC) was an Ancient Greek philosopher and polymath. His writings cover a broad range of subjects spanning the natural sciences, philosophy, linguistics, economics, politics, psychology, and the arts. As the founder of the Peripatetic schoo
    ...
Completion:
{'results': [
    {
        'id': 'chatcmpl-9eXL6sKWlUkP3f6QBnXvEiKkWKBK4',
        'choices': [
            {
                'finish_reason': 'stop',
                'index': 0,
                'logprobs': None,
                'message': {
                    'content': "Aristotle (384–322 BC) was an Ancient Greek philosopher and polymath whose writings covered a broad range of subjects including the natural sciences,
                    ...

Stream a RAG Response

python -m r2r.examples.quickstart rag --query="who was aristotle?" --client-server-mode --stream

<search>"{\"id\":\"004ae2e3-c042-50f2-8c03-d4c282651fba\",\"score\":0.7803140675 ...</search>
<completion>Aristotle was an Ancient Greek philosopher and polymath who lived from 384 to 322 BC [1]. He was born in Stagira, Chalcidi....</completion>

Hello r2r

Building with R2R is easy - see the hello_r2r example below:

from r2r import Document, GenerationConfig, R2R

app = R2R() # You may pass a custom configuration to `R2R`

app.ingest_documents(
    [
        Document(
            type="txt",
            data="John is a person that works at Google.",
            metadata={},
        )
    ]
)

rag_results = app.rag(
    "Who is john", GenerationConfig(model="gpt-3.5-turbo", temperature=0.0)
)
print(f"Search Results:\n{rag_results.search_results}")
print(f"Completion:\n{rag_results.completion}")

# RAG Results:
# Search Results:
# AggregateSearchResult(vector_search_results=[VectorSearchResult(id=2d71e689-0a0e-5491-a50b-4ecb9494c832, score=0.6848798582029441, metadata={'text': 'John is a person that works at Google.', 'version': 'v0', 'chunk_order': 0, 'document_id': 'ed76b6ee-dd80-5172-9263-919d493b439a', 'extraction_id': '1ba494d7-cb2f-5f0e-9f64-76c31da11381', 'associatedQuery': 'Who is john'})], kg_search_results=None)
# Completion:
# ChatCompletion(id='chatcmpl-9g0HnjGjyWDLADe7E2EvLWa35cMkB', choices=[Choice(finish_reason='stop', index=0, logprobs=None, message=ChatCompletionMessage(content='John is a person that works at Google [1].', role='assistant', function_call=None, tool_calls=None))], created=1719797903, model='gpt-3.5-turbo-0125', object='chat.completion', service_tier=None, system_fingerprint=None, usage=CompletionUsage(completion_tokens=11, prompt_tokens=145, total_tokens=156))

R2R Dashboard

Interact with R2R using our open-source React+Next.js dashboard. Check out the Dashboard Cookbook to get started!

Community and Support

• Discord: Chat live with maintainers and community members
• Github Issues: Report bugs and request features

Explore our R2R Docs for tutorials and cookbooks on various R2R features and integrations, including:

RAG Cookbooks

• Multiple LLMs: A simple cookbook showing how R2R supports multiple LLMs.
• Hybrid Search: A brief introduction to running hybrid search with R2R.
• Multimodal RAG: A cookbook on multimodal RAG with R2R.
• Knowledge Graphs: A walkthrough of automatic knowledge graph generation with R2R.
• Local RAG: A quick cookbook demonstration of how to run R2R with local LLMs.
• Reranking: A short guide on how to apply reranking to R2R results.

App Features

• Client-Server: An extension of the basic R2R Quickstart with client-server interactions.
• Document Management: A cookbook showing how to manage your documents with R2R.
• Analytics & Observability: A cookbook showing R2Rs end to end logging and analytics.
• Dashboard: A how-to guide on connecting with the R2R Dashboard.

Contributing

We welcome contributions of all sizes! Here's how you can help:

• Open a PR for new features, improvements, or better documentation.
• Submit a feature request or bug report

Our Contributors