io.github.Whatsonyourmind/modelforge

List every financial-model template the server can build, with a count. Use this FIRST to discover which model types are available (e.g. DCF, three-statement, M&A merger, LBO, project finance, NPL portfolio, structured credit, IPO, restructuring) before calling build_model or ingest_dataroom. Returns {templates: [{name, registered, preview}], count} from the live REGISTRY. Conversational loop: STEP 1 — pick a model_type here, then call spec_guide(model_type) to learn how to author its spec.

Return a concise authoring guide for one model_type: required blocks, Source/Assumption ID rules, a starter example, and the most common validation errors. Use BEFORE drafting a spec so the first draft validates. The ``example_yaml`` is seeded from a shipped, build-ready example (or an honest required-field stub when ``example_is_stub`` is true — currently ipo/restructuring); edit its placeholder values rather than authoring from a blank page. ``required_blocks``/``optional_blocks`` are the legal top-level YAML keys. Returns {model_type, required_blocks, optional_blocks, id_discipline, example_yaml, example_is_stub, common_errors, workflow} or {error} for an unknown model_type. Conversational loop: STEP 2 — after list_templates, before drafting. Call get_spec_schema for the full field-level JSON Schema.

Return the full JSON Schema (draft 2020-12) for a model_type's YAML spec. Use when spec_guide's block list is not enough and you need exact field-level types, enums, ranges, and nested structures while drafting or repairing a spec. Same schema the CLI's `modelforge schema` command emits. Returns {model_type, schema} or {error} for an unknown model_type. Conversational loop: STEP 2 (detail level) — alongside spec_guide, before validate_spec.

Validate a draft YAML spec WITHOUT building — the fast pre-flight check. Runs the same friendly validation chain as the CLI's `modelforge validate`: YAML parse errors, non-mapping documents, unknown model_type (with the known list), Pydantic field errors as plain-language one-liners with dotted paths (e.g. "Missing required field: pl.revenue_growth_by_year"), unknown top-level keys as WARNINGS (silent-typo guard), and dangling `*_source_id` references as ERRORS (fabricated-citation guard). ``spec_yaml`` is the YAML text itself (a path to an existing .yaml file also works); optional ``model_type`` is used only when the spec omits its own `model_type:` key. Returns {valid, model_type, errors[], warnings[]} — never raises on a bad spec. Conversational loop: STEP 4 — call after EVERY draft/edit and iterate until valid:true BEFORE spending a build via build_model or certify.

Build from a YAML spec (or take an existing workbook) and run the zero-formula-error certification audit. Pass EITHER ``spec_yaml`` (YAML text or a path to a .yaml file — it is validated, built exactly as the CLI `build` command ships it, including the Trust/Moat sheets and the deterministic finishing chain) OR ``workbook_path`` (an already-built .xlsx to audit as-is). The auditor recomputes every formula with the third-party `formulas` engine and flags any Excel error cell (#REF!/#DIV0!/#VALUE!/#NAME?/#NUM!/#N/A) plus numeric cells lacking font colour or number_format. Returns {verdict: CERTIFIED|WARN|FAIL, formula_errors[], formula_error_count, style_gaps[], style_gap_count, manifest_sha, xlsx, ...}. CERTIFIED = zero errors and zero styling gaps; WARN = zero errors, some styling gaps; FAIL = at least one formula error. An invalid spec returns {verdict: INVALID_SPEC, errors, warnings} without building. A spec is first run through the evidence-binding gate (optionally against the source documents in ``dataroom``); a BROKEN or CONTESTED binding — or, with ``evidence_strict``, an UNVERIFIED one — returns {verdict: EVIDENCE_BLOCKED, blocking[], evidence_summary} without building. Conversational loop: STEP 5+6 in one call (build + audit) after validate_spec passes — or STEP 6 alone on a workbook built earlier. Walk provenance next via list_sources / lineage_walk on the returned graph_db.

Generate a live-formula Excel workbook (.xlsx) plus its SQLite linkage graph (.graph.db) from a typed YAML spec. Use when the user has (or has just produced) a ModelForge YAML spec and wants the actual workbook — formulas in every cell, scenario toggles, and source-tagged inputs. Takes spec_path and optional output_dir; returns {xlsx, graph_db, evidence, spec, ok} or {error}. The evidence-binding gate runs first (optionally against the source documents in ``dataroom``). A BROKEN or CONTESTED binding — or, with ``evidence_strict``, an UNVERIFIED one — returns {verdict: EVIDENCE_BLOCKED, blocking[], evidence_summary} and builds nothing. Conversational loop: STEP 5 — only after validate_spec returns valid:true. Prefer certify(spec_yaml=...) when you also want the audit verdict in the same call; build_model alone does NOT inject the Trust/Moat sheets the CLI `build` ships.

Run the automated structural QC gate on a ModelForge workbook and return a per-check pass/fail report. Use after build_model (or on any ModelForge .xlsx) to verify it is audit-ready before exporting or sharing. Runs 8 checks: QC-sheet presence, sign-convention declaration, scenario-toggle named range, named-range population, comments on hardcoded cells, source references resolving, print areas, and no orphan sheets. Takes xlsx_path; returns {xlsx, report} or {error}. Conversational loop: STEP 6 (structural pass) — pair with certify, which runs the formula-recalc audit; use both before exporting or sharing.

Flag hardcoded numbers wedged inside a formula series — the certify-blind defect. certify proves a workbook has zero formula errors, but it cannot see a cell that SHOULD be a formula and was overwritten with a bare number (e.g. a value typed over year 4 of a 10-year debt schedule). This auditor catches exactly that: a non-innocuous hardcode sitting BETWEEN formula cells in a contiguous period series. Edge-period inputs and input/reference/audit sheets are excluded, so it is high-precision (zero findings on all certified examples). Takes xlsx_path; returns {xlsx, verdict, findings[], finding_count, sheets_scanned} or {error}. Advisory — pair with certify (formula errors) and qc_workbook (structure) for a full pre-share check.

Recompute the QC sheet and require ALL_PASS==1 — the other certify-blind defect. certify proves zero formula errors, but a conservation check that legitimately recomputes to 0 (a balance sheet that doesn't balance, a debt roll-forward that telescopes, NI != EBT + tax) is a VALID formula returning 0 — not an Excel error — so it certifies CERTIFIED today. This recomputes every formula with the `formulas` engine, reads the recomputed ALL CHECKS PASS aggregator plus every per-check on the QC sheet, and requires the aggregator to be 1 with no per-check at 0. Deterministic, zero-LLM. Takes xlsx_path; returns {xlsx, status (PASS/ FAIL/INDETERMINATE), passed, qc_sheet, all_pass_ref, all_pass_value, n_checks, findings[], finding_count} or {error}. No recalc engine / no QC sheet -> INDETERMINATE (a failure). Pair with certify (formula errors) + audit_schedule.

Shock each input driver ±5% and require the QC conservation invariants to HOLD. The baseline conservation gate recomputes the QC sheet only at the built numbers, so a "total" hardcoded to its baseline value still passes `Total == Σ parts` and certifies clean — a latent input-dependent defect. This compiles the workbook once, shocks every resolved input driver UP and DOWN, recomputes, and re-reads the QC checks. A conservation identity holds two-sided for any inputs, so a check breaking under BOTH directions is a genuine defect; a one-sided break is a legitimate validity threshold and is NOT flagged. Deterministic, zero-LLM. Takes xlsx_path; returns {xlsx, status (PASS/FAIL/INCONCLUSIVE/INDETERMINATE), passed, qc_sheet, drivers_active, drivers_probed, rel_delta, findings[], finding_count} or {error}. Pair with certify + audit_conservation (baseline) + audit_schedule.

Enumerate the source citations recorded in a model's linkage graph. Returns the doc, page, publisher, date and URL behind each S-NNN reference. Use when an agent needs the provenance list for a built model (e.g. to render a citations table or verify every input is sourced). Takes graph_db (the .graph.db from build_model); returns {graph_db, sources, count} or {error}. Conversational loop: STEP 7 — after a successful build/certify, before or alongside lineage_walk.

Trace a single output cell back through its drivers to the underlying source document and page. Use when the user asks 'where does this number come from?' or 'show the audit trail for cell X' on a built model. Takes graph_db and a cell reference (e.g. "Returns!E45"); returns an ordered list of upstream hops cell -> driver -> source -> doc page. Conversational loop: STEP 7 (final) — the provenance walk that closes the loop: any number in the certified workbook traces back to a source doc page.

Read a folder of PDFs/XLSXs/CSVs and produce a Pydantic-validated ModelForge YAML spec plus an ingestion report. Use when the user has a directory of raw deal documents and wants to turn them into a buildable spec without hand-coding it. Each extracted field is traced to its source. Requires the [ingest] extra and an Anthropic API key. Takes dataroom_path, template (default project_finance), optional output_spec; returns paths to the YAML + ingestion report + extracted_fields count. Conversational loop: alternative to hand-drafting at STEP 3 when raw deal documents exist — still run validate_spec, then build/certify, on the extracted spec.

Generate an executive PowerPoint deck (.pptx) summarizing a built ModelForge workbook. Use when the user wants a presentation-ready summary of a model for a committee or stakeholder review. Requires the [export] extra (python-pptx). Takes xlsx_path and optional output_path; returns {xlsx, pptx, ok} or {error}. Conversational loop: STEP 8 (deliverable) — only after certify returns CERTIFIED (or the user accepts a WARN).

Render a certified, hash-stamped board deck (.pptx) from a ModelForge workbook or spec — fail-closed. Pass EITHER ``workbook_path`` (a built .xlsx with its ``<stem>.manifest.json`` sidecar next to it) OR ``spec_path`` (a YAML spec, built exactly as the CLI ``build`` ships it — Trust/Moat sheets, deterministic finishing, manifest — before the deck chain runs). Fail-closed chain: manifest verify → certification audit must be CERTIFIED → supported-template fact extraction (every numeric fact carries its sheet!cell ref) → compose (``ic_memo`` or ``teaser``) + mandatory "Certification & Red Flags" final slide → render → deterministic stamp. The .pptx embeds spec_sha256 + workbook_sha256 in its core-property keywords and is byte-identical for the same workbook. ``ground_numbers`` (opt-in) adds a fail-closed numeric-grounding gate: every rendered slide token must reconcile to a recomputed certified-cell fact or a whitelisted derivation (leverage / LTV / percent-of-total), catching a millions-vs-thousands scale error the internal-consistency checks miss; an unreconciled token returns {error}. Returns {pptx, deck_type, theme, slides, workbook, workbook_sha256, spec_sha256, audit_verdict, template, red_flags, source_cells, grounding_ok, unreconciled_count, ok} or {error} (uncertified/tampered workbooks and unsupported templates are refused with a plain-language reason). Conversational loop: STEP 8 (deliverable) — the certified-deck upgrade of export_pptx; use after certify returns CERTIFIED.

Filter and rank a directory of deal spec YAMLs by quantitative criteria without building each workbook. Use when the user wants to triage many candidate deals — e.g. 'rank all specs with EBITDA margin >= 20% and leverage <= 5x by base-case IRR'. Filter keys support _min (>=), _max (<=), _in (membership), or bare key (equality); rank_by weights are positive (higher better) or negative (lower better). Takes spec_dir, filters, rank_by, top_n (default 25); returns a ranked list of {deal_id, spec_path, summary, score}. Conversational loop: outside the single-model loop — use to pick WHICH spec to take through validate_spec → certify when many candidates exist.

Compute corporate income tax (effective rate + total tax) for one of seven jurisdictions from pretax book income. Use when a model or analysis needs a quick jurisdiction-aware tax figure. US, UK, DE, FR, ES, JP are fully wired; IT returns a pointer to the dedicated italian_tax module for full IRES/IRAP inputs. Takes jurisdiction code, pretax_book_income, and optional jurisdiction-specific kwargs; returns {jurisdiction, etr, total_tax} or an error for an unknown code. Conversational loop: helper at STEP 3 — ground a spec's tax-rate assumption in the right jurisdiction while drafting.

Generate a structured Word memo (.docx) from a built ModelForge workbook. Sections: Executive Summary, Transaction Overview, cited Key Assumptions, Risk Analysis, Recommendation. Use when the user wants a written investment/credit memo derived from a model. Requires the [export] extra (python-docx). Takes xlsx_path and optional output_path; returns {xlsx, docx, ok} or {error}. Conversational loop: STEP 8 (deliverable) — only after certify returns CERTIFIED (or the user accepts a WARN).

List every registered market-data provider with its tier and an availability flag. Use this FIRST before quote/history/fundamentals/search_filings to see which providers are actually usable in the current environment (free providers work out of the box; paid/institutional ones activate only when their API keys are set). Returns {providers, available_count, total_count}. Conversational loop: outside the core loop — check it before using the market-data tools to ground spec assumptions at STEP 3.

Fetch the latest price quote for a ticker, auto-routed to the best available market-data provider. Use when the user needs a current price for a symbol. Takes a vendor-native symbol (e.g. AAPL, BNP.PA) and an optional ``prefer`` provider to try first; returns the quote fields, or an {error, hint} if no provider is configured. Conversational loop: market-data helper at STEP 3 (drafting) — e.g. to set a spec's share-price or market-cap input from a live quote.

Fetch historical OHLCV price bars for a ticker over a date range and interval. Use when the user needs a price series (e.g. daily bars for the last year, or intraday bars). Takes symbol, interval (1m/5m/1h/1d/1wk/1mo), optional start/end ISO dates, limit, and optional prefer provider; returns {symbol, interval, bars: [...]} or {error}. Conversational loop: market-data helper at STEP 3 (drafting) — e.g. for volatility or historical-growth inputs to a spec.

Fetch reported financial statements (income, balance, or cashflow) for a ticker, newest first. Use when the user needs historical fundamentals to seed or sanity-check a model. Takes symbol, statement (income/balance/cashflow), period (annual/quarter), limit, optional prefer provider; returns {symbol, statement, period, data: [...]} or {error}. Conversational loop: market-data helper at STEP 3 (drafting) — seed historical_revenue/EBITDA blocks of a spec from reported figures.

List recent SEC EDGAR filings (10-K, 10-Q, 8-K, etc.) for a US ticker. Use when the user wants to find or link a company's primary filings for due diligence or sourcing. Takes ticker, optional form filter (e.g. 10-K), and limit; returns {ticker, filings: [...]} or {error}. Conversational loop: sourcing helper at STEP 3 (drafting) — a filing makes a strong `sources:` entry (doc, page, publisher, date) for spec inputs.

Resolve a legal entity by LEI, FIGI, or ticker and return its canonical legal name plus any cross-reference IDs. Use to disambiguate a counterparty or issuer before building a model spec or wiring market data. Takes any one of lei / figi / ticker; returns the resolved Entity record or {error}. Conversational loop: drafting helper at STEP 3 — pin down the exact legal entity a spec's target block refers to.

Free-text search for securities/entities across configured reference data providers, returning the first non-empty result set. Use when the user has a company name or fragment and needs to find the matching ticker/identifier. Takes a query string and limit (default 20); returns {query, results} or {error}. Conversational loop: drafting helper at STEP 3 — resolve a company name to a ticker before quote/fundamentals/search_filings.