Metadata-Version: 2.4
Name: hunter-rag
Version: 0.4.0b1
Summary: Agentic retrieval, the way a coding agent works a codebase — typed, addressable CDUs + Hunter, the agent that navigates them.
Author-email: Arc Intelligence <contact@arcintelligence.ai>
License-Expression: LicenseRef-Arc-Source-Available-1.0
Project-URL: Homepage, https://cdu.arcintelligence.ai
Project-URL: Source, https://github.com/arcintelligence/hunter-rag
Project-URL: Issues, https://github.com/arcintelligence/hunter-rag/issues
Project-URL: Changelog, https://github.com/arcintelligence/hunter-rag/blob/main/CHANGELOG.md
Keywords: rag,retrieval,agent,documents,llm,obsidian
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: openai
Requires-Dist: duckdb
Requires-Dist: pyyaml
Requires-Dist: beautifulsoup4
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: pymupdf4llm<1.0,>=0.3.4
Dynamic: license-file

<!-- readme: projection of canon.md · re-derived 2026-10-07 -->
# hunter-rag

Agentic retrieval, the way a coding agent works a codebase: documents become typed, addressable units, and an agent navigates them instead of searching chunks.

Coding agents didn't get good because someone built a better code search.
They got good because they stopped being *fed* context and started
*navigating* it — grep for the symbol, open the file, read the function,
jump to the caller. The filesystem gave them typed, addressable, inspectable
objects, and the loop let them decide what to look at next.

Documents never got that treatment. RAG pipelines embed fragments of a
document into vectors, retrieve the nearest few, and hope the answer survived
the chopping. The retrieval decision is made *before* the question is
understood, by a similarity function that has never seen a balance sheet
hold together.

**hunter-rag gives documents a filesystem.** A document is compiled into
**CDUs — Coherent Document Units**: sections, tables, equations, figures and
code blocks, each kept whole and given a stable address (`doc:type:elem`),
held in a queryable store. An agent navigates them in a loop: it orients,
finds, peeks before committing context, reads what it needs, and follows
the document's own references.

## See it

The offline walkthrough in this repository needs no API key. Abridged output:

```
$ uv run python examples/navigate.py
loaded sci_native_1304_5603: 29 CDUs

── open_document → element types
{'sections': 10, 'tables': 3, 'equations': 8, 'figures': 8, 'code_blocks': 0}

── find_units(element_type='table')
[{'unit_id': 'sci_native_1304_5603:table:tab_000', 'heading': 'Test of the model for SARS in 2003', …}, …]

── peek_unit(sci_native_1304_5603:table:tab_000)
{'unit_id': '…:table:tab_000', 'label': 'tab1', 'caption': 'Predicted number $H$ and date $D$ compared with …', …}

── get_neighbors(sci_native_1304_5603:table:tab_000)
{'scope': 'section', 'n_neighbors': 5, 'neighbors': [{'unit_id': '…:section:sec_008', 'heading': 'Test of the model for SARS in 2003', …}, …]}

Every id above is a stable citation target: doc:type:elem.
```

## What that buys

- **A table is a table.** It is never sliced into fixed-size fragments; an equation stays LaTeX, a figure keeps its caption.
- **No vector database in the critical path.** The agent sees the structure and chooses what to open.
- **Evidence you can resolve.** An answer's evidence is the set of units the agent read in full, each an address a program can open.
- **A trajectory you can debug.** Every call is recorded; a wrong answer shows the step that went wrong.
- **Your notes become a knowledge base.** In the full product, `hunterrag index ./vault` compiles a folder of markdown notes, an Obsidian vault included: every note becomes addressable units, frontmatter becomes queryable fields, and `[[wikilinks]]` (with `[[Note|alias]]` and `[[Note#Heading]]` forms) become links the agent follows the way it follows a figure reference. No embeddings, no server; incremental re-indexing.

Where it is not the better tool: on some prose and code questions, chunk retrieval does as well or better, and reading whole units can cost more tokens per question.

## What this repository is

The **reference implementation and home of the CDU paradigm**: the navigation
core (nine primitives), the CDU store, a minimal tool-use agent loop, and a
toy markdown ingester — small enough to read in an afternoon, offline-testable,
for research reproduction, teaching and protocol discussion. Issues and
discussions for the hunter-rag product live here too.

The **full product** — production ingestion, table operations with evidence
binding, the SQL query layer, corpus-level operations, vault indexing, the
`hunterrag` / `cdu` CLI — ships as the **`hunter-rag` package**.

## Try it

```bash
uv sync && uv run python examples/navigate.py      # offline, no API key
```

```python
from hunter_rag_reference import CDUStore, ActiveRAGAgent, parse_markdown_file

store = CDUStore()
store.load_dict(parse_markdown_file("my_doc.md"))       # toy ingestion

agent = ActiveRAGAgent(store, model="gpt-4o-mini")      # any OpenAI-compatible endpoint
result = agent.run("What does the first equation define?", doc_id="my_doc")
print(result.answer)
print(result.evidence_units)                            # the units it read in full
```

The full product: `pip install hunter-rag`.

## Status

Reference core: `complete` — the CDU schema and the navigation protocol are the stable layer. Product: `beta`; releases in [CHANGELOG.md](https://github.com/arcintelligence/hunter-rag/blob/main/CHANGELOG.md).

## Where next

- [docs/paradigm.md](https://github.com/arcintelligence/hunter-rag/blob/main/docs/paradigm.md) — the paradigm, in prose.
- [cdu.arcintelligence.ai](https://cdu.arcintelligence.ai) — how it works, and the full product.
- Enterprise and industrial deployments, built and supported by Arc's engineers: [contact@arcintelligence.ai](mailto:contact@arcintelligence.ai).

## License

Arc Source-Available License 1.0 — [LICENSE.md](https://github.com/arcintelligence/hunter-rag/blob/main/LICENSE.md). Patent pending. The fixture under `tests/data/` is a parsed representation of [arXiv:1304.5603](https://arxiv.org/abs/1304.5603), included solely as a test fixture.
