equity-desk

A grounded AI equity-research analyst — give it a ticker; it pulls the real SEC filings and market prices, computes the fundamentals itself, and writes a cited buy/hold/sell memo in which every number is enforced to trace to a source. The LLM is never allowed to invent a figure.

Why grounded?

Most "AI stock analyst" projects hand a ticker to an LLM and hope. An AI that invents numbers in a financial report isn't a demo problem — it's the reason enterprises don't ship LLM features. equity-desk inverts the trust:

1. Hand-rolled Python computes every number — ratios, peer ranks, a DCF fair value — from SEC EDGAR filings and market prices.
2. The LLM receives a fact sheet of pre-computed, source-tagged figures. Its only job is prose.
3. A citation guard scans the finished memo and rejects it if any number matches no fact. Fail loud, not quiet.

Headline metric: 100% of numbers in every memo trace to source — enforced by a test, not a promise.

flowchart LR
    T[ticker] --> D[data layer\nEDGAR + yfinance\nlive, cached fallback]
    D --> A[analysis engine\nratios · peers · DCF\nhand-rolled]
    A --> F[fact sheet\nevery number + its source]
    F --> W[LLM writer\nqwen local / claude opt-in\nprose only]
    W --> G{citation guard}
    G -->|every number traces| M[cited memo ✓]
    G -->|invented number| X[memo rejected ✗]

What the analysis engine computes (all hand-rolled)

Axis	Metrics
Valuation	P/E, P/S, EV/EBITDA, market cap
Profitability	gross→net margins, return on equity
Growth	revenue YoY, EPS
Leverage	debt/equity, net debt
Peers	the same ratios computed from each peer's own filings; median comparison
Intrinsic value	5-year DCF over EDGAR free cash flow → fair value vs price, assumptions stated
Verdict	a stated rule over DCF gap + peer valuation — decided by code, never by the LLM

The interesting parts are deliberately framework-free (~600 lines of plain Python): XBRL tag extraction from EDGAR company-facts, the ratio math, the DCF, and the guard's number-matching are all in equitydesk/, readable and defensible line by line.

Run it (no API key, no network needed)

pip install -r requirements.txt

python -m equitydesk AAPL --offline          # bundled SEC snapshots, deterministic writer
python -m equitydesk AAPL                    # live EDGAR + yfinance
python -m equitydesk AAPL --provider ollama  # a local LLM writes the prose
python -m equitydesk AAPL --provider claude  # opt-in; only the fact sheet is sent, never the vault of filings
python -m equitydesk AAPL --json             # just the grounded fact sheet

python -m equitydesk.web                     # the dashboard → http://127.0.0.1:8000

Sample output: memos/AAPL-sample.md

When the guard catches an invented number, the memo is rejected with the receipt:

CITATION GUARD FAILED — memo rejected:
  ✗ 31.2 does not trace to any fact in the AAPL fact sheet

The recommendation is a rule, not a vibe

buy: DCF upside > +15% AND not richer than peer median P/E sell: DCF downside < −15% AND not cheaper than peer median P/E hold: everything else

The LLM explains the verdict; it cannot change it. The DCF's assumptions (FCF growth clamped to 2–15%, WACC 9%, terminal 2.5%, 5 years) are printed in every memo — conservative by design, and honestly stated rather than hidden.

MCP server

The desk doubles as an MCP server, so AI agents on your machine can use grounded equity research as a tool:

python mcp_server.py

{"mcpServers": {"equity-desk": {"command": "python", "args": ["/path/to/equity-desk/mcp_server.py"]}}}

Tools: analyze_ticker(ticker, provider) → citation-guarded memo · fact_sheet(ticker) → grounded numbers as JSON.

Measured, not vibed

• Citation-integrity test — generates a memo from real (frozen) AAPL data and asserts the guard finds 0 un-sourced numbers. This is the repo's headline claim, running in CI on every push.
• Hand-worked math tests — every ratio and the DCF are asserted against fixtures computed by hand first.
• Golden-ticker CI — a committed EDGAR/yfinance snapshot makes the whole pipeline run offline and identically every time.

pip install -r requirements-dev.txt && python -m pytest   # 28 tests

Honest limitations

• Supported universe is the 8 tickers in data/peers.json (v1) — add a ticker by adding its CIK and peers.
• FCF growth is proxied by revenue growth (clamped 2–15%); WACC is a fixed 9%. A conservative DCF will call every richly-valued growth stock overvalued — the point is that the assumptions are stated, not that they're clairvoyant.
• EDGAR tag mapping trusts fp=FY labelling; odd fiscal calendars may misparse.
• The guard checks numeric provenance, not narrative truth — it stops invented figures, not bad arguments.

Phase 2 (documented, not built)

10-K risk-factor mining · multi-ticker comparison memos · PDF export · broader universe

---

Not investment advice. Data: SEC EDGAR company facts + Yahoo Finance. MIT.