r3con
Context representation for large-scale reasoning with smaller, cheaper models.
Ask a question whose evidence is spread across many documents. r3con finds and
organizes the relevant information, then reasons over it to produce an answer.
App
First install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Run r3con in your browser:
uv tool install "r3context[app]"
r3con app
Library
Install
pip install r3context
Or uv add r3context.
Set the API key(s) for the AI provider(s) you use:
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
You can also put them in a .env file in your working directory.
Command line
Ask a question about documents in a folder:
r3con run "Which supplier missed the most delivery windows?" ./reports \
--model openai/gpt-6-luna
./reports is the folder containing your documents. --model selects the AI
model to use.
You can use any model supported by LiteLLM, for example:
anthropic/claude-sonnet-5-5
gemini/gemini-3.8-flash
hosted_vllm/Qwen/Qwen3.5-35B-A3B
The default is openai/gpt-6-luna.
You can read an entire folder, select files using glob patterns, or specify
individual files. A glob pattern uses * to match filenames and ** to
include subfolders.
# All supported files in reports and its subfolders
r3con run "Who approved the Q3 overspend?" ./reports
# Only PDF files directly inside reports
r3con run "Who approved the Q3 overspend?" "./reports/*.pdf"
# PDF files inside reports and its subfolders
r3con run "Who approved the Q3 overspend?" "./reports/**/*.pdf"
# Only these three files
r3con run "Who approved the Q3 overspend?" q1.md q2.md q3.md
Keep glob patterns in quotes, as shown above. When reading a folder or using a glob pattern, r3con skips links to files outside the selected folder. Individual files can be specified directly.
Python
Load documents from a folder, glob pattern, or list of files:
from r3con import r3con
docs = r3con.read_documents("./reports")
result = r3con.run(
"Which supplier missed the most delivery windows?",
docs,
)
print(result) # "Ardent Logistics missed the most delivery windows: 8 in total."
read_documents supports PDF, Word (.docx), .txt, .md, .csv, .json,
.html, and .xml files. It skips hidden files and folders when reading
directories or using glob patterns.
It returns each document's text along with its filename. If a file is inside
a subfolder, its name includes that subfolder. For example, a file at reports/q3/ardent.pdf is named q3/ardent.pdf.
Here, q3 is simply the subfolder name, and ardent.pdf is the filename.
If your documents are already stored as text in Python, pass them directly without reading files:
result = r3con.run(
"Which supplier missed the most delivery windows?",
[doc_a, doc_b, doc_c],
)
You can provide documents as a list:
documents = [doc_a, doc_b, doc_c]
Or give them names:
documents = {
"report_a": doc_a,
"report_b": doc_b,
"report_c": doc_c,
}
Re-use Representation
To ask another question without repeating the earlier processing, use
r3con.ask:
other = r3con.ask(result, "Which supplier delivered on time most often?")
print(other)
This reuses the information organized during the first run and only repeats the final reasoning step.
Provenance
result.provenance["quotes"] lists the sentences the answer is based on.
Each has the document's name, the quoted text, and its start and end
characters in that document:
quote = result.provenance["quotes"][0]
print(quote["name"], quote["text"]) # q3/ardent.pdf Ardent missed 8 delivery windows.
examples/provenance.ipynb
shows the rest of the provenance.
Notebooks
The examples use five short memos, with the information spread across them so no single document contains the complete answer:
examples/quickstart.ipynb— a complete example of using r3con.examples/provenance.ipynb— checking the original sentences, snippets, and records behind an answer.examples/options.ipynb— configuring models, relevance rounds, reasoning, generation settings, custom connections, and saved files.examples/vllm.ipynb— using an AI model hosted on your own vLLM server.
Output
r3con.run(...) returns the answer and the information created during the run:
result.answer # Final answer
result.relevant_context # Relevant text found in the documents
result.structured_context # Information extracted and organized from the documents
result.provenance # What the answer is based on (see Provenance above)
result.run_dir # Folder where this run's files are saved
Run artifacts
Every run saves its results and processing records in a folder under ./logs.
logs/<timestamp>_<hex>/ <- result.run_dir
├── ids.json <- each document's ID
├── names.json <- each document's filename
├── events.jsonl <- when each processing step started and finished
├── splits.json <- how documents were split, if necessary
├── relevance/
│ ├── result.json <- relevant text and supporting quotes
│ └── calls.json <- AI requests made during relevance checking
├── structuring/
│ ├── schema/
│ │ ├── result.json <- structure created for organizing information
│ │ ├── calls.json <- AI requests
│ │ └── transcript.yaml <- record of the process
│ └── parsing/
│ ├── result.json <- information extracted from documents
│ └── calls.json <- AI requests
├── reasoning/
│ ├── result.json <- final answer
│ ├── calls.json <- AI requests
│ └── transcript.yaml <- record of the reasoning process
└── asks/<folder>/ <- saved results for each additional question
Evaluation
For benchmark results, comparisons with other methods, and evaluation code, see r3con-evaluation.
License
MIT — see LICENSE.
src/r3con/runtime/python_executor.py includes modified code from
smolagents, licensed under
Apache-2.0 and © HuggingFace Inc.
See THIRD-PARTY-NOTICES.
Metadata
Release files for r3context 0.6.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| r3context-0.6.10.tar.gz | 230.0 kB | With provenance | Details for r3context-0.6.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| r3context-0.6.10-py3-none-any.whl | Python 3 | none | any | Details for r3context-0.6.10-py3-none-any.whl |
Total release size: 523.4 kB
Release files / r3context-0.6.10.tar.gz
| Download URL | r3context-0.6.10.tar.gz |
|---|---|
| Size | 230.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c819074d1caad879d839a23270eb990ccba4ce163f6766ab92a69250e65b2f3
|
|
BLAKE2b-256 checksum How to use checksums |
08bc08026f6bcff042f73a4bafca857a6d3598c75937b3c932c2f59c2b9179d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / r3context-0.6.10-py3-none-any.whl
| Download URL | r3context-0.6.10-py3-none-any.whl |
|---|---|
| Size | 293.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e6dfd27f58111261b841328b85e8089b3b057f1c3f44182875a6250350bcc770
|
|
BLAKE2b-256 checksum How to use checksums |
0fb12526d5e597cd33fb69dbcce987dd4b2a48bfbadbbcee6d481640039753c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for r3context 0.6.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for r3context-0.6.10.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.