Narrative vs. Numbers
Does management allocate capital and produce operating results consistent with what it says is strategically important?
This backend reads a company's 10-K, extracts what management claims is strategically important, pulls the XBRL financial facts for the same years, and scores whether the spending and the results actually back the claims.
The split is deliberate: the LLM only ever produces a label, a category, a quote and a confidence. Every number and every score comes from deterministic code.
Running it
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env # then set SEC_USER_AGENT to a real contact address
.venv/bin/python -m uvicorn app.main:app --reload
SEC rejects requests that do not identify the caller, so SEC_USER_AGENT must contain a real email address.
Then open http://localhost:8000 for the UI, or go straight to the API below.
With LLM_PROVIDER=stub (the default) the pipeline runs end to end without an API key, using a checked-in fixture for the extraction step. Every analysis produced this way says so in its limitations. Set LLM_PROVIDER=openai or anthropic with the matching key for a real extraction.
.venv/bin/python -m pytest
API
All routes are under /api/v1.
| Method | Path | Purpose |
|---|
| GET | /companies/{ticker} | Resolve a ticker to its SEC company record |
| GET | /companies/{ticker}/filings?form=10-K&limit=3 | Recent filings |
| GET | /companies/{ticker}/financials?annual_periods=3 | Normalized annual metrics |
| POST | /analysis | Start an analysis, returns an id immediately |
| GET | /analysis/{analysis_id} | Fetch the result |
curl -X POST localhost:8000/api/v1/analysis \
-H 'Content-Type: application/json' \
-d '{"ticker": "MSFT", "annual_periods": 3}'
Analysis runs through a durable SQLite-backed queue, so the HTTP connection is not held open and interrupted work is re-queued after a process restart. Poll the second endpoint until status is complete or failed. Equivalent completed reports are reused for 24 hours by default.
The UI
Served from / by the same process, as plain HTML, CSS and JS calling the same /api/v1 routes. There is no build step and no framework: app/static/ is three files, mounted with StaticFiles.
The layout is built around the one distinction that matters here, and it is carried by the typography: a serif holds what management said — the quoted sentence, its label and category, all model-produced — and tabular sans holds what the numbers did, which is arithmetic over XBRL facts. Metric identifiers stay in mono because that is what the API returns.
Each claim opens onto its own arithmetic: the three components with their weights and the contribution of each, then every metric the category permits, showing the raw observation next to the threshold that makes it decisive, the resulting 0–100 score as a bar diverging from 50, and one cell per scored year so persistence is visible rather than asserted. Raw filed figures and derived normalized figures are kept in separate, labelled blocks of the financial record, so a reported dollar value is never mistaken for a score.
Gaps are shown, not smoothed over. A missing component says its weight was redistributed, the base year is marked as supplying a denominator only, and if the analysis ran on the stub provider the report says so above the score rather than in a footnote — because that caveat changes how everything below it should be read.
How a score is built
Alignment = 0.50 x action evidence + 0.30 x outcome evidence + 0.20 x persistence
Each strategy category maps to approved metrics together with the direction each must move, in app/strategy/evidence_mapper.py. A metric scores 50 + 50 * clamp(direction * value / threshold, -1, +1), where the threshold is 15% for year-over-year rates and 1 percentage point for margin and intensity shifts. Action evidence asks whether management spent the money; outcome evidence asks whether the result moved; persistence asks whether it held up across years.
When a component has no data its weight is redistributed across the rest and the gap is listed in limitations rather than scored as a zero.
Analytical confidence is tracked separately from alignment, because a company can look well aligned on very thin evidence.
Every priority in the response carries its component breakdown and the metric values behind it, so no score is ever unexplained:
{
"label": "Expand AI infrastructure capacity",
"category": "capacity_investment",
"score": 100.0,
"components": { "action_evidence": 100.0, "outcome_evidence": 100.0, "persistence": 100.0 },
"supporting_metrics": [
{ "metric": "capex_growth", "value": 0.7962, "expected_direction": 1, "score": 100.0 }
]
}
Design notes
Strategy is read from the most recent 10-K only. That filing states the current plan; the earlier years supply the financial history that persistence is measured against. Tracking how the stated strategy itself drifts across years is a future extension, not part of this MVP.
Section parsing. A plain Item N search is unusable: one Microsoft 10-K produces 119 matches across the table of contents, page headers and cross-references, and inline-XBRL styling splits headings into ITEM 1. B USINESS. The parser requires the section title beside the item number, matches it character by character with optional gaps, and takes the last such header as the section start.
No pandas. Each metric series is three to five annual points. Plain dicts are easier to read and test.
Caching. Mutable SEC indexes and facts use the TTL from CACHE_TTL_HOURS; immutable filing text and LLM extractions remain reusable until the cache needs space. Extractions are keyed by filing, prompt version, provider and model. CACHE_MAX_MB bounds the cache for a small persistent volume.
Hosting
The recommended deployment is one Docker service on Railway Hobby with a 1 GB persistent volume mounted at /app/data. The checked-in image, production configuration checks, durable serial worker and request limits are ready for that setup. Follow DEPLOYMENT.md for the exact dashboard values and verification commands.
Layout
app/
static/ the UI: index.html, app.css, app.js
clients/ SEC HTTP access, disk cache, LLM provider abstraction
ingestion/ filing lists, 10-K section parsing, XBRL to annual table
finance/ canonical tag mapping, derived metrics, trends
strategy/ extraction prompt handling, taxonomy, strategy-to-metric map
scoring/ alignment, contradictions, confidence
models/ SQLAlchemy tables and Pydantic schemas
db/ engine, session, repositories
pipeline.py orchestration
prompts/ versioned extraction prompt
tests/ unit and integration tests over stored fixtures
Companies, filings and completed analyses are persisted to SQLite. Priorities are stored inside the analysis result rather than in their own table, since nothing in the MVP queries them independently.
