# Glass Box Framework
[](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
## What it is
The Glass Box Framework hands an `(question, answer)` pair to a runtime verification pipeline and returns a structured **Trust Card** containing:
It is intentionally **not a wrapper around a single LLM call** — the reasoning chain on every claim, the formula on the ECS, and the determinism of the audit hash together form the "Glass Box" principle: no opaque scores.
## Quick start (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)
## The six tools
| Tool | Purpose |
| :--- | :--- |
| `glassbox_verify_answer` | Full pipeline → Trust Card |
| `glassbox_extract_claims` | Atomic claims with reasoning chains |
| `glassbox_score_ecs` | ECS with full breakdown + formula |
| `glassbox_red_team` | Glassbox Court — 7 adversarial probes |
| `glassbox_generate_trust_card` | Assemble a Trust Card from prebuilt parts (no LLM call) |
| `glassbox_export_audit_report` | Full pipeline + deterministic SHA-256 audit log |
Full schemas, examples, and configuration: [`mcp/README.md`](mcp/README.md). Python pip-specific docs: [`mcp/python/README.md`](mcp/python/README.md).
## Architecture (two-layer)
┌──────────────────────────────────────────────────────────┐
│ 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 │
└──────────────────────────────────────────────────────────┘
The Python client makes zero LLM calls itself; it forwards arguments to the MCP server over stdio and renders the returned JSON. Set `ANTHROPIC_API_KEY` once and both layers use it.
## Use with Claude Desktop
{
"mcpServers": {
"glass-box": {
"command": "npx",
"args": ["-y", "@glassbox-framework/mcp"],
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}
## Determinism
Audit `log_id`s are SHA-256 over canonicalised JSON of `(inputs_hash, claims, ECS dimensions, red-team probe verdicts, constitution evaluations)`. Timestamps are recorded but never enter the hash, so identical inputs *and* identical engine outputs always produce the same `log_id` — across runs, machines, and even languages (the Python client → Node server → JSON canonicalisation produces byte-identical hashes).
Verifiable example, no API key needed:
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
"
## Project layout
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
## Author
**Karthik Barma** · MS Artificial Intelligence · Northeastern University.
**Powered by Aura.**
Issues + PRs: