attestant 0.10.0
Attestant: Cryptographically Provable AI Compliance for Banks
Requires Python: >=3.9
Keywords: provenance, ml, machine-learning, data-lineage, audit, compliance, fairness, fair-lending, disparate-impact, documentation, model-risk-management, sr-11-7, ecoa, eu-ai-act, banking

# Attestant

Compliance platform for regulated ML. Most functionality is accessed through the dashboard.

The Python library is **optional** and used only to integrate your ML pipeline with Attestant for automated compliance testing and fairness analysis.

```
pip install attestant
```

**→ [See IMPLEMENTATION.md for full setup guide](../../IMPLEMENTATION.md)**

## Quick Start

For most users, you don't need to write code. Just:

1. **Log into your dashboard** → https://your-company.attestant.ai/
2. **Upload a model** → Models → Upload
3. **View compliance scores** → Dashboard shows fairness, compliance, deployment status

## Pipeline Integration (Optional)

If you want your ML pipeline to auto-submit models to Attestant, use the Python library:

```python
import attestant
from attestant.api.orchestrator import run_full_pipeline

attestant.configure(api_key="pvt_live_...")

# After training your model
model = train_model(data)
model.save("model.pkl")

# Submit to Attestant for compliance testing
results = run_full_pipeline(
    model_path="model.pkl",
    data=test_data,
    protected_attributes=["race", "gender"],
    pipeline_name="credit_v2",
)

if results['deployment_decision'] == "approved":
    deploy_to_production(model)
```

Everything else happens in the dashboard.

## CLI

```bash
attestant fairness analyze --model m.pkl --data d.csv --protected race,sex --industry lending
attestant docs generate --template sr11-7 --model metadata.json
attestant docs templates
attestant dashboard
```

## Architecture

```
              attestant.configure(api_key="...")
                         |
    +--------------------+--------------------+
    |                    |                    |
  wrap(df)         FairLensEngine      ComplianceScorer
    |                    |                    |
 DAGTracker        DI / Proxy / LDA    SR 11-7 / ECOA / EU AI Act
    |                    |                    |
 fingerprints       fairness_results    compliance_report
    |                    |                    |
    +--------+-----------+--------------------+
             |
      DeploymentGate  ------>  Approved / Blocked
             |
      AsyncWriter  ---------> PostgreSQL / S3
             |
      Dashboard Sync  ------> Admin + Client Dashboards
```

## Modules

| Module | Description |
|--------|-------------|
| `attestant` | Core provenance DAG engine with 24-bit tamper-proof fingerprints and Merkle tree anchoring |
| `attestant.fairness` | Disparate impact analysis, proxy detection, LDA search, adverse action reason codes |
| `attestant.compliance` | SR 11-7, ECOA / Reg B, EU AI Act, Colorado AI Act, NYC Local Law 144 engines |
| `attestant.deployment` | Hard deployment gate that blocks non-compliant models, fairness regression testing |
| `attestant.docs` | Auto-generated SR 11-7, EU AI Act, Model Card, ECOA, GDPR, NIST AI RMF documents |
| `attestant.persistence` | PostgreSQL, S3, DuckDB, hosted HTTP storage backends with async writer |
| `attestant.dashboard` | Admin dashboard (platform-wide) and client dashboard (per-tenant compliance portal) |
| `attestant.api` | REST API server with pipeline sync, provenance storage, and orchestration |
| `attestant.governance` | Model registry, PII detection, retention policies, regulatory calendar |
| `attestant.vendor` | Third-party risk management, SOC 2 / ISO 27001 certification tracking |
| `attestant.examiner` | Exam preparation packages and model card generation |

## Compliance Engines

Each engine returns a `ComplianceReport` with regulation-specific findings, severity levels, regulatory citations, and remediation guidance.

| Engine | Regulation | Key Checks |
|--------|-----------|------------|
| SR 11-7 | OCC 2011-12 | Model validation, ongoing monitoring, documentation |
| ECOA | Reg B (12 CFR 1002) | Disparate impact, adverse action notices, four-fifths rule |
| EU AI Act | Regulation (EU) 2024/1689 | Risk classification, transparency, human oversight |
| Colorado | SB 24-205 | Algorithmic discrimination, impact assessments |
| NYC LL144 | Local Law 144 | Automated employment decision tools, bias audits |

## Dashboards

Two Flask-based dashboards connect to Aurora PostgreSQL in production.

**Admin Dashboard** (port 5004) — Platform-wide view for Attestant operators:
- System health, client directory, alert management
- Cross-tenant compliance scoring, fairness analysis, pipeline monitoring
- Revenue tracking and model inventory

**Client Dashboard** (port 5003) — Per-tenant view for bank CROs/CCOs:
- Compliance score with 7-point provenance quality assessment
- Disparate impact analysis with auto-computed DI ratios
- Risk heatmap, examiner readiness checklist, peer benchmarking
- Action center, remediation queue, regulatory change tracking
- Report generation (SR 11-7, ECOA, Model Card) with PDF/DOCX export
- Value-level lineage explorer with per-applicant decision tracing

```bash
DASH_WRITER_DSN=postgresql://... ADMIN_TOKEN=... attestant-admin-dashboard
DASH_WRITER_DSN=postgresql://... DASH_TENANT=... attestant-client-dashboard
```

## API Server

REST API for cloud-hosted provenance persistence and dashboard data sync.

```bash
ATTESTANT_DSN=postgresql://... ATTESTANT_API_SECRET=... attestant-api
```

Key endpoints:

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/auth/validate` | Validate API key |
| POST | `/v1/pipelines` | Register pipeline run |
| POST | `/v1/nodes` | Store DAG nodes (batch) |
| POST | `/v1/edges` | Store DAG edges (batch) |
| POST | `/v1/values` | Store row-level values (batch) |
| GET | `/v1/values` | Retrieve value-level lineage for a row |
| POST | `/v1/dashboard/sync` | Sync pipeline results to dashboard tables |
| GET | `/v1/health` | Health check |

## Deployment

### AWS (Production)

The `deploy/` directory contains everything needed for EC2 + Aurora PostgreSQL deployment:

- `deploy.sh` — Main deployment script (rsync, pip install, service restart, health checks)
- `setup-ec2.sh` — EC2 instance provisioning
- `nginx.conf` — Reverse proxy for admin (/admin/), client (/client/), API (/v1/)
- Systemd service files for API, admin, and client dashboards
- CloudFormation templates for Aurora, ALB, Cognito, S3 lifecycle, deployment gate Lambda

```bash
./deploy/deploy.sh
```

### AWS Lambda (Deployment Gate)

The deployment gate runs as a Lambda function for CI/CD integration:

```bash
./deploy/deploy-gate-lambda.sh
```

## Storage Backends

```python
from attestant.persistence import create_storage, PostgreSQLStorage

# PostgreSQL (production — used directly)
storage = PostgreSQLStorage(dsn="postgresql://user:pass@host/db")

# S3 (archival)
storage = create_storage("s3://bucket/prefix")

# DuckDB (analytics)
storage = create_storage("duckdb:///analytics.duckdb")

# Hosted API (client SDK → Attestant cloud)
from attestant.persistence import HostedStorage
storage = HostedStorage(api_url="https://api.attestant.ai", api_key="pvt_live_...")
```

## Install

```bash
pip install attestant                          # core (numpy, pandas)
pip install "attestant[fairness]"              # + scikit-learn
pip install "attestant[dashboard]"             # + flask
pip install "attestant[server]"               # + flask, psycopg2, gunicorn
pip install "attestant[dashboard,server]"      # dashboards + API server
pip install "attestant[export]"               # + PDF and DOCX generation
pip install "attestant[all]"                  # everything
```

## Test

```bash
pytest tests/ -v
```

## Requirements

- Python >= 3.9
- numpy >= 1.24
- pandas >= 2.0

## License

Business Source License 1.1 (BUSL-1.1). Copyright (c) 2024-2026 Attestant, Inc.