glassbox-framework

Glass Box Framework

AI 回答的运行时宪法验证。 每项声明都带有推理链。每个评分都有细分依据。每个判定都可追溯。

⭐️ 如果你希望运行时 AI 验证成为默认做法，请为此仓库点亮 Star。 每颗 Star 都会提升 Glassbox 在 GitHub、MCP Registry 和 Smithery 上的搜索排名，这意味着会有更多开发者在发布缺少 Trust Card 的 AI 功能之前发现它。

pip install glassbox-framework         # Python
npm install -g @glassbox-framework/mcp # Node / MCP
brew install thebarmaeffect/glassbox/glassbox-mcp   # macOS

零成本公共版 GlassBox Lite

此仓库还提供独立的确定性 Lite 验证器和跨平台网关，无需付费模型 API：

• Web 应用 / 可安装的 PWA
• 公共远程 MCP，适用于 ChatGPT、Claude 和兼容的客户端
• GitHub App
• Discord
• Telegram
• Notion：嵌入 https://glassbox-platform-gateway.onrender.com/app
• 浏览器、VS Code 和 JetBrains 软件包：最新 GitHub 版本

Lite 执行有界结构检查，不会浏览网页或判定事实真伪。下文介绍的原始六工具模型辅助 MCP 是独立的服务。

有关每项集成的准确实时、可下载、试点和外部审核状态，请参阅 PLATFORMS.md。

概述

Glass Box Framework 会将一对 (question, answer) 传入运行时验证流水线，并返回一张结构化的 Trust Card，其中包含：

• Claims — 答案中的每条原子断言，以及与之配对的推理链，说明为何作出该断言、哪些依据可以支持它，以及哪些证据可以证伪它。
• Epistemic Confidence Score (ECS) — 对五个维度进行透明的加权汇总，采用已公开的公式，并始终显示各维度的明细。
• Glassbox Court — 七项对抗性探测（捏造、来源操纵、偏见注入、上下文攻击、过度自信、描述不充分、违反宪章）。
• Constitution — 将你用自然语言表达的部署者意图编译为结构化运行时规则，并根据答案进行评估。
• Verdict — trust / caution / reject，并附上推导该结论的确切理由。
• Audit reference — 确定性的 SHA-256 log_id；相同输入在不同运行和语言中会生成相同标识符。

它有意不只是对单次 LLM 调用的包装器——每条 Claim 的推理链、ECS 的计算公式，以及审计哈希的确定性，共同构成了“Glass Box”原则：不提供不透明的评分。

快速开始（Python）

from glassbox_framework import Glassbox

with Glassbox() as gb:
    card = gb.verify_answer(
        question="Can intermittent fasting cure type 2 diabetes?",
        answer="Yes ...",
        intents=[
            "Never make specific medical claims without citing peer-reviewed sources.",
            "Always recommend consultation with a licensed healthcare professional.",
        ],
    )

print(card["verdict"])              # "reject"
print(card["ecs"]["total"])         # 0.6032
print(card["audit"]["log_id"])      # glassbox-85cc09903bd4...  (deterministic)

六种工具

工具	用途
glassbox_verify_answer	完整流水线 → Trust Card
glassbox_extract_claims	原子 Claim 及其推理链
glassbox_score_ecs	ECS，包含完整明细和公式
glassbox_red_team	Glassbox Court — 7 项对抗性探测
glassbox_generate_trust_card	使用预先构建的部分内容组装 Trust Card（不调用 LLM）
glassbox_export_audit_report	完整流水线 + 确定性的 SHA-256 审计日志

完整的 Schema、示例和配置：mcp/README.md。Python pip 专用文档：mcp/python/README.md。

架构（两层）

┌──────────────────────────────────────────────────────────┐
│ glassbox-framework (PyPI)         Python client          │
│   thin JSON-RPC stdio wrapper                            │
│   spawns ↓                                               │
├──────────────────────────────────────────────────────────┤
│ @glassbox-framework/mcp (npm)     Node MCP server        │
│   6 tools, Zod-validated I/O                             │
│   ↳ verify_answer  ↳ extract_claims  ↳ score_ecs         │
│   ↳ red_team       ↳ generate_trust_card                 │
│   ↳ export_audit_report                                  │
└──────────────────────────────────────────────────────────┘

Python 客户端本身不会调用 LLM；它通过 stdio 将参数转发给 MCP 服务，并呈现返回的 JSON。只需设置一次 ANTHROPIC_API_KEY，两层都会使用它。

与 Claude Desktop 搭配使用

{
  "mcpServers": {
    "glass-box": {
      "command": "npx",
      "args": ["-y", "@glassbox-framework/mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json。

确定性

审计 log_id 是对 (inputs_hash, claims, ECS dimensions, red-team probe verdicts, constitution evaluations) 的规范化 JSON 计算 SHA-256 得出的。系统会记录时间戳，但不会将其纳入哈希，因此相同的输入和相同的引擎输出始终会生成相同的 log_id，无论运行次数、机器，甚至所用语言如何（Python 客户端 → Node 服务 → JSON 规范化会生成字节完全相同的哈希）。

可验证示例，无需 API key：

pip install glassbox-framework
python -c "
import json
from glassbox_framework import Glassbox
with open('mcp/demo/raw-inputs.json') as f: i = json.load(f)
with Glassbox() as gb:
    c = gb.generate_trust_card(
        question=i['question'], answer=i['answer'],
        claims=i['claims'], red_team=i['red_team'], ecs=i['ecs'],
        constitution=i['constitution'])
print(c['audit']['log_id'])   # glassbox-85cc09903bd4b3f8022a4087
"

项目结构

mcp/                       — the MCP server + Python client (this release)
  ├── src/                 — TypeScript MCP server (6 tools)
  ├── python/              — Python pip package (glassbox-framework)
  ├── homebrew/            — Homebrew formula
  ├── assets/              — Launch video + reveal + title cards
  ├── demo/                — Live terminal demo with prebuilt Trust Card
  ├── Dockerfile           — Container image
  ├── server.json          — MCP Registry manifest
  ├── smithery.yaml        — Smithery.ai manifest
  ├── LAUNCH.md            — Launch kit
  └── DISTRIBUTION.md      — Every channel's status + commands
LICENSE                    — Apache 2.0
ROADMAP.md                 — Phase 5 (governor) plans for the broader framework
CONTRIBUTING.md
CHANGELOG.md

贡献

Glassbox 基于 Apache 2.0 开源，并且积极欢迎分叉和 PR。 以下是我们特别希望获得帮助的几个方面：

• 更多红队探测 — mcp/src/engines/redteam.ts 中有针对 alignment_faking、reasoning_trace_deception、eval_awareness_gaming、agentic_misalignment 和 sustained_jailbreak 的 // v2: 占位符。每一项都适合作为一个 PR 来实现——结构与现有的 7 项探测相同，只是切入角度不同。请参阅 .github/ISSUE_TEMPLATE/good_first_issue.md。
• 更多语言客户端 — 目前支持 Python（glassbox-framework）和 Node（@glassbox-framework/mcp）。欢迎 Go、Rust、Ruby、Swift、Kotlin 客户端，它们可以作为轻量级 JSON-RPC 客户端，启动现有的 MCP 服务。
• 更多集成 — Cursor / Cline / Continue / Roo Cline / Zed / Neovim——任何读取 MCP 的地方，都应该能通过粘贴一次配置来接入 Glassbox。
• 真实世界的 Trust Card 示例 — 提交来自你自己的 AI 工作流中的（Q，A）对，帮助测试套件覆盖更多场景。

流程：

1. 选择一个 good first issue，或提出你的想法并创建一个 issue
2. 分叉、创建分支并开始开发——PR 模板会引导你完成验证
3. CI 必须通过（.github/workflows/ci.yml）——TS 严格模式、Python wheel 构建、规范审计哈希的跨语言确定性
4. 提交 PR；我们力争在 48 小时内完成审核

行为准则：Contributor Covenant 2.1。请友善交流，聚焦实质内容，不要骚扰他人。如需联系以进行非公开沟通，请发邮件至 [email protected]。

给这个仓库点个星 ⭐

现在最快的帮助方式就是给这个仓库点个星。每一颗星都能：

• 让 Glassbox 在 GitHub 的 MCP 主题列表中排名更靠前
• 提升项目在 MCP Registry 和 Smithery 排名中的位置
• 告诉正在评估 AI 安全工具的开发者：这是一个备受关注的项目

⭐ 给 Glassbox 点星

作者

Karthik Barma · 人工智能硕士 · Northeastern University。

由 Aura 提供支持。

Issues + PR：https://github.com/TheBarmaEffect/glassbox/issues