TheBarmaEffect/glassbox
GitHub: TheBarmaEffect/glassbox
一个 AI 回答运行时验证框架，通过断言级推理链、多维度置信度评分和对抗性探测生成可审计的 Trust Card。
Stars: 11 | Forks: 0
# Glass Box 框架
[](https://github.com/TheBarmaEffect/glassbox/actions/workflows/ci.yml)
[](https://pypi.org/project/glassbox-framework/)
[](https://www.npmjs.com/package/@glassbox-framework/mcp)
[](https://github.com/TheBarmaEffect/homebrew-glassbox)
[](https://registry.modelcontextprotocol.io/v0/servers?search=glassbox-framework)
[](https://pypi.org/project/glassbox-framework/)
[](LICENSE)
[](https://github.com/TheBarmaEffect/glassbox/stargazers)
```
pip install glassbox-framework # Python
npm install -g @glassbox-framework/mcp # Node / MCP
brew install thebarmaeffect/glassbox/glassbox-mcp # macOS
```
## 它是什么
Glass Box Framework 将 `(question, answer)`（问题，答案）对传递给 runtime 验证 pipeline，并返回一个结构化的 **Trust Card**，其中包含：
- **Claims** — 答案中的每一个原子断言，都附带一个 *reasoning chain*，解释为什么这样断言、什么能支持它、以及什么能证伪它。
- **Epistemic Confidence Score (ECS)** — 一个透明的、基于五个维度加权计算的综合分数，具有*公开的公式*以及始终可见的各维度细分。
- **Glassbox Court** — 七个对抗性探测（捏造、来源操纵、偏见注入、上下文攻击、过度自信、欠规范、违规）。
- **Constitution** — 您的自然语言部署意图，被编译成结构化的 runtime 规则，并针对答案进行评估。
- **Verdict** — `trust` / `caution` / `reject`，以及得出该结论的确切推理过程。
- **Audit reference** — 确定性的 SHA-256 log_id；相同的输入在不同运行和不同语言中会重现相同的标识符。
它特意**不是围绕单次 LLM 调用的包装器**——每个 claim 上的 reasoning chain、ECS 上的公式，以及 audit 哈希的确定性，共同构成了“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` | 完整 pipeline → Trust Card |
| `glassbox_extract_claims` | 附带 reasoning chain 的原子 claims |
| `glassbox_score_ecs` | 包含完整细分和公式的 ECS |
| `glassbox_red_team` | Glassbox Court — 7 次对抗性探测 |
| `glassbox_generate_trust_card` | 从预构建的组件组装 Trust Card（无 LLM 调用） |
| `glassbox_export_audit_report` | 完整 pipeline + 确定性的 SHA-256 audit 日志 |
完整的 schema、示例和配置：[`mcp/README.md`](mcp/README.md)。Python pip 专属文档：[`mcp/python/README.md`](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`。
## 确定性
Audit `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
```
## 作者
**Karthik Barma** · 人工智能硕士 · Northeastern University。
**由 Aura 提供支持。**
Issues + PRs：
标签：AI可解释性, MCP, MITM代理, Python, 人工智能, 内容验证, 无后门, 用户模式Hook绕过, 自动化攻击, 请求拦截, 逆向工具