OSprey

Evidence-first municipal bond extraction and validation

I built OSprey, an evidence-first workflow for turning land-secured municipal bond Official Statements into a reviewable pricing-comps dataset. The production project combined document ingestion, deterministic extraction, field-level source evidence, human review gates, financial validation, and a tightly controlled Excel export.

For the final internal delivery, I assembled a 37-deal / 98-maturity-row Texas comp workbook, completed a 407-field source audit, and ran 17 automated export checks. The production workbook, source documents, employer materials, credentials, and private development history are intentionally not included here.

This repository is a sanitized, runnable portfolio edition. Every issuer, amount, date, and description in examples/ is fictional.

What this demonstrates

• Evidence-linked extraction: every extracted field retains its source line.
• Correct date semantics: the comp Date is the pricing date, not the settlement/delivery date.
• Fail-closed validation for missing evidence, invalid chronology, duplicate or unordered maturities, and implausible pricing values.
• Deterministic calculations for MMD spread and debt per lot.
• Reproducible export with an explicit 13-column contract.
• Automated regression tests for parsing, date semantics, calculations, validation, and exact export output.

flowchart LR
    A["Official Statement"] --> B["Deterministic extraction"]
    B --> C["Field + source evidence"]
    C --> D["Validation and review gates"]
    D --> E["Pricing comps export"]

Loading

Quick start

The showcase has no runtime dependencies beyond Python 3.11+.

python -m pip install -e .
osprey examples/synthetic_official_statement.txt \
  --output /tmp/synthetic_pricing_comps.csv

Expected terminal output:

Validated 1 synthetic deal with 3 maturity rows.
Pricing date: 2026-03-12 | Delivery date: 2026-04-02
Wrote /tmp/synthetic_pricing_comps.csv

Run the test suite:

python -m pip install -e '.[dev]'
pytest

Repository map

Path	Purpose
src/texas_muni_showcase/parser.py	Parses a small OS-like text fixture and captures line evidence
src/texas_muni_showcase/validation.py	Applies fail-closed data-quality gates
src/texas_muni_showcase/exporter.py	Produces the public 13-column CSV contract
examples/	Fictional source input and expected output
tests/	Unit and end-to-end regression tests
docs/architecture.md	Production-inspired architecture and public/private boundary
docs/validation.md	Validation rules and financial calculations

Scope and privacy

This is a compact engineering demonstration, not the production application and not investment research. It does not retrieve documents, automate EMMA access, make credit judgments, or contain real transaction data. See NOTICE.md and SECURITY.md.