This basic quickstart shows how to:
  1. Ingest files into your R2R system
  2. Search over ingested files
  3. Request or stream a RAG (Retrieval-Augmented Generation) response
  4. Use the RAG Agent for more complex, interactive queries
Be sure to complete the installation instructions before continuing with this guide. If you prefer to dive straight into the API details, select a choice from below:

API Reference

Python SDK

Javascript SDK

​
Getting started

Start by checking that you have correctly deployed your R2R instance locally: 
curl http://localhost:7272/v2/health
# {"results":{"response":"ok"}}
SciPhi Cloud includes a generous free tier and is the quickest way to get up and running with R2R. Check out the documentation here to skip the local installation!

​
Ingesting file(s) and directories

The remainder of this quickstart will proceed with CLI commands, but all of these commands are easily reproduced inside of the Javascript or Python SDK. Ingest your selected files or directories: 
r2r ingest-files --file-paths /path/to/your_file_1 /path/to/your_dir_1 ...
For testing: Use the sample file(s) included inside the R2R project: 
r2r ingest-sample-file
# or r2r ingest-sample-files for multi-ingestion
Example output: 
[{'message': 'Ingestion task queued successfully.', 'task_id': '2b16bb55-4f47-4e66-a6bd-da9e215b9793', 'document_id': '9fbe403b-c11c-5aae-8ade-ef22980c3ad1'}]
When no document ID(s) are provided to the ingest_files endpoint, a unique document ID is automatically generated for each ingested document from the input filepath and user id.
We can monitor the ingestion status by querying the documents overview endpoint: 
watch -n 1 r2r documents-overview
Example output: 
{
    'id': '9fbe403b-c11c-5aae-8ade-ef22980c3ad1',
    'title': 'aristotle.txt',
    'user_id': '2acb499e-8428-543b-bd85-0d9098718220',
    ...
    'ingestion_status': 'parsing',
    ...
}
... within 10s ...
{
    'id': '9fbe403b-c11c-5aae-8ade-ef22980c3ad1',
    ...
    'ingestion_status': 'success',
    ...
}
Ingestion is complete when all documents are in a success or failed state. Perform a search query: 
r2r search --query="who was aristotle?"
The search query will use basic similarity search to find the most relevant documents. You can use advanced search methods like hybrid search or knowledge graph search depending on your use case. Example output: 
{'results': {'vector_search_results': [
    {
        'fragment_id': '34c32587-e2c9-529f-b0a7-884e9a3c3b2e',
        'extraction_id': '8edf5123-0a5c-568c-bf97-654b6adaf8dc',
        'document_id': '9fbe403b-c11c-5aae-8ade-ef22980c3ad1',
        'user_id': '2acb499e-8428-543b-bd85-0d9098718220',
        'collection_ids': [],
        'score': 0.780314067545999,
        '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.',
        'metadata': {
            'title': 'aristotle.txt',
            'version': 'v0',
            'chunk_order': 0,
            ...

​
RAG Response

Generate a RAG response: 
r2r rag --query="who was aristotle?" --use-hybrid-search
Example output: 
Search Results:
{'vector_search_results': ... }
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

Stream a RAG response: 
r2r rag --query="who was aristotle?" --stream --use-hybrid-search
Example output (streamed): 
<search>"{\"fragment_id\":\"34c32587-e2c9-52.....}"</search>
<completion>Aristotle (384–322 BC) was an Ancient Greek philosopher ... </completion>

​
Using the RAG Agent

The RAG Agent provides a more interactive and intelligent way to query your knowledge base. It can formulate its own questions, search for information, and provide informed responses based on the retrieved context.

​
Basic RAG Agent Usage

Here’s how to use the RAG Agent for a simple query: 
from r2r import R2RClient

client = R2RClient("http://localhost:7272")
# when using auth, do client.login(...)

messages = [
    {"role": "user", "content": "What was Aristotle's main contribution to philosophy?"},
    {"role": "assistant", "content": "Aristotle made numerous significant contributions to philosophy, but one of his main contributions was in the field of logic and reasoning. He developed a system of formal logic, which is considered the first comprehensive system of its kind in Western philosophy. This system, often referred to as Aristotelian logic or term logic, provided a framework for deductive reasoning and laid the groundwork for scientific thinking."},
    {"role": "user", "content": "Can you elaborate on how this influenced later thinkers?"}
]

result = client.agent(
    messages=messages,
    vector_search_settings={"use_hybrid_search":True},
    rag_generation_config={"model": "openai/gpt-4o", "temperature": 0.7}
)
print(result)