r3con
Context representation for large-scale reasoning with smaller, cheaper models.
Ask a question whose evidence is scattered across many documents. r3con builds a
task-specific representation of the context, then reasons over it to produce an answer.
App
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 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
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. A directory or a
quoted glob reads only files inside that directory, or the glob's part before its first
wildcard, and logs and skips a link that points outside it; a file you name is read as
named.
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 reads PDF and Word (.docx) files, and text files such as .txt,
.md, .csv, .json, .html and .xml, and skips a folder's hidden files and folders;
a glob's wildcards skip them too, as in the shell.
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 another question over the same run, r3con.ask runs only the reasoning step
again:
other = r3con.ask(result, "Which supplier delivered on time most often?")
print(other)
Pass cancel=threading.Event() to run or ask and set it to stop: no new model call is
sent and it raises r3con.Cancelled, keeping what it did. A call already sent, and
retries you set yourself (completion= or params), run their course.
Notebooks
The examples use five short memos arranged so that no single document contains the full answer:
examples/quickstart.ipynb— an end-to-end example.examples/provenance.ipynb— tracing an answer back to the documents and relevance snippets it came from.examples/options.ipynb— models, relevance rounds, the reasoning path, generation parameters, run configuration, custom connections, and artifact paths.examples/vllm.ipynb— using a self-hosted vLLM endpoint.
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 relevance snippet 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.
API keys a provider's error echoes are masked before r3con writes or logs them; a
completion= wrapper that adds its own key registers 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.6.3
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.3.tar.gz | 193.0 kB | With provenance | Details for r3context-0.6.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| r3context-0.6.3-py3-none-any.whl | Python 3 | none | any | Details for r3context-0.6.3-py3-none-any.whl |
Total release size: 432.4 kB
Release files / r3context-0.6.3.tar.gz
| Download URL | r3context-0.6.3.tar.gz |
|---|---|
| Size | 193.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c7ee570cb50a9cd04dc5a4dd1d7b21a6fbfedbffc417e33cdd0f1091c8cdf271
|
|
BLAKE2b-256 checksum How to use checksums |
b9fbc71d4abbbadda859ad0659b643419afd1bb0c3750710e349e7a54c3889dd
|
| 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 31, 2026.
Transparency logRelease files / r3context-0.6.3-py3-none-any.whl
| Download URL | r3context-0.6.3-py3-none-any.whl |
|---|---|
| Size | 239.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4228c6b32f760581738557ff3bf592e1d9d45a686f446b0a4b650195d777ecca
|
|
BLAKE2b-256 checksum How to use checksums |
a0854046e4ebd13b63504f8c48022df22b4518113eabb23007bf414db18b9ab4
|
| 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 31, 2026.
Transparency logSecurity for r3context 0.6.3
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.3.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 31, 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.