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, in real time: a folder of memos is dropped on the panel and shows as a file tree, then a loose memo is dropped beside it; a run on them builds its representation, then lights the answer's provenance through the tree to the four memos it used, leaving the other two grey; the sites folder, closed, counts its sources, clicking one of those memos in the panel opens it with the sentences the answer quotes marked, and the panel's answer and summary nodes open their popups

App

Mac (Apple silicon)

Direct

Download R3Con, double-click it, and drag R3Con to Applications.

The R3Con disk image window: drag R3Con onto the Applications folder

Brew

brew install michaeltheologitis/r3con/r3con

Either way, R3Con updates itself: R3Con → Check for Updates…

Any computer

First install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Run R3Con in your browser:

uv tool install --python 3.15 "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.

Add --evidence-level document to skip quoting sentences: the answer's provenance then lists only its documents.

Carry On a Stopped Run

If a run fails or you stop it partway, it prints the command that carries it on:

r3con resume logs/20261105T173546Z_bb4f0c37 ./reports

Give it the same sources the run read, in the same order. It reuses what the run finished and only does the rest.

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, .htm, and .xml files; Word files and web pages are read as Markdown, a web page under the title, author, dates and address its metadata gives. 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,
}

To skip quoting, run at the document level:

result = r3con.run(
    "Which supplier missed the most delivery windows?",
    docs,
    evidence_level="document",
)

R3Con then doesn't ask the model for quotes, so the provenance lists only documents (result.provenance["documents"]), not their sentences.

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.

Resume a Run

If a run fails or is stopped partway, for example by a rate limit or a lost connection, r3con.resume carries it on from where it was, in the same folder. Give it the run's folder (the error names it) and the same documents:

result = r3con.resume("logs/20261105T173546Z_bb4f0c37", docs)

It checks that the documents are the run's, reuses each result the run had saved, document by document, and computes only what is missing, then the final reasoning step.

Provenance

result.provenance["documents"] lists the documents behind the relevance snippets the answer cites, directly or through the parsed records it cites, each with its document ID and name.

result.provenance["quotes"] lists the sentences the answer is based on. Each has the document's name, text as the AI model quoted it, and document_text, the document's own words, from its start to its end character in that document. The two differ when the model changed the wording. match says how the sentence was found: exact, normalized (only spacing, case, quotation marks, dashes or markup differ), elided (the model wrote ... for words it left out) or fuzzy (some words differ), and a fuzzy one has a score out of 100:

quote = result.provenance["quotes"][0]
print(quote["name"], quote["match"], quote["score"])  # q3/ardent.pdf fuzzy 94.1
print(quote["text"])  # Ardent missed 8 delivery windows, mainly in August.
print(quote["document_text"])  # Ardent missed 8 delivery windows, mostly in August.

With evidence_level="document", quotes is empty.

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
├── documents.json               <- each document's SHA-256 (UTF-8, lone surrogates passed through)
├── 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.33

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.33
File Size Uploaded Provenance Actions
r3context-0.6.33.tar.gz 296.3 kB With provenance Details for r3context-0.6.33.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for r3context 0.6.33
File Interpreter ABI Platform Actions
r3context-0.6.33-py3-none-any.whl Python 3 none any Details for r3context-0.6.33-py3-none-any.whl

Total release size: 662.2 kB

Release files / r3context-0.6.33.tar.gz

Download URL r3context-0.6.33.tar.gz
Size 296.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c5970733658982511c1d0048e8d7ff9152d2f18baafc4f6c591d71f87edd89e2
BLAKE2b-256 checksum
How to use checksums
e765a7e6462c9f590f410b6dfb2b8dcb26c6ad8a65afa25103d08fdb281ba1c9
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 16, 2026.

Transparency log

Release files / r3context-0.6.33-py3-none-any.whl

Download URL r3context-0.6.33-py3-none-any.whl
Size 365.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7131299ce10db66be2099077af3eb85fc4501f28feb80d13750aafc46b67258b
BLAKE2b-256 checksum
How to use checksums
befdd63acca93b4f903c511b8f53885dae7c46b0c6e536ae7d3802767a9985be
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 16, 2026.

Transparency log

Security for r3context 0.6.33

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