WhitePact β an independent runtime authority, governance, and assurance layer for autonomous systems: a five-way governance decision engine (ALLOW / ALLOW_WITH_REDACTION / REQUIRE_APPROVAL / DENY / QUARANTINE), trust scoring, bias detection, guardrails, hallucination detection, compliance mapping (NIST AI RMF / EU AI Act / ISO 42001), cost intelligence, drift monitoring, a public Trust Index / leaderboard / AI Incident Database, and an MCP server (30 tools, 20 resources) with LangChain, LangGraph, and Google ADK trust-gate integrations.
``` ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β WhitePact v1.2.3 β β β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β β Governance β β Trust Score β β Compliance β β Guardrails β β β β 5-way decide β β 6-dim AβF β β NIST/EU/ISO β β PII + Tox β β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β β Hallucinationβ β Cost Intel β β Red Team β β Drift Monitor β β β β Self-consist.β β Route+Budgetβ β 10 attacks β β Alerts+Trend β β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β β AI Passport β β BiasBuster β β PrivacyLabel β β MCP Server β β β β SHA-256 cert β β 6 probes+CI β β Federated β β 30 tools/HTTP β β β ββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β β Governance Dashboard β FastAPI Β· Per-org rate limit Β· Alembic Β· OTEL β β β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ ``` --- ## What this solves Every team deploying AI in production faces the same gap: **no unified way to prove a model β or an autonomous agent's actions β is safe, fair, compliant, and accountable.** Audits are manual, bias is discovered in production, compliance is a spreadsheet, an agent's tool calls go ungoverned, and nobody knows what the LLM bill will be next month. WhitePact gives you one platform β a REST API, a Python SDK, an MCP server, and a live dashboard β that covers the full governance lifecycle: | Problem | Module | Output | |---|---|---| | Should this agent action be allowed, redacted, held for approval, denied, or quarantined? | `WhitePactRuntimeGateway` (governance core) | A five-way `GovernanceDecision`, deterministic, no LLM call in the decision path | | Is this model trustworthy? | `TrustScoreEngine` | 0β100 score, AβF grade, risk level | | Does it comply with regulations? | `ComplianceEngine` | NIST AI RMF, EU AI Act tier, ISO 42001 | | Is it exposing PII? | `GuardrailsEngine` | Block / redact with audit log | | Is it hallucinating? | `HallucinationDetector` | Risk score, unsupported claims | | Can it be attacked? | `RedTeamSimulator` | 10 vectors, CVE IDs, safe-refusal rate | | How much is it costing? | `CostTracker` + `ModelRouter` | Per-model USD, routing to cheapest viable model | | Is it getting worse over time? | `TrustDriftMonitor` | 7/30-day trend, severity alerts | | Is it biased? | `BiasBuster` | 6 demographic probes, CI gate | | Is this data labeled privately? | `PrivacyLabel` | Federated DP labels, never leaves device | | Is this media real? | `DeepfakeDetector` | Ensemble confidence, method detected | | Can I trust a third-party MCP server before connecting to it? | `SupplyChainScanner` | VERIFIED_FACT / INFERRED_SIGNAL / UNKNOWN verdicts β typosquat, description-content, known-incident checks | | Is there a tamper-evident record of every governance decision? | `EvidenceRepository` | Hash-chained `EvidenceRecord`, per-org, `verify_chain()` | | Does a risky action get a human in the loop? | `ApprovalRepository` | Race-safe `PENDING β APPROVED/DENIED` workflow | | How does this model rank against others, independently? | `Public Leaderboard` | Cross-model trust ranking from actually calling each model's API, not self-reported | | Can I cite and verify a trust score anywhere? | `Trust Index` | Free self-assessed or human-reviewed certified passport, verifiable at `/verify/{id}`, embeddable badge | | Has this AI system failed publicly before? | `AI Incident Database` | Crowd-reported, moderator-reviewed, hash-chained public registry | | Should my agent trust this third-party tool before calling it? | `rai_check_trust` + LangChain/LangGraph/ADK integrations | Free lookup, plus a real block/pause gate in-agent | | Can any MCP client govern every AI call? | `MCP Server` | 27 governance tools over stdio, Streamable HTTP, or legacy HTTP+SSE | --- ## Install ```bash # Governance platform + REST API pip install "rai-governance-platform[dashboard]" # With PostgreSQL support pip install "rai-governance-platform[dashboard,postgres]" # With Redis + OpenTelemetry pip install "rai-governance-platform[dashboard,redis,telemetry]" # With LLM providers pip install "rai-governance-platform[dashboard,openai,anthropic]" # Everything pip install "rai-governance-platform[all]" ``` The published PyPI package name (`rai-governance-platform`) and the import name (`responsibleai`) predate the WhitePact rename and are kept as-is β see `MIGRATION_WHITEPACT_V2.md` Section 3 for why an alias package (`whitepact`) was added instead of renaming the published package outright. --- ## 30-second quickstart ```bash # Start the governance dashboard pip install "rai-governance-platform[dashboard]" uvicorn responsibleai.dashboard.app:app --port 8765 # Evaluate a model (no LLM key needed β supply your own scores) curl -X POST http://localhost:8765/api/evaluate \ -H "Content-Type: application/json" \ -d '{ "model_name": "gpt-4o", "provider": "openai", "fairness": 0.80, "privacy": 0.85, "security": 0.82, "robustness": 0.78, "compliance": 0.90, "authenticity": 0.88 }' ``` ```json { "trust_score": { "trust_score": 83.65, "grade": "B", "risk": "LOW" }, "compliance": { "overall_score": 80.5, "eu_ai_act_tier": "limited_risk", "violations": 0 }, "passport_id": "rai-a3f7c2b1", "passport_hash": "4d8e1f2a9c3b7e6d...", "drift_alert": null } ``` Open `http://localhost:8765` for the live dashboard and `http://localhost:8765/api/docs` for interactive API docs. --- ## Governance core β five-way decisions, not a binary block/allow `src/responsibleai/governance/` (see `SPEC.md` Sections 4-8 for the full architecture contract) is a deterministic runtime authority sitting in front of agent tool calls: ```python from responsibleai.governance import WhitePactRuntimeGateway, ActionRequest, AuthorityContext gateway = WhitePactRuntimeGateway() result = gateway.evaluate( action=ActionRequest(tool_name="rai_scan", arguments={"text": "..."}), authority=AuthorityContext(org_id="acme", agent_id="agent-1"), ) print(result.decision) # GovernanceDecision.ALLOW | ALLOW_WITH_REDACTION | REQUIRE_APPROVAL | DENY | QUARANTINE ``` - **Risk tiering** (`governance/risk.py`) β every MCP tool is classified against a hardcoded, drift-tested table, not inferred at call time. - **Policy engine** (`governance/policy.py`) β first-match-wins rules with `ALLOW` / `DENY` / `REQUIRE_APPROVAL` effects. - **Evidence** (`governance/evidence.py`) β every decision is written to a per-org, hash-chained `EvidenceRecord`; `verify_chain()` detects tampering. Raw argument values are never stored, only field-name keys. - **Approval workflow** (`governance/approval.py`) β `REQUIRE_APPROVAL` decisions queue a real, race-safe `ApprovalRequest` with a resolution API, not just a log line. - **Supply-chain scanner** (`src/responsibleai/supplychain/`) β before an agent trusts a third-party MCP server or tool, `SupplyChainScanner` returns one of three explicit verdicts (`VERIFIED_FACT` / `INFERRED_SIGNAL` / `UNKNOWN`) β never a single opaque trust score β from typosquat detection, tool-description scanning, and known-incident cross-reference. - **Identity Bridge** (`integrations/identity_bridge.py`) β maps Entra ID, Google Workspace, Okta, and AWS (Cognito / IAM Identity Center) ID token claims into `IdentityContext`, plus `map_groups_to_authority()` to turn IdP group membership into a granted-action-types `AuthorityContext`. See `MACHINE_AUTHORITY_V1.md`'s Identity Bridge section for exactly what's verified (claim-shape correctness against each provider's public docs) versus not (live-tenant testing, Graph/Admin-SDK group-name resolution, AWS's non-JWT SigV4 path). No governance decision is LLM-based; see `DETERMINISTIC_VS_PROBABILISTIC.md` for why. **See it end-to-end**: `examples/08_whitepact_enterprise_scenario.py` runs a full scenario (an org onboarding an autonomous finance agent) through all eight machine-authority invariants β ceiling, delegation, attenuation, approval quorum, workflow composition, autonomy budget, memory firewall, evidence bundle β against real code, no API keys required: ```bash python examples/08_whitepact_enterprise_scenario.py ``` --- ## MCP Server β govern every AI call from Claude Code, Claude Desktop, or any MCP client The MCP (Model Context Protocol) server exposes WhitePact as **30 tools and 20 resources** (10 canonical resource URIs, dual-advertised under both `whitepact://` and `rai://` schemes β see `MIGRATION_WHITEPACT_V2.md`) to any MCP-compatible client β Claude Code, Claude Desktop, Cursor, Windsurf, or your own agent runtime. Three transports are supported: stdio, Streamable HTTP (`/mcp`, current MCP spec), and legacy HTTP+SSE (`/sse` + `/messages/`, kept for older clients). When a team's client points at this server, every AI interaction is automatically governed β five-way governance decisions, trust scoring, guardrails, compliance checks (NIST AI RMF / EU AI Act / ISO 42001), bias evaluation, drift detection, cost tracking, and hash-chained audit evidence run on any call without code changes. ### Setup ```bash # Install pip install "rai-governance-platform[dashboard,mcp]" # Start the REST API (MCP tools call it internally) RAI_DB_PATH=/var/lib/rai/governance.db \ RAI_API_KEYS=your-key-here \ uvicorn responsibleai.dashboard.app:app --host 127.0.0.1 --port 8765 & # Add to Claude Code (~/.claude/claude_desktop_config.json or via /mcp) ``` ```json { "mcpServers": { "whitepact": { "command": "whitepact-mcp", "env": { "RAI_API_URL": "http://localhost:8765", "RAI_API_KEY": "your-key-here" } } } } ``` `whitepact-mcp` and `responsibleai-mcp` are the same entry point β see `pyproject.toml`'s `[project.scripts]`; both will keep working, use whichever name you prefer. ### Available tools (27) | Tool | What it does | |---|---| | `rai_scan` | Detect and redact PII + harmful content before it reaches a log | | `rai_trust_score` | Composite AI Trust Score (0-100) across 6 governance dimensions | | `rai_compliance` | NIST AI RMF / EU AI Act / ISO 42001 compliance evaluation | | `rai_hallucination` | Hallucination risk from hedging, consistency, unsupported claims | | `rai_cost_estimate` | USD cost of a model API call from token counts | | `rai_redteam_payloads` | Adversarial attack payloads (prompt injection, jailbreak, etc.) | | `rai_redteam_analyze` | Security report from model responses to red team payloads | | `rai_compare_models` | Compare two models across all 6 trust dimensions | | `rai_audit_summary` | Governance capability summary (tools, frameworks, attack vectors) | | `rai_health` | Status and module availability of the governance engine | | `rai_bias_evaluate` | Demographic bias across 6 probe dimensions with confidence intervals | | `rai_drift_check` | Trust score drift between a baseline and current evaluation | | `rai_passport_generate` | Verifiable, tamper-evident AI Passport for vendor risk assessment | | `rai_budget_check` | Spend vs. budget, per-team/model breakdown, month-end projection | | `rai_policy_check` | Text/response against a governance policy (blocklists, disclaimers) | | `rai_stream_scan` | PII/harm scan across streaming LLM output chunks | | `rai_benchmark` | Score responses against truthfulqa / bbq / hellaswag suites | | `rai_benchmark_prompts` | Question set for a benchmark suite | | `rai_model_route` | Cheapest model that can handle a task, with cost/quality tradeoff | | `rai_pii_report` | PII audit report by category with GDPR/CCPA remediation guidance | | `rai_incident_log` | Structured governance incident record for audit/SIEM | | `rai_eu_ai_act_classify` | EU AI Act risk tier classification with compliance roadmap | | `rai_iso42001_gap` | ISO/IEC 42001:2023 AI Management System gap analysis | | `rai_executive_summary` | Board-ready governance summary with RAG status indicators | | `rai_org_status` | Governance status snapshot: models, grades, compliance, risk | | `rai_webhook_status` | Webhook delivery health, failure analysis, remediation actions | | `rai_check_trust` | Free public Trust Index lookup for a **third-party** model/tool, before an agent invokes it β unlike every other tool above, which evaluates output the caller itself produced | ### Agent-framework integrations β LangChain, LangGraph, Google ADK `src/responsibleai/integrations/` wires `rai_check_trust` directly into three agent frameworks so an agent can be gated on a tool's public trust score before invoking it, not just log the call after the fact: - **LangChain** (`langchain_middleware.py`) β `TrustGateMiddleware`, a `wrap_tool_call` middleware that blocks a call outright when its score is below threshold. Requires `pip install "rai-governance-platform[langchain]"`. - **LangGraph** (`langgraph_gate.py`) β `make_trust_gate_node()`, a node that pauses the graph with `interrupt()` for a human approve/reject decision on a below-threshold call, instead of a hard block. Requires `pip install "rai-governance-platform[langgraph]"`. - **Google ADK** (`adk_toolset.py`) β `build_stdio_toolset()` / `build_http_toolset()`, thin factories over ADK's `McpToolset`, which auto-discovers this project's MCP server's tools with no custom glue code. Requires `pip install "rai-governance-platform[adk]"`. All three, or any subset, install via `pip install "rai-governance-platform[agent-frameworks]"`. See `GAME_CHANGER_BUILD_PLAN.md` Phase B for the reasoning behind each. ### Available resources (20) 10 canonical resources, each advertised under both the `whitepact://` and `rai://` URI schemes (dual scheme is additive β see `MIGRATION_WHITEPACT_V2.md`; the table below shows the canonical URI): | Resource | URI | Contents | |---|---|---| | Health | `whitepact://health` | Current health status of the governance service | | Model pricing catalog | `whitepact://models/catalog` | Supported models with per-token pricing | | Compliance frameworks | `whitepact://compliance/frameworks` | NIST AI RMF, EU AI Act, ISO 42001 | | Red team categories | `whitepact://redteam/categories` | Adversarial attack categories | | Trust dimensions | `whitepact://trust/dimensions` | The 6 dimensions behind the Trust Score | | Bias probe catalog | `whitepact://bias/probes` | Available bias probes and scoring interpretation | | Governance policy template | `whitepact://governance/policy` | Default policy template for `rai_policy_check` | | Trust grade reference | `whitepact://trust/grades` | Grade thresholds, risk tiers, deployment guidance | | NIST AI RMF checklist | `whitepact://compliance/checklist/nist` | Actionable NIST implementation checklist | | EU AI Act checklist | `whitepact://compliance/checklist/eu-ai-act` | Compliance checklist for high-risk operators | ### MCP directory listings WhitePact is listed and queryable today on real MCP directories β not aspirational, all verified live: - **Official MCP Registry** β `server.json` at the repository root (schema `2025-12-11`, listing version `1.2.3`) is published as `io.github.Guruprasath-Annadurai/whitepact`, confirmed queryable at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io). Advertises both the PyPI/stdio package (`whitepact-mcp`, self-hosted, free, unrestricted) and a `remotes` entry pointing at the hosted Streamable HTTP and SSE transports (`whitepact-mcp-http.onrender.com`) β a one-click remote connector, not just an installable package. - **Antigravity CLI plugin** β `plugins/whitepact/` at the repository root follows the [official Antigravity plugin manifest format](https://antigravity.google/docs/plugins), connecting to the same hosted Streamable HTTP transport via `serverUrl`. No official Antigravity plugin directory exists yet, so this is distributed directly from the repo β see `plugins/whitepact/README.md`. - **Smithery** β listed as [`guruprasathannadurai-official/whitepact`](https://smithery.ai/server/guruprasathannadurai-official/whitepact), 30 tools and 20 resources discovered against the hosted Streamable HTTP transport (`whitepact-mcp-http.onrender.com/mcp`, a separate Render service from the main dashboard). This deployment has no OAuth authorization server configured β only static Bearer API keys β so a public, unauthenticated `/.well-known/mcp/server-card.json` serves the same live `TOOL_DEFS`/`RESOURCE_DEFS` the server itself advertises, for directories whose scanners can't complete a live authenticated crawl. See `compliance/MCP_DISTRIBUTION_GUIDE.md` for the full distribution plan, including directories not yet submitted to. ### Platform integrations WhitePact connects to the major AI platforms as one MCP server through standards-compliant clients β no per-platform forks, no per-platform governance logic. See [`docs/integrations/`](https://github.com/Guruprasath-Annadurai/Whitepact/blob/HEAD/docs/integrations/) for the canonical compatibility matrix (`PLATFORM_COMPATIBILITY.md`), per-platform setup docs (GitHub Copilot, Microsoft Copilot, Claude, Grok, Gemini, Amazon Q, AWS Bedrock AgentCore, Mistral Le Chat, Cursor), and `FOUNDER_ACTIONS.md` for what still needs a human. Run `python scripts/integration_smoke.py` for a live protocol-level preflight against the hosted endpoint. --- ## Python SDK ### Trust scoring ```python from responsibleai import TrustScoreEngine, PassportGenerator engine = TrustScoreEngine() score = engine.compute( fairness=0.80, privacy=0.85, security=0.82, robustness=0.78, compliance=0.90, authenticity=0.88, ) print(f"{score.overall:.1f} / 100 Grade: {score.grade} Risk: {score.risk_level}") # β 83.7 / 100 Grade: B Risk: LOW passport = PassportGenerator().generate( model_name="gpt-4o", provider="openai", trust_score=score, compliance_summary={"overall": 80.5}, ) print(passport.passport_id) passport.export_html("passport.html") ``` ### Guardrails β block PII before it reaches a log ```python from responsibleai import GuardrailsEngine guardrails = GuardrailsEngine() result = guardrails.scan("Customer SSN is 123-45-6789, email: alice@company.com") print(result.is_blocked) # True print(result.pii_count) # 2 print(result.redacted_text) # "Customer SSN is [SSN], email: [EMAIL]" ``` ### Hallucination detection ```python from responsibleai import HallucinationDetector detector = HallucinationDetector() result = detector.analyze( "AI will replace all human jobs by 2025.", candidates=[ "AI will automate some repetitive tasks.", "AI creates new job categories alongside displacing others.", ], ) print(f"Risk: {result.hallucination_risk:.2f} Level: {result.risk_level}") ``` ### Compliance β NIST AI RMF, EU AI Act, ISO 42001 ```python from responsibleai import ComplianceEngine engine = ComplianceEngine() report = engine.evaluate( fairness_score=0.80, privacy_score=0.85, security_score=0.82, robustness_score=0.78, compliance_maturity=0.90, use_case="credit_scoring", ) print(f"Score: {report.compliance_score * 100:.1f}%") print(f"EU AI Act tier: {report.eu_ai_act_tier.value}") # high_risk ``` ### Red team simulation ```python from responsibleai import RedTeamSimulator simulator = RedTeamSimulator() report = simulator.run_all() print(f"Security score: {report.security_score:.1f}/100") print(f"Vulnerabilities: {len(report.vulnerabilities)}") for v in report.critical_vulnerabilities: print(f" [{v['cwe_id']}] {v['name']}") ``` ### Cost intelligence ```python from responsibleai import CostTracker, ModelRouter, TokenUsage, BudgetPolicy tracker = CostTracker(db_path="~/.responsibleai/data.db", policy=BudgetPolicy(monthly_limit_usd=500.0)) usage = TokenUsage.create( provider="openai", model="gpt-4o", input_tokens=2000, output_tokens=800, team="product", ) record = tracker.record(usage) print(f"This call: ${record.total_cost:.4f}") print(f"Month to date: ${tracker.total_cost(30):.2f}") router = ModelRouter() decision = router.route("Classify this email as spam or not spam", "balanced") print(f"Recommended: {decision.recommended_model} ${decision.estimated_cost_per_1k:.4f}/1k tokens") ``` ### Trust drift monitoring ```python from responsibleai import TrustScoreEngine, TrustDriftMonitor monitor = TrustDriftMonitor(db_path=":memory:", alert_threshold=5.0) engine = TrustScoreEngine() for fairness in [0.90, 0.88, 0.85, 0.72]: score = engine.compute(fairness=fairness, privacy=0.85, security=0.80, robustness=0.80, compliance=0.85, authenticity=0.85) alert = monitor.record("gpt-4o", "openai", score) if alert: print(f"Drift alert! {alert.severity}: {alert.delta:.1f} pt drop") ``` --- ## Governance Dashboard A production FastAPI application with a dark-mode SPA. A live instance is hosted at **[whitepact.com](https://whitepact.com)**. ```bash # Development (auth off, SQLite in-memory) RAI_AUTH_ENABLED=false uvicorn responsibleai.dashboard.app:app --port 8765 # Production (auth + persistent DB) RAI_API_KEYS=your-key-here \ RAI_DB_PATH=/data/responsibleai.db \ uvicorn responsibleai.dashboard.app:app --host 0.0.0.0 --port 8765 --workers 4 # Docker docker compose up -d ``` ### REST API endpoints | Method | Path | Description | |---|---|---| | `GET` | `/api/health` | Health β DB, auth, OTEL, version | | `GET` | `/api/metrics` | Uptime, request count, error rate, monthly spend | | `POST` | `/api/evaluate` | Full evaluation β trust + compliance + passport | | `GET` | `/api/trust-score/{model}/{provider}` | Score history + drift trend | | `GET` | `/api/models` | All evaluated models | | `POST` | `/api/scan` | Guardrails β PII detection + redaction | | `POST` | `/api/hallucination` | Hallucination risk analysis | | `POST` | `/api/cost/record` | Record token usage | | `GET` | `/api/cost/summary` | Cost breakdown by model / team / day | | `POST` | `/api/cost/analyze` | Prompt efficiency β detect bloat | | `POST` | `/api/cost/route` | Route task to cheapest viable model | | `GET` | `/api/cost/models` | Full model pricing catalogue | | `GET` | `/api/drift/{model}/{provider}` | Drift trend + history | | `GET` | `/api/audit` | Paginated audit log (org-scoped) | | `GET` | `/api/audit/export` | Export audit log as JSONL or CSV | | `GET` | `/api/audit/summary` | Audit counts grouped by endpoint | | `GET` | `/api/redteam/payloads` | Red team payload library (10 vectors) | | `POST` | `/api/redteam/analyze` | Analyze model responses for vulnerabilities | | `GET` | `/api/billing/usage` | Token spend and budget status | | `GET` | `/api/leaderboard` | Public cross-model trust leaderboard (no auth) | | `GET` | `/api/leaderboard/{model}/{provider}/history` | Trend over time for one model (no auth) | | `GET` | `/api/leaderboard/{model}/{provider}/diagnostic` | Per-prompt findings β PRO plan required | | `POST` | `/api/trust-index/assess` | Free, public self-assessment against the open Trust Index standard | | `GET` | `/api/trust-index/verify/{passport_id}` | Verify a cited Trust Index score (no auth) | | `GET` | `/api/trust-index/check` | Free, public β trust score + incident count for a named model/tool, by exact name (no auth); what `rai_check_trust` and the LangChain/LangGraph/ADK integrations call | | `GET` | `/api/trust-index/registry` | Every assessed model/tool, certified and self-reported, newest first (no auth) β data source for the public `/registry` page | | `GET` | `/api/trust-index/certified` | Directory of certified passports (no auth) | | `POST` | `/api/trust-index/certify/{passport_id}` | Certify a passport β super-admin only | | `GET` | `/api/trust-index/badge/{passport_id}.svg` | Embeddable trust badge (Self-Assessed / Certified), no auth | | `POST` | `/api/incident-db/report` | Report a publicly observed AI incident (no auth, rate-limited) | | `GET` | `/api/incident-db` | Browse published incidents β filter by model, provider, severity, type (no auth) | | `GET` | `/api/incident-db/check` | Pre-deployment exact-match incident check for a model/provider β PRO/ENTERPRISE | | `GET` | `/api/incident-db/verify` | Recompute the hash chain over every published entry (no auth) | | `POST` | `/api/orgs/{org_id}/keys/{key_id}/mfa/enroll` | Enroll an API key in TOTP MFA | | `POST` | `/api/orgs/{org_id}/keys/{key_id}/mfa/verify` | Verify a TOTP code / backup code | | `GET`/`POST` | `/api/governance/evidence` | Read/write hash-chained governance evidence records | | `GET`/`POST` | `/api/governance/approvals` | Queue and resolve `REQUIRE_APPROVAL` decisions | Interactive docs at `/api/docs`. Public leaderboard page at `/leaderboard` β see `compliance/LEADERBOARD_METHODOLOGY.md` for the published scoring methodology and `scripts/run_leaderboard_eval.py` to run evaluations. Open Trust Index standard and passport verification at `/verify/{id}` β see `compliance/TRUST_INDEX_SPEC.md`. Free, zero-signup self-assessment at `/assess`; browse every assessed model/tool at `/registry`. `/llms.txt` points AI crawlers/answer engines at these as canonical sources β see `GAME_CHANGER_STRATEGY.md` for why. ### Production features | Feature | Detail | |---|---| | Authentication | Bearer token (`RAI_API_KEYS`) with RBAC (OWNER / ADMIN / ANALYST / VIEWER) | | MFA | TOTP (RFC 6238) on the interactive login step, org-enforceable, single-use backup codes | | Field-level encryption | Opt-in (`RAI_FIELD_ENCRYPTION_KEY`) on `audit_log.ip_address`, incident reporter contact info, webhook secrets, MFA secrets β with key-rotation support (`MultiFernet`) | | Per-org rate limiting | Each Bearer token gets its own rate limit bucket (SHA-256 keyed) β no shared global pool | | CORS | Configurable origins (`RAI_ALLOWED_ORIGINS`) | | Security headers | CSP, X-Frame-Options, X-Content-Type-Options | | Structured logging | JSON via structlog + request IDs | | Database | SQLite (default) or PostgreSQL (`RAI_DATABASE_URL`) with Alembic migrations | | Observability | OpenTelemetry traces + metrics (`RAI_OTEL_ENDPOINT`) | | Webhooks | HMAC-signed delivery with DB-persisted retry queue (survives restarts) | | Exception handling | No raw stack traces reach clients | | Governance evidence | Hash-chained, per-org, tamper-evident (`GET /api/governance/evidence`) | --- ## Database migrations (Alembic) Schema changes are managed with Alembic. Run `alembic history` for the current, authoritative migration count and table list β this number changes frequently enough that a hardcoded count here goes stale fast; the command itself is the source of truth. ```bash # Upgrade to latest schema RAI_DB_PATH=/var/lib/rai/governance.db alembic upgrade head # PostgreSQL RAI_DB_URL=postgresql://user:pass@host:5432/responsibleai alembic upgrade head # Show migration history alembic history # Generate a new migration after changing engine.py alembic revision --autogenerate -m "add_new_column" ``` All migrations use `render_as_batch=True` so they run on both SQLite and PostgreSQL without changes. --- ## Webhook notifications Register an endpoint and receive signed events when governance thresholds fire. ```bash # Register a Slack webhook curl -X POST http://localhost:8765/api/webhooks \ -H "Authorization: Bearer your-key" \ -H "Content-Type: application/json" \ -d '{ "name": "ops-slack", "url": "https://hooks.slack.com/services/...", "events": ["drift_alert", "budget_exceeded", "guardrail_triggered"], "provider": "slack", "secret": "hmac-secret-for-signature-verification", "max_retries": 5 }' ``` Deliveries are persisted to the database. If the server restarts during a retry cycle, the background worker picks up where it left off on next boot. Retry schedule: 1 s β 5 s β 30 s β 2 min β 10 min. Verify payloads with the `X-RAI-Signature-256: sha256=