Finance AI Excel Plugin

An AI-powered Excel agent for investment banking and hedge fund workflows. Generates formula-driven, professionally formatted spreadsheet operations from natural language.

Architecture

User <-> Excel Add-in (Office.js + React + TypeScript) <-> FastAPI Backend <-> ReAct Planner/Tools <-> LLM (LM Studio/Ollama/Claude/GPT-4o)

Quick Start

1. Backend (Python)

cd backend
pip install -r requirements.txt
cp ../.env.example ../.env   # Edit with your API keys
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

2. Ollama (Local LLM — Optional)

# Install: https://ollama.com/download
ollama pull llama3.1:8b
ollama serve

3. Excel Plugin

cd plugin
npm install
npm run dev        # Starts HTTPS server on port 3443
npm run generate:api-types
npm run verify     # Typecheck + production build
npm run sideload   # Sideloads into Excel

4. Verify Everything

.\scripts\verify.ps1
.\scripts\verify-full-stack.ps1   # slower V7 default-readiness gate

5. Docker (Full Stack)

cp .env.example .env   # Edit with your API keys
docker-compose up -d

Project Structure

excel-ai-plugin/
├── backend/                # Python FastAPI backend
│   ├── agents/             # ReAct loop, tools, rules, prompts, and template routing
│   ├── api/routes/         # Trust-first task, session, document, benchmark, template, and enterprise APIs
│   ├── benchmarks/         # Production benchmark suite and deterministic quality gate
│   ├── excel/              # Formula, formatting, chart, citation, diff, and fingerprint helpers
│   ├── llm/                # Multi-provider LLM layer
│   │   ├── router.py       # Smart routing (local → cloud)
│   │   └── providers/      # Ollama, Anthropic, OpenAI
│   ├── models/             # Typed workbook operation contracts
│   ├── services/           # Operation planning and validation services
│   ├── storage/            # SQLite migrations and storage protocols
│   ├── config.py           # Configuration, paths, providers, and enterprise flags
│   └── main.py             # FastAPI app assembly and legacy compatibility tail
├── plugin/                 # Office.js Excel Plugin
│   ├── manifest.xml        # Add-in manifest
│   └── src/taskpane/       # React trust workspace, API client, and Excel adapter
└── docker-compose.yml      # Full stack orchestration

IB Formatting Standards

• Blue font: Hard-coded inputs/assumptions
• Black font: Formulas
• Green font: Cross-sheet links
• Parentheses: Negative numbers
• Double border: Totals
• Calibri 10pt: Standard font

v0.5 Trust-First Flow

• POST /api/v1/tasks/plan creates a typed, validated workbook operation plan.
• POST /api/v1/tasks/apply approves a plan, records a durable rollback snapshot, and issues a durable two-phase apply token before Excel writes.
• POST /api/v1/tasks/apply/result verifies the apply token, records the Office.js apply outcome, and marks the plan applied, failed, or abandoned.
• POST /api/v1/tasks/ask answers workbook questions without mutations.
• GET /api/v1/tasks/plans/{plan_id}/v2 returns a strict OperationPlanV2 contract view of an existing durable plan.
• POST /api/v1/contracts/operation-plan-v2/validate validates the discriminated V2 operation plan schema without touching Excel.
• GET /api/v1/sessions/{id}/timeline returns messages, plans, snapshots, and audit events.
• GET /api/v1/sessions/{id}/citations returns source/document/formula citations for the session.
• GET /api/v1/sessions/{id}/audit/export exports audit events as CSV.
• POST /api/v1/sessions/{id}/rollback returns restore operations for a saved snapshot.
• Frontend API contracts are generated from FastAPI OpenAPI into plugin/src/taskpane/api-types.ts; do not edit that file by hand.

Experimental Local Accuracy Workbench

• V7 stays experimental: defaults remain on PLAN_ENGINE_VERSION=v2, and live workbook mutation still goes only through Office.js after explicit approval.
• POST /api/v1/experiments/v7/reviews builds a read-only V7WorkbookReview combining truth model V5, formula graph V5, simulation V6, source evidence V3, registry coverage, confidence gaps, checkpoints, repair candidates, and next actions.
• GET /api/v1/experiments/v7/reviews/{review_id} reloads the durable SQLite artifact; /export returns a JSON audit artifact.
• GET /api/v1/experiments/v7/readiness, POST /api/v1/experiments/v7/readiness/run, and GET /api/v1/experiments/v7/readiness/history expose the persisted V7DefaultReadinessReport and compact history used to decide whether V7 is blocked, warning, or ready for a later default switch.
• GET /api/v1/experiments/v7/replays, POST /api/v1/experiments/v7/replays/evaluate, POST /api/v1/experiments/v7/replays/capture, GET /api/v1/experiments/v7/replays/baselines, and POST /api/v1/experiments/v7/replays/baselines expose anonymized local replay artifacts, deterministic drift evaluation, privacy-checked local capture, and pinned local replay baselines. Capture stores schema versions, operation types, counts, gate statuses, checkpoint counts, rollback availability, and stable hashes; payloads containing workbook values, formulas, raw prompts, sheet text, or source content are rejected.
• GET /api/v1/experiments/v7/golden-cases and POST /api/v1/experiments/v7/golden-cases/evaluate expose the workbook fixture gate as golden-case evidence for truth, formula, simulation, rollback, and repair expectations.
• The taskpane Settings drawer includes a persisted local V7 local accuracy mode toggle and replay-capture controls. When the toggle is off, planning stays on the shipped V2 path; when on, V7 review, readiness, replay, simulation, and agent-run calls use the experimental surfaces while writes remain checkpointed Office.js handoffs.
• The taskpane command palette includes a read-only V7 workbench across Understand, Trace, Simulate, Repair, and Audit plus readiness history, replay baselines, golden cases, retry/resume, rollback, and audit commands without switching the default planner.
• The V7 registry now marks screenshot and sparkline operations as low-risk opt-in coverage with host-capability fallbacks; pivot mutations remain safely gated with explicit readiness reasons.
• Local verification entrypoints:
  • .\scripts\verify-full-stack.ps1
  • python -m backend.benchmarks.local_accuracy
  • python -m backend.benchmarks.local_replay --evaluate
  • python -m backend.benchmarks.v7_readiness
  • python -m backend.benchmarks.v7_golden_cases
  • .\scripts\verify-local-accuracy.ps1
  • .\scripts\verify-v7-default-prep.ps1
  • cd plugin && npm run lint
  • cd plugin && npm run test:office-mock
  • cd plugin && npm run test:taskpane

Local Data Hygiene

• Runtime state lives under data/ and is ignored by git.
• To back up local sessions, stop the backend and copy data/sessions.db plus any matching sessions.db-wal/sessions.db-shm files to a secure backup location.
• Avoid committing .env, cache folders, generated frontend dist/, or local database exports.
• Private local golden workbooks can live under backend/benchmarks/fixtures/private/; that folder is ignored so power-user regression cases stay local.

Shortcut-Parity Surfaces

• Source-backed modeling: POST /api/v1/documents/upload, GET /api/v1/documents/{id}, and POST /api/v1/documents/{id}/plan persist PDF/CSV/XLSX artifacts and create cited typed plans.
• Benchmark gates: POST /api/v1/benchmarks/run, GET /api/v1/benchmarks/runs, GET /api/v1/benchmarks/cases, and GET /api/v1/benchmarks/regression. Runtime benchmark history is stored under the managed data directory.
• Enterprise controls: /api/v1/enterprise/* exposes SQLite-backed users, API keys, teams, roles, SSO/provider/retention policies, and readiness summaries.
• The React taskpane wires ask/preview/apply, audit/rollback, upload-to-plan, template forms, rules, benchmarks, settings, and formula trace. Google Sheets is intentionally out of scope.

Verification

• python -m pytest backend\tests -q
• python -m backend.benchmarks.local_accuracy
• python -m backend.benchmarks.local_replay --evaluate
• python -m backend.benchmarks.v7_readiness
• python -m backend.benchmarks.v7_golden_cases
• python -c "import asyncio, json; from backend.benchmarks import get_benchmark_runner, deterministic_benchmark_pipeline, evaluate_gates; run=asyncio.run(get_benchmark_runner().run_suite(pipeline_fn=deterministic_benchmark_pipeline)); gate=evaluate_gates(run); print(json.dumps({'run_id': run.run_id, 'score': run.overall_score, 'gate': gate['status']}, indent=2)); raise SystemExit(0 if gate['status']=='passed' else 1)"
• cd plugin && npm run verify && npm run lint && npm run test:office-mock && npm run test:taskpane && npm audit --audit-level=critical
• cd workbook-worker && npm test
• python -c "from backend.main import app; print(app.title)"
• .\scripts\verify.ps1
• .\scripts\verify-v7-default-prep.ps1
• .\scripts\verify-full-stack.ps1