bondfoundry 0.3.0

BondFoundry — the governance fabric for AI agents on the buy-side fixed-income desk.

An AI assistant for the buy-side fixed-income desk — and the working reference implementation of the FINOS AI Governance Framework v2.0.

30-second pitch. BondFoundry is a self-hosted AI assistant for buy-side fixed-income desks — Claude-backed pricing, risk, scenario analysis, curve ingestion, and HITL-gated trade booking over a real FIX 4.4 connection. It's also the working reference implementation of FINOS AI Governance Framework v2.0: every gate decision, every audit row, every eval case carries a structured framework_ref pointing to the AIGF v2.0 risks + mitigations it satisfies. Two truths, one codebase — the bond desk gets a credible agent surface, the auditor gets a complete control mapping.

Why this exists

BondFoundry was built for the buy-side fixed-income desk first — the kind of team that already prices bonds in QuantLib, holds positions across USD / EUR / GBP / JPY books, and would like a Claude-backed analyst on the desk without handing the keys to a vendor SaaS. While building it we realised the governance machinery underneath was reusable and well-aligned with the FINOS AIGF v2.0 taxonomy, so we shipped it as the FINOS reference implementation too.

FINOS AIGF v2.0 shipped 23 risks + 23 mitigations as a Markdown taxonomy. The cost of that framework-agnostic format: no runnable artifact for new adopters to study, audit, or fork. finos/air-accelerator is the slot waiting to be filled.

BondFoundry is that artifact. Every AIGF v2.0 risk has a mapped mitigation in code, every mitigation has at least one passing eval case, every audit row carries the framework reference an external auditor needs to verify coverage. The CI gate fails any PR that drops AIGF coverage below 85%.

See FINOS.md for the full positioning and reference-implementation status. For the buy-side workflow walkthrough, start at documentation/for-buy-side/.

Pick your path

📈 Buy-side desk Price, risk, scenarios, FIX-booked trades — with HITL above your materiality. The agent your PM, trader, and treasury team actually use. For the buy-side desk →

⚙️ CTOs & engineers Architecture, hash-chained audit internals, fastworker operations, FIX gateway, threat model. For engineers →

🧠 Quants & AI architects Agent loop, MCP boundary, four-dimension eval, policy gate as a pure function you can embed. For quants →

🏛️ FINOS / compliance The reference implementation. Mapping, evidence pack, cross-framework alignment, submission status. For FINOS reviewers →

---

What this is — and isn't

Is. A self-hostable AI assistant for the buy-side fixed-income desk — QuantLib pricing, KRD / DV01, scenario shocks, curve ingestion (ECB / UST / Bloomberg BVAL / Refinitiv / CSV), FIX 4.4 OMS connectivity, Slack + Teams approval notifications, an operator workspace with HITL queue, hash-chained audit trail. It's also a complete, self-hostable reference for putting Claude-backed AI agents in front of any governed financial workflow: forkable control plane (policy gate, append-only audit, HITL flows, eval harness, OIDC SSO) with every primitive mapped to FINOS AIGF v2.0.

Isn't. A pricing engine for live trading without your own validation — the QuantLib backend is parity-tested for vanilla bonds; callables / FRNs / inflation-linked are scaffolded but you bring the reference bonds. A managed-service SaaS. A replacement for BlackRock Aladdin, SimCorp Dimension, Charles River, or Bloomberg AIM (the goal is to sit alongside whatever OMS / book-of-record you already run, not replace it).

The four pillars

Pillar	What it is	Where it lives	FINOS AIGF v2.0 ID
Policy gate	Single pure function every governed action passes through. Tier-routed by reversibility (T0/T1/T2/T3). Verbatim rule citation on every blocked decision.	packages/bondfoundry_policy/	AIR-OP-6 Tier routing, AIR-OP-4 SoD
Hash-chained audit log	Append-only at the DB layer (Postgres triggers reject UPDATE/DELETE) + sha256 chain across rows (Tier 3 tamper-evidence).	packages/bondfoundry_engine/.../audit/chain.py	AIR-DET-21 Tier 3, AIR-RC-22
HITL approval envelopes	HMAC-signed envelopes the agent can't forge. Single-HITL (T2) + dual-HITL (T3). SoD enforced server-side.	packages/bondfoundry_policy/envelope.py	AIR-SEC-24, AIR-OP-18
AIGF coverage gate	Continuous monitoring as CI: every PR runs the eval harness, fails the build if AIGF coverage drops below 85% or any risk has zero passing cases.	packages/bondfoundry_eval/.../coverage.py	AIR-OP-14

Quick start

Docker compose (60-second demo)

cp .env.example .env
python -c "import secrets; print('BONDFOUNDRY_SESSION_SECRET=' + secrets.token_hex(32))" >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

make demo

Open http://localhost:5173.

Local development with uv

uv sync --all-extras --all-packages
make migrate
make seed
make test                    # 126+ unit tests across 5 packages
make eval                    # 4-dim battery + AIGF coverage report
bondfoundry-finos coverage --threshold 0.85
bondfoundry-finos mapping --format markdown
bondfoundry-finos evidence-pack --period 30d

Python packages

BondFoundry is published to PyPI as eight independently installable packages plus a metapackage. Pick what you need; each is import-safe on its own.

Package	What it gives you	Install
bondfoundry	Metapackage — installs all eight below.	pip install bondfoundry
bondfoundry-policy	Pure-function policy gate (Allow / RequireHumanApproval / Deny). Zero runtime deps beyond pyyaml.	pip install bondfoundry-policy
bondfoundry-authlib	FastAPI auth — header-trust + OIDC + signed-cookie sessions.	pip install bondfoundry-authlib
bondfoundry-engine	Fixed-income pricing, risk, curves, trades, positions, MCP server.	pip install bondfoundry-engine
bondfoundry-agent	Claude-backed Bond Quant Analyst service that drives the engine over MCP.	pip install bondfoundry-agent
bondfoundry-eval	Four-dimension eval harness (accuracy / policy / robustness / latency).	pip install bondfoundry-eval
bondfoundry-finos	FINOS AIGF v2.0 CLI — mapping, coverage, evidence-pack, submission render, badges.	pip install bondfoundry-finos
bondfoundry-fix	FIX 4.4 acceptor for buy-side OMS integration.	pip install bondfoundry-fix
bondfoundry-notifications	Slack + Teams webhook dispatcher for governance audit events.	pip install bondfoundry-notifications

All packages require Python ≥ 3.12 and are released under MIT.

Architecture

   browser (web/)  ──HTTP/SSE──>  agent service (:9000)
                                    │  Claude Agent SDK loop
                                    │  X-Actor-Id: llm:<sess>
                                    │  X-Tenant-Id: <tenant>
                                    ▼
                            engine MCP (:8001)  ──┐
                                    │             │   policy gate (pure fn)
                                    ▼             │   bondfoundry_policy.evaluate
                            engine REST (:8000)   │
                                    │             ▼
                                    └──> Postgres ──> audit_events (hash-chained, append-only)
                                    │
                                    └──> fastworker control plane (:6000)
                                    │       └──> subworkers (EOD, curves, scenarios)
                                    │
                                    └──> FIX 4.4 acceptor (:9876)
                                    │       └──> OMS New Order Single → create_trade (T2 + HITL)
                                    │
                                    └──> notifications dispatcher
                                            └──> Slack + Teams webhooks

Identity travels on X-Actor-Id (transport-bound — the LLM cannot forge it) and X-Tenant-Id (also transport-bound and validated against the actor's tenant). The agent has zero Python imports from the engine; everything goes through MCP HTTP.

Tool surface

15 MCP tools registered with tiers + AIGF framework_ref. See documentation/reference/mcp-tools.md for the full catalogue. Headline:

Tier	Tools	Materiality routing
T0 read	price_bond, calculate_risk, run_scenario, list_*, get_*, query_audit	n/a
T1 reversible	ingest_curve, generate_eod_report, flag_exception	auto-confirm; audited
T2 above-materiality	create_instrument, create_trade, upload_trades_csv	HITL above threshold; session-aggregate ledger closes the split-trade bypass
T3 destructive	delete_instrument, purge_trades, update_portfolio_policy	manager-only, dual-HITL, rationale required, LLM denied outright

What's shipped vs. planned

Capability	Status
Policy gate (pure function + 65 tests)	✅ shipped
HMAC-signed approval envelopes	✅ shipped
Session-aggregate materiality ledger	✅ shipped
JWKS TTL cache with rotation	✅ shipped
Session-bound OIDC state cookies	✅ shipped
AIGF v2.0 risk+mitigation enums + tool catalog	✅ shipped
bondfoundry-finos CLI (mapping, coverage, evidence-pack, submission render, badges)	✅ shipped
Cross-framework refs (NIST AI RMF / NIST 800-53r5 / EU AI Act / ISO 42001 / SR 11-7 / OWASP / FFIEC / MAS)	✅ shipped
FINOS submission package (9 mi-*.md files)	✅ shipped
documentation/for-finos/ branch	✅ shipped
Hash-chained audit log (Tier 3) + verifier	🚧 in progress (Phase D)
QuantLib pricing	🚧 in progress (Phase F)
FIX 4.4 OMS gateway	🚧 in progress (Phase M)
Bloomberg + Refinitiv curve adapters	🚧 in progress (Phase N)
Slack + Teams notifications	🚧 in progress (Phase O)
Multi-agent A2A flows	🚧 in progress (Phase P)
End-to-end OpenTelemetry traces	🚧 in progress (Phase Q)
Per-portfolio policy editor (workspace)	🚧 in progress (Phase R)
HA + restore drills	🚧 in progress (Phase S)

See ROADMAP.md for the full v0.3.0 cut.

Configuration

All settings live in BONDFOUNDRY_* env vars. See .env.example and documentation/reference/env-vars.md.

Key knobs:

• BONDFOUNDRY_ENV — dev / staging / prod
• BONDFOUNDRY_AUTH_BACKEND — header-trust / oidc
• BONDFOUNDRY_SESSION_SECRET — rotate to log everyone out
• BONDFOUNDRY_ENVELOPE_SECRET — HMAC key for approval envelopes (defaults to session secret)
• BONDFOUNDRY_MATERIALITY_USD — global T2 threshold (overridable per portfolio)
• BONDFOUNDRY_PROMPT_FIREWALL_MODE — off / detect / detect-and-sanitise / block

License + governance

MIT. See LICENSE, SECURITY.md, COMPLIANCE.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md.