cto-legends · module specification · intelligence · v0.3.0
legends-grant: Nationwide US Grant Discovery, SQLite Evidence Ledger & Proposal Workbench
Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.
GitHub Repository (https://github.com/avalonreset/legends-grant) · Handoff: cto-legends handoff legends-grant
legends-grant (runtime module grant_engine) is a zero-API-key, Python 3.11+ standard-library CLI and agent workflow for US grant discovery, immutable evidence collection, deterministic qualification review, and evidence-linked proposal drafting. Serving businesses, nonprofits, tribes, governments, researchers, and individuals across federal, state, local, and private funding, it ships with a researched machine-readable source registry (`grant_engine/data/us-sources.json`) covering all 50 US states, DC, and 5 territories without imposing a federal-first bias.
The runtime connects source planning (`plan`) with bounded live discovery against public Grants.gov APIs and four vetted CommonGrants state feeds (California, Pennsylvania, Washington, and Maryland), ingesting public opportunity records into a local SQLite evidence store (`ingest`, `report`, `search`, `changes`, `export`, `replay`, `check`) with immutable revisions and strict separation from private client data. For active opportunities, `collect-document` and `verify-documents` fetch and hash-verify official HTTPS notices and PDF attachments (with optional `.[pdf]` pypdf extraction), `review` evaluates mandatory eligibility predicates against separate private applicant facts, and the offline `proposal` workbench (`scaffold`, `check`, `render`) enforces word limits, exact decimal budget arithmetic, `fact_refs` citation resolution, and placeholder screens (`[[OPEN: ...]]`) on agent-written grant narratives.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Ask a raw frontier LLM to 'find grants and write my proposal' and it will hallucinate expired programs, confuse loans or historical awards with open grants, invent applicant statistics or partner commitments to sound persuasive, and miscalculate budget tables. A static markdown prompt cannot query live Grants.gov or CommonGrants endpoints, track material notice amendments across SQLite snapshots, verify exact UTF-8 SHA-256 document quotes, or mechanically block a proposal when budget lines fail to sum or required attachments are missing.
- Immutable SQLite Evidence Ledger & Snapshot Diffing: `grant_engine ingest` separates retrieval observations from material field changes in SQLite, preventing older feed syncs from overwriting newer records, rejecting known credential/profile fields, and flagging exact program/cycle field diffs via `grant_engine changes` without assuming an uncollected record is closed.
- Content-Addressed Notice Collection & Quote-Bound Qualification: `collect-document` downloads public HTTPS notices within strict bounds (10 MB, 20s HTTP timeout) and records byte and extracted-text hashes. `grant_engine review` verifies that every eligibility citation quote appears verbatim in the UTF-8 document text (`sha256(text.encode('utf-8'))`) and evaluates typed predicates (`equals`, `one_of`, `at_least`, `at_most`, `contains`, `manual`) against a separate private facts file (`private_facts_sha256`).
- Deterministic Proposal Checker & Decimal Budget Arithmetic: `grant_engine proposal check` validates that grant budget lines (enforced as exact decimal strings, rejecting floating-point JSON numbers) sum precisely to the total requested, enforces per-question and total alphanumeric word limits, verifies that every answer's `fact_refs` resolve to declared `historical`, `estimate`, or `commitment` facts, and blocks unresolved `{{ }}`, `[[ ]]`, `???`, or `TODO/TBD/TBC/XXX` markers.
- Hard Storage Isolation Between Public Evidence & Private Facts: Public opportunity evidence lives in SQLite, while applicant facts, qualification assessments, and proposal drafts stay in private case files. File-identity, resolved-suffix, and SQLite magic-byte guards prevent `proposal` commands from ever overwriting input files or targeting a public evidence database.
CLI Subcommands & Capability Surface
python -m grant_engine plan --jurisdiction <US|STATE> --applicant-type <type> --purpose <tag> & discover grants-gov | common-grants — 56-Jurisdiction Source Planning & Bounded Feed Discovery: Combines national and jurisdiction-specific sources across 50 states, DC, and 5 territories, generating explicit `agent_research` tasks for directory sources without API adapters. Retrieves bounded public opportunity packets (`--limit`, `--page-size`) from Grants.gov and the CA, PA, WA, and MD CommonGrants feeds.python -m grant_engine ingest | report | search | check | export [--history] | replay | changes --before <a.json> --after <b.json> — SQLite Evidence Ingestion, Keyword Search & Snapshot Diffs: Stores public opportunity records with immutable revision history and collection receipts in SQLite. Supports offline keyword search (up to 10,000 records / 50 MB) with visible source authority, funding-instrument, and freshness labels, deterministic history replay into clean databases, and material change detection across exports.python -m grant_engine collect-document --url <https-url> --bundle <dir> & python -m grant_engine verify-documents --bundle <dir> — Bounded Official Notice & Attachment Collection: Fetches a single public HTTPS notice or attachment (bounded to 10 MB and 20s), saves raw bytes and extracted text under content hashes, inventories document links, and writes an immutable receipt. With the optional `.[pdf]` extra (`pypdf`), extracts text up to 200 pages and 2M characters within a 15s parser limit.python -m grant_engine review --review <qualification-review.json> --facts <private-facts.json> --output <assessment.json> — Evidence-Linked Qualification Review Engine: Evaluates a reviewed set of mandatory notice rules (`schema_version: 1`) against a separate private applicant facts file without mutating inputs or writing to SQLite. Verifies UTF-8 document text SHA-256 hashes, exact quoted passages, 1-to-30-day freshness windows, and typed predicates to return `eligible-for-review`, `ineligible`, or `unresolved` with an application checklist.python -m grant_engine proposal scaffold | check | render --proposal <proposal.json> --facts <facts.json> --output <out> — Offline Grant Proposal Scaffolding & Mechanical Constraint Checker: Scaffolds structured proposal and fact files (`historical`, `estimate`, `commitment` kinds; `private` or `shareable` visibility). `proposal check` enforces word counts, `fact_refs` resolution, decimal-string budget summation, required attachment states, privacy leaks in shared evidence, and `[[OPEN: ...]]` placeholder blockers while emitting `claim_to_review` warnings for manual verification.docs/PROPOSAL-WRITING.md + python -m grant_engine proposal render --proposal <proposal.json> --facts <facts.json> --output <draft.md> — 9-Stage Evidence-Audited Narrative & Mock Review Workflow: Pairs the deterministic CLI workbench with a 9-stage agent drafting protocol that requires inline fact ID citations, visible `[[OPEN: ...]]` gaps instead of invented statistics, and a cold-read Stage 7 sentence-by-sentence claim/evidence audit table before rendering the private Markdown review package.
Raw Frontier LLM vs. legends-grant Execution Matrix
- Source Discovery & Ordering: Raw LLM (Defaults to generic federal guesses or hallucinates state/local programs from stale pre-training memory.) vs. Module (Plans across a 56-jurisdiction registry tailored to applicant type and purpose, plus bounded Grants.gov and 4 state CommonGrants feeds.) — `grant_engine doctor` and `plan` outputs distinguish live adapter feeds from explicit `agent_research` directory tasks.
- Eligibility & Rule Evaluation: Raw LLM (Reads a snippet or third-party summary and declares the applicant 'eligible' without checking amendments or exclusions.) vs. Module (Requires authoritative notice hashes, verbatim quote citations, complete document inventory attestation, and typed predicate evaluation.) — `grant_engine review` forces `unresolved` whenever any document is stale, unreviewed, conflicted, or uses a `manual` clause.
- Proposal Narrative Integrity: Raw LLM (Invents beneficiary headcounts, letters of support, or past outcomes ('hundreds of teens') to polish prose.) vs. Module (Requires every answer to cite `fact_refs` from the private facts file and keeps missing evidence as explicit `[[OPEN: ...]]` notes.) — `grant_engine proposal check` flags unresolved `[[...]]` placeholders, uncited answers, and unknown fact IDs as mechanical blockers.
- Budget & Privacy Enforcement: Raw LLM (Produces floating-point rounding errors, mismatched budget tables, or mixes private client data into shared corpora.) vs. Module (Enforces exact decimal-string budget arithmetic, blocks `private` facts in shared evidence lists, and isolates SQLite from client files.) — Hardlink file-identity and SQLite magic-byte guards reject unsafe output paths; `unittest` verifies 100% of schema constraints.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does legends-grant separate the SQLite opportunity store from applicant facts and proposal files?
- Public funding notices, feed snapshots, and collection receipts are reusable public evidence, whereas an applicant's EIN, financials, staff details, and draft narratives are confidential. Keeping applicant facts in separate private JSON files (with SQLite magic-byte and hardlink guards on output paths) prevents cross-client data leakage.
- What does mechanical_checks_passed mean in grant_engine proposal check?
- It means deterministic constraints hold: all required answers are present, word counts are within per-question and total limits, every answer cites valid `fact_refs`, grant budget lines (as decimal strings) sum exactly to the total requested, no unallowable cost categories or unresolved `[[OPEN: ...]]` placeholders remain, and no `private` facts leak into shared evidence. Substantive entailment and rubric alignment are still verified through the Stage 7 mock review and recorded in `substantive_review`.
- Does legends-grant require paid API keys or third-party packages to run?
- No. The core runtime (`grant_engine`) uses only the Python 3.11+ standard library and queries public Grants.gov and CommonGrants endpoints without API keys. Installing the optional `.[pdf]` extra adds `pypdf` for local PDF text extraction; even without it, `collect-document` still preserves raw PDF bytes and SHA-256 receipts.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.