Stop embedding what you can just address.

A vector database bills you before it's answered a single question

Chunk the corpus, embed every chunk, store every vector, re-embed on every edit — that's the fixed cost of a conventional pipeline before "hello world" runs once. treehash's structural resolver never embeds anything at ingest; the optional semantic tier only computes vectors per-query, on demand, and throws them away.

Three moves instead of one similarity search

A conventional RAG pipeline chunks every document, embeds every chunk, and pays a similarity search over every vector for every query. treehash resolves structure first.

treehash vs. a typical chunk-and-embed pipeline

Every "typical pipeline" column below is the honest, unglamorous default — a standard chunker, a standard embedding call, a standard vector store — not a strawman. See benchmarks/ingest_cost/ and BENCHMARKS.md to run the comparison yourself.

Install it and it runs

No model downloads, no API key needed to use the core engine, no sklearn/torch/numpy to even get started. Published on PyPI — this is a real, working install, not a "coming soon."

from treehash import KnowledgeBase

kb = KnowledgeBase(domain="finance")   # or "medical", "education", or None
kb.add_document("10k_2025", filing_text)

result = kb.query("What was revenue in Q2 2025?")
print(result.method)              # "structural" — resolved by address, not search
print(result.hits[0]["content"])   # "6.1M"

ctx = kb.context_for_llm("What was revenue in Q2 2025?")
print(ctx["estimated_tokens"])     # a handful of tokens, not a whole page

Feed context_for_llm()'s output to your own LLM call, or let kb.ask(query, api_key=..., provider="anthropic") do it and hand back the provider-reported token counts — so any reduction shows up as a real number on your bill, not an estimate.

What each module actually does

We publish our own bugs. Most projects don't.

Every claim on this page is backed by a script anyone can re-run — that's DISCLOSURE_STANDARD.md's whole job. The clearest proof isn't a number — it's watching the number get worked on in public. Three consecutive rounds: find the highest-leverage real gap, fix exactly that, verify zero regression at the individual-case level before keeping it.

Blended accuracy across all 1,104 cases moved 84.4% → 92.0% over the three rounds above, on a bank where every generated case's expected answer traces back to a fact a human already verified — never invented. Full methodology and numbers in accuracy_cases/ITERATION_LOG.md.

An address, a method, a confidence — not a similarity score

A cosine-similarity hit names a nearest neighbor. This names an address — inspectable, hash-chained, exportable as evidence.

answer = kb.ask("What was revenue in Q2 2025?", api_key="sk-...")  # recorded automatically

ok, bad_index = kb.audit_log.verify()          # hash-chain integrity check
kb.audit_log.export_csv("audit-trail.csv")         # for a human reviewer
report = kb.cost_savings_report(input_cost_per_1k=0.15)  # real, provider-billed tokens

• Every ask() call is recorded with its literal source addresses, resolution method, confidence, answer, and real provider-billed token usage.
• Hash-chained — the same content-addressing idea this project already applies to tree nodes, applied to log entries: each record's hash covers its own fields plus the previous record's, so editing or reordering an earlier record is detectable, not just trusted.
• Cost savings, verified not asserted — the actual-cost half of cost_savings_report() comes from real provider-billed tokens; the baseline-cost half is honestly labeled as an estimate, since that path is never actually run against a real API.
• A runnable starter kit for the vertical this project is strongest in — finance 10-K/10-Q analysis — end to end, no API key required: examples/tenk_analysis_audit_trail.py.

An agent already knows what it wants — give it an address, not a guess

Deterministic address resolution fits a tool-calling agent better than a human typing a question. treehash exposes that directly as MCP tools.

# pip install treehash[mcp]
python3 -m treehash.mcp_server   # stdio transport — plug into Claude, LangGraph, any MCP host

• Structured tools first — get_section, get_table_cell, get_by_address bypass the natural-language resolver entirely, calling the tree/hash index directly. Deterministic by construction, not by a query happening to match a regex.
• query (natural language) stays available as a fallback for exploratory use with no known address — but it isn't the primary surface here the way it is for a human chatting.
• ask() is deliberately not exposed as a tool — the calling agent already is the LLM; it doesn't need this to call another one, and a tool that accepts an API key is a credential smell for no benefit.
• Same TREEHASH_DATA_DIR/sharding/audit-log config as the HTTP server — an MCP client and Server mode can point at the same data.

Three suites — synthetic at scale, adversarial at scale, and real filings under real spend

Every number below was measured, including the ones that don't flatter the project. See benchmark.py, benchmarks/financebench/, and benchmarks/ingest_cost/ to reproduce any of these yourself — the methodology itself is written out as a checklist in DISCLOSURE_STANDARD.md.

What real documents and real traffic actually broke

• Memory — pdfplumber's per-page cache, never released, cost 1.5GB to parse one 13MB report. Fixed with page.close(): 69MB, 22× smaller.
• Concurrency — 5 real OS processes writing to the same SQLite file lost writes under the default journal mode. Fixed with WAL, busy_timeout, and BEGIN IMMEDIATE; verified with a real subprocess-based test.
• Crash recovery — a process SIGKILLed mid-write, an open gap this project named itself. A real subprocess is killed partway through an uncommitted transaction; the test confirms the database still opens and that none of the killed write is partially visible.
• Multi-tenant auth — per-KB bearer keys (TREEHASH_API_KEYS), so one tenant's key can't read another tenant's kb; a single shared token remains a fallback for kbs with no per-kb keys configured.
• Enterprise-shaped scale — thousands of SEPARATE documents (not one giant document) found two real O(n_documents) bugs in the structural resolver, both fixed; confirmed flat lookup latency from 100 to 20,000 documents afterward.
• A table-lookup that quietly stopped being O(1) — a repeated label word in a table's row key made candidate generation cost O(corpus size); fixed by checking a token's selectivity before paying to fetch its match set. 18.9ms → 0.013ms at 100,000 elements.
• A single-document ingest that quietly became O(n²) — every section in one giant document shared one parent, and adding a child rebuilt that parent's whole list every time. Fixed with an O(1) membership check. 121s → 7.34s at 1,000,000 elements.
• Postgres — a StorageBackend reachable from multiple machines, not just one SQLite file. Found and fixed a real concurrency bug (schema creation races under concurrent first-open) and two round-trip-reduction fixes; its own latency numbers are reported as directional, not a tight bound — see BENCHMARKS.md.
• Server — a per-IP rate limit (60/min default, in-memory by default, Redis-backed across worker processes when configured), a request-size ceiling (150MB), and structured request logging.
• Tables and figures — PDF and DOCX extract embedded images and attach nearby "Figure N"/"Table N" captions; a text-position table-detection strategy was tested and rejected after it shredded ordinary prose on most real documents it was tried against.
• Domain aliases — a section alias ("item", "chapter") resolved the ordinal query form ("the second chapter") but silently not the bare-number form ("chapter 2"), for every domain pack, until a new generic contract test — written so any future domain pack gets the same coverage automatically — caught it.

Every phase, found through testing — not assumed and patched in the abstract

In order. The most recent phases are a self-directed loop: expand the test bank, measure, fix the single highest-leverage gap, verify zero regression, repeat.

1. 1

   Productized rewrite 9b4033c

   Zero-dependency core, persistent SQLite backend, three domain packs, multi-format parsing, LangChain/LlamaIndex adapters, an HTTP server.

2. 2

   Real-world benchmark harness 34449e6

   Added FinanceBench: real SEC 10-K/10-Q filings, real GPT-4o-mini calls, provider-reported token usage — not estimated.

3. 3

   PDF headings, concurrency, hardening 41ffe9c

   Font-size-only heading detection found 1 section in a real 121-page 10-K; rewritten to combine size, boldness, and SEC pattern matching → 9 sections, 497 subsections. Fixed real multi-process SQLite write loss. Server hardened.

4. 4

   Memory and capacity 2b69aad

   A real 13MB/248-page report used 1.5GB peak RSS to parse. Fixed: 69MB, a 22× reduction. Validated against ten real documents and a 110MB combined-PDF stress test.

5. 5

   Accuracy investigation 2fc93b7

   Bare table-cell values ("21.6") were losing context-ranking to verbose but useless text — labeled with row/header context. Added lightweight stemming.

6. 6

   Images, tables, and a rejected idea 5c68dfb

   Added image + caption extraction to both parsers. A hybrid table-detection strategy looked promising on one document, failed on several others, and was documented as not shipped.

7. 7

   Three real retrieval bugs c580b0e

   Built a free, offline recall checker (no LLM call) and found: a domain alias word matching entire documents' worth of tables; a thin stopword list; a redundant ancestor/descendant ranking bug.

8. 8

   Paid confirmation 6885a3b

   Re-ran the real, billed FinanceBench suite to confirm the free checker's finding wasn't an artifact of its own grading logic. It wasn't.

9. 9

   Cost gap, adversarial set, a real O(n) bug d053abc

   Investigated a claimed FinanceBench cost regression — the premise was stale; treehash already used fewer tokens. Built a 48-case hand-verified adversarial set (paraphrase/typo/multihop/vague) and found a real accuracy gap. Found and fixed a table-lookup that had quietly stopped being O(1) at scale.

10. 10

    Published to PyPI 07e53a6

    pip install treehash-rag went from "reserved but never published" to actually working — verified in a brand-new virtualenv against the real PyPI index, not local source.

11. 11

    Ingest cost, and a real O(n²) bug 4b4af68

    Set out to measure treehash's $0 ingest cost against a chunk-and-embed baseline; building the 1M-element test case exposed a quadratic-scaling bug in MemoryBackend. Fixed: 121s → 7.34s.

12. 12

    1,104-case accuracy bank, iteration 1 21396d8

    Mechanically expanded the 48 hand-verified facts into a >=1,000-case tagged bank. Found and fixed a multi-section resolver gap it surfaced.

13. 13

    Two more fixes, v1.0.1 published 4a5e4ee

    Typo-tolerance for anchor words, then a multi-hop connector split — each verified with zero case-level regressions before keeping it. Version bumped and republished to PyPI the same day.

What's still unsolved

Stated plainly rather than scoped away — every number on this page is something that was actually measured.

• The vague/underspecified query category still lags (58.3%, n=12) — the smallest, least statistically trustworthy category in the adversarial bank, and the only one below this project's own 0.75 per-category bar. Growing it into a generated category, the way the other five already are, is the honest next step.
• The medical corpus's token reduction is negative (treehash uses slightly more tokens than the naive baseline there) — a real, disclosed exception to the blended 11.0% reduction figure, not smoothed into it.
• Multi-hop, computed-metric questions (a 3-year average margin spanning several statements) still aren't reliably retrieved — BM25/FTS5 under-ranks terse, numbers-dense table sections against narrative prose that repeats the same terms without the number.
• The resolver is still curated patterns written by a person, not a trained model — a genuinely novel query shape still lands on BM25 (or the optional semantic tier). What changed: a query log now surfaces which fallthrough queries repeat and which words are disproportionately common in them, so the next pattern written is backed by real traffic, not guesswork — the decision is still manual.
• No OCR — a scanned PDF with no text layer yields no elements.
• PDF parsing assumes single-column layout; charts drawn with vector operators (not embedded as a raster image) aren't captured.