ModelGuard 2.0

Evidence-first review for Excel financial models: deterministic spreadsheet checks, finance tie-outs, cell-level proof, and a cited analyst memo.

ModelGuard is a portfolio project that explores how software can make the first pass through a financial model faster without pretending to replace an analyst, accountant, or auditor.

The problem

Financial-model review is necessary but repetitive. Reviewers spend time locating formula errors, hidden logic, external links, overwritten forecast cells, and statement inconsistencies before they can focus on judgment.

Generic AI review introduces a second problem: an explanation can sound confident even when it is not grounded in the workbook. ModelGuard takes the opposite approach. It detects structured evidence first and permits explanation only after a finding exists.

What ModelGuard does

Upload an .xlsx workbook or run the recommended Atlas Full Model demo. ModelGuard:

1. Parses workbook structure with openpyxl.
2. Runs deterministic spreadsheet and finance checks.
3. Assigns transparent severity-based score deductions.
4. Shows the exact sheet, cell, formula or value, nearby cells, and manual review steps.
5. Builds an analyst-style memo using only the structured audit report.
6. Exports the review as Markdown without exporting raw workbook content.

The Atlas Full Model demonstrates the complete workflow with a stable 56/100 High score, 16 findings, and 6/6 finance checks completed.

Why it is trustworthy

• Evidence before explanation. A finding must come from a deterministic rule before it can appear in the memo.
• Exact citations. Issue claims cite stable finding IDs and link back to cell-level evidence.
• Conservative language. Findings describe detected risk, potential issues, and items requiring manual review.
• No silent correction. ModelGuard never changes the uploaded workbook.
• Transparent scoring. The API returns the starting score, deductions, final score, risk band, and top drivers.
• Safe fallback. The portfolio release uses a deterministic memo template; no AI provider is required or configured.
• In-memory processing. Uploaded workbook bytes are parsed for the request and are not persisted by the application.

Screenshots

View	Preview
Landing page and sample selector
Risk score dashboard
Cell evidence panel
Finance finding
Analyst review memo
Exported Markdown report

Checks included

Spreadsheet checks

• Sheet inventory and visibility
• Used ranges and formula counts
• Numeric hardcodes and internal blanks
• Explicit formula errors
• External workbook links
• Named ranges
• Hidden sheets containing formulas
• Hardcoded constants inside formulas
• Horizontal formula-pattern breaks
• Volatile or complex suspicious formulas

Finance checks

• Total Assets versus Total Liabilities & Equity
• Cash Flow Ending Cash versus Balance Sheet Cash
• Displayed revenue growth versus calculated growth
• Displayed EBITDA margin versus EBITDA / Revenue
• Implied interest rate using interest expense and average debt
• Enterprise Value versus identified metric × multiple

Finance checks run only when required labels and comparable numeric values can be identified conservatively. If coverage is unavailable, ModelGuard reports that status instead of inventing a finding.

Architecture

Layer	Technology	Responsibility
Frontend	Next.js, React, TypeScript	Upload, samples, evidence dashboard, memo, export
Backend	FastAPI, Pydantic	Upload contract, audit orchestration, report export
Workbook parsing	openpyxl	Workbook structure, formulas, values, names, links
Audit engine	Python	Deterministic spreadsheet and finance checks
Tests	pytest, Node test runner, ESLint	Scoring, contracts, samples, export, rendered UI

The audit pipeline is deliberately one-way:

.xlsx workbook
      ↓
deterministic parser and checks
      ↓
structured AuditReport with finding IDs
      ↓
cited memo and Markdown export

The memo generator and exporter never receive direct workbook access.

Run locally

Requirements:

• Node.js 22.13 or later
• Python 3.11 or later

Install dependencies:

npm install
python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

Start the API:

source .venv/bin/activate
uvicorn backend.app.main:app --reload --port 8000

Start the frontend in another terminal:

npm run dev

Open http://localhost:3000. To use another API URL:

NEXT_PUBLIC_API_URL=http://localhost:8000 npm run dev

Run the verification suite:

source .venv/bin/activate
pytest backend/tests -q
npm run lint
npm test

Sample workflow

1. Select Try Full Model — recommended.
2. Read the 56/100 risk score, severity mix, and top risk drivers.
3. Review the 6/6 finance-check coverage.
4. Expand ISS-002 to inspect the balance sheet difference, compared cells, threshold, context grid, and manual steps.
5. Select a cited finding ID in the analyst memo to jump back to its evidence.
6. Select Export Report to download the structured Markdown review.

The compact Atlas sample remains available for a faster spreadsheet-only walkthrough.

API

POST /api/audit/upload

• Accepts one .xlsx file as multipart field file
• Parses the workbook in memory
• Returns the v1.0 structured audit, score, findings, finance coverage, and memo

POST /api/report/export

• Accepts a validated v1.0 AuditReport
• Returns text/markdown
• Includes cited findings, finance coverage, memo, limitations, timestamp, and disclaimer
• Does not accept workbook bytes or export raw workbook content

Interactive API documentation is available at http://localhost:8000/docs.

Regenerate the samples

source .venv/bin/activate
python scripts/generate_sample.py
python scripts/create_full_sample_workbook.py

The Full Model generator is byte-for-byte deterministic. It writes the root workbook and the identical browser-demo copy in public/. Static comparison rows are intentional because openpyxl does not calculate formulas or write reliable cached formula results.

Limitations

• ModelGuard is a first-pass review aid, not a complete model validation engine.
• openpyxl does not calculate formulas; uncached formula results may be unavailable.
• Finance checks rely on recognizable English labels, consistent period headers, and comparable numeric values.
• Label matching does not cover every accounting convention, fiscal calendar, unit, debt instrument, or valuation adjustment.
• Pattern checks are conservative heuristics and still require manual review.
• Context previews do not replace full precedent and dependent tracing in Excel.
• External links are detected but their targets and availability are not validated.
• The score measures findings from implemented rules only; it is not a probability of correctness.
• Markdown is the only export format.
• .xls, .xlsm, macros, protected workbooks, Google Sheets, authentication, persistence, payments, and automatic correction are outside this release.

Roadmap

• Broader financial-label dictionaries and fiscal-calendar handling
• Configurable materiality and rule profiles
• Richer formula lineage and precedent/dependent tracing
• Additional deterministic working-capital and schedule tie-outs
• PDF or styled document export
• Optional AI explanation behind the existing evidence-only provider boundary

Project documentation

• Case study
• Portfolio summary
• Demo script
• Product specification
• Audit-check catalog
• Full Model sample guide

Disclaimer

ModelGuard provides review support only. It does not provide financial, accounting, audit, legal, tax, or investment advice; certify model correctness; or replace professional judgment and manual validation in Excel.