Skip to content

Commit b4ef06a

Browse files
TamTunnelTamTunnel
committed
feat(v0.3): Add Policy Engine, Multi-tenancy, Observability
Policy Engine: - Add Policy and PolicyViolation models with enforcement - Add policy_engine.py with condition checks - Add policy_routes.py with CRUD and violations API - Block actions that violate active policies - Create audit log entries for violations Multi-tenancy: - Add Organization model - Add Environment enum (dev/test/staging/prod) - Add organization_id and environment to ModelRegistry - Add organization_routes.py with CRUD API Observability: - Add Prometheus-compatible /metrics endpoint - Expose model counts, risk levels, violations Frontend: - Add PolicyList page with create modal - Add PolicyViolations page - Add Policies button to ModelList - Update types.ts with Policy/Organization types Documentation: - Update README with Policy Engine section - Add Security & Deployment section - Add Observability section with Prometheus example - Add Backup & Data Export section Tests: - Add test_policies.py - Add test_organizations.py
1 parent f18763c commit b4ef06a

File tree

18 files changed

+1136
-148
lines changed

18 files changed

+1136
-148
lines changed

‎README.md‎

Lines changed: 168 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -7,198 +7,224 @@
77

88
A **centralized platform** for managing your organization's AI models—a registry that tracks every AI system, its versions, performance metrics, risk profiles, and a complete audit trail for EU AI Act compliance.
99

10+
**v0.3** adds: **Policy Engine** with enforcement, **Multi-tenancy** with org/environment scoping, and **Prometheus-compatible metrics** for enterprise observability.
11+
1012
---
1113

1214
## Who Is This For?
1315

1416
| Role | Value |
1517
|------|-------|
16-
| **ML Engineers** | Register models, track versions, store evaluation metrics automatically via CI/CD |
17-
| **Compliance Officers** | View audit trails, approve compliance status, generate PDF reports for regulators |
18-
| **CTOs/Engineering Leaders** | Dashboard overview of model risk levels and compliance status across the organization |
19-
| **Auditors** | Read-only access to model registry, versions, metrics, and audit logs |
18+
| **ML Engineers** | Register models, track versions, store evaluation metrics via CI/CD |
19+
| **Compliance Officers** | Define policies, approve models, generate PDF reports |
20+
| **CTOs/CISOs** | Dashboard overview, policy enforcement, observability metrics |
21+
| **Auditors** | Read-only access to models, audit logs, policy violations |
2022

2123
---
2224

23-
## Usage Scenarios
25+
## Key Features
26+
27+
| Feature | Description |
28+
|---------|-------------|
29+
| **Model Registry** | Register AI models with name, owner, risk profile |
30+
| **Risk Profiles** | EU AI Act levels (minimal, limited, high, unacceptable) |
31+
| **Compliance Lifecycle** | Status: draft → under_review → approved → retired |
32+
| **Policy Engine** | Define and enforce governance rules automatically |
33+
| **Policy Violations** | Track blocked actions with full audit trail |
34+
| **Multi-Tenancy** | Organization + environment (dev/test/prod) scoping |
35+
| **Prometheus Metrics** | `/api/v1/metrics` endpoint for observability |
36+
| **PDF Reports** | EU AI Act style compliance documentation |
37+
| **RBAC** | admin, model_owner, auditor roles |
2438

25-
### Scenario 1: New Model Deployment
26-
1. ML team trains a new fraud detection model
27-
2. CI/CD pipeline automatically registers the model and pushes evaluation metrics
28-
3. Model starts in `draft` status with `high` risk level (finance domain)
29-
4. Compliance team reviews via `/dashboard`, updates to `under_review`
30-
5. After approval, status changes to `approved` with full audit trail
39+
---
3140

32-
### Scenario 2: EU AI Act Audit
33-
1. Regulator requests documentation for high-risk AI systems
34-
2. Compliance officer filters models by `risk_level=high`
35-
3. Downloads PDF compliance report for each model
36-
4. Report includes: intended purpose, data sources, evaluation metrics, oversight plan
41+
## Policy Engine
3742

38-
### Scenario 3: Model Retirement
39-
1. Old recommendation model needs to be retired
40-
2. Admin changes compliance status to `retired` with reason
41-
3. Audit log captures the change for future reference
42-
4. Model remains in registry for historical records
43+
### Supported Policy Types
4344

44-
---
45+
| Policy | Description |
46+
|--------|-------------|
47+
| `require_evaluation_before_approval` | Models must have evaluation metrics before approval |
48+
| `block_high_risk_without_approval` | High-risk models cannot skip `under_review` status |
49+
| `require_review_for_high_risk` | High-risk models require explicit review |
4550

46-
## Key Features
51+
### How It Works
4752

48-
| Feature | Description |
49-
|---------|-------------|
50-
| **Model Registry** | Register AI models with name, owner, description |
51-
| **Risk Profiles** | Classify models by EU AI Act risk levels (minimal, limited, high, unacceptable) |
52-
| **Compliance Lifecycle** | Track status: draft → under_review → approved → retired |
53-
| **Version Tracking** | Track model versions and artifact locations (S3) |
54-
| **Evaluation Metrics** | Store accuracy, F1, bias scores per version |
55-
| **Audit Logging** | Automatic immutable trail for all changes |
56-
| **Compliance Dashboard** | Visual overview of models by risk level and status |
57-
| **PDF Reports** | Generate EU AI Act style compliance documentation |
58-
| **Role-Based Access** | admin, model_owner, auditor roles |
59-
| **OAuth2 Auth** | JWT authentication |
60-
| **CI/CD Integration** | GitHub Actions workflow examples |
53+
1. **Define a policy** via API or UI (`/policies`)
54+
2. **Policy engine evaluates** on compliance status changes
55+
3. **Violations are blocked** with clear error messages
56+
4. **PolicyViolation record** created with full details
57+
5. **Audit log entry** captures the blocked action
58+
59+
### Example: Create a Policy
60+
61+
```bash
62+
curl -X POST "http://localhost:8000/api/v1/policies/" \
63+
-H "Content-Type: application/json" \
64+
-d '{
65+
"name": "Require Evaluation Before Approval",
66+
"description": "Models must have metrics before being approved",
67+
"scope": "global",
68+
"condition_type": "require_evaluation_before_approval",
69+
"is_active": true
70+
}'
71+
```
6172

6273
---
6374

64-
## Roles & Permissions (RBAC)
75+
## Organizations & Environments
76+
77+
### Conceptual Model
78+
79+
```
80+
Organization (e.g., "Agency A", "Department B")
81+
└── Environment (dev, test, staging, prod)
82+
└── Models (scoped by org + env)
83+
```
84+
85+
### How to Use
86+
87+
- **Models** include `organization_id` and `environment` fields
88+
- **API queries** can be filtered by organization/environment
89+
- **Users** belong to organizations (planned: multi-org access)
6590

66-
| Role | Permissions |
67-
|------|-------------|
68-
| `admin` | Full access - create, modify, delete models and users |
69-
| `model_owner` | Create/modify models, change compliance status |
70-
| `auditor` | Read-only - view models, audit logs, download reports |
91+
### Enterprise Mapping
92+
93+
| Enterprise Concept | Platform Feature |
94+
|-------------------|------------------|
95+
| Department/Agency | Organization |
96+
| SDLC Stage | Environment (dev/test/prod) |
97+
| Data Classification | Risk Level |
7198

7299
---
73100

74-
## EU AI Act Feature Mapping
101+
## Observability
102+
103+
### Prometheus Metrics
104+
105+
Access metrics at: `GET /api/v1/metrics`
106+
107+
```prometheus
108+
# HELP ai_governance_models_total Total number of registered AI models
109+
ai_governance_models_total 42
110+
111+
# HELP ai_governance_violations_total Total policy violations
112+
ai_governance_violations_total 3
113+
114+
# Models by risk level
115+
ai_governance_models_by_risk{risk_level="high"} 5
116+
ai_governance_models_by_risk{risk_level="minimal"} 20
117+
```
118+
119+
### Grafana Integration
75120

76-
| EU AI Act Requirement | Platform Feature |
77-
|----------------------|------------------|
78-
| Risk Classification | `risk_level` field (minimal, limited, high, unacceptable) |
79-
| Intended Purpose Documentation | `intended_purpose` field |
80-
| Data Sources Transparency | `data_sources` field |
81-
| Performance Metrics | Evaluation metrics per version |
82-
| Human Oversight Plan | `oversight_plan` field |
83-
| Change Audit Trail | Automatic compliance logs |
84-
| Lifecycle Management | `compliance_status` (draft → approved → retired) |
121+
1. Add Prometheus data source pointing to your Prometheus server
122+
2. Create dashboard with key metrics:
123+
- Model counts by risk level
124+
- Policy violations over time
125+
- Compliance status distribution
85126

86127
---
87128

88-
## Architecture
129+
## Security & Deployment Considerations
130+
131+
### Network Placement
132+
133+
> [!IMPORTANT]
134+
> This application should be deployed **behind a reverse proxy** (Nginx, Envoy, API Gateway) and not directly exposed to the internet.
89135
136+
**Recommended topology:**
90137
```
91-
┌─────────────────────────────────────────────────────────────┐
92-
│ FRONTEND (React) │
93-
│ • Model Registry List • Compliance Dashboard │
94-
│ • Risk Level Badges • Status Filters │
95-
└─────────────────────────────────────────────────────────────┘
96-
│ REST API
97-
▼
98-
┌─────────────────────────────────────────────────────────────┐
99-
│ BACKEND (FastAPI) │
100-
│ /api/v1/models → Model registry CRUD │
101-
│ /api/v1/models/{id}/risk-profile → Update risk profile │
102-
│ /api/v1/models/{id}/compliance-status → Change status │
103-
│ /api/v1/dashboard/stats → Dashboard statistics │
104-
│ /api/v1/versions → Version management │
105-
│ /api/v1/metrics → Evaluation metrics │
106-
│ /api/v1/audit-logs → Compliance history │
107-
│ /api/v1/reports/{id}/compliance-report → PDF download │
108-
└─────────────────────────────────────────────────────────────┘
109-
│
110-
▼
111-
┌─────────────────────────────────────────────────────────────┐
112-
│ DATABASE (PostgreSQL) │
113-
│ Tables: modelregistry, modelversion, evaluationmetric, │
114-
│ compliancelog, user │
115-
└─────────────────────────────────────────────────────────────┘
138+
Internet → Load Balancer → Nginx/Envoy (TLS) → AI Governance Hub → PostgreSQL
116139
```
117140

118-
---
141+
### TLS/HTTPS
119142

120-
## Quick Start
143+
- Configure TLS termination at the reverse proxy
144+
- Use Let's Encrypt or organizational certificates
145+
- Enforce HTTPS redirects
121146

122-
### Prerequisites
123-
- Docker & Docker Compose
124-
- Node.js 18+ (for frontend development)
147+
### Secrets Management
125148

126-
### Run with Docker
127-
```bash
128-
git clone https://github.com/TamTunnel/AI-Governance-Hub.git
129-
cd AI-Governance-Hub
130-
cp .env.example .env
131-
docker compose up --build
149+
| Secret | Source |
150+
|--------|--------|
151+
| `DATABASE_URL` | Environment variable |
152+
| `SECRET_KEY` | Environment variable (min 32 chars) |
153+
| `POSTGRES_PASSWORD` | Environment variable or secrets manager |
154+
155+
> [!CAUTION]
156+
> Never commit secrets to version control. Use `.env` files for local development only.
157+
158+
### Rate Limiting
159+
160+
Rate limiting should be configured at the reverse proxy level:
161+
162+
```nginx
163+
# Example Nginx rate limiting
164+
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
165+
location /api/ {
166+
limit_req zone=api burst=20 nodelay;
167+
}
132168
```
133169

134-
**URLs:**
135-
| Service | URL |
136-
|---------|-----|
137-
| Frontend | http://localhost:3000 |
138-
| Dashboard | http://localhost:3000/dashboard |
139-
| API Docs | http://localhost:8000/docs |
170+
### Logging & SIEM Integration
171+
172+
- All governance actions are logged to `ComplianceLog` table
173+
- Logs include: entity, action, user, timestamp, details (JSON)
174+
- Export logs to SIEM via database replication or API polling
140175

141176
---
142177

143-
## CI Integration
178+
## Backup & Data Export
144179

145-
### Example: Register model after training
180+
### PostgreSQL Backup
146181

147182
```bash
148-
# Register a new model
149-
curl -X POST "http://localhost:8000/api/v1/models/" \
150-
-H "Content-Type: application/json" \
151-
-d '{
152-
"name": "fraud-detector-v2",
153-
"owner": "ML Team",
154-
"risk_level": "high",
155-
"domain": "finance",
156-
"intended_purpose": "Detect fraudulent transactions"
157-
}'
183+
# Full backup
184+
pg_dump -h localhost -U postgres ai_governance > backup.sql
158185

159-
# Create a version
160-
curl -X POST "http://localhost:8000/api/v1/versions/" \
161-
-H "Content-Type: application/json" \
162-
-d '{
163-
"model_id": 1,
164-
"version_tag": "v1.0.0",
165-
"s3_path": "s3://models/fraud-detector/v1.0.0"
166-
}'
186+
# Restore
187+
psql -h localhost -U postgres ai_governance < backup.sql
188+
```
167189

168-
# Push evaluation metric
169-
curl -X POST "http://localhost:8000/api/v1/metrics/" \
170-
-H "Content-Type: application/json" \
171-
-d '{
172-
"version_id": 1,
173-
"metric_name": "accuracy",
174-
"value": 0.95
175-
}'
190+
### API Export
176191

177-
# Update compliance status
178-
curl -X PATCH "http://localhost:8000/api/v1/models/1/compliance-status" \
179-
-H "Content-Type: application/json" \
180-
-d '{
181-
"status": "under_review",
182-
"reason": "Ready for compliance review"
183-
}'
192+
- `GET /api/v1/models/` - Export all models
193+
- `GET /api/v1/audit-logs/` - Export audit trail
194+
- `GET /api/v1/policies/violations/` - Export policy violations
195+
196+
---
197+
198+
## Quick Start
199+
200+
```bash
201+
git clone https://github.com/TamTunnel/AI-Governance-Hub.git
202+
cd AI-Governance-Hub
203+
cp .env.example .env
204+
docker compose up --build
184205
```
185206

186-
See [`examples/ci-integration.yml`](examples/ci-integration.yml) for a complete GitHub Actions workflow.
207+
| Service | URL |
208+
|---------|-----|
209+
| Frontend | http://localhost:3000 |
210+
| Dashboard | http://localhost:3000/dashboard |
211+
| Policies | http://localhost:3000/policies |
212+
| API Docs | http://localhost:8000/docs |
213+
| Metrics | http://localhost:8000/api/v1/metrics |
187214

188215
---
189216

190217
## Roadmap
191218

192-
### Planned Features
193-
194-
| Priority | Feature | Description |
195-
|----------|---------|-------------|
196-
| 🔴 High | **Policy Engine** | Define and enforce compliance rules automatically |
197-
| 🔴 High | **Model Lineage** | Track data and model dependencies |
198-
| 🟡 Medium | **Notifications** | Webhooks and email alerts for status changes |
199-
| 🟡 Medium | **MLflow Integration** | Import models directly from MLflow |
200-
| 🟢 Future | **Kubernetes Operator** | Auto-register models deployed to K8s |
201-
| 🟢 Future | **LLM Governance** | Prompt tracking and response auditing |
219+
| Status | Feature |
220+
|--------|---------|
221+
| ✅ Done | Policy Engine with enforcement |
222+
| ✅ Done | Organization + environment scoping |
223+
| ✅ Done | Prometheus metrics endpoint |
224+
| 🔜 Planned | SSO/SAML integration |
225+
| 🔜 Planned | Webhooks for status changes |
226+
| 🔜 Planned | MLflow integration |
227+
| 🔜 Planned | Kubernetes operator |
202228

203229
---
204230

@@ -210,7 +236,7 @@ See [`examples/ci-integration.yml`](examples/ci-integration.yml) for a complete
210236
| Backend | Python 3.11, FastAPI, SQLModel, Pydantic |
211237
| Database | PostgreSQL 15 |
212238
| Auth | OAuth2, JWT, bcrypt, RBAC |
213-
| Reports | ReportLab (PDF) |
239+
| Observability | Prometheus-compatible metrics |
214240
| Infrastructure | Docker, Docker Compose, Nginx |
215241
| CI/CD | GitHub Actions |
216242

0 commit comments

Comments
 (0)