backdraft

Drop-in provenance for factual claims: one click from any claim to the receipt behind it.

An analyst who cannot show where a number came from either re-reads the source or does not use the output. Backdraft removes that cost. In the usual loop, an agent does the writing: it reads your source documents only through a gate that mints a citation token over every span it shows, cites those tokens inline, and a postprocess resolves them, attaches the verbatim evidence, and renders one self-contained HTML file, the memo with the actual cited pages and spreadsheet cells embedded inside it. The human just reads that file: click a claim, see the source.

It works the same whether the writer is a model or a person, and whether the citations were minted during writing or attached to a document afterwards.

Docs live at backdraft.dev, one page for people, and backdraft.dev/llms.txt for agents.

60 seconds

uv tool install backdraft
cd demo

Ingest the sources. Every anchor is minted here, chunks for PDF pages, cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, XLS, CSV/TSV, DOCX, PPTX, HTML, images (png, jpeg, tiff, through the vision model), plain text and Markdown. A source can also be an http(s) URL — the page is fetched once and snapshotted like any other source, and the URL travels with it. A source that cannot be read does not end the run: the rest of the list is ingested anyway, and the command exits 1 naming each source that failed and why. The why is written to be acted on rather than relayed — a directory says to name the files inside it or pass a glob, a missing path says to check the spelling, an unreadable file says to fix its permissions or ingest a copy, and a source with no bytes in it is a failure rather than a document with nothing to cite.

$ backdraft init
registry: /…/demo/.backdraft
documents: 0
… plus where settings live and what to do next

$ backdraft ingest sources/t12-summary.pdf sources/underwriting-model.xlsx
t12-summary  t12-summary.pdf  pdf  3 pages  8865 chars
underwriting-model  underwriting-model.xlsx  xlsx  2 sheets  2357 chars
note: extracted with pdf-text (the embedded text layer). Glossy or scanned PDFs extract better through a vision model: set BACKDRAFT_VLM_API_KEY in .backdraft/env.

$ backdraft ingest "https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775" --slug franklin-county
franklin-county  https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775  html  1 page  34141 chars

The demo cites that page for market context. It is Wikipedia's permanent link — ?oldid= serves one revision's bytes forever — because a citation into a live article reports drifted the moment somebody edits it, and the quoted sentence would no longer be the sentence there.

--slug is there because that URL's default name would be en-wikipedia-org-index — its last segment is /index.php, a handler rather than a page, so the host stands in — and a slug is permanent once tokens carry it. backdraft ingest <source> --dry-run is how to see that before choosing: it prints the slug, media type and extractor each source would take and stops, fetching nothing, writing nothing and calling no model, and it says when a source is already ingested or when the name it wants is taken. The extractor is the line to read before a PDF batch: vlm is a vision-model call per page, spent against BACKDRAFT_VLM_API_KEY, and pdf-text reads the text layer for free. An unknown --extractor or a --config key the chosen one never reads fails the dry run the way it would fail the ingest. Permanent means --slug only ever names a new document: on a source already ingested the line says --slug not applied and a note names the slug it keeps — and forget then a re-ingest brings back that same slug rather than a new one, since identity is the bytes, not the name.

Every ingest line ends with how much text came out, and says which of three things happened: a document created, a new generation of one whose bytes moved — which is when citations into the previous snapshot start reporting drifted, and backdraft locate says where their text went — or unchanged, a no-op because re-running would reproduce what is already there. When almost no text came out, a note names the likely cause (a scan with no text layer, a page behind a login) and what to do; it is a note at exit 0, because a thin snapshot is still a real one. That source keeps the mark afterwards — backdraft read's document list, its table of contents and backdraft ls end its row with little text: N chars — because a registry travels with the project folder and whoever writes against it is usually not whoever ingested it. Ordinary sources gain nothing: only the rows worth doubting say anything. A table is judged by its cells rather than its length — a three-row rate card is small and complete, so a spreadsheet or CSV is marked only when none of its cells holds a value, which is what a workbook of charts or images extracts to.

Read. The page arrives with a citable name over each chunk. This is the whole mechanism: what you can cite is exactly what you were shown.

This is the beginning of the README. Read the rest at the original. Read the full README ↗