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, 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 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 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.

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

$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:

1from r2r import R2RClient
2
3client = R2RClient("http://localhost:7272")
4# when using auth, do client.login(...)
5
6messages = [
7    {"role": "user", "content": "What was Aristotle's main contribution to philosophy?"},
8    {"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."},
9    {"role": "user", "content": "Can you elaborate on how this influenced later thinkers?"}
10]
11
12result = client.agent(
13    messages=messages,
14    vector_search_settings={"use_hybrid_search":True},
15    rag_generation_config={"model": "openai/gpt-4o", "temperature": 0.7}
16)
17print(result)

Additional Features

R2R offers additional features to enhance your document management and user experience:

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:

If you have any questions or need further assistance, please refer to the R2R documentation or reach out to our support team.