FinSmolAgent

A multi-agent quantitative finance orchestration platform that automates KYC screening, market research, earnings analysis, financial modeling, backtesting, and valuation reporting through a managed-agent pipeline.

+------------------------------+        +--------------------------------+
| Vite + React Client          |        |  Human Review Console          |
| - Pipeline graph             | <----> |  - Compliance / IR approvals   |
| - Recharts                   |        |  - Approve / Reject gates      |
+---------------+--------------+        +----------------+---------------+
                | HTTP + WebSocket                         |
                v                                          v
+---------------+------------------------------------------+---------------+
| FastAPI API + WebSocket Broadcaster                                      |
| - Session routing                                                          |
| - Pipeline state + approval state                                          |
| - Event streaming                                                          |
+---------------+------------------------------+----------------------------+
                |                              |
                v                              v
+---------------+---------------+   +----------+----------------------------+
| Orchestrator                  |   | Async Task Queue                      |
| - Managed agent dispatch      |   | - Backtest/optimizer jobs             |
| - Handoff validation          |   | - Retry + job attempts                |
| - Schema validation           |   +----------+----------------------------+
+---------------+---------------+              |
                |                              v
                |                   +----------+----------------------------+
                |                   | Pi Sandbox Worker                     |
                |                   | - Headless Pi CLI                     |
                |                   | - Workspace jail + timeout            |
                |                   | - Deterministic seeds                 |
                |                   +----------+----------------------------+
                |                              |
                v                              v
+---------------+------------------------------+----------------------------+
| PostgreSQL / TimescaleDB                                                    |
| - clients, fundamentals, quant features, backtests                         |
| - pipeline_runs, approval events, provenance, execution_jobs               |
+----------------------------------------------------------------------------+

---

What It Does

The system runs an end-to-end quantitative finance pipeline across six stages, orchestrated by managed agents:

1. KYC/AML Screening (kyc-screener)

Parses onboarding document packets, applies KYC/AML rules, screens against sanctions/PEP lists, and produces a risk disposition (clear, request-docs, escalate-EDD, decline-recommend). If the disposition requires escalation, the pipeline blocks and waits for a compliance officer to approve or reject.

2. Market Research (market-researcher)

Produces sector or thematic research: industry overview, competitive landscape, comparable-company analysis (trading/transaction comps), and an ideas shortlist. Outputs research notes with optional PowerPoint slides.

3. Earnings Review (earnings-reviewer)

Processes an earnings event end-to-end: reads call transcripts and SEC filings, detects beat/miss vs consensus, updates the financial model with actuals, revises forward estimates, and drafts the post-earnings note.

4. Model Building (model-builder)

Builds financial models from scratch: DCF (three-scenario, sensitivity tables), LBO, integrated three-statement models, and trading comps. All models produced as structured Excel workbooks with audit checks.

5. Backtest & Optimize (pi / Pi Sandbox)

Runs quantitative portfolio optimization and backtesting in a sandboxed Pi environment. The sandbox enforces workspace jailing, timeout budgets, deterministic seeds, and a whitelist of allowed Python packages (pandas, numpy, PyPortfolioOpt, cvxpy, etc.).

6. Valuation Reporting (valuation-reviewer)

Ingests GP valuation packages, runs portfolio company valuations, computes waterfall/LP distribution, and stages LP reporting materials.

---

Agent Skills

Each agent has a set of composable skills:

kyc-screener

Skill	Purpose
kyc-doc-parse	Parse onboarding PDFs into structured JSON (entity, beneficial owners, documents)
kyc-rules	Apply AML rules grid, risk-rate, determine disposition
xlsx-author	Headless .xlsx workbook production

market-researcher

Skill	Purpose
sector-overview	Industry overview with market size, growth, value chain
competitive-analysis	Competitive landscape mapping and positioning
comps-analysis	Institutional comparable-company analysis in Excel
idea-generation	Systematic stock screening and idea presentation
pptx-author	Headless .pptx slide deck production

earnings-reviewer

Skill	Purpose
earnings-analysis	8-12 page earnings update reports with charts
model-update	Plug actuals into model, revise estimates, revalue
morning-note	Concise morning meeting notes (1-page)
xlsx-author	Headless .xlsx workbook production
audit-xls	Formula errors, hardcodes, balance checks

model-builder

Skill	Purpose
dcf-model	DCF with projection period, terminal value, WACC, three scenarios, sensitivity tables
lbo-model	LBO with sources & uses, debt schedule, IRR/MOIC
3-statement-model	Integrated IS/BS/CF with scenario analysis
comps-analysis	Comparable company analysis with trading multiples
audit-xls	Spreadsheet audit and model integrity
xlsx-author	Headless .xlsx workbook production

valuation-reviewer

Skill	Purpose
returns-analysis	IRR/MOIC sensitivity tables for PE deal evaluation
portfolio-monitoring	Track portco performance vs plan, flag variances
ic-memo	Structured investment committee memos
xlsx-author	Headless .xlsx workbook production

---

Pipeline & State Machine

Pipeline Steps (execution order)

DOCUMENT_PARSING   → KYC Screener
DATA_INGESTION     → Market Researcher + Earnings Reviewer (parallel)
MODEL_BUILDING     → Model Builder (DCF)
RUN_BACKTEST       → Pi Sandbox (backtest/optimization)
PERSIST_AND_COMPARE → Valuation Reviewer

Step Status

Each step transitions through:

PENDING → RUNNING → SUCCESS
                 → FAILED
                 → BLOCKED_AWAITING_APPROVAL

Human Approval Gate

If the KYC screener's disposition is request-docs, escalate-EDD, or decline-recommend, the pipeline blocks at HUMAN_REVIEW and emits an APPROVAL_REQUIRED event. A compliance officer must call POST /api/runs/{id}/approve to approve or reject before execution continues.

Approval states: NOT_REQUIRED → PENDING → APPROVED | REJECTED

---

Runtime Modes

Mode	Agent Calls	Backtest	Dependencies
mock	Deterministic stubs	Deterministic results.json via SHA-256 seeded generation	None (Python only)
managed	Real Anthropic managed-agent API (POST /v1/agents/{id}/steer)	Real pi CLI execution in sandboxed workspace	ANTHROPIC_API_KEY, agent IDs, pi binary

What mock mode provides

• Full pipeline orchestration without any external API or binary
• Deterministic outputs (token-based branching for KYC, seeded backtest metrics)
• Logs every simulated call (MOCK_AGENT_CALL agent=...)
• Useful for frontend development, integration testing, and demonstration

What managed mode provides

• Real LLM-driven agent responses via Anthropic's managed-agent API
• Real Pi binary execution for backtesting with configurable timeout and seed
• Live HTTP call logging (MANAGED_AGENT_CALL agent=... endpoint=...)
• Production-grade execution with proper error handling and retry

---

Quick Start (Mock Mode)

Prerequisites

• Python 3.11+
• Node.js 20+
• pip install -r backend/requirements.txt

Backend

# from repository root
source backend/.venv/bin/activate
export FSI_AGENT_MODE=mock
export PI_WORKSPACE_ROOT=/tmp/finsmol-workspace
export FSI_CORS_ALLOW_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
uvicorn backend.app.main:app --reload

The API starts at http://127.0.0.1:8000.

Frontend

cd frontend
npm install
npm run dev

The UI opens at http://127.0.0.1:5173. It proxies /api and /ws to the backend automatically.

---

API Surface

Method	Path	Description
POST	/api/run-pipeline	Start a new pipeline run
GET	/api/runs	List recent runs (?limit=N)
GET	/api/runs/{run_id}	Get run status snapshot
GET	/api/runs/{run_id}/events	Get event history for a run
POST	/api/runs/{run_id}/approve	Approve or reject a blocked run
GET	/api/health	Liveness check (returns current mode)
WS	/ws/runs/{run_id}	Live event stream (status, approval, completion)

---

Key Design Principles

• Three-tier trust boundary: untrusted document readers (Read/Grep only) → trusted orchestrator (read-only MCP) → single write-holder leaf worker
• Schema-validated handoffs: every agent-to-agent handoff payload validates against versioned JSON Schema before dispatch
• Provenance tracking: every metric persisted downstream carries source system, document, location, retrieval timestamp, and confidence
• Pi sandbox guardrails: workspace jail, hard timeout kill, deterministic PYTHONHASHSEED, allowed-imports whitelist, structured results.json output validation
• Pluggable task queue: in-memory queue scaffold ships by default; production deployments can swap in Redis, Celery, or Temporal
• Human-in-the-loop: compliance approval gates block execution until explicit approve/reject decision via REST API