Quickstart

Getting started with R2R

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, click below:

API & SDKs

Getting started

Start by checking that you have correctly deployed your R2R instance locally:

$curl http://localhost:7272/v3/health
># {"results":{"response":"ok"}}

SciPhi offers managed enterprise solutions for R2R. If you’re interested in a fully managed, scalable deployment of R2R for your organization, please contact their team at [email protected] for more information on enterprise offerings.

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 documents create --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 documents create-sample
># or r2r documents create-samples 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.

After successful ingestion, the documents overview endpoint will return output like so:

$r2r documents list

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',
    'created_at': '2024-12-02T22:55:38.701770Z'
    ...
    'summary': "The document contains an overview of Aristotle, an Ancient Greek philosopher and polymath who lived from 384 to 322 BC. It highlights his extensive contributions across various fields, including natural sciences, philosophy, and the arts, and notes his role as the founder of the Peripatetic school in Athens. The document discusses his early life, education under Plato, and his later work tutoring Alexander the Great. It emphasizes the lasting impact of Aristotle's teachings on medieval scholarship, logic, and ethics, as well as his influence on Judeo-Islamic and Christian thought throughout history. Despite only a fraction of his works surviving, his ideas continue to be relevant in contemporary philosophical discussions."    
    'ingestion_status': 'success',
    'extraction_status': 'pending',
    ...
}

Ingestion is complete when all documents are in a success or failed state.

Perform a search query:

$r2r retrieval 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 graph search depending on your use case.

Example output:

{'results':
    {'chunk_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 retrieval rag --query="who was aristotle?" --use-hybrid-search=True

Example output:

Search Results:
{'chunk_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 retrieval rag --query="who was aristotle?" --stream --use-hybrid-search=True

Example output (streamed):

<search>"{\"fragment_id\":\"34c32587-e2c9-52.....}"</search>
<completion>Aristotle (384–322 BC) was an Ancient Greek philosopher ... </completion>

Using the R2R RAG Agent

The RAG agent inside R2R 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:

1# Use the RAG assistant via the agent endpoint
2first_reply = client.retrieval.agent(
3    message={"role": "user", "content": "Who was aristotle?"},
4    search_settings={"limit": 5, "filters": {}},
5)
6print(first_reply)
7# {'results': {'messages': [
8#    {'role': 'function', 'content': 'Vector Search Results:\nSource [1]:\nAristotle[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.\nSource [2]:\nAristotle was revered among medieval Muslim scholars as "The First Teacher", and among medieval Christians like Thomas Aquinas as simply "The Philosopher", while the poet Dante called him "the master of those who know". His works contain the earliest known formal study of logic, and were studied by medieval scholars such as Peter Abelard and Jean Buridan. Aristotle\'s influence on logic continued well into the 19th century. In addition, his ethics, although always influential, gained renewed interest with the modern advent of virtue ethics.\nSource [3]:\nLittle is known about Aristotle\'s life. He was born in the city of Stagira in northern Greece during the Classical period. His father, Nicomachus, died when Aristotle was a child, and he was brought up by a guardian. At 17 or 18, he joined Plato\'s Academy in Athens and remained there until the age of 37 (c.\u2009347 BC). Shortly after Plato died, Aristotle left Athens and, at the request of Philip II of Macedon, tutored his son Alexander the Great beginning in 343 BC. He established a library in the Lyceum, which helped him to produce many of his hundreds of books on papyrus scrolls.\n\nThough Aristotle wrote many elegant treatises and dialogues for publication, only around a third of his original output has survived, none of it intended for publication. Aristotle provided a complex synthesis of the various philosophies existing prior to him. His teachings and methods of inquiry have had a significant impact across the world, and remain a subject of contemporary philosophical discussion.\nSource [4]:\nThough Aristotle wrote many elegant treatises and dialogues for publication, only around a third of his original output has survived, none of it intended for publication. Aristotle provided a complex synthesis of the various philosophies existing prior to him. His teachings and methods of inquiry have had a significant impact across the world, and remain a subject of contemporary philosophical discussion.\n\nAristotle\'s views profoundly shaped medieval scholarship. The influence of his physical science extended from late antiquity and the Early Middle Ages into the Renaissance, and was not replaced systematically until the Enlightenment and theories such as classical mechanics were developed. He influenced Judeo-Islamic philosophies during the Middle Ages, as well as Christian theology, especially the Neoplatonism of the Early Church and the scholastic tradition of the Catholic Church.\nKG Search Results:\nSource [5]:\nName: ARISTOTLE\nDescription: Aristotle was an Ancient Greek philosopher and polymath, founder of the Peripatetic school of philosophy in Athens, and a significant figure in the development of modern science.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [6]:\nName: THOMAS AQUINAS\nDescription: Thomas Aquinas was a medieval philosopher who revered Aristotle as "The Philosopher."\nMetadata:\n- associated_query: Who was Aristotle?\nSource [7]:\nName: PLATO\nDescription: Plato was a philosopher and the founder of the Academy in Athens, where Aristotle studied.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [8]:\nName: LYCEUM\nDescription: The Lyceum was the school founded by Aristotle in Athens, where he taught and established a library.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [9]:\nName: STAGIRA\nDescription: Stagira is the city in northern Greece where Aristotle was born.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [10]:\nRelationship: ARISTOTLE - Pioneer - LOGIC\nMetadata:\n- associated_query: Who was Aristotle?\nSource [11]:\nRelationship: THOMAS AQUINAS - Revered Figure - ARISTOTLE\nMetadata:\n- associated_query: Who was Aristotle?\nSource [12]:\nRelationship: ARISTOTLE - Birthplace - STAGIRA\nMetadata:\n- associated_query: Who was Aristotle?\nSource [13]:\nRelationship: ARISTOTLE - Student-Teacher - PLATO\nMetadata:\n- associated_query: Who was Aristotle?\nSource [14]:\nRelationship: DANTE - Revered Figure - ARISTOTLE\nMetadata:\n- associated_query: Who was Aristotle?\nSource [15]:\nName: Aristotle and His Legacy\nSummary: This community centers around Aristotle, a foundational figure in Western philosophy, and his profound influence on various intellectual traditions, including virtue ethics, logic, and medieval scholarship. Key figures such as Dante and Thomas Aquinas revered Aristotle, highlighting his enduring impact on philosophy and education.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [16]:\nName: Aristotle, Plato, and the Lyceum\nSummary: This community comprises key historical figures Aristotle and Plato, along with the educational institution Lyceum, which was founded by Aristotle. Their relationships highlight a foundational network in Western philosophy and education, emphasizing the influence of Plato on Aristotle\'s teachings and the establishment of the Lyceum.\nMetadata:\n- associated_query: Who was Aristotle?\nSource [17]:\nName: Aristotle, Philip II of Macedon, and Alexander the Great\nSummary: This community comprises key historical figures including Aristotle, Philip II of Macedon, and Alexander the Great, who are interconnected through a significant tutor-student relationship. Aristotle\'s role as the tutor of Alexander, at the behest of Philip II, highlights the profound influence of education on leadership and governance in ancient history.\nMetadata:\n- associated_query: Who was Aristotle?', 'name': 'search', 'function_call': None, 'tool_calls': None}, 
9#    {'role': 'assistant', 'content': 'Aristotle (384–322 BC) was an Ancient Greek philosopher and polymath whose work has had a profound and lasting impact on various fields of knowledge. Here are some key points about him:\n\n1. **Philosophical Contributions**: Aristotle\'s writings cover a broad range of subjects, including natural sciences, philosophy, linguistics, economics, politics, psychology, and the arts. He is known for founding the Peripatetic school of philosophy in the Lyceum in Athens, which laid the groundwork for the development of modern science [1].\n\n2. **Influence and Legacy**: Aristotle was highly revered among medieval Muslim scholars as "The First Teacher" and among medieval Christians like Thomas Aquinas as "The Philosopher." His works contain the earliest known formal study of logic, which continued to influence scholars well into the 19th century. His ethical theories have also gained renewed interest with the modern advent of virtue ethics [2].\n\n3. **Life and Education**: Born in Stagira, northern Greece, Aristotle joined Plato\'s Academy in Athens at the age of 17 or 18 and remained there until he was 37. After Plato\'s death, Aristotle left Athens and tutored Alexander the Great at the request of Philip II of Macedon. He later established a library in the Lyceum, which helped him produce many of his works [3].\n\n4. **Surviving Works**: Although Aristotle wrote many treatises and dialogues, only about a third of his original output has survived. His teachings provided a complex synthesis of various philosophies existing before him and have had a significant impact on subsequent intellectual traditions [4].\n\n5. **Impact on Medieval Scholarship**: Aristotle\'s views shaped medieval scholarship, influencing Judeo-Islamic philosophies and Christian theology, particularly the scholastic tradition of the Catholic Church. His influence extended from late antiquity through the Renaissance until the Enlightenment [4].\n\nAristotle\'s contributions to philosophy and science have made him one of the most influential figures in Western intellectual history.', 'name': None, 'function_call': None, 'tool_calls': None}], 'conversation_id': 'b9ec67cf-29ff-4bf4-8ac8-6dea1b19391b'}
10#  ]
11# }
12conversation_id = first_reply["results"]["conversation_id"]
13
14second_reply = client.retrieval.agent(
15    message={"role": "user", "content": "What were his contributions to philosophy?"},
16    search_settings={"limit": 5, "filters": {}},
17    conversation_id=conversation_id,
18)
19print(second_reply)
20# {
21#  'results': {'messages': [
22#    {'role': 'function', 'content': 'Vector Search Results:\nSource [1]:\nAristotle was revered among medieval Muslim scholars as "The First Teacher", and among medieval Christians like Thomas Aquinas as simply "The Philosopher", while the poet Dante called him "the master of those who know". His works contain the earliest known formal study of logic, and were studied by medieval scholars such as Peter Abelard and Jean Buridan. Aristotle\'s influence on logic continued well into the 19th century. In addition, his ethics, although always influential, gained renewed interest with the modern advent of virtue ethics.\nSource [2]:\nAristotle[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.\nSource [3]:\nThough Aristotle wrote many elegant treatises and dialogues for publication, only around a third of his original output has survived, none of it intended for publication. Aristotle provided a complex synthesis of the various philosophies existing prior to him. His teachings and methods of inquiry have had a significant impact across the world, and remain a subject of contemporary philosophical discussion.\n\nAristotle\'s views profoundly shaped medieval scholarship. The influence of his physical science extended from late antiquity and the Early Middle Ages into the Renaissance, and was not replaced systematically until the Enlightenment and theories such as classical mechanics were developed. He influenced Judeo-Islamic philosophies during the Middle Ages, as well as Christian theology, especially the Neoplatonism of the Early Church and the scholastic tradition of the Catholic Church.\nSource [4]:\nLittle is known about Aristotle\'s life. He was born in the city of Stagira in northern Greece during the Classical period. His father, Nicomachus, died when Aristotle was a child, and he was brought up by a guardian. At 17 or 18, he joined Plato\'s Academy in Athens and remained there until the age of 37 (c.\u2009347 BC). Shortly after Plato died, Aristotle left Athens and, at the request of Philip II of Macedon, tutored his son Alexander the Great beginning in 343 BC. He established a library in the Lyceum, which helped him to produce many of his hundreds of books on papyrus scrolls.\n\nThough Aristotle wrote many elegant treatises and dialogues for publication, only around a third of his original output has survived, none of it intended for publication. Aristotle provided a complex synthesis of the various philosophies existing prior to him. His teachings and methods of inquiry have had a significant impact across the world, and remain a subject of contemporary philosophical discussion.\nKG Search Results:\nSource [5]:\nName: ARISTOTLE\nDescription: Aristotle was an Ancient Greek philosopher and polymath, founder of the Peripatetic school of philosophy in Athens, and a significant figure in the development of modern science.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [6]:\nName: THOMAS AQUINAS\nDescription: Thomas Aquinas was a medieval philosopher who revered Aristotle as "The Philosopher."\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [7]:\nName: PLATO\nDescription: Plato was a philosopher and the founder of the Academy in Athens, where Aristotle studied.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [8]:\nName: ATHENS\nDescription: Athens is the city in Greece where Aristotle studied at Plato\'s Academy and later founded the Lyceum.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [9]:\nName: LYCEUM\nDescription: The Lyceum was the school founded by Aristotle in Athens, where he taught and established a library.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [10]:\nRelationship: ARISTOTLE - Influence - VIRTUE ETHICS\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [11]:\nRelationship: ARISTOTLE - Influence - MEDIEVAL SCHOLARSHIP\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [12]:\nRelationship: ARISTOTLE - Pioneer - LOGIC\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [13]:\nRelationship: THOMAS AQUINAS - Revered Figure - ARISTOTLE\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [14]:\nRelationship: ARISTOTLE - Associated With - ATHENS\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [15]:\nName: Aristotle and His Legacy\nSummary: This community centers around Aristotle, a foundational figure in Western philosophy, and his profound influence on various intellectual traditions, including virtue ethics, logic, and medieval scholarship. Key figures such as Dante and Thomas Aquinas revered Aristotle, highlighting his enduring impact on philosophy and education.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [16]:\nName: Aristotle, Plato, and the Lyceum\nSummary: This community comprises key historical figures Aristotle and Plato, along with the educational institution Lyceum, which was founded by Aristotle. Their relationships highlight a foundational network in Western philosophy and education, emphasizing the influence of Plato on Aristotle\'s teachings and the establishment of the Lyceum.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy\nSource [17]:\nName: Aristotle, Philip II of Macedon, and Alexander the Great\nSummary: This community comprises key historical figures including Aristotle, Philip II of Macedon, and Alexander the Great, who are interconnected through a significant tutor-student relationship. Aristotle\'s role as the tutor of Alexander, at the behest of Philip II, highlights the profound influence of education on leadership and governance in ancient history.\nMetadata:\n- associated_query: Aristotle\'s contributions to philosophy', 'name': 'search', 'function_call': None, 'tool_calls': None},
23#    {'role': 'assistant', 'content': 'Aristotle made numerous significant contributions to philosophy, many of which have had a lasting impact on various fields of study. Here are some of his key contributions:\n\n1. **Logic**: Aristotle is often credited with founding the field of formal logic. His work in this area, particularly the "Organon," laid the groundwork for the study of logic for centuries. His syllogistic method was the dominant form of logic until the 19th century [1][12].\n\n2. **Metaphysics**: In his work "Metaphysics," Aristotle explored the nature of reality, substance, and existence. He introduced concepts such as potentiality and actuality, which have been fundamental to subsequent metaphysical thought [1][3].\n\n3. **Ethics**: Aristotle\'s "Nicomachean Ethics" is one of the most influential works in moral philosophy. He introduced the concept of virtue ethics, which emphasizes the development of good character traits (virtues) as the basis for ethical behavior. This approach contrasts with other ethical theories that focus on rules or consequences [1][10].\n\n4. **Political Philosophy**: In "Politics," Aristotle examined various forms of government and their functions. He argued for a mixed government system and emphasized the importance of the middle class in achieving political stability. His ideas have influenced political theory throughout history [1][2].\n\n5. **Natural Sciences**: Aristotle made significant contributions to the natural sciences, including biology, zoology, and physics. His observations and classifications of living organisms were used as a reference for many centuries. Although some of his scientific theories were later disproven, his empirical approach laid the groundwork for future scientific inquiry [2][3].\n\n6. **Epistemology**: Aristotle\'s theory of knowledge emphasized empirical observation and logical reasoning. He believed that knowledge is derived from sensory experience and that the mind can abstract universal principles from particular instances [1][3].\n\n7. **Rhetoric and Poetics**: Aristotle\'s works "Rhetoric" and "Poetics" have been foundational texts in the study of communication and literary theory. In "Rhetoric," he analyzed the art of persuasion, while in "Poetics," he examined the principles of dramatic and literary composition [2][3].\n\nAristotle\'s comprehensive approach to philosophy and his method of systematic inquiry have made him one of the most influential figures in Western intellectual history. His ideas continue to be studied and debated in contemporary philosophical discussions.', 'name': None, 'function_call': None, 'tool_calls': None}], 'conversation_id': 'f737345d-3fca-4cce-b896-f61f229c410d'}
24#  ]
25# }

Additional Features

R2R offers the additional features below to enhance your document management and user experience.

Graphs

R2R provides powerful entity and relationshipo extraction capabilities that enhance document understanding and retrieval. These can leveraged to construct knowledge graphs inside R2R. The system can automatically identify entities, build relationships between them, and create enriched knowledge graphs from your document collection.

Knowledge Graphs

Automatically extract entities and relationships from documents to form knowledge graphs.

GraphRAG

Explore advanced techniques for utilizing graph-based retrieval in R2R.

User Authentication

R2R provides a complete set of user authentication and management features, allowing you to implement secure and feature-rich authentication systems or integrate with your preferred authentication provider.

User Auth Cookbook

Learn how to implement user registration, login, email verification, and more using R2R’s built-in authentication capabilities.

Auth Providers

Explore the available authentication provider options in R2R and how to integrate with your preferred provider.

Collections

Collections in R2R enable efficient access control and organization of users and documents. With collections, you can manage permissions and access at a group level.

Collections Cookbook

Discover how to create, manage, and utilize collections in R2R for granular access control and document organization.

Collection Permissions

Learn about best practices for implementing collection permissions and customizing access control in your R2R application.

Next Steps

Now that you have a basic understanding of R2R’s core features, you can explore more advanced topics: