backdraft 0.2.1__tar.gz → 0.3.0__tar.gz

backdraft-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+      - run: uv build

backdraft-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: release
+on:
+  release:
+    types: [published]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing: OIDC, no stored token
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

backdraft-0.3.0/.github/workflows/site.yml

@@ -0,0 +1,26 @@
+name: site
+on:
+  push:
+    branches: [main]
+    paths: ["site/**"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deployment
+        uses: actions/deploy-pages@v4

{backdraft-0.2.1 → backdraft-0.3.0}/.gitignore

@@ -22,3 +22,4 @@ uv.lock.bak
 
 # Claude Code session state and agent worktrees
 .claude/
+.private/

{backdraft-0.2.1 → backdraft-0.3.0}/DESIGN.md

@@ -1,12 +1,12 @@
 # Backdraft — Design
 
-Status: v0 design, 2026-07-27. Decisions below are made unless marked open. Research backing this is in [research/20260727-research-findings.md](research/20260727-research-findings.md).
+Status: v0 design, 2026-07-27. Decisions below are made unless marked open.
 
 ## The point
 
-Drop-in provenance for factual claims: one click from any claim to the evidence behind it. Extracted from what was built inside the HighRoad app, redesigned from scratch, released standalone. The working problem statement is **verification cost** — an analyst who can't show where a number came from either re-reads the document or doesn't use the output, and both outcomes destroy the value of extraction.
+Drop-in provenance for factual claims: one click from any claim to the evidence behind it. The working problem statement is **verification cost** — an analyst who can't show where a number came from either re-reads the document or doesn't use the output, and both outcomes destroy the value of extraction.
 
-Not a port. The app proved the product (citations worked great from the frontend) but its mechanism was path-dependent: random UUIDs, four citation grammars, four resolver copies, silent failure everywhere, anchors that die on reprocessing. We port the ideas, not the code.
+Designed from first principles against the failure modes that kill citation systems in practice: random anchor ids, competing citation grammars, duplicated resolvers, silent failure, anchors that die on reprocessing.
 
 ## Principles
 
@@ -14,7 +14,7 @@ Not a port. The app proved the product (citations worked great from the frontend
 2. **Content-addressed everything.** Anchors derive their identity from document content + location, not from a run. Reprocessing the same bytes yields the same anchors; citations survive.
 3. **The receipt travels with the claim.** An anchor is not a pointer — it is a pointer plus captured evidence: verbatim snippet, content hash, location. Defensible without reopening the source.
 4. **Failures are data.** Unresolvable tokens, drifted sources, unmatched claims are first-class records in reports and artifacts — never warn-and-drop.
-5. **Coordinates live in-band.** The app's only working sub-page attribution was Excel, because `[B10]` markers sat in the text the model read. Human-readable location in the token; side-channel geometry rots (bbox was plumbed through six layers and read by nothing).
+5. **Coordinates live in-band.** Sub-page attribution works when markers like `[B10]` sit in the text the model reads. Human-readable location in the token; side-channel geometry rots (a bbox plumbed through six layers ends up read by nothing).
 6. **The format is the product.** Substrates (skill, CLI, SDK, viewer) are thin shells over one spec + one library. Artifacts are self-describing and outlive any substrate (subtext's `$format` + embedded legend pattern).
 
 ## Architecture: three layers
@@ -27,13 +27,13 @@ Not a port. The app proved the product (citations worked great from the frontend
 ### 2. The library / CLI (the system)
 Four verbs:
 - **`ingest`** — deterministically anchor source documents (PDF/xlsx/md/…) into the registry: extract, locate, snapshot snippets, hash.
-- **`read` / `search`** — the gate. Emit token-marked context for a model. Search results are themselves mintable evidence (fixing pipeline-v2's gap where search returned nothing citable and forced a page read).
+- **`read` / `search`** — the gate. Emit token-marked context for a model. Search results are themselves mintable evidence (search that returns nothing citable forces a page read purely to obtain an anchor).
 - **`bind`** — postprocess a written document: resolve tokens, run enabled verification switches, backfill surface forms (doc names, pages, quotes), emit sidecar claims file + binding report.
 - **`render`** — produce the clickable artifact.
 
 ### 3. Substrates (sequenced)
 1. **Skill + CLI, together** (first release). The CLI is the system; the skill is ~a page instructing an agent to use it. Ships both the agent-native wedge and the zero-integration backfill demo.
-2. **SDK middleware** — wrap a model call: minted context in, bound citations out. The app-developer drop-in (LoanCore validation-layer shape).
+2. **SDK middleware** — wrap a model call: minted context in, bound citations out. The drop-in for application developers.
 3. **Viewer** — the artifact carries its own single-file viewer; a component version for embedding comes later.
 
 ## The registry
@@ -43,7 +43,7 @@ Four verbs:
 Tables (shape, not final DDL):
 - `documents` — path, display name, **slug**, content sha256, media type, ingest metadata.
 - `anchors` — token, document, locator, verbatim snippet, snippet sha256, created-by (ingest run).
-- `ledger` — session id, token, when shown. Records every token minted into context. Bind distinguishes "cited what you saw" from "cited a valid token you were never shown" — a caught hallucination class the app couldn't express.
+- `ledger` — session id, token, when shown. Records every token minted into context. Bind distinguishes "cited what you saw" from "cited a valid token you were never shown" — a caught hallucination class most systems cannot express.
 - `claims` (written at bind) — claim span text, source doc, citation tokens, verification records.
 
 FTS5 backs `search`. No server, no tenancy — single-analyst/single-project scope; multi-user is a substrate concern, not a registry concern.
@@ -54,7 +54,7 @@ FTS5 backs `search`. No server, no tenancy — single-analyst/single-project sco
 
 - `slug` — short kebab doc identifier assigned at ingest, unique per registry (`t12-audit`, `rent-roll-2025`).
 - `locator` — media-native:
-  - PDF/text: `p8` (page), `p8.c3` (chunk ordinal within page; chunking is deterministic with an explicit within-page ordinal — the column the app never had)
+  - PDF/text: `p8` (page), `p8.c3` (chunk ordinal within page; chunking is deterministic with an explicit within-page ordinal)
   - Excel: `Rent!B10`, `Rent!B10:C12` (sheet + cell/range, spreadsheet-native)
   - Prose files: heading-path or line-range forms (open detail)
 - `hash` — first 4+ hex of sha256 of the normalized snippet. Catches transcription typos, detects drift after re-ingest, and makes the token content-addressed. Registry extends length on collision.
@@ -65,11 +65,11 @@ Reserved extension — **declared derivations**: a claim whose value appears in
 
 ## The gate (context construction)
 
-Ported ideas from pipeline-v2's read tool, rebuilt local:
+The read tool's shape:
 - Unified dispatch: list docs → per-doc TOC of page/sheet summaries → page/range read → batch read. Short slugs everywhere.
 - Progressive disclosure with continuation, plus search hints.
-- **Excel**: sheet-per-page markdown table with `Row | A | B | …` headers and `[B10] value` cell prefixes — the representation that made Excel the app's only working sub-page attribution. Hardening kept: dimension caps, inflated-sheet placeholders, trimming.
-- Fixes over the app: search mints citable snippet tokens; Excel long-context gets structural navigation (detected regions/ranges) instead of char-offset slicing (open design area).
+- **Excel**: sheet-per-page markdown table with `Row | A | B | …` headers and `[B10] value` cell prefixes — the representation that makes cell-level attribution work. Hardening: dimension caps, inflated-sheet placeholders, trimming.
+- Search mints citable snippet tokens; Excel long-context gets structural navigation (detected regions/ranges) rather than char-offset slicing (open design area).
 
 The skill's core instruction is a substitution: for source documents, use `backdraft read`/`search`, not raw Read/Grep.
 
@@ -97,11 +97,11 @@ Independent checks per citation, recorded as graded evidence, never gating gener
 | 3 | `entail` | Model judge: does snippet support claim — tiny closed question, batchable, async | qualitative |
 | 4 | `recompute` | Deterministic re-execution of declared derivations | derived values |
 
-Rationale for default-off: out of the box this is pure provenance (one click to the receipt); verification is opt-in per claim class. Rung-pass rates aggregated per run/model double as an eval substrate (the Clarion use).
+Rationale for default-off: out of the box this is pure provenance (one click to the receipt); verification is opt-in per claim class. Rung-pass rates aggregated per run/model double as an eval substrate.
 
 ## Modes
 
-- **Front-walk** — citations minted during generation; bind resolves against the session ledger. The high-quality integrated path (what the app did).
+- **Front-walk** — citations minted during generation; bind resolves against the session ledger. The high-quality integrated path.
 - **Backfill** — an existing document + ingested sources; for each claim: search → propose anchors → bind via the fuzzier strategies (overlap, value-trace, structured lookup). Unmatched claims land in an explicit unresolved list, not silent non-attribution. Zero integration required — the demo wedge.
 
 Same anchors, same bind, same artifact out.
@@ -127,9 +127,9 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-07-27 | CLI unified on the gate's patterns: shared `cli_context` (constants, discovery, sessions, one error guard mapping `BackdraftError` → exit 1), `Annotated` params, relative imports. Test fakes renamed so the real and fake registries cannot be confused. |
 | 2026-07-27 | File naming is part of the artifact format, owned by `kernel/artifact.py`: `<stem>.bound.md`, `<stem>.backdraft.json`, `<stem>.backdraft.html`, `<stem>.footnotes.md`. |
 | 2026-07-27 | `bind --check entail` without the extra records `skip` verdicts carrying the reason — verifiers never gate, including at the CLI layer. |
-| 2026-07-27 | **Supersedes "VLM when key present":** credentials are explicit. Ambient provider keys (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`) are never read; a credential reaches backdraft only via `--config`, a `BACKDRAFT_*` variable, or `.backdraft/env` (`init` writes a template). `vlm_ready` — the `auto` gate — is therefore equivalent to consent. Decided after a real unapproved-spend incident during the Darnell trial: presence of a generic key in the environment is not consent to spend it or send documents to its provider. |
+| 2026-07-27 | **Supersedes "VLM when key present":** credentials are explicit. Ambient provider keys (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`) are never read; a credential reaches backdraft only via `--config`, a `BACKDRAFT_*` variable, or `.backdraft/env` (`init` writes a template). `vlm_ready` — the `auto` gate — is therefore equivalent to consent. Decided after a real unapproved-spend incident during the first field trial: presence of a generic key in the environment is not consent to spend it or send documents to its provider. |
 | 2026-07-28 | **Reader doctrine (supersedes "no script"):** the artifact is designed for two readers — the writer verifying the AI's work, and a normal person the document is sent to — in three disclosure layers: the document (editorial typography, quiet marks), the footnote (click a claim → the source's own words, named and paged — no tokens, no hashes, no jargon), and the record (one deliberate step to the full machine-readable layer). **Success is silent; only failure speaks**: a fully-resolved artifact looks like a well-made document, while unresolved citations announce themselves before the reader invests belief. The load-bearing constraint is *no network, single file* — enforced by a CSP `meta` tag (`default-src 'none'`) — not *no script*: inline JS is allowed as progressive enhancement over a CSS-only baseline that survives script-stripping. Decided after field use: the v1 artifact rendered success and failure at equal volume and read as machinery, not a document. |
-| 2026-07-28 | **Evidence embeds in the artifact (supersedes "no page images in v0"):** the footnote layer carries the evidence itself, not just the quote — the cited page as an image, the cited cell in a mini-grid window (neighbors, row labels, column headers). Bounded by *what is cited*, never the corpus, so a memo citing ten pages costs ~2–3 MB; `--lean` skips images. Evidence is assembled at **bind** (the step that has the registry) and travels in the sidecar; render stays registry-blind and the artifact stays reproducible from the two files a reader was handed. For the VLM path, the page image the model was shown is stored at **ingest** — for a non-deterministic extractor the input pixels are the only reproducible snapshot, so the image completes the receipt chain (claim → quote → page). Reference shapes ported from embed-ses `generate-preview`: WebP quality 85 for pages; sheet windows as compact JSON with typed cell values and column-letter headers. |
+| 2026-07-28 | **Evidence embeds in the artifact (supersedes "no page images in v0"):** the footnote layer carries the evidence itself, not just the quote — the cited page as an image, the cited cell in a mini-grid window (neighbors, row labels, column headers). Bounded by *what is cited*, never the corpus, so a memo citing ten pages costs ~2–3 MB; `--lean` skips images. Evidence is assembled at **bind** (the step that has the registry) and travels in the sidecar; render stays registry-blind and the artifact stays reproducible from the two files a reader was handed. For the VLM path, the page image the model was shown is stored at **ingest** — for a non-deterministic extractor the input pixels are the only reproducible snapshot, so the image completes the receipt chain (claim → quote → page). Reference shapes: WebP quality 85 for pages; sheet windows as compact JSON with typed cell values and column-letter headers. |
 | 2026-07-28 | **Exhibits: the evidence-first inversion.** The artifact carries a second reading mode: every source document with the data points cited from it, each with its evidence context and backlinks to the claims that lean on it — "this memo rests on N data points across M documents." Ranking is deterministic in v1 (an anchor cited by three claims outranks one cited once); model-judged importance is a later switch. This is the skeptical reader's entry point and the writer's spot-check checklist. |
 
 ## Open
@@ -139,8 +139,8 @@ substrates); this list is questions still awaiting a decision:
 
 - Re-bind/orphan pass on re-ingest of changed docs (chunk ordinal drift)
 - Prose-file locator forms; slug assignment/collision rules (the trailing-hyphen
-  truncation from the Darnell trial lives here)
+  truncation from the first field trial lives here)
 - Distribution: published to PyPI as `backdraft` 0.2.0 (2026-07-28); domain
   backdraft.dev acquired; still open: skill registration, deploying site/
-- First external user (LoanCore validation layer vs Clarion eval substrate vs
+- First external user (design-partner validation layer vs eval substrate vs
   open release feedback)

{backdraft-0.2.1 → backdraft-0.3.0}/PKG-INFO

@@ -1,7 +1,11 @@
 Metadata-Version: 2.4
 Name: backdraft
-Version: 0.2.1
+Version: 0.3.0
 Summary: Drop-in provenance for factual claims: one click from any claim to the evidence behind it.
+Project-URL: Homepage, https://backdraft.dev
+Project-URL: Documentation, https://backdraft.dev/docs.html
+Project-URL: Repository, https://github.com/spencerbraun/backdraft
+Project-URL: Roadmap, https://github.com/spencerbraun/backdraft/blob/main/ROADMAP.md
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.13
@@ -45,7 +49,8 @@ cd demo
 ```
 
 **Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
-cells for spreadsheet sheets.
+cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff, through the vision model), plain text and Markdown.
 
 ```console
 $ backdraft init
@@ -210,12 +215,12 @@ 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):
+Three agent skills ship inside the package, and the CLI installs them:
 
 ```bash
-cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
 ```
 
 | Skill | For |

{backdraft-0.2.1 → backdraft-0.3.0}/README.md

@@ -28,7 +28,8 @@ cd demo
 ```
 
 **Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
-cells for spreadsheet sheets.
+cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff, through the vision model), plain text and Markdown.
 
 ```console
 $ backdraft init
@@ -193,12 +194,12 @@ 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):
+Three agent skills ship inside the package, and the CLI installs them:
 
 ```bash
-cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
 ```
 
 | Skill | For |

{backdraft-0.2.1 → backdraft-0.3.0}/ROADMAP.md

@@ -14,7 +14,7 @@ losing it. Items graduate by getting built and deleted.
   2026-07-28 pending a real audience for it.*
 
 - **Excel region maps and range reads** — navigation for large sheets. The
-  research is done (`research/20260727-excel-region-detection.md`): a
+  research is done (notes kept privately): a
   deterministic detection cascade (declared tables → named ranges → print
   areas / freeze panes → merged-aware connected components) producing a
   table of contents per sheet. Two hard constraints from that research:
@@ -23,24 +23,22 @@ losing it. Items graduate by getting built and deleted.
 
 ## Formats
 
-Today: PDF (VLM primary, text-layer floor), XLSX, plain text and Markdown.
-Each new format is one Extractor implementing the existing protocol — pages
-out, receipts quotable, nothing downstream changes.
+Today: PDF (VLM primary, text-layer floor), XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff — VLM, the file is its own snapshot), plain text and
+Markdown. Each new format is one Extractor implementing the existing
+protocol — pages out, receipts quotable, nothing downstream changes.
 
-- **Images (png, jpeg, tiff)** — a photographed or scanned page is a
-  one-page document; the VLM extractor already is this pipeline minus the
-  pdf2image step, and the source file is its own stored snapshot. Cheapest
-  high-value addition.
-- **CSV** — a workbook with one sheet; reuse the sheet representation (A1
-  refs, cell anchors) wholesale. Deterministic, keyless, near-trivial.
 - **DOCX** — leases, LOIs, agreements. Structured XML, so the deterministic
   path is the good path (paragraphs and tables straight out of the file, no
-  OCR); tables render to markdown like sheets do.
+  OCR); tables render to markdown like sheets do. Needs a decision row
+  first: DOCX has no pages, so locators want synthesizing from heading
+  sections.
 - **PPTX** — offering memoranda that arrive as decks. Slide text is
-  extractable deterministically as the floor; the faithful path renders
-  slides to images through the VLM like PDF pages.
-- **XLS / XLSM** — legacy and macro workbooks. openpyxl covers xlsm;
-  xls wants the calamine fallback embed-ses already proved in production.
+  extractable deterministically as the floor; the faithful path (slide
+  images) needs a renderer on PATH, LibreOffice or similar, behind a
+  capability check like poppler's.
+- **XLS** — legacy workbooks; python-calamine as the tolerant fallback
+  behind an extra.
 - **Someday**: HTML pages, email (.eml) — both arrive in diligence folders,
   both have messy identity questions (what is "the source" of a web page?)
   that deserve a decision row before code.
@@ -52,10 +50,11 @@ out, receipts quotable, nothing downstream changes.
   malformed-on-purpose). The field-trial case: "about 4% of embedded
   loss-to-lease," derived from two cited cells, currently an honest
   value-trace fail with nowhere to point.
-- **Sheet styling fidelity** — carry bold / fills / merges / column widths
-  through ingest so sheet evidence looks like the workbook, not just its
-  values. The shapes to port are embed-ses `generate-preview`'s
-  (`SheetData.cell_styles`, `merged_ranges`, `column_widths`, `frozen_panes`).
+- **Merged-cell and frozen-pane rendering** — ingest already captures
+  `merged` and `frozen` in sheet meta; the artifact's sheet view renders
+  neither yet (merges want colspan/rowspan grid building, frozen panes want
+  a second sticky axis). Styling, number formats, and column widths already
+  render.
 - **Living documents** — re-ingest, re-bind, and a drift-first report: "these
   claims cite figures that changed; cited-then vs. now." The primitives
   (generations, `drifted`, the word-diff) all exist; the missing piece is a
@@ -64,8 +63,8 @@ out, receipts quotable, nothing downstream changes.
   and `--to json` contracts are already shaped for it), and a client-side
   drag-drop viewer page (no upload — the file never leaves the reader's
   machine).
-- **Distribution** — PyPI publish decision and the "backdraft" name check;
-  install is git-only until then.
+- **Distribution** — published on PyPI; still queued: a skills-registry
+  listing when one becomes the standard channel.
 
 ## Someday
 

{backdraft-0.2.1 → backdraft-0.3.0}/SPEC.md

@@ -44,9 +44,9 @@ backdraft/
     extract/
       base.py               # Extractor protocol + registry of extractors
       pdf_text.py           # pdfplumber text-layer; paragraph breaks rebuilt from line geometry
-      xlsx.py               # calamine/openpyxl → markdown table with [B10] refs (port the app's representation)
+      xlsx.py               # openpyxl → markdown table with [B10] refs
       text.py               # md/txt passthrough
-      vlm.py                # [vlm] extra: zerox-minimal pattern (pdf→images→VLM per page)
+      vlm.py                # [vlm] extra: pdf→images→VLM per page
       vlm_settings.py       # provider/model/base-url resolution; stdlib-only, imports without the extra
     gate/
       reader.py             # ls / toc / read page-range → token-marked context; records ledger
@@ -113,7 +113,7 @@ Deterministic, pure: `chunk(page_text) -> [Chunk(ordinal, text, start, end)]`.
 1. Split on blank lines: regex `\n\s*\n`.
 2. Merge forward: any segment < 200 chars merges into the following segment (the last merges backward).
 3. Split long: any segment > 2400 chars splits at the sentence boundary nearest each 1200-char multiple (sentence = terminal `.!?` + space + uppercase/digit start; no abbreviation table in v0 — splitting slightly wrong is fine, it only shifts chunk boundaries deterministically). A final piece under 200 chars merges backward, since merging ran before splitting and could not see it; a chunk is therefore under 200 chars only when it is the only chunk on its page.
-4. Ordinals `c1..cN` in order. No per-page rebalancing, no chunk-count caps (the app's balancing caused tail-loss bugs; deliberately dropped).
+4. Ordinals `c1..cN` in order. No per-page rebalancing, no chunk-count caps (rebalancing causes tail-loss bugs; deliberately avoided).
 
 Anchor identity for a chunk: (extraction, page number, ordinal). `start`/`end` are char offsets into the page text — stored, enabling future span/region features.
 
@@ -218,7 +218,7 @@ class Extractor(Protocol):
     def extract(self, path: Path, config: dict) -> Iterator[ExtractedPage]: ...
 ```
 
-Registered in a plain dict; `ingest --extractor auto` picks the first `can_handle`, built-ins ordered `xlsx, pdf-text, text`. `vlm` (extra) follows the zerox-minimal pattern — pdf→images→VLM per page, OpenAI-compatible client, model configurable. **For PDFs, `auto` prefers `vlm` when it is installed and an API key is configured** (glossy layouts and info boxes extract badly from the text layer, and the snapshot is the receipt); otherwise it falls back to `pdf-text` and prints a one-line nudge naming the VLM option. An explicit `--extractor` always wins. xlsx ports the app's representation: `Row | A | B...` header, `[B10] value` prefixes, dimension caps, inflated-sheet placeholder pages; cell values are never rounded, since the snapshot is the receipt a claim is traced against. `pdf-text` reconstructs paragraph breaks from line geometry before handing the page over, so the chunker's blank-line rule has something to fire on.
+Registered in a plain dict; `ingest --extractor auto` picks the first `can_handle`, built-ins ordered `xlsx, pdf-text, text`. `vlm` (extra) is pdf→images→VLM per page, OpenAI-compatible client, model configurable. **For PDFs, `auto` prefers `vlm` when it is installed and an API key is configured** (glossy layouts and info boxes extract badly from the text layer, and the snapshot is the receipt); otherwise it falls back to `pdf-text` and prints a one-line nudge naming the VLM option. An explicit `--extractor` always wins. xlsx's representation: `Row | A | B...` header, `[B10] value` prefixes, dimension caps, inflated-sheet placeholder pages; cell values are never rounded, since the snapshot is the receipt a claim is traced against. `pdf-text` reconstructs paragraph breaks from line geometry before handing the page over, so the chunker's blank-line rule has something to fire on.
 
 ## Gate (gate/)
 

{backdraft-0.2.1 → backdraft-0.3.0}/demo/generate_sources.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from pathlib import Path
 
 from openpyxl import Workbook
-from openpyxl.styles import Alignment, Font
+from openpyxl.styles import Alignment, Font, PatternFill
 from reportlab.lib.enums import TA_JUSTIFY
 from reportlab.lib.pagesizes import LETTER
 from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
@@ -306,13 +306,42 @@ def build_xlsx(path: Path) -> None:
     for row in ASSUMPTIONS:
         assumptions.append(list(row))
 
+    # Styling, the way a sponsor's model actually looks: a dark header band,
+    # inputs in modeling blue, currency and percent number formats, a frozen
+    # header row. Values are untouched — the snapshot text and every token
+    # are identical with or without this block.
+    header_fill = PatternFill("solid", fgColor="FF1F4E79")
     for sheet in (rent, assumptions):
         for cell in sheet[1]:
-            cell.font = Font(bold=True)
+            cell.font = Font(bold=True, color="FFFFFFFF")
+            cell.fill = header_fill
             cell.alignment = Alignment(horizontal="left")
         widths = {"A": 30, "B": 14, "C": 14, "D": 16, "E": 16, "F": 28}
         for column, width in widths.items():
             sheet.column_dimensions[column].width = width
+        sheet.freeze_panes = "A2"
+
+    for row in range(2, 6):  # unit-mix money and occupancy columns
+        for column, fmt in (("C", "#,##0"), ("D", '"$"#,##0'), ("E", '"$"#,##0')):
+            rent[f"{column}{row}"].number_format = fmt
+        rent[f"F{row}"].number_format = "0.0%"
+    for cell in rent[7]:
+        cell.font = Font(bold=True)
+    rent["F7"].number_format = "0.0%"
+    rent["B9"].number_format = '"$"#,##0'
+    rent["B10"].number_format = "0.0%"
+    rent["B11"].number_format = '"$"#,##0'
+
+    input_font = Font(color="FF0000CC")  # modeling convention: inputs in blue
+    percent_rows = (2, 3, 5, 6, 7, 8, 12, 16)
+    money_rows = (9, 10, 11, 14)
+    for row in range(2, 17):
+        cell = assumptions[f"B{row}"]
+        cell.font = input_font
+        if row in percent_rows:
+            cell.number_format = "0.00%"
+        elif row in money_rows:
+            cell.number_format = '"$"#,##0'
 
     book.save(path)