WhitePact

WhitePact — 面向自主系统的独立运行时授权、治理与保障层：包含五向治理决策引擎（ALLOW / ALLOW_WITH_REDACTION / REQUIRE_APPROVAL / DENY / QUARANTINE）、信任评分、偏见检测、护栏、幻觉检测、合规映射（NIST AI RMF / EU AI Act / ISO 42001）、成本智能、漂移监控、公开的信任指数 / 排行榜 / AI 事件数据库，以及一个 MCP 服务（30 个工具、20 个资源），并支持与 LangChain、LangGraph 和 Google ADK 的信任门集成。

┌──────────────────────────────────────────────────────────────────────────────┐
│                        WhitePact  v1.3.1                                     │
│                                                                              │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ 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  │ │
│  └──────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘

---

解决的问题

每个在生产环境中部署 AI 的团队都会面临同一个问题：**没有统一的方式来证明模型——或自主 Agent 的操作——安全、公平、合规且可问责。**审计依赖人工，偏见要到生产环境中才会被发现，合规情况记录在电子表格中，Agent 的工具调用无人治理，而且没人知道下个月的大模型账单会是多少。

WhitePact 为你提供一个平台——包括 REST API、Python SDK、MCP 服务和实时仪表板——覆盖治理的整个生命周期：

问题	模块	输出
是否应允许、脱敏、暂缓以待审批、拒绝或隔离此 Agent 操作？	WhitePactRuntimeGateway（治理核心）	五选一的 GovernanceDecision，结果确定，决策路径中不调用大模型
这个模型可信吗？	TrustScoreEngine	0–100 分、A–F 等级、风险级别
它是否符合法规要求？	ComplianceEngine	NIST AI RMF、EU AI Act 风险等级、ISO 42001
它是否暴露个人身份信息（PII）？	GuardrailsEngine	阻止／脱敏，并记录审计日志
它是否在产生幻觉？	HallucinationDetector	风险评分、不受支持的主张
它可能遭受攻击吗？	RedTeamSimulator	10 种攻击向量、CVE ID、安全拒绝率
它的成本是多少？	CostTracker + ModelRouter	按模型统计的美元费用，将请求路由到可用的最低成本模型
它的表现是否在持续变差？	TrustDriftMonitor	7／30 天趋势、严重性警报
它是否存在偏见？	BiasBuster	6 项人口统计探测、CI 门禁
是否以私密方式标记了这些数据？	PrivacyLabel	联邦差分隐私（DP）标签，不会离开设备
这段媒体是真的吗？	DeepfakeDetector	集成置信度、检测到的方法
连接第三方 MCP 服务之前，我能确认它是否可信吗？	SupplyChainScanner	VERIFIED_FACT / INFERRED_SIGNAL / UNKNOWN 判定——检查仿冒拼写、描述与内容是否一致以及已知事件
是否为每项治理决策保留了防篡改记录？	EvidenceRepository	按组织保存、通过哈希链连接的 EvidenceRecord，支持 verify_chain()
高风险操作是否会由人工介入处理？	ApprovalRepository	可防竞态的 PENDING → APPROVED/DENIED 工作流
如何独立比较此模型与其他模型的排名？	Public Leaderboard	通过实际调用各模型的 API 得出的跨模型信任排名，而非模型自我报告
我能否在任何地方引用并验证信任评分？	Trust Index	免费自我评估或经人工审核认证的护照，可通过 /verify/{id} 验证，并可嵌入徽章
这个 AI 系统过去是否曾公开发生故障？	AI Incident Database	由用户报告、版主审核并通过哈希链连接的公开登记库
调用第三方工具之前，我的 Agent 应如何判断它是否可信？	rai_check_trust + LangChain/LangGraph/ADK 集成	免费查询，并在 Agent 内提供真正的阻止／暂停门禁
任何 MCP 客户端都能治理每次 AI 调用吗？	MCP Server	30 种生产级治理工具，支持 stdio、Streamable HTTP 或旧版 HTTP+SSE

---

安装

# 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]"

已发布到 PyPI 的软件包名称（rai-governance-platform）和导入名称（responsibleai）早于 WhitePact 的更名，因此保留原样——安装名称、导入名称和产品名称的说明，请参阅 MIGRATION_WHITEPACT_V2.md 第 3 节和 docs/PACKAGE_IDENTITY.md（除非 PyPI 文档明确说明该发行包，否则请勿使用 pip install whitepact）。

---

30 秒快速入门

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

打开 http://localhost:8765 查看实时仪表板，打开 http://localhost:8765/api/docs 查看交互式 API 文档。

---

治理核心 — 五类决策，而非二元的阻止/允许

src/responsibleai/governance/（完整架构约定请参阅 SPEC.md 第 4-8 节）是一个位于 Agent 工具调用之前的确定性运行时权限层：

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

• 风险分级（governance/risk.py）——每个 MCP 工具都根据硬编码且经过漂移测试的表进行分类，而非在调用时推断。
• 策略引擎（governance/policy.py）——采用首条匹配规则生效的规则，并支持 ALLOW / DENY / REQUIRE_APPROVAL 效果。
• 证据（governance/evidence.py）——每项决策都会写入按组织划分、采用哈希链的 EvidenceRecord；verify_chain() 可检测篡改。绝不存储原始参数值，只存储字段名键。
• 审批工作流（governance/approval.py）——REQUIRE_APPROVAL 决策会进入真正的、可防竞态的 ApprovalRequest 队列，并提供解决 API，而不只是写入一条日志。
• 供应链扫描器（src/responsibleai/supplychain/）——在 Agent 信任第三方 MCP 服务或工具之前，SupplyChainScanner 会通过错别字仿冒检测、工具描述扫描和已知事件交叉比对，返回三种明确判定之一（VERIFIED_FACT / INFERRED_SIGNAL / UNKNOWN），绝不会只给出一个不透明的信任分数。
• 身份桥接（integrations/identity_bridge.py）——将 Entra ID、Google Workspace、Okta 和 AWS（Cognito / IAM Identity Center）的 ID 令牌声明映射为 IdentityContext，并提供 map_groups_to_authority()，将 IdP 群组成员身份转换为已授予操作类型的 AuthorityContext。关于具体验证内容（根据各提供商的公开文档验证声明结构正确性）与未验证内容（实时租户测试、Graph/Admin-SDK 群组名称解析、AWS 的非 JWT SigV4 路径），请参阅 MACHINE_AUTHORITY_V1.md 中的 Identity Bridge 部分。

所有治理决策都不是基于大模型的；原因请参阅 DETERMINISTIC_VS_PROBABILISTIC.md。

端到端示例：examples/08_whitepact_enterprise_scenario.py 使用真实代码运行完整场景（某组织为自主财务 Agent 办理入职），涵盖全部八项机器权限不变量——上限、委派、衰减、审批法定人数、工作流组合、自主预算、记忆防火墙、证据包，无需 API 密钥：

python examples/08_whitepact_enterprise_scenario.py

---

MCP 服务 — 从 Claude Code、Claude Desktop 或任何 MCP 客户端治理每次 AI 调用

MCP（Model Context Protocol）服务向任何兼容 MCP 的客户端（Claude Code、Claude Desktop、Cursor、Windsurf 或你自己的 Agent 运行时）提供 WhitePact 的30 个工具和 20 个资源（10 个规范资源 URI，同时通过 whitepact:// 和 rai:// 方案进行双重发布——参阅 MIGRATION_WHITEPACT_V2.md）。支持三种传输方式：stdio、Streamable HTTP（/mcp，当前 MCP 规范）以及旧版 HTTP+SSE（/sse + /messages/，保留以支持较旧的客户端）。当团队的客户端连接到此服务后，每次 AI 交互都会自动受到治理——五类治理决策、信任评分、护栏、合规性检查（NIST AI RMF / EU AI Act / ISO 42001）、偏见评估、漂移检测、成本跟踪和哈希链审计证据都会在每次调用时运行，无需更改代码。

设置

# 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 和 responsibleai-mcp 是同一个入口点——请参阅 pyproject.toml 中的 [project.scripts]；两者都会继续可用，可任选其一。

可用工具（27 个）

工具	功能
rai_scan	在内容进入日志前检测并编辑个人身份信息（PII）和有害内容
rai_trust_score	从 6 个治理维度计算综合 AI 信任评分（0-100）
rai_compliance	评估是否符合 NIST AI RMF / EU AI Act / ISO 42001
rai_hallucination	根据模糊措辞、一致性和无依据的说法评估幻觉风险
rai_cost_estimate	根据令牌数量估算模型 API 调用的美元费用
rai_redteam_payloads	生成对抗性攻击载荷（提示词注入、越狱等）
rai_redteam_analyze	根据模型对红队载荷的响应生成安全报告
rai_compare_models	从全部 6 个信任维度比较两个模型
rai_audit_summary	治理能力摘要（工具、框架、攻击向量）
rai_health	显示治理引擎的状态和模块可用性
rai_bias_evaluate	从 6 个探测维度评估人口群体偏差，并提供置信区间
rai_drift_check	比较基线评估与当前评估的信任评分漂移
rai_passport_generate	生成可验证、防篡改的 AI Passport，用于供应商风险评估
rai_budget_check	检查支出与预算，按团队/模型细分，并预测月底支出
rai_policy_check	根据治理策略检查文本/响应（黑名单、免责声明）
rai_stream_scan	扫描 LLM 流式输出块中的 PII/有害内容
rai_benchmark	使用 truthfulqa / bbq / hellaswag 套件为响应评分
rai_benchmark_prompts	提供基准测试套件的问题集
rai_model_route	选择能够处理任务且成本最低的模型，并权衡成本与质量
rai_pii_report	按类别生成 PII 审计报告，并提供 GDPR/CCPA 补救指导
rai_incident_log	生成结构化治理事件记录，用于审计/SIEM
rai_eu_ai_act_classify	对照 EU AI Act 风险等级分类，并提供合规路线图
rai_iso42001_gap	分析 ISO/IEC 42001:2023 AI 管理体系差距
rai_executive_summary	生成适合董事会审阅的治理摘要，并附 RAG 状态指示器
rai_org_status	治理状态快照：模型、评级、合规情况、风险
rai_webhook_status	Webhook 投递状况、故障分析和补救措施
rai_check_trust	免费查询第三方模型/工具的公开信任指数，供 Agent 调用前使用；与上述其他工具不同，后者评估的是调用方自身生成的输出

Agent 框架集成 — LangChain、LangGraph、Google ADK

src/responsibleai/integrations/ 将 rai_check_trust 直接接入三个 Agent 框架，以便在 Agent 调用工具前，根据该工具的公开信任评分决定是否放行，而不只是事后记录调用：

• LangChain（langchain_middleware.py）— TrustGateMiddleware 是一个 wrap_tool_call 中间件；当评分低于阈值时，会直接阻止调用。需要 pip install "rai-governance-platform[langchain]"。
• LangGraph（langgraph_gate.py）— make_trust_gate_node() 是一个节点； 对于评分低于阈值的调用，它会通过 interrupt() 暂停图，等待人工批准/拒绝， 而不是直接阻止。需要 pip install "rai-governance-platform[langgraph]"。
• Google ADK（adk_toolset.py）— build_stdio_toolset() / build_http_toolset() 是基于 ADK McpToolset 的轻量工厂函数，可自动发现本项目 MCP 服务的工具，无需编写自定义胶合代码。 需要 pip install "rai-governance-platform[adk]"。

三者全部安装或按需安装任意子集，均可使用 pip install "rai-governance-platform[agent-frameworks]"。 各项设计的原因请参阅 GAME_CHANGER_BUILD_PLAN.md 中的 Phase B。

可用资源（20）

10 个规范资源均通过 whitepact:// 和 rai:// URI 方案发布（双方案为增补形式 — 参见 MIGRATION_WHITEPACT_V2.md；下表显示规范 URI）：

资源	URI	内容
健康状态	whitepact://health	治理服务的当前健康状态
模型定价目录	whitepact://models/catalog	支持的模型及其每 token 定价
合规框架	whitepact://compliance/frameworks	NIST AI RMF、EU AI Act、ISO 42001
红队类别	whitepact://redteam/categories	对抗性攻击类别
信任维度	whitepact://trust/dimensions	Trust Score 背后的 6 个维度
偏见探测目录	whitepact://bias/probes	可用的偏见探测及评分说明
治理策略模板	whitepact://governance/policy	rai_policy_check 的默认策略模板
信任等级参考	whitepact://trust/grades	等级阈值、风险层级和部署指南
NIST AI RMF 检查清单	whitepact://compliance/checklist/nist	可执行的 NIST 实施检查清单
EU AI Act 检查清单	whitepact://compliance/checklist/eu-ai-act	面向高风险运营者的合规检查清单

MCP 目录列表

WhitePact 目前已在实际运行的 MCP 目录中上架并可查询 — 并非计划中的设想，所有信息均已在线验证：

• 官方 MCP 注册表 — 仓库根目录下的 server.json （架构版本 2025-12-11，上架版本 1.2.3）已作为 io.github.Guruprasath-Annadurai/whitepact 发布，并已确认可在 registry.modelcontextprotocol.io 查询。 它同时发布了 PyPI/stdio 软件包（whitepact-mcp，可自托管、 免费、不受限制），以及指向托管式 Streamable HTTP 和 SSE 传输的 remotes 条目（whitepact-mcp-http.onrender.com） — 这是一个一键式远程连接器，而不仅仅是可安装的软件包。
• Antigravity CLI 插件 — 仓库根目录下的 plugins/whitepact/ 遵循官方 Antigravity 插件清单 格式，通过 serverUrl 连接到 同一托管式 Streamable HTTP 传输。目前尚无官方的 Antigravity 插件目录，因此该插件直接从仓库分发 — 参见 plugins/whitepact/README.md。
• Smithery — 已上架为 guruprasathannadurai-official/whitepact， 通过托管式 Streamable HTTP 传输（whitepact-mcp-http.onrender.com/mcp，与主仪表板分属不同的 Render 服务）发现了 30 个工具和 20 个资源。此部署未配置 OAuth 授权服务器 — 仅使用静态 Bearer API 密钥 — 因此公开、无需身份验证的 /.well-known/mcp/server-card.json 会提供与服务本身发布内容相同的实时 TOOL_DEFS/RESOURCE_DEFS，供无法完成实时身份验证式 抓取的目录使用。

完整的分发计划（包括尚未提交的目录）请参见 compliance/MCP_DISTRIBUTION_GUIDE.md。

平台集成

WhitePact 通过符合标准的客户端，作为一个 MCP 服务连接到主流 AI 平台 — 无需为各个平台单独分支，也无需为各个平台单独编写治理逻辑。有关规范兼容性矩阵（PLATFORM_COMPATIBILITY.md）、各平台的 设置文档（GitHub Copilot、Microsoft Copilot、Claude、Grok、Gemini、 Amazon Q、AWS Bedrock AgentCore、Mistral Le Chat、Cursor），以及 仍需人工处理的事项（FOUNDER_ACTIONS.md），请参见 docs/integrations/。 运行 python scripts/integration_smoke.py，即可对托管端点执行实时协议级预检。

---

Python SDK

信任评分

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

护栏 — 在个人身份信息进入日志前将其拦截

from responsibleai import GuardrailsEngine

guardrails = GuardrailsEngine()
result = guardrails.scan("Customer SSN is 123-45-6789, email: [email protected]")

print(result.is_blocked)      # True
print(result.pii_count)       # 2
print(result.redacted_text)   # "Customer SSN is [SSN], email: [EMAIL]"

幻觉检测

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

合规 — 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

红队模拟

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']}")

成本智能

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

信任漂移监控

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

---

治理仪表板

一个采用深色模式 SPA 的生产级 FastAPI 应用。实时实例托管于 whitepact.com。

# 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 端点

方法	路径	描述
GET	/api/health	健康状态 — DB、身份验证、OTEL、版本
GET	/api/metrics	运行时间、请求数、错误率、月度支出
POST	/api/evaluate	完整评估 → 信任度 + 合规性 + 护照
GET	/api/trust-score/{model}/{provider}	分数历史 + 漂移趋势
GET	/api/models	所有已评估的模型
POST	/api/scan	防护措施 — PII 检测 + 脱敏
POST	/api/hallucination	幻觉风险分析
POST	/api/cost/record	记录 Token 用量
GET	/api/cost/summary	按模型 / 团队 / 日期划分的成本明细
POST	/api/cost/analyze	提示词效率 — 检测冗余
POST	/api/cost/route	将任务路由到成本最低且可胜任的模型
GET	/api/cost/models	完整的模型定价目录
GET	/api/drift/{model}/{provider}	漂移趋势 + 历史记录
GET	/api/audit	分页审计日志（限定组织范围）
GET	/api/audit/export	将审计日志导出为 JSONL 或 CSV
GET	/api/audit/summary	按端点分组的审计计数
GET	/api/redteam/payloads	红队载荷库（10 种向量）
POST	/api/redteam/analyze	分析模型响应中的漏洞
GET	/api/billing/usage	Token 支出和预算状态
GET	/api/leaderboard	跨模型公开信任度排行榜（无需身份验证）
GET	/api/leaderboard/{model}/{provider}/history	单个模型的历史趋势（无需身份验证）
GET	/api/leaderboard/{model}/{provider}/diagnostic	按提示词列出的发现 — 需要 PRO 套餐
POST	/api/trust-index/assess	免费公开地依据开放 Trust Index 标准进行自我评估
GET	/api/trust-index/verify/{passport_id}	验证引用的 Trust Index 分数（无需身份验证）
GET	/api/trust-index/check	免费公开 — 按确切名称查询指定模型 / 工具的信任度分数 + 事件计数（无需身份验证）；rai_check_trust 和 LangChain/LangGraph/ADK 集成会调用此接口
GET	/api/trust-index/registry	所有已评估的模型 / 工具，包括认证和自我报告的结果，按最新优先排序（无需身份验证）— 公开 /registry 页面的数据源
GET	/api/trust-index/certified	已认证护照目录（无需身份验证）
POST	/api/trust-index/certify/{passport_id}	认证护照 — 仅限超级管理员
GET	/api/trust-index/badge/{passport_id}.svg	可嵌入的信任徽章（自我评估 / 已认证），无需身份验证
POST	/api/incident-db/report	报告公开观察到的 AI 事件（无需身份验证，设有速率限制）
GET	/api/incident-db	浏览已发布事件 — 按模型、提供方、严重性、类型筛选（无需身份验证）
GET	/api/incident-db/check	部署前针对模型 / 提供方进行精确匹配的事件检查 — PRO/ENTERPRISE
GET	/api/incident-db/verify	重新计算所有已发布条目的哈希链（无需身份验证）
POST	/api/orgs/{org_id}/keys/{key_id}/mfa/enroll	为 API 密钥启用 TOTP MFA
POST	/api/orgs/{org_id}/keys/{key_id}/mfa/verify	验证 TOTP 代码 / 备用代码
GET/POST	/api/governance/evidence	读取 / 写入哈希链式治理证据记录
GET/POST	/api/governance/approvals	排队处理并解决 REQUIRE_APPROVAL 决策

交互式文档位于 /api/docs。公开排行榜页面位于 /leaderboard — 有关已发布的评分方法，请参阅 compliance/LEADERBOARD_METHODOLOGY.md， 有关运行评估，请参阅 scripts/run_leaderboard_eval.py。开放的 Trust Index 标准和护照验证位于 /verify/{id} — 请参阅 compliance/TRUST_INDEX_SPEC.md。免费、无需注册的自我评估位于 /assess；可在 /registry 浏览所有已评估的模型 / 工具。/llms.txt 会将 AI 爬虫 / 答案引擎引导至这些规范来源 — 原因请参阅 GAME_CHANGER_STRATEGY.md。

生产功能

功能	详情
身份验证	Bearer 令牌（RAI_API_KEYS），带有 RBAC（OWNER / ADMIN / ANALYST / VIEWER）
MFA	在交互式登录步骤中使用 TOTP（RFC 6238），可由组织强制启用，备份码仅可使用一次
字段级加密	可选启用（RAI_FIELD_ENCRYPTION_KEY），用于 audit_log.ip_address、事件报告者联系信息、webhook 密钥、MFA 密钥，并支持密钥轮换（MultiFernet）
按组织限流	每个 Bearer 令牌都有独立的限流桶（以 SHA-256 为键），不共享全局池
CORS	可配置来源（RAI_ALLOWED_ORIGINS）
安全标头	CSP、X-Frame-Options、X-Content-Type-Options
结构化日志	使用 structlog 生成 JSON，并包含请求 ID
数据库	SQLite（默认）或 PostgreSQL（RAI_DATABASE_URL），使用 Alembic 迁移
可观测性	OpenTelemetry 跟踪和指标（RAI_OTEL_ENDPOINT）
Webhook	使用 HMAC 签名交付，并通过数据库持久化重试队列（重启后仍保留）
异常处理	不会向客户端返回原始堆栈跟踪
治理证据	按组织进行哈希链记录，防篡改（GET /api/governance/evidence）

---

数据库迁移（Alembic）

使用 Alembic 管理架构变更。运行 alembic history，查看当前权威的迁移数量和表列表——这个数字变动很频繁，硬编码在此处很快就会过时；命令本身才是事实来源。

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

所有迁移都使用 render_as_batch=True，因此无需修改即可在 SQLite 和 PostgreSQL 上运行。

---

Webhook 通知

注册一个端点，在触发治理阈值时接收签名事件。

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

交付记录会持久化到数据库。如果服务在重试周期中重启，后台工作进程会在下次启动时从中断处继续。重试计划：1 秒 → 5 秒 → 30 秒 → 2 分钟 → 10 分钟。

使用 X-RAI-Signature-256: sha256=<hex> 标头验证载荷。

---

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（横向扩展）

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

异步数据库层使用 SQLAlchemy 和连接池（pool_size=10、max_overflow=20、pool_pre_ping=True）。设置 RAI_REDIS_URL 后，限流会切换到由 Redis 支持的存储。

---

BiasBuster — 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())

可用探测项： gender-bias、racial-bias、age-bias、religious-bias、occupational-stereotype、cultural-bias

评分： TF-IDF 余弦差异 + 长度不对称性 + VADER 情感差异、95% Bootstrap 置信区间、交叉性共同失败放大（×1.15）。

---

PrivacyLabel — 设备端联邦标注

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

实现 Laplace、Gaussian、Exponential 和 DP-SGD 机制。通过 Weiszfeld 几何中位数实现拜占庭鲁棒聚合。

---

GitHub Actions — 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 }}

---

环境变量

变量	默认值	描述
RAI_DB_PATH	governance.db	SQLite 路径
RAI_DB_URL	(未设置 = SQLite)	完整的 SQLAlchemy URL — 优先于 RAI_DB_PATH
RAI_DATABASE_URL	(未设置)	RAI_DB_URL 的别名
RAI_API_KEYS	(空 = 关闭身份验证)	以逗号分隔的 bearer 令牌
RAI_AUTH_ENABLED	true	切换是否强制执行身份验证
RAI_REDIS_URL	(未设置 = 使用内存)	用于分布式速率限制的 Redis URL
RAI_RATE_LIMIT_DEFAULT	100/minute	每个组织的速率限制（以 Bearer 令牌为键）
RAI_OTEL_ENDPOINT	(未设置 = 禁用)	OTLP HTTP 端点
RAI_OTEL_SERVICE_NAME	responsibleai	跟踪的服务名称
RAI_ALERT_THRESHOLD	5.0	触发漂移警报的信任评分降幅
RAI_MONTHLY_BUDGET_USD	10000.0	每月 AI 支出限额
RAI_LOG_LEVEL	INFO	日志级别
RAI_LOG_JSON	true	结构化 JSON 日志
RAI_HOST	127.0.0.1	绑定地址
RAI_PORT	8765	端口

文档 MIGRATION_WHITEPACT_V2.md 中说明的这些变量对应的双前缀 WHITEPACT_* 版本也会被读取 — RAI_* 名称仍是主要且始终受支持的形式。

---

开发

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
PYTHONPATH=src pytest tests/ -ra

# Enterprise SaaS Layer 1 (identity, RBAC, verified principal gate)
PYTHONPATH=src pytest tests/test_enterprise_saas_layer1.py tests/test_enterprise_saas_layer1_pg.py -ra

# 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.md 中的权威 NOW/NEXT/LATER 计划。以下列表是按版本汇总的历史变更记录，仅供参考。

• v0.1 — BiasBuster：性别探测、4 个提供商、命令行、CI 集成
• v0.2 — 种族／年龄／宗教／职业探测、HTML 报告器、PrivacyLabel 联邦 DP
• v0.3 — 文化偏见、交叉性分析、DeepfakeDetector 集成
• v0.4 — 成本智能（CostTracker、ModelRouter、16 种模型定价）、信任漂移监控器
• v0.5 — 治理仪表板（FastAPI）、信任评分、AI Passport、护栏、幻觉检测、合规、红队、CI/CD、Docker、SLA
• v0.6 — 异步 PostgreSQL（SQLAlchemy）、Redis 速率限制、OpenTelemetry APM、大模型集成测试
• v1.0 — WebSocket 漂移警报、Prometheus 端点、多租户 RBAC、组织管理 API
• v1.1 — MCP 服务（10 个工具、5 个资源）、审计日志 API、红队 API、计费 API、Alembic 迁移、每组织速率限制、数据库持久化的 webhook 重试队列
• v1.2 — 公共排行榜、Trust Index／Passports + 可嵌入徽章、AI 事件数据库、TOTP MFA、扩展字段加密、数据库持久化的 webhook、完整重建仪表板 UI、白标品牌、真正运行中的托管实例 — 完整列表请参阅 CHANGELOG.md
• WhitePact 迁移（1.2.0 → 1.2.2）— 治理决策核心、MCP Streamable HTTP + OAuth/OIDC、风险分级 + 策略引擎、哈希链证据、审批工作流、多审批者法定人数 + 委派链、上游 MCP 工具发现、MCP 信任／供应链扫描器、高可用 Helm 部署、供应链安全（SBOM／来源证明）、发布工程、开源治理、在官方 MCP Registry 和 Smithery 上的实时列表 — 完整的逐阶段记录及尚未完成的事项，请参阅 MIGRATION_WHITEPACT_V2.md
• v2.0 及后续版本 — 请参阅 VERSION_ROADMAP.md 中截至 v6.0 的逐阶段计划
• 战略方向 — GAME_CHANGER_STRATEGY.md 阐述了以基础设施为先的战略（免费的公共信任注册表、原生支持 Agent 的信任检查基础能力、可被 AI 答案引擎引用），作为企业 SaaS 路线的替代方案；GAME_CHANGER_BUILD_PLAN.md 则根据当前代码库将其拆解为具体的工程阶段

---

安全与开源保障

官方的 OpenSSF/OSPS BadgeApp 项目 目前记录了 OpenSSF 最佳实践银级和 OSPS 基线等级 1。 这些是自愿提供的项目证据，不代表独立审计、渗透测试、SOC 2 或 ISO 认证。当前的技术边界和声明边界记录于 WHITEPACT_TRUST_STATUS.md 和 PUBLIC_TRUST_CLAIMS.md。

发布版本的使用者可以查看签名标签证据、 发布流程、安全政策、 SLSA 证据边界和 使用者验证指南。可复用的可信构建器 流水线已存在于 main。发布版本 v1.2.6 完成了该流程：其 wheel 和 sdist 经过复现、哈希计算、证明生成，并在发布作业中独立验证；发布到 PyPI 时未重新构建， 其哈希与 PyPI 上的文件匹配，并随 CycloneDX SBOM 附加至 GitHub Release。 2026-08-31 再次进行了独立的使用者验证。该发布版本的专属证据经评估符合 SLSA v1.2 Build L3；SLSA 是 符合性框架，不是认证，也不保证工件安全。

---

延伸阅读

• SPEC.md — 当前的架构契约
• MACHINE_AUTHORITY_PROBLEM.md — v3 权限层工作要解决的问题
• MACHINE_AUTHORITY_V1.md — 八项机器权限核心不变量的清单（委派图、自主权预算、记忆防火墙、证据包等）
• ENFORCEMENT_BOUNDARY.md — 每项不变量的权限边界：内联强制执行还是自愿设置的关卡
• LEGACY_TO_MACHINE_AUTHORITY_MAP.md — 将 RBAC/OAuth/IAM 概念映射到对应的 WhitePact 概念，供熟悉传统访问控制的读者参考
• MIGRATION_WHITEPACT_V2.md — 按阶段记录的迁移日志，说明已完成的工作和明确未做的工作
• DEFINITION_OF_DONE.md — 收尾报告：当前实际存在的内容、不存在的内容，以及如何验证
• SECURITY_THREAT_MODEL.md — 当前的安全威胁与攻击面模型
• DETERMINISTIC_VS_PROBABILISTIC.md — 治理决策为何具有确定性
• SLA.md、ENTERPRISE_SECURITY.md、SECURITY.md — 企业级安全态势，如实说明
• compliance/SOC2_ALTERNATIVE_PATH.md — 现阶段真实、免费的可独立验证信任信号；以及在有预算时取得真正 SOC 2 的诚实路径
• docs/ACCESSIBILITY.md、docs/INTERNATIONALIZATION.md — WCAG2AA 无障碍方案和仪表板的国际化架构，两者均设有真实的自动化 CI 检查关卡
• compliance/PROJECT_CONTINUITY_PLAN.md — 如果创始人无法履职，第二个人所需的访问／恢复清单；如实说明这是一份计划，而非具备冗余人员保障的证明（目前尚无第二个人拥有这些访问权限）

---

许可证

MIT — 详见 LICENSE。