Metadata-Version: 2.5
Name: ai-mrg
Version: 0.3.0
Summary: Open-source, full-lifecycle AI and model risk governance toolkit for U.S. regulated industries.
Project-URL: Homepage, https://github.com/abiroland/ai-mrg-framework
Project-URL: Documentation, https://abiroland.github.io/ai-mrg-framework/
Project-URL: Issues, https://github.com/abiroland/ai-mrg-framework/issues
Project-URL: Changelog, https://github.com/abiroland/ai-mrg-framework/blob/main/CHANGELOG.md
Author: AI-MRG Framework contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: AI governance,NIST AI RMF,SR 26-2,adverse action,fair lending,model risk management
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mlflow-skinny>=2.12; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
Requires-Dist: streamlit>=1.50; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == 'api'
Requires-Dist: python-multipart>=0.0.9; extra == 'api'
Requires-Dist: uvicorn>=0.29; extra == 'api'
Provides-Extra: dashboard
Requires-Dist: httpx>=0.27; extra == 'dashboard'
Requires-Dist: streamlit>=1.50; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: mlflow-skinny>=2.12; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: python-docx>=1.1; extra == 'dev'
Requires-Dist: python-multipart>=0.0.9; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: streamlit>=1.50; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == 'docx'
Provides-Extra: mlflow
Requires-Dist: mlflow-skinny>=2.12; extra == 'mlflow'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# AI-MRG Framework

**An open-source, full-lifecycle AI and model risk governance toolkit for U.S. regulated industries — starting with financial services.**

> Status: **v0.3 (Phase 3 complete)**. New in v0.3: a **web dashboard**, **MLflow** integration, **Docker Compose**, the generative/agentic AI track (evaluation, red-team and agent-permission checks mapped to NIST AI 600-1), Colorado SB 26-189 controls and draft notices, and verifiable examination packages. From v0.2: Inventory, classification, risk tiering, control planning, automated checks (data, performance, stability, outcomes, **fair lending**, **adverse-action reasons**), a gated **lifecycle workflow** with independent approval, a tamper-evident evidence trail, findings with aging, reports in Markdown and Word, a **REST API** with role-based access, **PostgreSQL** support and signed **webhooks**. Next: practitioner review, pilots and the 1.0 hardening (Phase 4). See [`docs/ROADMAP.md`](docs/ROADMAP.md). Pack content has **not yet been reviewed by practitioners**.

[![CI](https://github.com/abiroland/ai-mrg-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/abiroland/ai-mrg-framework/actions/workflows/ci.yml)

---

## Why this exists

U.S. guidance tells institutions *what* good AI and model governance looks like. Turning that into day-to-day practice is the hard part. That means inventories, risk tiers, validation evidence, fairness testing, adverse-action reasons, monitoring thresholds and audit-ready documents. Enterprise platforms do this well, but they are licensed products. Community banks, credit unions, fintech start-ups and academic researchers often cannot justify the cost.

The 2026 regulatory reset makes the gap sharper:

- **SR 26-2 / OCC Bulletin 2026-13 (April 17, 2026)** replaced SR 11-7. It is principles-based and risk-based, sets no enforceable standards and is aimed mainly at banks over $30B in assets. **It explicitly excludes generative and agentic AI.** Institutions are told to cover those with their own governance practices.
- **ECOA / Regulation B** still require specific, accurate adverse-action reasons, whatever the model's complexity (CFPB Circulars 2022-03 and 2023-03).
- **Colorado SB 26-189** brings automated-decision-making obligations for lending and other consequential decisions starting **January 1, 2027**.
- **NIST AI RMF 1.0** and its **Generative AI Profile (NIST AI 600-1)** remain the main voluntary reference. A revision is in progress.

AI-MRG turns these sources into **versioned control catalogs, automated checks, evidence trails and document templates** that any institution can run locally, with no license fee, no vendor account and no telemetry.

## What it will do

| Capability | Description |
|---|---|
| **Inventory & classification** | Register every model and AI system. Classify it as *model* under SR 26-2, or as GenAI or agentic AI, and route it to the right governance track. |
| **Risk tiering** | Configurable scoring on inherent risk, exposure, purpose, materiality and aggregate risk, using SR 26-2's risk factors. |
| **Control catalog** | Lifecycle controls stored as data (YAML), each with its regulatory references, required evidence and applicability rules. |
| **Checks library** | Python checks for data quality, performance, stability, outcomes analysis, fair lending and adverse-action reason quality. |
| **Evidence & audit trail** | Append-only, hash-chained evidence records linked to controls, findings and approvals. |
| **Document generation** | Development documents, validation reports, monitoring reports, adverse-action reason maps and inventory reports. |
| **Dashboard** | A web UI for inventory, review workflows, findings and monitoring. |

## What it is not

- Not legal advice, and not a certification. Using AI-MRG does not by itself make an institution compliant.
- Not a replacement for independent validation or human judgment. It structures and evidences that work.
- Not a hosted service. You run it yourself.

## Quick start

```bash
git clone https://github.com/abiroland/ai-mrg-framework
cd ai-mrg-framework
pip install -e ".[dev]"

# A complete run on a simulated credit model: registry, evidence, findings, reports
python examples/credit-scorecard/run_example.py demo
```

Or run PostgreSQL, the API and the dashboard together:

```bash
POSTGRES_PASSWORD='choose-one' docker compose up -d --build
docker compose exec api cat /data/bootstrap-admin-token   # sign in at http://127.0.0.1:8501
```

![AI-MRG dashboard](docs/img/dashboard-lifecycle.png)

Then follow [Getting started](docs/getting-started.md) for the step-by-step workflow (`aimrg init → register → classify → tier → plan → check run → report render → audit verify`). See [Checks](docs/checks.md) and [Writing packs](docs/packs.md) for details.

## Documentation

- [Architecture](docs/ARCHITECTURE.md): system design, modules, data model, interfaces
- [Regulatory map](docs/REGULATORY_MAP.md): how controls trace to SR 26-2, ECOA/Reg B, NIST AI RMF, Colorado and others
- [Roadmap](docs/ROADMAP.md): phased delivery plan and success metrics
- [Architecture decision records](docs/adr/)

## Scope by release

- **Financial services (U.S. banking and consumer lending)**: first, v0.1–v1.0
- **Healthcare**: planned as a second sector pack on the same core, after v1.0

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Regulatory content changes must cite a primary source.

## License

Apache License 2.0. See [ADR-0001](docs/adr/0001-license-apache-2.md).
