backdraft 0.2.0__py3-none-any.whl

backdraft-0.2.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: backdraft
+Version: 0.2.0
+Summary: Drop-in provenance for factual claims: one click from any claim to the evidence behind it.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: typer>=0.12
+Provides-Extra: entail
+Requires-Dist: anthropic>=0.40; extra == 'entail'
+Provides-Extra: vlm
+Requires-Dist: openai>=1.0; extra == 'vlm'
+Requires-Dist: pdf2image>=1.17; extra == 'vlm'
+Description-Content-Type: text/markdown
+
+<img src="assets/backdraft-mark.svg" width="56" alt="">
+
+# 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](https://backdraft.dev) — one page for people, and
+[backdraft.dev/llms.txt](https://backdraft.dev/llms.txt) for agents.
+
+## 60 seconds
+
+```bash
+uv tool install git+https://github.com/spencerbraun/backdraft
+cd demo
+```
+
+**Ingest** the sources. Every anchor is minted here — chunks for PDF pages,
+cells for spreadsheet sheets.
+
+```console
+$ backdraft init
+registry: /…/demo/.backdraft
+documents: 0
+
+$ backdraft ingest sources/t12-summary.pdf sources/underwriting-model.xlsx
+t12-summary  t12-summary.pdf  pdf  3 pages
+underwriting-model  underwriting-model.xlsx  xlsx  2 pages
+note: extracted with pdf-text (the embedded text layer). Glossy or scanned PDFs extract better through a vision model: install backdraft[vlm] and set BACKDRAFT_VLM_API_KEY in .backdraft/env.
+```
+
+**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.
+
+```console
+$ backdraft read t12-summary p1
+# t12-summary p1  (page 1 of 3)
+
+[bd:t12-summary:p1.c1:c2e8]
+Bridgeview Commons — Trailing Twelve Month Summary
+
+Property: Bridgeview Commons, 4400 Halsted Avenue, Columbus, OH 43214. 128 units across four three-story
+garden buildings on 6.2 acres, built in 1998 and substantially renovated between 2019 and 2021. This summary
+covers the trailing twelve months ended March 31, 2026, prepared from the borrower's monthly operating
+statements and reconciled against the property manager's general ledger. Figures are unaudited.
+
+[bd:t12-summary:p1.c2:7f11]
+Total effective gross income for the trailing twelve months was $2,684,400, against gross potential rent of
+$2,972,160. The resulting economic occupancy of 90.3% reflects an average physical occupancy of 94.1% offset
+by concessions, bad debt, and vacancy loss. Physical occupancy was 96.4% in the most recent month and has not
+fallen below 92.0% in any month of the period.
+
+… five more chunks, c3 through c7.
+```
+
+Chunks fall on the document's own paragraphs. A PDF stores glyphs at
+coordinates, not paragraphs, so the extractor rebuilds the breaks from the line
+geometry before the chunker sees the page.
+
+Search results are citable too — no page read required to get an anchor:
+
+```console
+$ backdraft search "24850000"
+1 result for "24850000"
+
+[bd:underwriting-model:assumptions!B10:964a]  underwriting-model p2
+  24850000
+
+[Read the page: backdraft read underwriting-model p2]
+```
+
+A cell you can already see mints directly:
+
+```console
+$ backdraft cell underwriting-model "assumptions!B10"
+[bd:underwriting-model:assumptions!B10:964a]  24850000
+```
+
+**Cite** by writing the token as the href of a markdown link on the claim span.
+Multiple citations are `;`-separated in one href.
+
+```markdown
+[net operating income of $1,429,600](bd:t12-summary:p1.c3:f10b)
+[Effective gross income of $2,684,400](bd:t12-summary:p1.c2:7f11;bd:underwriting-model:rent-roll!B11:4b79)
+```
+
+**Bind.** Every token resolves or is reported. Nothing drops silently.
+
+```console
+$ backdraft bind memo.md --session s-bridgeview --check value-trace,overlap
+bound 15 claim(s), 16 citation(s) [frontwalk]
+  resolved: 15
+  unresolved: 1
+  overlap: partial 4, pass 11
+  value-trace: pass 15
+  ! unresolved: bd:t12-summary:p4.c1:1a2b
+wrote .backdraft/records/memo.backdraft.json
+
+$ echo $?
+2
+```
+
+Exit 2 means a citation did not resolve — the code a `Stop` hook or a CI job
+gates on.
+
+**Render.** One self-contained HTML file: the document, the receipts, the
+evidence — cited page images, spreadsheet cells in place, the machine-readable
+record — all embedded, no network, nothing to install for the reader.
+
+```console
+$ backdraft render memo.md --to html
+memo.backdraft.html
+```
+
+That file is the whole deliverable: send it over email or Slack and the
+recipient gets the full experience by double-clicking it.
+
+The full version of this, with every command and every output:
+[`demo/walkthrough.md`](demo/walkthrough.md). The artifact it produces is checked
+in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
+
+## The design in five sentences
+
+Reading is a **gate**: source documents reach the writer only through `read` and
+`search`, which mint a token over everything they show and record it in a
+**ledger**, so the set of citable things is exactly the set of things shown — and
+a citation to something the writer never saw is a distinguishable failure rather
+than an invisible one. **Anchors are content-addressed**: a token's identity
+derives from the document's content and a location inside it, and it binds to an
+extraction snapshot, so re-ingesting the same bytes yields the same tokens and a
+changed source yields `drifted` instead of a broken link. **The receipt travels
+with the claim** — an anchor is not a pointer but a pointer plus the verbatim
+snippet and its hash, which is why the finished artifact is defensible with the
+registry deleted and the sources gone. **Verification is a set of switches,
+default off**: resolution is inherent to binding, but `value-trace`, `overlap`
+and `entail` are opt-in, recorded as graded evidence and never used as gates, so
+out of the box this is provenance rather than a truth oracle. **Artifacts are
+self-describing**: each carries a `$format` string matched byte-for-byte and an
+embedded `$legend` that teaches a reader who has never heard of backdraft how to
+decode and check it, so the format outlives this implementation.
+
+Failures are data throughout: `unresolved`, `not_shown`, `drifted`, `malformed`
+and `unmatched` are first-class records in the report and visible sections in the
+artifact. Nothing is ever warned about and dropped.
+
+## What lives where
+
+A working directory stays clean: the authored document and its artifact are
+the only visible outputs. Everything else — registry, credentials, bind
+records — lives under one hidden `.backdraft/` directory, and
+`backdraft clean` tidies strays from older versions. The registry contains the
+full text of everything ingested, so **gitignore `.backdraft/` for
+confidential corpora**.
+
+## Install
+
+Not yet on PyPI — install from the repository:
+
+```bash
+uv tool install git+https://github.com/spencerbraun/backdraft      # CLI
+uv add "backdraft @ git+https://github.com/spencerbraun/backdraft" # as a dependency
+pip install git+https://github.com/spencerbraun/backdraft          # or plain pip
+```
+
+Python 3.13+. Two extras:
+
+| Extra | Adds | For |
+|---|---|---|
+| `[vlm]` | `openai`, `pdf2image` | the VLM extractor — the recommended path for real PDFs (glossy layouts, info boxes, scans): a vision model reads each page and its clean representation becomes the receipt. `--extractor auto` prefers it only on explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or `.backdraft/env` — `backdraft init` writes a template). Ambient `OPENAI_API_KEY`/`OPENROUTER_API_KEY` are deliberately never read; a generic key in the environment is not consent to send documents to its provider. The default provider is OpenRouter running Gemini 3.1 Flash Lite; direct OpenAI is base_url + model, set explicitly. Without a scoped key, `auto` falls back to the keyless text layer and says so. Needs poppler installed separately |
+| `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
+
+```bash
+pip install "backdraft[vlm,entail] @ git+https://github.com/spencerbraun/backdraft"
+```
+
+From a checkout:
+
+```bash
+uv sync
+uv run backdraft --help
+uv run pytest
+```
+
+## Skills
+
+Three agent skills ship in [`skills/`](skills). Copy the ones you want into your
+agent's skills directory — for Claude Code, `~/.claude/skills/` (personal) or
+`.claude/skills/` (per project):
+
+```bash
+cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+```
+
+| Skill | For |
+|---|---|
+| [`backdraft`](skills/backdraft/SKILL.md) | writing a new document from sources, citing as it goes |
+| [`backdraft-backfill`](skills/backdraft-backfill/SKILL.md) | attributing a document that already exists |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
+
+The CLI is the system; a skill is one page telling an agent to use it. Nothing in
+the skills is required to use backdraft by hand.
+
+## Documentation
+
+| Document | Is |
+|---|---|
+| [DESIGN.md](DESIGN.md) | why it is shaped this way — principles, architecture, decision log |
+| [SPEC.md](SPEC.md) | the builders' contract — types, grammar, DDL, CLI surface, module boundaries |
+| [spec/tokens.md](spec/tokens.md) | the citation token grammar, normatively |
+| [spec/chunking.md](spec/chunking.md) | the deterministic chunker |
+| [spec/artifact.md](spec/artifact.md) | the artifact format — sidecar payload, legend, HTML rules |
+| [demo/walkthrough.md](demo/walkthrough.md) | the whole thing end to end, with real output |
+
+The three files under `spec/` are the portable specification: another
+implementation reads them and nothing else.
+
+## Status
+
+v1. The registry format, the token grammar and the artifact format are pinned
+by prose specs and golden-file tests. What is deliberately queued — exhibits,
+Excel region maps, more formats, `bd:calc` derivations — is written down in
+[ROADMAP.md](ROADMAP.md).
+
+MIT licensed.

backdraft-0.2.0.dist-info/RECORD

@@ -0,0 +1,50 @@
+backdraft/__init__.py,sha256=dkCDv9tf_LE80W3zacOQSsgjCN1AcIkV2aVYv_jPRM4,412
+backdraft/cli.py,sha256=nV_uPKIVzQ2qELstLSWMhD4U0Fqgm8Oi2Gd0Uvab6oE,12079
+backdraft/cli_context.py,sha256=-d33EiI4YxiqqQBZD2xt6d-cq28V_UmoSVXdQtJQwx0,5292
+backdraft/credentials.py,sha256=HgyhTjZJrVGeJqmQ15pxT6O7nvUuNcMhMhPvN1ZWizs,4035
+backdraft/bind/__init__.py,sha256=mI0nmsY_7zvkf4_wLZG6LbgDpuUpZGtivyxN8UuBdGg,1080
+backdraft/bind/binder.py,sha256=LehgwqDRrxVIBnx5V7VXPxuGvp65I7jUMjz5W142H90,25333
+backdraft/bind/cli.py,sha256=4xoEolrXJcNN85uWXXB2x3qKW9Bw09H78vwLvXj3gMs,5125
+backdraft/bind/evidence.py,sha256=bDxQnfQRlWEsY0HW9nwhJkLnUF15dImVBWo5aV22hZE,8303
+backdraft/bind/verify/__init__.py,sha256=8RQfb7v1KSc9yDlb0oH-W-BdhW6qxKsW1lTzVJNNb2I,838
+backdraft/bind/verify/base.py,sha256=jOCdK7UUGaqAgUwu-XKxI9lN5vxqYYZ7eGRSnu6q4U8,2606
+backdraft/bind/verify/entail.py,sha256=2lvE2blmwxIyXTxXHNbCP2h6jtP4nBcbeC3s-sSFLFk,6582
+backdraft/bind/verify/overlap.py,sha256=5598QjS1gnx0jtGG91qT2V8waxDLDZVgjD929wQArAg,4561
+backdraft/bind/verify/recompute.py,sha256=G_5KJAB-SEm-ipCrOPgI5mm9pgKiQtUxjjW_idDDhoI,1819
+backdraft/bind/verify/value_trace.py,sha256=I-XdGThH8uHiHoGCCAdlnIQKN0a1YqD9LFyO91O92Eg,13360
+backdraft/extract/__init__.py,sha256=tYJkRq5r5IYgwP_fDScD2SPRbsl5pwLyx-bYqCkWIWY,787
+backdraft/extract/base.py,sha256=961v91VwCKZcbdULDKt-ff2oSg2J74KBYjK0vxR5w_Y,6496
+backdraft/extract/pdf_text.py,sha256=y3XNlol17JBy68qzLt_Husu9a3cn35Ren4tAfY-qo6w,5050
+backdraft/extract/text.py,sha256=a5vkWNcHL8eRjWk8CHOnh0t5YA2DCxqaJ1EwnCPpvPI,1369
+backdraft/extract/vlm.py,sha256=eZiItol4pVPlZ_gJtyt3x6hO_0VAooeB7JJ372T5Whg,6809
+backdraft/extract/vlm_settings.py,sha256=6agaEWwQFfoVRXsPcshJ-LKvPnJfX96ZzgPyY-cfImc,7208
+backdraft/extract/xlsx.py,sha256=7wyBGTJE1u8AS6FZcDoJP-ecpq5h3duIh-eaBwxraT8,9000
+backdraft/gate/__init__.py,sha256=YmnC7w5tgHKZJCAF_t8ZdpGI-TTIYZAK5tCQmq0MSXY,1080
+backdraft/gate/cli.py,sha256=tzK44Y6NY_asa7qCYbcsRKkrM3Eicnl-g7_S2X4_mWU,4723
+backdraft/gate/reader.py,sha256=k9SY3H-Nu4XryH-3edYuRf2szNlU6OhqlUzU1Y4SV9M,22387
+backdraft/gate/searcher.py,sha256=EVmEKOZQKKhoX4Ns1sdCgBAZUmlck4Zu5xU-as77VhU,4675
+backdraft/kernel/__init__.py,sha256=NcrHGTFxs-dr1RiC5fcp0RNkbtqj_5HEgeIkRI8u6G0,996
+backdraft/kernel/artifact.py,sha256=UgHEBBNJyUi6Ii3D0m6lWL28teloIo87iJmKu8Q3r9w,10793
+backdraft/kernel/chunking.py,sha256=gWdTM7ybnZ1MdWv_1MGOMXG7IWn9De_s0annMxMW7Ys,6088
+backdraft/kernel/claims.py,sha256=FBD6_j46r9W3KlWUrtYjMhjWnKG1O9FBQBjnk1mg1M8,5043
+backdraft/kernel/errors.py,sha256=aecKYN2clJx2LWOpOBIQKYxsgO1Fd0yOK44Rks-J5IM,1032
+backdraft/kernel/hashing.py,sha256=xjxlDeTDd0Nek5vRsCtXhr4J0r-w7dTDPoI5VnAieLg,2895
+backdraft/kernel/model.py,sha256=s4zvpCJAOnRFumShL6wzaGTBRvb0HlGgrq_-_ErFD70,10049
+backdraft/kernel/tokens.py,sha256=Tx1wPZ6Llwy6KvJbui7GjleuWp4VwsvDFqYJwxF9HTA,9809
+backdraft/registry/__init__.py,sha256=Y78nNU8zZ1Qg80VRSWcex8ysHPODZVORD6QSSMzaJ-I,1007
+backdraft/registry/ledger.py,sha256=sBNo1RurwfGSqCKV7aYCm0XQLojujokzAiw6-UxuwMA,2740
+backdraft/registry/schema.sql,sha256=ngwmg4PF2iYiMDF6e0KTSEfhQ8lQZA05ab0UKFduHSc,3477
+backdraft/registry/store.py,sha256=UG59_nsS5JjkIfMXwU6-hTQg--dYWeKJBeJQHm9FO2M,36419
+backdraft/render/__init__.py,sha256=iEah2YoZRtj6ZRK6IXbd5P-QjvrOJYrt2OCbfVR6-8Y,1132
+backdraft/render/_text.py,sha256=75ZtemjMD2GMS7xecm2Clret1PpJqgSiDSiLGU6N4xo,2880
+backdraft/render/cli.py,sha256=cJn0Ay2dMFOPl7UjDX2Y7t0u-lCl-_VJanNfw0nrwfc,3699
+backdraft/render/footnotes.py,sha256=k__tXW_ze_kBeH4UHIa4ROYMA9TLwyC1FyOShOIDRk8,6561
+backdraft/render/html.py,sha256=1dA0E_K_qUlnqi4SGc-MdblYgG6ypSb2eSLmRNvK0Qc,49613
+backdraft/render/markdown.py,sha256=0tFt8limamR94i3iG26PwgXMwG-dYU5xeS9b_d0_5Iw,11222
+backdraft/render/placement.py,sha256=04Y5n9gekE9KNIqRN-BnkD6850oH2qId7tjbTJ7Hi-0,3913
+backdraft/render/sidecar.py,sha256=WIz9MGmJNLFw7M6o1dl4G9oWQVpu0dvcwuuxHYYgBJs,5555
+backdraft-0.2.0.dist-info/METADATA,sha256=wM2iRJ0-qnyPU_gS32ScL4YfuhtaQn4PVMk_mnZ_Pv4,10637
+backdraft-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+backdraft-0.2.0.dist-info/entry_points.txt,sha256=bk-TQiaxqdx0IySRm5RPoPip8DNJV6uokDWqG1prHwE,49
+backdraft-0.2.0.dist-info/licenses/LICENSE,sha256=23xc3FdDmd6cxW3y_c1SgjpzfFy1VMt26xCRKLh64TY,1070
+backdraft-0.2.0.dist-info/RECORD,,

backdraft-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

backdraft-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+backdraft = backdraft.cli:main

backdraft-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spencer Braun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.