Quickstart

Getting started with R2R is easy.

1

Create an Account

Create an account with SciPhi Cloud. It’s free!

For those interested in deploying R2R locally, please refer here.

2

Install the SDK

R2R offers Python and JavaScript SDKs to interact with.

1pip install r2r
3

Environment

After signing into SciPhi Cloud, navigate to the homepage and click Create New Key (for the self-hosted quickstart, refer here): API Key

Next, set your local environment variable R2R_API_KEY. Be sure to include the entire API key `pk_...sk_...`. Alternatively, you may login directly with the client.

4

Client

1# export R2R_API_KEY=...
2from r2r import R2RClient
3
4client = R2RClient() # can set remote w/ R2RClient(base_url=...)
5
6# or, alternatively, client.users.login("[email protected]", "my_strong_password")
5

Ingesting files

When you ingest files into R2R, the server accepts the task, processes and chunks the file, and generates a summary of the document.

1client.documents.create_sample(hi_res=True)
2# to ingest your own document, client.documents.create(file_path="/path/to/file")

Example output:

IngestionResponse(message='Document created and ingested successfully.', task_id=None, document_id=UUID('e43864f5-a36f-548e-aacd-6f8d48b30c7f'))
6

Getting file status

After file ingestion is complete, you can check the status of your documents by listing them.

1client.documents.list()

Example output:

[
DocumentResponse(
id=UUID('e43864f5-a36f-548e-aacd-6f8d48b30c7f'),
collection_ids=[UUID('122fdf6a-e116-546b-a8f6-e4cb2e2c0a09')],
owner_id=UUID('2acb499e-8428-543b-bd85-0d9098718220'),
document_type=<DocumentType.PDF: 'pdf'>,
metadata={'title': 'DeepSeek_R1.pdf', 'version': 'v0'},
version='v0',
size_in_bytes=1768572,
ingestion_status=<IngestionStatus.SUCCESS: 'success'>,
extraction_status=<GraphExtractionStatus.PENDING: 'pending'>,
created_at=datetime.datetime(2025, 2, 8, 3, 31, 39, 126759, tzinfo=TzInfo(UTC)),
updated_at=datetime.datetime(2025, 2, 8, 3, 31, 39, 160114, tzinfo=TzInfo(UTC)),
ingestion_attempt_number=None,
summary="The document contains a comprehensive overview of DeepSeek-R1, a series of reasoning models developed by DeepSeek-AI, which includes DeepSeek-R1-Zero and DeepSeek-R1. DeepSeek-R1-Zero utilizes large-scale reinforcement learning (RL) without supervised fine-tuning, showcasing impressive reasoning capabilities but facing challenges like readability and language mixing. To enhance performance, DeepSeek-R1 incorporates multi-stage training and cold-start data, achieving results comparable to OpenAI's models on various reasoning tasks. The document details the models' training processes, evaluation results across multiple benchmarks, and the introduction of distilled models that maintain reasoning capabilities while being smaller and more efficient. It also discusses the limitations of current models, such as language mixing and sensitivity to prompts, and outlines future research directions to improve general capabilities and efficiency in software engineering tasks. The findings emphasize the potential of RL in developing reasoning abilities in large language models and the effectiveness of distillation techniques for smaller models.", summary_embedding=None, total_tokens=29673)] total_entries=1
), ...
]
8

RAG

Generate a RAG response:

1client.retrieval.rag(
2 query="What is DeepSeek R1?",
3)

Example output:

RAGResponse(
generated_answer='DeepSeek-R1 is a model that demonstrates impressive performance across various tasks, leveraging reinforcement learning (RL) and supervised fine-tuning (SFT) to enhance its capabilities. It excels in writing tasks, open-domain question answering, and benchmarks like IF-Eval, AlpacaEval2.0, and ArenaHard [1], [2]. DeepSeek-R1 outperforms its predecessor, DeepSeek-V3, in several areas, showcasing its strengths in reasoning and generalization across diverse domains [1]. It also achieves competitive results on factual benchmarks like SimpleQA, although it performs worse on the Chinese SimpleQA benchmark due to safety RL constraints [2]. Additionally, DeepSeek-R1 is involved in distillation processes to transfer its reasoning capabilities to smaller models, which perform exceptionally well on benchmarks [4], [6]. The model is optimized for English and Chinese, with plans to address language mixing issues in future updates [8].',
search_results=AggregateSearchResult(
chunk_search_results=[ChunkSearchResult(score=0.643, text=Document Title: DeepSeek_R1.pdf ...)]
),
citations=[Citation(id='cit_3a35e39', object='citation', payload=ChunkSearchResult(score=0.676, text=Document Title: DeepSeek_R1.pdf\n\nText: However, DeepSeek-R1-Zero encounters challenges such as poor readability, and language mixing. To address these issues and further enhance reasoning performance, we introduce DeepSeek-R1, which incorporates a small amount of cold-start data and a multi-stage training pipeline. Specifically, we begin by collecting thousands of cold-start data to fine-tune the DeepSeek-V3-Base model. Following this, we perform reasoning-oriented RL like DeepSeek-R1-Zero. Upon nearing convergence in the RL process, we create new SFT data through rejection sampling on the RL checkpoint, combined with supervised data from DeepSeek-V3 in domains such as writing, factual QA, and self-cognition, and then retrain the DeepSeek-V3-Base model. After fine-tuning with the new data, the checkpoint undergoes an additional RL process, taking into account prompts from all scenarios. After these steps, we obtained a checkpoint referred to as DeepSeek-R1, which achieves performance on par with OpenAI-o1-1217.)), Citation(id='cit_ec89403', object='citation', payload=ChunkSearchResult(score=0.664, text=Document Title: DeepSeek_R1.pdf\n\nText: - We introduce our pipeline to develop DeepSeek-R1. The pipeline incorporates two RL stages aimed at discovering improved reasoning patterns and aligning with human preferences, as well as two SFT stages that serve as the seed for the model's reasoning and non-reasoning capabilities. We believe the pipeline will benefit the industry by creating better models.)), ...],
metadata={'id': 'chatcmpl-B0BaZ0vwIa58deI0k8NIuH6pBhngw', 'choices': [{'finish_reason': 'stop', 'index': 0, 'logprobs': None, 'message': {'refusal': None, 'role': 'assistant', 'audio': None, 'function_call': None, 'tool_calls': None}}], 'created': 1739384247, 'model': 'gpt-4o-2024-08-06', 'object': 'chat.completion', 'service_tier': 'default', 'system_fingerprint': 'fp_4691090a87', ...}
)
9

Streaming RAG

Generate a streaming RAG response:

1from r2r import (
2 CitationEvent,
3 FinalAnswerEvent,
4 MessageEvent,
5 SearchResultsEvent,
6 R2RClient,
7)
8
9
10result_stream = client.retrieval.rag(
11 query="What is DeepSeek R1?",
12 search_settings={"limit": 25},
13 rag_generation_config={"stream": True},
14)
15
16# can also do a switch on `type` field
17for event in result_stream:
18 if isinstance(event, SearchResultsEvent):
19 print("Search results:", event.data)
20 elif isinstance(event, MessageEvent):
21 print("Partial message:", event.data.delta)
22 elif isinstance(event, CitationEvent):
23 print("New citation detected:", event.data)
24 elif isinstance(event, FinalAnswerEvent):
25 print("Final answer:", event.data.generated_answer)

Example output:

Search results: id='run_1' object='rag.search_results' data={'chunk_search_results': [{'id': '1e40ee7e-2eef-524f-b5c6-1a1910e73ccc', 'document_id': '652075c0-3a43-519f-9625-f581e7605bc5', 'owner_id': '2acb499e-8428-543b-bd85-0d9098718220', 'collection_ids': ['122fdf6a-e116-546b-a8f6-e4cb2e2c0a09'], 'score': 0.7945216641038179, 'text': 'data, achieving strong performance across various tasks. DeepSeek-R1 is more powerful,\nleveraging cold-start data alongside iterative RL fine-tuning. Ultimately ...
...
Partial message: {'content': [MessageDelta(type='text', text={'value': 'Deep', 'annotations': []})]}
Partial message: {'content': [MessageDelta(type='text', text={'value': 'Seek', 'annotations': []})]}
Partial message: {'content': [MessageDelta(type='text', text={'value': '-R', 'annotations': []})]}
...
New Citation Detected: 'cit_3a35e39'
...
Final answer: DeepSeek-R1 is a large language model developed by the DeepSeek-AI research team. It is a reasoning model that has been trained using multi-stage training and cold-start data before reinforcement learning (RL). The model demonstrates superior performance on various benchmarks, including MMLU, MMLU-Pro, GPQA Diamond, and FRAMES, particularly in STEM-related questions. ...
10

Streaming Agentic RAG

R2R offers a powerful agentic retrieval mode that performs in-depth analysis of documents through iterative research and reasoning. This mode can leverage a variety of tools to thoroughly investigate your data and the web:

1from r2r import (
2 ThinkingEvent,
3 ToolCallEvent,
4 ToolResultEvent,
5 CitationEvent,
6 FinalAnswerEvent,
7 MessageEvent,
8 R2RClient,
9)
10
11results = client.retrieval.agent(
12 message={"role": "user", "content": "What does deepseek r1 imply for the future of AI?"},
13 rag_generation_config={
14 "model": "anthropic/claude-3-7-sonnet-20250219",
15 "extended_thinking": True,
16 "thinking_budget": 4096,
17 "temperature": 1,
18 "top_p": None,
19 "max_tokens_to_sample": 16000,
20 "stream": True
21 },
22)
23
24# Process the streaming events
25for event in results:
26 if isinstance(event, ThinkingEvent):
27 print(f"🧠 Thinking: {event.data.delta.content[0].payload.value}")
28 elif isinstance(event, ToolCallEvent):
29 print(f"🔧 Tool call: {event.data.name}({event.data.arguments})")
30 elif isinstance(event, ToolResultEvent):
31 print(f"📊 Tool result: {event.data.content[:60]}...")
32 elif isinstance(event, CitationEvent):
33 print(f"📑 Citation: {event.data}")
34 elif isinstance(event, MessageEvent):
35 print(f"💬 Message: {event.data.delta.content[0].payload.value}")
36 elif isinstance(event, FinalAnswerEvent):
37 print(f"✅ Final answer: {event.data.generated_answer[:100]}...")
38 print(f" Citations: {len(event.data.citations)} sources referenced")

Example of streaming output:

🧠 Thinking: Analyzing the query about DeepSeek R1 implications...
🔧 Tool call: search_file_knowledge({"query":"DeepSeek R1 capabilities advancements"})
📊 Tool result: DeepSeek-R1 is a reasoning-focused LLM that uses reinforcement learning...
🧠 Thinking: The search provides valuable information about DeepSeek R1's capabilities
🧠 Thinking: Need more specific information about its performance in reasoning tasks
🔧 Tool call: search_file_knowledge({"query":"DeepSeek R1 reasoning benchmarks performance"})
📊 Tool result: DeepSeek-R1 achieves strong results on reasoning benchmarks including MMLU...
📑 Citation: cit_54c45c8
🧠 Thinking: Now I need to understand the implications for AI development
🔧 Tool call: web_search({"query":"AI reasoning capabilities future development"})
📊 Tool result: Advanced reasoning capabilities are considered a key milestone toward...
📑 Citation: cit_d1152e7
💬 Message: DeepSeek-R1 has several important implications for the future of AI development:
💬 Message: 1. **Reinforcement Learning as a Key Approach**: DeepSeek-R1's success demonstrates...
📑 Citation: cit_eb5ba04
💬 Message: 2. **Efficiency Through Distillation**: The model shows that reasoning capabilities...
✅ Final answer: DeepSeek-R1 has several important implications for the future of AI development: 1. Reinforcement Learning...
Citations: 3 sources referenced

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.

Users and Collections

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. Further, collections exist to enable efficient access control and organization of users and documents.

Next Steps

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