{
  "markdown": "# ModelForge\n\n<!-- mcp-name: io.github.Whatsonyourmind/modelforge -->\n\n[![Version](https://img.shields.io/pypi/v/modelforge-finance?label=version&color=blue)](https://pypi.org/project/modelforge-finance/) [![Tests](https://img.shields.io/badge/tests-1486%2F1486-brightgreen)](./tests) [![Trust](https://img.shields.io/badge/trust--layer-v1%20(14%2F14%20FAIL--clean)-brightgreen)](./AUDIT_REPORT.md) [![MCP](https://img.shields.io/badge/MCP-native-orange)](./modelforge/mcp_server.py) [![Templates](https://img.shields.io/badge/templates-19%20(17%20shipped%20%2B%202%20preview)-blue)](./modelforge/templates/) [![SBOM](https://img.shields.io/badge/SBOM-CycloneDX%201.5-purple)](./.github/workflows/ci.yml)\n\nBulge-tier Excel financial model factory for credit & structured finance. Every cell live-formulated. Every number traceable back to the source document page it came from.\n\nA developer tool for analysts and engineers who build credit and corporate-finance models programmatically. Covers unitranche, sponsor-backed LBO, project finance, real estate credit, NPL, structured credit, restructuring, M&A, DCF and IPO templates. Extensible to any asset class.\n\n**The moat:** builds are **byte-identical deterministic** (same spec → same workbook bytes, every run) and ship with a verifiable **manifest + certificate** — formula integrity, accounting/conservation invariants (balance sheet balances, cash ties out), and SHA-256 hashes of spec + sources + workbook. Run `certify --strict` / `build --trust-strict` and it's **fail-closed**: non-zero exit on any integrity violation, so a broken model never ships. That's model generation *with* a portable audit trail — not just generation. For an AI agent or an app that emits financial models, it's the layer that turns \"the LLM produced a spreadsheet\" into \"here is a certificate that the spreadsheet is internally correct and reproducible.\"\n\n---\n\n> **🚀 Using ModelForge in production — or want managed features, priority support, or a specific template/connector?**\n> [**Tell me about your use case →**](https://github.com/Whatsonyourmind/modelforge/issues/new?template=early-access.yml) — I read every one.\n\n---\n\n## What this solves\n\n- Your agent needs to produce an Excel model from a structured spec — without an LLM hallucinating numbers directly into cells. ModelForge keeps the model deterministic: the LLM writes a typed YAML spec with source IDs, and a Python builder emits the live-formula workbook.\n- You need every output number to be auditable back to where it came from — without manually maintaining a sources sheet. Each hardcoded input carries a source ID, and the model's linkage graph is persisted to SQLite so a cell can be traced to its driver, source, and document page.\n- You want a model that recalculates instead of being a static dump — without writing formula strings by hand. Every cell is a real Excel formula, with named ranges, sign conventions, and WORST/BASE/BEST scenario toggles wired across sheets.\n- You need to gate a workbook for review — without eyeballing it. The QC tool runs an automated structural check suite (QC sheet present, named ranges populated, source references resolve, print areas set, no orphan sheets) and returns a per-check pass/fail report.\n- You need to triage many candidate deals fast — without building a workbook for each one. The screening tool filters and ranks a directory of spec YAMLs by quantitative criteria (margins, leverage, IRR) on their `screening:` block alone.\n- You want the whole pipeline available to an AI assistant — without bespoke glue code. ModelForge ships an MCP server (`modelforge-mcp`) so agents in Claude Code, Cursor, Cline, or ChatGPT Enterprise can list templates, build, QC, trace lineage, ingest a data room, and export deliverables.\n\n---\n\n## Use it inside Claude Code, Cursor, ChatGPT Enterprise (MCP-native)\n\n**PyPI name**: `modelforge-finance` (the unscoped `modelforge` was taken by source{d}'s ML library). **Import name** stays `modelforge`.\n\n```bash\npip install \"modelforge-finance[mcp,export]\"\n\n# wire into your MCP client config:\n{\n  \"mcpServers\": {\n    \"modelforge\": { \"command\": \"modelforge-mcp\" }\n  }\n}\n```\n\nThen in your AI assistant:\n> *\"Build me a unitranche LBO model from this YAML spec, export the committee deck.\"*\n\nTools available: `list_templates` · `build_model` · `qc_workbook` · `list_sources` · `lineage_walk` · `ingest_dataroom` · `screen_deals` · `compute_tax` · `export_pptx` · `export_docx` · plus 7 unified-feed tools (`data_providers_status` · `quote` · `history` · `fundamentals` · `search_filings` · `entity_lookup` · `search_securities`) across a 14-provider data stack.\n\n## The architectural principle\n\n> **LLMs produce specs + sources + narrative. Deterministic Python produces the workbook.**\n\nThe LLM never writes a number into a cell. It writes a typed YAML spec with source IDs. A deterministic builder emits the Excel via openpyxl. A QC gate validates before export. Excel is a render of a linkage graph; the graph is persisted to SQLite and is the canonical artifact.\n\n## Quality standards (bulge-tier, non-negotiable)\n\n**Formatting**\n- Blue = hardcoded input. Black = formula. Green = cross-sheet link. Red = warning.\n- No mixed formulas (no magic numbers embedded). Named ranges for every driver.\n- Costs NEGATIVE (sign convention enforced and checked).\n- EN primary labels, multi-language secondary (DE / ES / IT shipped; SV / NO / DA / NL on the v0.10 roadmap as design-partner asks).\n- Historical vs Projected column separator, obvious.\n- Check row at top of every sheet (BS balance, CFS tie, covenant headroom — TRUE or 0).\n\n**Sourcing**\n- Every hardcoded cell has a comment with source ID (S-001, S-002, ...).\n- `Sources` sheet lists each source: doc, page, publisher, date, URL, verified-flag.\n- Assumptions (not sourced) tagged A-001 with rationale + confidence H/M/L.\n\n**Scenarios**\n- WORST / BASE / BEST toggle on Assumptions. Drives every sheet via CHOOSE.\n- Every sheet respects the toggle — no orphan assumptions.\n\n**Audit**\n- `QC` sheet with 8 automated checks, all must pass.\n- Revision log on Cover.\n- Named ranges mandatory.\n- Print areas set. Print-ready on every sheet.\n\n## Quick start\n\n```bash\npip install \"modelforge-finance[mcp,export]\"\n\n# Scaffold a ready-to-build spec — no repo checkout needed (works for any of the 19\n# templates; run `modelforge list-templates` to see them all)\nmodelforge scaffold dcf -o demo_dcf.yaml\n\n# Build it: live-formula workbook + linkage graph + manifest sidecar\nmodelforge build demo_dcf.yaml            # -> output/demo_dcf.xlsx\n\n# Certify the delivered artifact: zero formula errors, byte-identical, manifest-valid\nmodelforge certify output/demo_dcf.xlsx\n```\n\n## Trust Layer v1 (new in v0.9.7)\n\n> Why should a buyer trust the number in cell `B42`?\n\nThe Trust Layer is a **semantic** gate (separate from the structural QC gate). It answers the question every IC asks in the first five minutes: *is this number plausible?* It catches issues like a DCF EV that's 8× the company's real market cap before the model ever leaves QA.\n\n25+ built-in rules cover all shipped templates:\n\n- **DCF**: WACC band (3-25%), terminal growth ≤ GDP + 1%, EV vs market-cap deviation, terminal-value share, sensitivity-table monotonicity\n- **Three-statement**: balance-sheet integrity, cash reconciliation, retained-earnings link\n- **NPL**: cumulative recovery ≤ 100%, vintage staircase monotone\n- **Project finance**: DSCR floor, wire degradation > 0, P90 < P50\n- **Sponsor LBO**: XIRR plausibility, multiple expansion vs entry\n- **M&A / fairness / structured credit / unitranche / credit memo**: per-template plausibility\n\nEach violation produces a `RedFlags` worksheet inside the built workbook with severity (`info` / `warn` / `fail`), the rule that fired, expected-vs-actual, and the recommended remediation.\n\n```bash\nmodelforge audit-all examples/   # every shipped example, 0 FAIL violations in current ship\n```\n\nSee [AUDIT_REPORT.md](./AUDIT_REPORT.md) for the current ship's audit.\n\n## Data-room ingestion (v0.3.1)\n\nTurn a directory of PDFs, XLSXs and CSVs into a validated ModelForge YAML spec using Claude Opus. Every extracted number traces back to a doc page via the auto-built Sources registry.\n\n```bash\npip install -e .[ingest]                # installs anthropic, pdfplumber, pypdf\nexport ANTHROPIC_API_KEY=sk-ant-...      # required\n\nmodelforge ingest path/to/dataroom/ \\\n    --template project_finance \\\n    -o output/my_deal.yaml --verbose\n\n# Review output/my_deal.yaml + output/my_deal.ingestion.md\n# (INGESTION_REPORT.md lists every extracted field, S-id, confidence)\n\nmodelforge build output/my_deal.yaml     # produces the workbook\nmodelforge qc output/my_deal.xlsx        # 8/8 quality gate\n```\n\nSupported template: `project_finance` (MVP). Templates 1, 3, 5-8 queued for v0.3.2.\n\n## Package layout\n\n```\nmodelforge/\n├── graph/            # First-class linkage graph (nodes, edges, SQLite persistence)\n├── spec/             # Pydantic schemas per template\n│   ├── base.py       # Source, Assumption, Scenario, Target (shared types)\n│   └── unitranche.py # Template 1: Unitranche LBO\n├── builder/          # Deterministic openpyxl writer\n│   ├── styles.py     # Bulge-tier formatting library\n│   ├── formulas.py   # Formula string builders\n│   ├── i18n.py       # EN/IT label dictionary\n│   ├── workbook.py   # Top-level builder\n│   └── sheets/       # One module per sheet (cover, sources, assumptions, ...)\n├── qc/               # Quality gate (8 structural checks + PDF report)\n├── data/             # Market data loaders (Damodaran, ECB, Borsa minibond)\n└── cli.py            # build | certify | qc | scaffold | validate | screen | ingest | ...\n```\n\n## Templates (19: 17 shipped + 2 preview)\n\n1. ✅ **Unitranche LBO** — Mid-market direct lending (Cash sweep + IFRS 9 EIR + covenant package)\n2. ✅ **Minibond / Private Placement Bond** — Direct private debt instrument (Gross YTM + Net YTM + jurisdiction-specific WHT)\n3. ✅ **Credit Memo** — Extends Unitranche with recovery waterfall + PD×LGD×EAD\n4. ✅ **Project Finance** — Construction + operating phases, DSCR-driven\n5. ✅ **Real Estate** — NOI build, exit cap, LP/GP promote waterfall\n6. ✅ **NPL Portfolio** — Collection curves, servicing fees, senior/mezz capital structure\n7. ✅ **Structured Credit** — Tranche waterfall with attachment/detachment points\n8. ✅ **3-Statement** — P&L + BS + CFS with BS balance integrity check\n9. ✅ **DCF** — WACC build, fade, terminal normalization, 2D sensitivity (Trust Layer protected)\n10. ✅ **Merger** — Accretion/dilution, breakeven, contribution, collar, PPA\n11. ✅ **Fairness Opinion** — Selected comps, regression, premium analysis\n12. ✅ **Sponsor LBO** — Returns waterfall, debt schedule, 14-story block\n13. ✅ **IPO** — Float build, lock-up, stabilization, fee schedule\n14. ✅ **Restructuring** — Going-concern recovery, plan-feasibility, creditor classes\n15. ✅ **Development (RE)** — Ground-up development: phased capex, lease-up S-curve, forward-NOI exit, LTC debt, promote\n16. ✅ **Bank / FIG** — NII, RWA, CET1 & leverage ratios, MDA-gated dividends & buybacks (Basel III/IV)\n17. ✅ **Loan-Tape Securitization** — CLO/RMBS: stratified tape, pool cashflow (CPR/CDR/recovery), sequential-pay turbo waterfall (OC/IC + reserve), note WAL/IRR/rating\n18. 🔬 **HGB Carveout** *(preview)* — German HGB carve-out financials\n19. 🔬 **Portfolio Review** *(preview)* — Multi-asset portfolio performance review\n\nRun `modelforge list-templates` to see them all (preview templates are flagged). Each shipped template has an anonymized example YAML in `examples/`.\n\n## Tax jurisdictions (7)\n\n```\nUS  · Federal CIT + state + NOL + R&D credit + GILTI + BEAT + ASC 740\nUK  · FRS 102 + main rate + marginal relief + RDEC + AIA + WDA + group relief\nDE  · KSt + SolZ + GewSt (Hebesatz + § 8 add-backs + min-tax loss CF) — HGB roadmap v0.10\nFR  · IS + small-profits + social surcharge + CVAE + CIR + 88% participation\nES  · IS + SME 23% + newly-created 15% + 95% participation + R&D + min-tax 15%\nJP  · NCT + LCT + Enterprise Tax + Special Local Corp Tax + R&D credit\nIT  · IRES / IRAP / SIIQ / PEX\n```\n\n## Data providers (14, unified `Provider` Protocol)\n\n**Tier-0 (free, live today)**: EDGAR · OpenFIGI · GLEIF · Yahoo Finance · FRED\n**Tier-1 (low-cost paid)**: Polygon ($29/mo) · FMP ($19/mo) · Finnhub · Tiingo · Alpha Vantage\n**Tier-2 (institutional)**: Bloomberg · Refinitiv · FactSet · S&P Capital IQ\n\nTier-1 and Tier-2 are interface-complete — paid keys activate them via env vars. Local TTL cache prevents rate-limit blow-ups.\n\n## Security & SBOM\n\n- **CycloneDX 1.5 SBOM** auto-generated by CI on every push and attached to every GitHub release (`scripts/generate_sbom.py`)\n- **CI gates**: pytest across Python 3.11 + 3.12, ruff lint, SBOM structure validation (`.github/workflows/ci.yml`)\n- **Audit log** with append-only SQLite (`modelforge/audit_log.py`)\n- **Trust Layer** semantic gates auto-injected into every built workbook\n- **Security policy**: see [SECURITY.md](./SECURITY.md)\n\nProcurement-grade controls (SOC 2 Type II, ISO 27001, pen-test, multi-tenant SaaS with SSO/SCIM) are Phase-B work.\n\n## The pitch\n\n> Bulge-tier Excel models, every cell live-formulated, every number traceable back to the data room page it came from.\n",
  "bytes": 13267,
  "sha": "c5ba1b8920e783daea2d0b032d94ac62ef20bddd6c27ad8971ecb888d043e4f5",
  "repo_slug": "whatsonyourmind/modelforge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_whatsonyourmind_modelforge_15becbe4/readme"
}