Glass Box

Model-risk validation for AI agents.

I validate market-risk models for a living. The rulebook for that is SR 11-7 (now SR 26-2), and the question an examiner asks never changes: how do you know this model is sound, and how do you monitor it? When a bank puts an AI agent into a decision, the same question applies, but the guidance doesn't. SR 26-2 (April 17, 2026) rewrote U.S. model-risk guidance for the first time in fifteen years and explicitly left generative and agentic AI out of scope, deferring them to a future interagency request for information. So the models that are hardest to validate are the ones with no binding standard.

Glass Box is my attempt to close that gap with the discipline I already use. Wrap the agent, run the tests a second-line validator would actually run, gate its actions, and write the workpaper that shows effective challenge happened.

What a run gives you

• a verdict: PASS, CONDITIONAL PASS or FAIL
• one finding per test, with the numbers behind it
• a self-contained HTML validation workpaper you can forward to a reviewer

The demo validates a volatility forecaster I made deliberately flawed. Glass Box fails it:

Glass Box validation: FAIL. 4 finding(s); 3 on core pillars (conceptual soundness / outcomes).

  [FAIL] Conceptual Soundness / Methodology checklist
         3/4 methodology assertions documented. MISSING: Model limitations stated.
  [FAIL] Conceptual Soundness / Determinism / stochasticity probe
         Mean across-run output variance = 1.767e-07 (tol 1e-09). STOCHASTIC: identical inputs yield varying outputs; validation must treat this as a model-uncertainty source and bound it.

  RiskGate: KILL-SWITCH tripped (drawdown -18.0% <= -15%)

Two of the five tests shown. A validation tool you have never watched fail a bad model is not worth much, so the demo is built to fail.

• examples/ has the complete captured output of a real run: the full verdict, the emitted workpaper, and a step-by-step trace of the risk gate's latching kill-switch, with the commands to reproduce each.
• docs/architecture.md has the pipeline and RiskGate diagrams, shows where a second-line model risk function plugs in, and lists which thresholds are hard-coded today.

What it is not

Not a general LLM-eval library. The tests here are the ones a market-risk validator runs: conceptual soundness, outcomes analysis, backtesting, ongoing monitoring, plus a determinism probe for the non-determinism that agents add and that SR 26-2 named but did not address. The judgment about what counts as a finding is the point of the project, not a side effect.

Tests by pillar

SR 11-7 pillar	Glass Box test
Conceptual soundness	methodology checklist; determinism / stochasticity probe
Outcomes analysis	prediction error and bias; Kupiec-style backtest exceptions
Ongoing monitoring	input/output drift (PSI)
Governance	exposure caps; fractional-Kelly sizing; drawdown kill-switch

Method, rationale and pass/fail logic for every test: METHODOLOGY.md.

The longer argument, written for second-line model risk heads: Validating Agentic AI in the SR 26-2 Gap, a working paper (2026).

Who it is for

Second-line model risk and independent validation teams at regulated firms, and the validation shops and risk-tech vendors that carry the validation liability without deep market-risk staff. If you have to sign the workpaper that says an agent is sound enough to deploy, this is for you.

Quickstart

Requires Python 3.10 or newer. Install from source; the package is not on PyPI yet.

git clone https://github.com/moxproj/glassbox && cd glassbox
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m demo.run_demo          # validates a sample agent, writes demo/validation_report.html
pytest                           # smoke tests

PYTHONPATH=. glassbox demo is the console-script equivalent and produces the same output. The PYTHONPATH=. matters: pyproject.toml ships only the glassbox package, so demo is reachable only from a source checkout.

The demo validates the flawed volatility forecaster across a calm regime and a turbulent (jump-diffusion) regime. Glass Box fails it: it under-forecasts risk in the regime shift, it is non-deterministic across identical inputs, and it has an undocumented limitation. The workpaper lands in demo/validation_report.html.

The run is seeded, so it reproduces exactly. Full captured output, all five tests: examples/demo-output.txt.

Modules

• glassbox/harness.py: wrap any agent; instrument outputs, latency and repeatability
• glassbox/evals.py: the model-risk eval suite (the SR 11-7 / SR 26-2 pillars)
• glassbox/scenarios.py: synthetic stress and turbulence packs (GBM, jump-diffusion)
• glassbox/riskgate.py: the governance primitive (caps, Kelly sizing, kill-switch)
• glassbox/report.py: the HTML validation workpaper
• demo/: end-to-end example on public and synthetic data
• examples/: captured output of a real run (examples/README.md)
• docs/architecture.md: pipeline, risk-gate and model-risk integration diagrams

Roadmap

• Validate a real open-source agent (an SEC EDGAR filing summarizer) end to end
• PDF export of the workpaper and a hosted report viewer
• FRTB / P&L-attribution and VaR-attribution scenario packs
• Pluggable LLM-agent adapters (LangGraph, raw tool loops)
• Design-partner mode: run a partner's agent, deliver the report

Data and scope

Everything here runs on public or synthetic data. Nothing from any employer is in this repository.

License

MIT, see LICENSE. Not financial or legal advice.