Metadata-Version: 2.4
Name: cairn-retrieval
Version: 0.1.0
Summary: Agent-retrieval layer on top of the Cairn entity engine — adaptive gate, signal orchestration (lexical/semantic/graph), and minimal context assembly. Zero generative-LLM on the hot path.
Project-URL: Homepage, https://github.com/leocelis/cairn
Project-URL: Source, https://github.com/leocelis/cairn
Project-URL: Issues, https://github.com/leocelis/cairn/issues
Author-email: Leo Celis <hello@leocelis.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,context-assembly,deterministic,rag,reranking,retrieval
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cairn-engine~=0.1.0
Description-Content-Type: text/markdown

# cairn-retrieval

**The agent-retrieval layer on top of the [`cairn-engine`](https://github.com/leocelis/cairn/tree/main/packages/cairn-engine) entity engine.**

The three retrieval primitives above the entity map — all deterministic, all
generative-LLM-free on the default path:

- **A · Adaptive gate** (`gate`) — two-stage, LLM-free decision *before* any
  signal runs: deterministic bypass (temporal markers, multi-entity relational,
  private entities) then a CA-RAG utility cost function. `strategy=none` (skip
  retrieval) is a first-class, reachable outcome — selective retrieval beats
  always-on empirically.
- **C · Signal orchestration** — `LexicalIndex` (pure-Python BM25) + `scan`
  (exact/regex), opt-in `SemanticIndex` (caller-supplied embedder; no model SDK
  imported), graph traversal via `cairn-engine`; ranked lists merged with `fuse`
  (Reciprocal Rank Fusion, k=1, rank-only — no score normalization).
- **E · Context assembler** (`assemble`) — budget → MMR select → cosine dedup →
  fold ordering (strongest evidence at the edges) → provenance-tagged emit with
  a trace manifest. Never re-embeds; zero LLM.

`RetrievalEngine.retrieve(query, *, budget)` ties them end-to-end:
resolve → gate → orchestrate → fuse → assemble. A query the gate routes to
`none` returns no context at all — the skip is the point.

Also here: `rank_links` — TF-IDF-cosine document↔document link recommendation
over shared canonical concepts — and `suggest_connections` — cold-start link
prediction: rank the existing entities a NEW candidate node should connect to
(content-first, seed-optional structural signal, full provenance).

> Status: **feature-complete, 0.x.** Stays 0.x until the benchmark phase
> (OP-31 eval vs. agentic-grep / vector-RAG / Graphiti) proves the quality
> claims. Depends only on `cairn-engine` (which is itself zero-dependency). See
> the [roadmap](https://github.com/leocelis/cairn/blob/main/ROADMAP.md) and
> [`intents/`](https://github.com/leocelis/cairn/tree/main/packages/cairn-retrieval/intents)
> for the constraint-tested design of each module.

## Install

```bash
pip install cairn-retrieval   # pulls cairn-engine automatically
```

## License

MIT — Copyright (c) 2026 Leo Celis
