redhop 0.1.2

Reasoning-aware context runtime for RAG — chunk, retrieve, and allocate the document context an LLM should see, with citations and a Decision Report. In-process, no vector DB.

RedHop

A reasoning-aware context runtime for RAG.

Hand it a document and a question. RedHop chunks, retrieves, and allocates the context your model should actually see — then tells you what it kept, what it dropped, and why, with citations back to the source. No vector database, no LLM, all in-process.

import redhop

doc = redhop.Document.from_file("contract.pdf")
ctx = doc.context("What is the governing law?")

answer = llm.generate(ctx.text())   # any LLM provider — no lock-in

pip install redhop

One self-contained wheel — no Python dependencies. The default lexical tier needs no model at all; the semantic/rerank tiers download a small model on first use (cached).

The idea

Retrieval quality is not the same as reasoning quality. Transformers tolerate irrelevant context far better than they tolerate missing reasoning links — so the chunk a multi-hop answer depends on is often low-relevance to the query and gets silently pruned. RedHop's default keeps it, and makes the trade-off visible. It is not a retriever, vector database, agent framework, or workflow engine — it does one thing: turn a document and a query into the right prompt context, and explain the decision.

It explains every decision

Every call returns a Decision Report — what it kept, what it dropped, and why, including when it deliberately leaves a small context untouched.

print(ctx.report)

RedHop Decision Report
══════════════════════

Decision: Auto → pruning (intervened on a diluted context)

  Why:
    - large/diluted contexts dilute attention; pruning recovers signal density
  Result:
    - removed distractor chunks, kept all query-relevant evidence
    - preserved a second-hop link a plain relevance filter would drop

Diagnostics
───────────
  Chunks:             24 → 3
  Second-hop rescues: 1

Read the fields directly via ctx.report.auto_decision, total_tokens, retained_evidence_ratio, or call doc.analyze(query) for the report without assembling a context.

Cite the evidence

Every selected chunk remembers where it came from:

for c in ctx.citations:
    print(c["source"], c["page"], c["heading"])
    # contract.pdf  3     None      ->  "contract.pdf, p.3"
    # notes.md      None  "Refunds" ->  "notes.md -> Refunds"

Loading documents

On-ramp	For
Document.from_text(text)	text you already have
Document.from_chunks([...])	content you already chunked
Document.from_file("x.pdf")	a file — PDF, DOCX, PPTX, XLSX, Markdown, or text/code
Document.from_bytes(data, source="x.pdf")	bytes you fetched (S3 / GCS / HTTP / DB)
Document.from_folder("./docs", persist=True)	a whole directory, with an optional incremental on-disk index

Retrieval tiers — no vector database

A ladder; start cheap, climb only when a query needs it. All in-process, no ANN, no index server.

doc = redhop.Document.from_text(text, retrieval="lexical")   # BM25 (default)
doc = redhop.Document.from_text(text, retrieval="hybrid",   model="bge-small")  # BM25 -> dense rerank
doc = redhop.Document.from_text(text, retrieval="semantic", model="bge-small")  # exact cosine over all chunks

Add rerank="cross-encoder" on any tier for a precise (slower) second stage.

Assembly strategies

strategy=	What it does
reasoning_preserving (default)	keep query-relevant seeds and rescue low-relevance chunks linked to one; drop only unlinked junk
distractor_filtered	drop everything below a query-grounding bar
max_density	greedily pack the densest chunks into the budget
raw_topk	keep retrieval order until the budget fills
auto	size-gated: pass small contexts through, prune large/diluted ones

Already have chunks from your own retriever? Use redhop.build_context(query, retrieved_chunks=chunks, ...) for the low-level surface.

Documentation

Full docs, the comparison vs LangChain / LlamaIndex, and the evidence behind every default: https://redhop.dev

Apache-2.0. Also available for Node.js (npm install redhop) and Rust (cargo add redhop).