Metadata-Version: 2.4
Name: bondfoundry
Version: 0.3.0
Summary: BondFoundry — the governance fabric for AI agents on the buy-side fixed-income desk.
Author: BondFoundry contributors
License-Expression: MIT
Project-URL: Homepage, https://bondfoundry.dev
Project-URL: Documentation, https://bondfoundry.dev
Project-URL: Repository, https://github.com/Skelf-Research/bondfoundry
Project-URL: Issues, https://github.com/Skelf-Research/bondfoundry/issues
Project-URL: Changelog, https://github.com/Skelf-Research/bondfoundry/blob/main/ROADMAP.md
Keywords: fixed-income,ai-governance,finos,aigf,mcp,claude,buy-side,bond-pricing,hitl,audit,compliance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bondfoundry-engine==0.3.0
Requires-Dist: bondfoundry-agent==0.3.0
Requires-Dist: bondfoundry-policy==0.3.0
Requires-Dist: bondfoundry-authlib==0.3.0
Requires-Dist: bondfoundry-eval==0.3.0
Requires-Dist: bondfoundry-finos==0.3.0
Requires-Dist: bondfoundry-fix==0.3.0
Requires-Dist: bondfoundry-notifications==0.3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pre-commit>=3.8; extra == "dev"
Requires-Dist: types-python-dateutil>=2.8.19; extra == "dev"
Requires-Dist: types-redis>=4.6.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="documentation/assets/logo.svg" width="240" alt="BondFoundry" />
</p>

<h3 align="center">An AI assistant for the buy-side fixed-income desk — and the working reference implementation of the FINOS AI Governance Framework v2.0.</h3>

<p align="center">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  <a href="pyproject.toml"><img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-blue.svg"></a>
  <a href="FINOS.md"><img alt="FINOS AIGF v2.0" src="https://img.shields.io/badge/FINOS%20AIGF-v2.0-7c3aed.svg"></a>
  <a href="FINOS.md"><img alt="AIGF coverage" src="https://img.shields.io/badge/AIGF%20coverage-23%2F23-4c1.svg"></a>
  <a href="documentation/for-finos/tier3-decision-audit.md"><img alt="AIR-DET-21 Tier 3" src="https://img.shields.io/badge/AIR--DET--21-Tier%203-4c1.svg"></a>
  <a href="ROADMAP.md"><img alt="Status: alpha" src="https://img.shields.io/badge/status-alpha-orange.svg"></a>
</p>

<p align="center">
  <img src="documentation/assets/hero-policy-gate.svg" width="720" alt="BondFoundry — agent actions flow through a single pure-function policy gate, into a hash-chained tamper-evident audit log, with HITL routing on above-materiality writes." />
</p>

> **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](https://air-governance-framework.finos.org/): 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](https://www.finos.org/blog/finos-ai-governance-framework-v2.0-addressing-agentic-ai-risks-in-a-rapidly-evolving-landscape) 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`](https://github.com/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`](FINOS.md) for the full positioning and reference-implementation status. For the buy-side workflow walkthrough, start at [`documentation/for-buy-side/`](documentation/for-buy-side/).

## Pick your path

<table>
<tr>
<td width="25%" align="center" valign="top">
<h3>📈 Buy-side desk</h3>
<p>Price, risk, scenarios, FIX-booked trades — with HITL above your materiality. The agent your PM, trader, and treasury team actually use.</p>
<a href="./documentation/for-buy-side/"><strong>For the buy-side desk →</strong></a>
</td>
<td width="25%" align="center" valign="top">
<h3>⚙️ CTOs & engineers</h3>
<p>Architecture, hash-chained audit internals, fastworker operations, FIX gateway, threat model.</p>
<a href="./documentation/for-engineers/"><strong>For engineers →</strong></a>
</td>
<td width="25%" align="center" valign="top">
<h3>🧠 Quants & AI architects</h3>
<p>Agent loop, MCP boundary, four-dimension eval, policy gate as a pure function you can embed.</p>
<a href="./documentation/for-quants/"><strong>For quants →</strong></a>
</td>
<td width="25%" align="center" valign="top">
<h3>🏛️ FINOS / compliance</h3>
<p>The reference implementation. Mapping, evidence pack, cross-framework alignment, submission status.</p>
<a href="./documentation/for-finos/"><strong>For FINOS reviewers →</strong></a>
</td>
</tr>
</table>

---

## 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/`](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`](packages/bondfoundry_engine/src/bondfoundry/audit/) | `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`](packages/bondfoundry_policy/src/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`](packages/bondfoundry_eval/src/bondfoundry_eval/coverage.py) | `AIR-OP-14` |

## Quick start

### Docker compose (60-second demo)

```bash
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

```bash
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`](https://pypi.org/project/bondfoundry/) | **Metapackage** — installs all eight below. | `pip install bondfoundry` |
| [`bondfoundry-policy`](https://pypi.org/project/bondfoundry-policy/) | Pure-function policy gate (Allow / RequireHumanApproval / Deny). Zero runtime deps beyond `pyyaml`. | `pip install bondfoundry-policy` |
| [`bondfoundry-authlib`](https://pypi.org/project/bondfoundry-authlib/) | FastAPI auth — header-trust + OIDC + signed-cookie sessions. | `pip install bondfoundry-authlib` |
| [`bondfoundry-engine`](https://pypi.org/project/bondfoundry-engine/) | Fixed-income pricing, risk, curves, trades, positions, MCP server. | `pip install bondfoundry-engine` |
| [`bondfoundry-agent`](https://pypi.org/project/bondfoundry-agent/) | Claude-backed Bond Quant Analyst service that drives the engine over MCP. | `pip install bondfoundry-agent` |
| [`bondfoundry-eval`](https://pypi.org/project/bondfoundry-eval/) | Four-dimension eval harness (accuracy / policy / robustness / latency). | `pip install bondfoundry-eval` |
| [`bondfoundry-finos`](https://pypi.org/project/bondfoundry-finos/) | FINOS AIGF v2.0 CLI — mapping, coverage, evidence-pack, submission render, badges. | `pip install bondfoundry-finos` |
| [`bondfoundry-fix`](https://pypi.org/project/bondfoundry-fix/) | FIX 4.4 acceptor for buy-side OMS integration. | `pip install bondfoundry-fix` |
| [`bondfoundry-notifications`](https://pypi.org/project/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`](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`](ROADMAP.md) for the full v0.3.0 cut.

## Configuration

All settings live in `BONDFOUNDRY_*` env vars. See [`.env.example`](.env.example) and [`documentation/reference/env-vars.md`](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`](LICENSE), [`SECURITY.md`](SECURITY.md), [`COMPLIANCE.md`](COMPLIANCE.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CONTRIBUTING.md`](CONTRIBUTING.md).
