rai-governance-platform 1.2.0

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 (27 tools, 20 resources) with LangChain, LangGraph, and Google ADK trust-gate integrations.

┌──────────────────────────────────────────────────────────────────────────────┐
│                        WhitePact  v1.2.0                                     │
│                                                                              │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ 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   │  │  27 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:

Install

# 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

# 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
  }'

{
  "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:

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.

No governance decision is LLM-based; see DETERMINISTIC_VS_PROBABILISTIC.md for why.

MCP Server — govern every AI call from Claude Code, Claude Desktop, or any MCP client

The MCP (Model Context Protocol) server exposes WhitePact as 27 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

# 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)

{
  "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)

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):

MCP registry manifest

server.json at the repository root is the official MCP registry manifest (schema 2025-12-11). It is not yet submitted — see compliance/MCP_DISTRIBUTION_GUIDE.md for the specific, real blockers (a PyPI release matching the manifest's version, GitHub namespace verification, and a real hosted transport URL).

Python SDK

Trust scoring

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

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

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

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

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

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

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.

# 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

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

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.

# 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.

# 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=<hex> header.

Docker

git clone https://github.com/Guruprasath-Annadurai/Whitepact.git
cd Whitepact

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

cp .env.example .env
# Edit .env — set RAI_API_KEYS

docker compose up -d
# Dashboard: http://localhost:8765
# API docs:  http://localhost:8765/api/docs

PostgreSQL + Redis (horizontal scaling)

# .env
RAI_DATABASE_URL=postgresql://rai:secret@db-host:5432/responsibleai
RAI_REDIS_URL=redis://redis-host:6379/0
RAI_OTEL_ENDPOINT=http://otel-collector:4318

pip install "rai-governance-platform[dashboard,postgres,redis,telemetry]"

# Run migrations before first start
RAI_DB_URL=postgresql://rai:secret@db-host:5432/responsibleai alembic upgrade head

The async database layer uses SQLAlchemy with connection pooling (pool_size=10, max_overflow=20, pool_pre_ping=True). Rate limiting switches to Redis-backed storage when RAI_REDIS_URL is set.

BiasBuster — bias evaluation in CI

# Fail CI when demographic bias exceeds threshold
biasbuster run \
  --provider openai --model gpt-4o \
  --probes gender-bias,racial-bias,cultural-bias \
  --threshold 0.20 \
  --output report --format html

from biasbuster import BiasBusterRunner, GenderBiasProbe, RacialBiasProbe
from biasbuster.providers import OpenAIProvider
import asyncio

async def main():
    provider = OpenAIProvider(api_key="sk-...", model="gpt-4o")
    runner = BiasBusterRunner(provider=provider)
    suite = await runner.run([
        GenderBiasProbe(threshold=0.20),
        RacialBiasProbe(threshold=0.20),
    ])
    print(f"Score: {suite.overall_score:.4f}  {'PASSED' if suite.passed else 'FAILED'}")

asyncio.run(main())

Available probes: gender-bias, racial-bias, age-bias, religious-bias, occupational-stereotype, cultural-bias

Scoring: TF-IDF cosine divergence + length asymmetry + VADER sentiment divergence, 95% bootstrap confidence intervals, intersectional co-failure amplification (×1.15).

PrivacyLabel — on-device federated labeling

from privacylabel import FederatedClient, FedAvgAggregator

client = FederatedClient(
    node_id="hospital-node-01",
    provider=MyProvider(),
    epsilon_per_round=0.1,
    total_epsilon=1.0,
    delta=1e-6,
    gradient_clip=1.0,
)
# Raw data stays on disk — only privatised gradients leave the device
summary = await client.train_round("data/local_records.jsonl")
print(f"Privacy budget used: ε={summary.privacy_spent['spent_epsilon']:.3f}")

Implements Laplace, Gaussian, Exponential, and DP-SGD mechanisms. Byzantine-robust aggregation via Weiszfeld geometric median.

GitHub Actions — bias gate in CI

- name: Bias evaluation
  run: |
    pip install "rai-governance-platform[openai]"
    biasbuster run \
      --provider openai --model gpt-4o-mini \
      --probes gender-bias,racial-bias,cultural-bias \
      --threshold 0.20
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Environment variables

Dual-prefixed WHITEPACT_* equivalents for these are also read where MIGRATION_WHITEPACT_V2.md documents them — the RAI_* names remain the primary, always-supported form.

Development

git clone https://github.com/Guruprasath-Annadurai/Whitepact.git
cd Whitepact

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Full test suite (1,538 tests, 85% coverage, as of this writing)
pytest

# Dashboard tests only
RAI_DB_PATH=:memory: RAI_AUTH_ENABLED=false pytest tests/test_dashboard_api.py

# Webhook persistence tests
pytest tests/test_webhook_persistence.py

# MCP server tests
pytest tests/test_mcp_server.py

# Lint + type check
ruff check src/ tests/
mypy src/responsibleai src/biasbuster

Roadmap

• v0.1 — BiasBuster: gender probe, 4 providers, CLI, CI integration
• v0.2 — Racial / age / religious / occupational probes, HTML reporter, PrivacyLabel federated DP
• v0.3 — Cultural bias, intersectional analysis, DeepfakeDetector ensemble
• v0.4 — Cost Intelligence (CostTracker, ModelRouter, 16-model pricing), Trust Drift Monitor
• v0.5 — Governance Dashboard (FastAPI), Trust Score, AI Passport, Guardrails, Hallucination, Compliance, Red Team, CI/CD, Docker, SLA
• v0.6 — Async PostgreSQL (SQLAlchemy), Redis rate limiting, OpenTelemetry APM, LLM integration tests
• v1.0 — WebSocket drift alerts, Prometheus endpoint, multi-tenant RBAC, org management API
• v1.1 — MCP server (10 tools, 5 resources), audit log API, red team API, billing API, Alembic migrations, per-org rate limiting, DB-persisted webhook retry queue
• v1.2 — Public Leaderboard, Trust Index/Passports + embeddable badges, AI Incident Database, TOTP MFA, expanded field encryption, DB-persisted webhooks, full dashboard UI rebuild, white-label branding, a genuinely live hosted instance — see CHANGELOG.md for the full list
• WhitePact migration (in progress across 1.2.0) — governance decision core, MCP Streamable HTTP + OAuth/OIDC, risk tiering + policy engine, hash-chained evidence, approval workflow, MCP trust/supply-chain scanner, HA Helm deployment, supply chain security (SBOM/provenance), release engineering, MCP registry manifest, open source governance — see MIGRATION_WHITEPACT_V2.md for the full phase-by-phase log and what's still not done
• v2.0 onward — see VERSION_ROADMAP.md for the phase-by-phase plan through v6.0
• Strategic direction — GAME_CHANGER_STRATEGY.md lays out an infrastructure-first bet (free public trust registry, an agent-native trust-check primitive, AI-answer-engine citability) as an alternative to the enterprise-SaaS path, with GAME_CHANGER_BUILD_PLAN.md breaking it into concrete engineering phases against the current codebase

Further reading

• SPEC.md — the current architecture contract
• MIGRATION_WHITEPACT_V2.md — phase-by-phase migration log, what's done and what's explicitly not
• DEFINITION_OF_DONE.md — closing report: what's real today, what isn't, verifiable
• THREAT_MODEL.md — threat model for the current attack surface
• DETERMINISTIC_VS_PROBABILISTIC.md — why governance decisions are deterministic
• SLA.md, ENTERPRISE_SECURITY.md, SECURITY.md — enterprise/security posture, stated honestly
• compliance/SOC2_ALTERNATIVE_PATH.md — real, free, independently verifiable trust signals for now; the honest path to a real SOC 2 when there's budget for one

License

MIT — see LICENSE.