Skip to main content

r3con

arXiv Python License

Context representation for large-scale reasoning.

Ask a question whose evidence is scattered across many documents. r3con builds a task-specific representation of that context, then reasons over it to produce an answer.

How r3con works

Install

pip install r3context

Set the API key(s) for the 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.

Usage

Command line

Pass a directory, glob, or list of files:

r3con run "Which supplier missed the most delivery windows?" ./reports \
  --model openai/gpt-6-luna

--model accepts any LiteLLM model string, 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.

Directories are searched recursively. You can also use glob patterns or pass files directly:

r3con run "Who approved the Q3 overspend?" "./reports/*.pdf"
r3con run "Who approved the Q3 overspend?" "./reports/**/*.pdf"
r3con run "Who approved the Q3 overspend?" q1.md q2.md q3.md

Quote glob patterns so your shell passes them to r3con unchanged.

Python

Load documents from a directory, glob, 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 .txt, .md, .csv, .json, .html, .xml, .pdf, and other common text formats.

If you already have the documents in memory, pass them directly:

result = r3con.run(
    "Which supplier missed the most delivery windows?",
    [doc_a, doc_b, doc_c],
)

documents is simply a list of strings, one per document.

To ask a new question over the same run, r3con.ask reuses what the run built and runs only the reasoning step, at a fraction of a run's cost:

other = r3con.ask(result, "Which supplier delivered on time most often?")
print(other)

To stop a run from another thread, pass cancel=threading.Event() and set it: no new model call is sent and the run raises r3con.Cancelled, leaving what it did so far in its folder. What is already under way runs its course: a call already sent (so a run on its last call finishes normally), resends r3con doesn't make itself (a completion=, or retry settings in params), and a sandbox step. r3con.ask takes cancel too.

Notebooks

The examples use five short memos arranged so that no single document contains the full answer:

Output

r3con.run(...) returns a result object containing the final answer and the representation built during the run:

result.answer  # str       — final answer
result.relevant_context  # list[str] — final relevance snippets
result.structured_context  # dict      — structured representation
result.run_dir  # Path      — directory containing run artifacts

r3con also records provenance, how the answer, each summary and each parse came to be; see examples/provenance.ipynb.

Run artifacts

Every run writes each stage's output and model calls, failed ones included, with their tokens, cost, and any resends and the wait between them, to a folder under ./logs. An API key that a provider's error echoes is masked before r3con writes or logs it: the keys r3con sends, a litellm.Router's included, and the environment's. A completion= wrapper that adds a key of its own must register it with r3con.masking.register_key(key).

logs/<timestamp>_<hex>/          <- result.run_dir
├── ids.json                     <- each document's id
├── events.jsonl                 <- each stage's start and finish, as they happened
├── splits.json                  <- only when a document was read in parts
├── relevance/
│   ├── result.json              <- each round's snippets
│   └── calls.json
├── structuring/
│   ├── schema/
│   │   ├── result.json
│   │   ├── calls.json
│   │   └── transcript.yaml
│   └── parsing/
│       ├── result.json          <- the parsed records
│       └── calls.json
├── reasoning/
│   ├── result.json              <- the answer
│   ├── calls.json
│   └── transcript.yaml
└── asks/<folder>/               <- one per r3con.ask: manifest.json, events.jsonl and reasoning/

Evaluation

Paper: for benchmark results, baselines, and evaluation code, see r3con-evaluation.

License

MIT — see LICENSE.

src/r3con/runtime/python_executor.py contains a modified version of the sandboxed interpreter from smolagents, licensed under Apache-2.0 and © HuggingFace Inc. See NOTICE and LICENSE-APACHE-2.0.

Metadata

Release files for r3context 0.5.0

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.5.0
File Size Uploaded Provenance Actions
r3context-0.5.0.tar.gz 129.5 kB With provenance Details for r3context-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 304.8 kB

Release files / r3context-0.5.0.tar.gz

Download URL r3context-0.5.0.tar.gz
Size 129.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b5061e7ebfd5436fd7257cdfcaf03343d4ba147bd54fa9857346b286d4a95b8b
BLAKE2b-256 checksum
How to use checksums
79948a37e30b2eb0c91c340f38eb6ebb38ff509556d8d47f0f75aacb08cfec80
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 Oct 29, 2026.

Transparency log

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

Download URL r3context-0.5.0-py3-none-any.whl
Size 175.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cfdb9bf75271aa1693fe6f7be242ad31e052bccbe2a618afbfbbd7e0fc1d7891
BLAKE2b-256 checksum
How to use checksums
c2316666c80ce9e542113d38d05b2707cb27ffb59c2aa92408a0db34e54fd4c3
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 Oct 29, 2026.

Transparency log

Security for r3context 0.5.0

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.5.0.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 Oct 29, 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.5.0 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