Quickstart

RedHop has the same API in three languages. Pick your tab, and the choice follows you down the page.

Install

Python

pip install redhop

Node.js

npm install redhop

Rust

cargo add redhop --features files,semantic

One package, no services, no vector DB. Document parsing (PDF/DOCX/PPTX/XLSX) and the optional semantic model are built in.

Reason over a document

Point RedHop at a file. It parses, chunks, and indexes it, then hands you back just the context your question needs, which you give to any LLM:

Python

import redhop
from openai import OpenAI

doc = redhop.Document.from_file("contract.pdf")   # parse + chunk + index
question = "What is the governing law of this contract?"
ctx = doc.context(question)

# Hand ctx.text() to any provider — no lock-in.
resp = OpenAI().chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": f"Use only this context:\n\n{ctx.text()}\n\nQ: {question}"}],
)
print(resp.choices[0].message.content)
print(ctx.report)          # the Decision Report ↓

Node.js

const { Document, Chunk } = require("redhop");
const OpenAI = require("openai");

const doc = Document.fromFile("contract.pdf");   // parse + chunk + index
const question = "What is the governing law of this contract?";
const ctx = doc.context(question);

// Hand ctx.text to any provider — no lock-in.
const resp = await new OpenAI().chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: `Use only this context:\n\n${ctx.text}\n\nQ: ${question}` }],
});
console.log(resp.choices[0].message.content);
console.log(ctx.report.rendered);   // the Decision Report ↓

Rust

let mut doc = redhop::read_file("contract.pdf")?;   // parse + chunk + index
let question = "What is the governing law of this contract?";
let ctx = doc.context(question)?;

// Hand ctx.text() to any LLM (async-openai, reqwest, …) — no lock-in.
let _prompt = format!("Use only this context:\n\n{}\n\nQ: {question}", ctx.text());
println!("{}", ctx.report.render(None));   // the Decision Report ↓

The Decision Report

Every call explains itself, including when RedHop deliberately does nothing:

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

Decision: Auto → passthrough (left the context intact)
  Why:
    - input is small: 91 tokens ≤ 1500 gate
    - under headroom, pruning is measured to be wash-to-harmful
    - intervention predicted to add no signal density here
  Result:
    - kept all retrieved chunks — full evidence preserved
    - avoided unnecessary intervention

Economics      retrieved / final tokens, savings, density, retained evidence
Diagnostics    chunks, distractor ratio, second-hop rescues, …

The decision is also available programmatically:

Python

ctx.report.auto_decision        # "passthrough" | "prune"
ctx.report.total_tokens
ctx.report.retained_evidence_ratio

Node.js

ctx.report.autoDecision         // "passthrough" | "prune"
ctx.report.totalTokens
ctx.report.retainedEvidenceRatio

Rust

ctx.report.auto_decision();        // AutoDecision::Passthrough | ::Prune
ctx.report.total_tokens;
ctx.report.retained_evidence_ratio;

Cite the evidence

Every selected chunk remembers where it came from, so you can show the model’s evidence trail, not just paste it:

Python

for c in ctx.citations:
    print(c["source"], c["page"])   # e.g. contract.pdf  3  → "from contract.pdf, p.3"

Node.js

for (const c of ctx.citations) {
  console.log(c.source, c.page);    // e.g. contract.pdf  3  → "from contract.pdf, p.3"
}

Rust

for c in &ctx.chunks {
    // source + page/heading/line live on each chunk's metadata
    println!("{} {:?}", c.source, c.metadata.get("page"));
}

Other ways to get content in

Loading a file is the quickest start, but it’s one of several on-ramps, and all return a Document:

Python

# Text you already have (your own parser/OCR, a DB field).
doc = redhop.Document.from_text(open("notes.md").read())
# Already chunked it yourself — wrap each in redhop.Chunk so source/id/metadata travel through.
doc = redhop.Document.from_chunks([
    redhop.Chunk("clause one …", source="msa.pdf", id="c1"),
    redhop.Chunk("clause two …", source="msa.pdf", id="c2"),
])
# A whole folder — one combined index, citations per file.
doc = redhop.Document.from_folder("./docs")
# Bytes from S3 / Azure / GCS / HTTP.
doc = redhop.Document.from_bytes(s3_object_bytes, source="contract.pdf")

Node.js

// Text you already have (your own parser/OCR, a DB field).
let doc = Document.fromText(fs.readFileSync("notes.md", "utf8"));
// Already chunked it yourself — wrap each in Chunk so source/id/metadata travel through.
doc = Document.fromChunks([
  new Chunk("clause one …", { source: "msa.pdf", id: "c1" }),
  new Chunk("clause two …", { source: "msa.pdf", id: "c2" }),
]);
// A whole folder — one combined index, citations per file.
doc = Document.fromFolder("./docs");
// Bytes from S3 / Azure / GCS / HTTP.
doc = Document.fromBytes(buffer, "contract.pdf");

Rust

// Text you already have (your own parser/OCR, a DB field).
let doc = redhop::Document::from_text("notes", text)?;
// Already chunked it yourself — Chunk::new(id, text, source, token_count).
use redhop::core::{Chunk, ChunkId, TokenCount};
let doc = redhop::Document::from_chunks(vec![
    Chunk::new(ChunkId::new("c1"), "clause one …", "msa.pdf", TokenCount(3)),
    Chunk::new(ChunkId::new("c2"), "clause two …", "msa.pdf", TokenCount(3)),
])?;
// A whole folder — one combined index, citations per file.
let doc = redhop::read_folder("./docs")?;
// Bytes from S3 / Azure / GCS / HTTP.
let doc = redhop::read_bytes(&bytes, "contract.pdf")?;

See all the loaders →, including a persistent, incremental on-disk index over thousands of files.

Knobs (sane defaults, tune when needed)

Python

doc = redhop.Document.from_file(
    "contract.pdf",
    chunk_size=128,          # index-time: how the doc is split
    strategy="auto",         # size-gated: prune only under dilution
)
ctx = doc.context(query, budget=2000)   # query-time: vary freely, no re-indexing

Node.js

const doc = Document.fromFile("contract.pdf", {
  chunkSize: 128,            // index-time: how the doc is split
  strategy: "auto",          // size-gated: prune only under dilution
});
const ctx = doc.context(query, 2000);   // query-time: vary freely, no re-indexing

Rust

use redhop::{Document, DocumentConfig};

let cfg = DocumentConfig { target_tokens: 128, ..Default::default() };
let mut doc = Document::from_text_with("doc", text, cfg)?;   // config-aware constructor
let ctx = doc.context_with(query, Some(2000), None)?;        // per-query budget

chunk_size is fixed at construction (it’s how the index is built). The per-query budget is free to vary. Every parameter has a default, see Options for the full list.

Next: Loaders for every way to get documents in · Overview for the one idea, and how it works · Retrieval options for when BM25 isn’t enough.