Skip to main content

r3con

arXiv Python License

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.

r3con app: a run on six memos builds its representation, then lights the answer's provenance back to the four memos it used; the sentences it quotes unfold under the answer, a file's name there opens its memo with the same sentences marked, and the panel's answer and summary nodes open their popups

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:

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)

Source distribution for r3context 0.6.10
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)

Table of built distributions (wheels) for r3context 0.6.10
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.6.10 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page