{
"markdown": "# Glass Box Framework\n\n> **Runtime constitutional verification for AI answers.** Every claim carries a reasoning chain. Every score breaks down. Every verdict is traceable.\n\n[](https://github.com/TheBarmaEffect/glassbox/actions/workflows/ci.yml)\n[](https://pypi.org/project/glassbox-framework/)\n[](https://www.npmjs.com/package/@glassbox-framework/mcp)\n[](https://github.com/TheBarmaEffect/homebrew-glassbox)\n[](https://registry.modelcontextprotocol.io/v0/servers?search=glassbox-framework)\n[](https://pypi.org/project/glassbox-framework/)\n[](LICENSE)\n[](https://github.com/TheBarmaEffect/glassbox/stargazers)\n\n> ⭐️ **Star this repo if you want runtime AI verification to become the default.** Every star moves Glassbox up the search ranking on GitHub, the MCP Registry, and Smithery — which means more developers find this before they ship an AI feature without a Trust Card.\n\n
\n \n
\n\n```bash\npip install glassbox-framework # Python\nnpm install -g @glassbox-framework/mcp # Node / MCP\nbrew install thebarmaeffect/glassbox/glassbox-mcp # macOS\n```\n\n## Zero-cost public GlassBox Lite\n\nThe repository also ships a separate deterministic Lite verifier and cross-platform gateway that require no paid model API:\n\n- [Web app / installable PWA](https://glassbox-platform-gateway.onrender.com/app)\n- [Public remote MCP](https://glassbox-platform-gateway.onrender.com/mcp) for ChatGPT, Claude, and compatible clients\n- [GitHub App](https://github.com/apps/glassbox-by-aura/installations/new)\n- [Discord](https://discord.com/oauth2/authorize?client_id=1536588680813350972)\n- [Telegram](https://t.me/GlassBoxAuditBot)\n- Notion: embed `https://glassbox-platform-gateway.onrender.com/app`\n- Browser, VS Code, and JetBrains packages: [latest GitHub release](https://github.com/TheBarmaEffect/glassbox/releases/latest)\n\nLite performs bounded structural checks and does not browse or establish factual truth. The original six-tool model-assisted MCP documented below remains a separate surface.\n\nSee [PLATFORMS.md](PLATFORMS.md) for the exact live, downloadable, pilot, and external-review status of every integration.\n\n## What it is\n\nThe Glass Box Framework hands an `(question, answer)` pair to a runtime verification pipeline and returns a structured **Trust Card** containing:\n\n- **Claims** — every atomic assertion in the answer, paired with a *reasoning chain* explaining why it's asserted, what would support it, and what would falsify it.\n- **Epistemic Confidence Score (ECS)** — a transparent, weighted aggregate over five dimensions with a *published formula* and an always-visible per-dimension breakdown.\n- **Glassbox Court** — seven adversarial probes (fabrication, source manipulation, bias injection, context attack, overconfidence, underspecification, constitutional violation).\n- **Constitution** — your natural-language deployer intents compiled into structured runtime rules and evaluated against the answer.\n- **Verdict** — `trust` / `caution` / `reject`, with the exact reasoning that derived it.\n- **Audit reference** — a deterministic SHA-256 log_id; identical inputs reproduce the same identifier across runs and languages.\n\nIt 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.\n\n## Quick start (Python)\n\n```python\nfrom glassbox_framework import Glassbox\n\nwith Glassbox() as gb:\n card = gb.verify_answer(\n question=\"Can intermittent fasting cure type 2 diabetes?\",\n answer=\"Yes ...\",\n intents=[\n \"Never make specific medical claims without citing peer-reviewed sources.\",\n \"Always recommend consultation with a licensed healthcare professional.\",\n ],\n )\n\nprint(card[\"verdict\"]) # \"reject\"\nprint(card[\"ecs\"][\"total\"]) # 0.6032\nprint(card[\"audit\"][\"log_id\"]) # glassbox-85cc09903bd4... (deterministic)\n```\n\n## The six tools\n\n| Tool | Purpose |\n| :--- | :--- |\n| `glassbox_verify_answer` | Full pipeline → Trust Card |\n| `glassbox_extract_claims` | Atomic claims with reasoning chains |\n| `glassbox_score_ecs` | ECS with full breakdown + formula |\n| `glassbox_red_team` | Glassbox Court — 7 adversarial probes |\n| `glassbox_generate_trust_card` | Assemble a Trust Card from prebuilt parts (no LLM call) |\n| `glassbox_export_audit_report` | Full pipeline + deterministic SHA-256 audit log |\n\nFull schemas, examples, and configuration: [`mcp/README.md`](mcp/README.md). Python pip-specific docs: [`mcp/python/README.md`](mcp/python/README.md).\n\n## Architecture (two-layer)\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ glassbox-framework (PyPI) Python client │\n│ thin JSON-RPC stdio wrapper │\n│ spawns ↓ │\n├──────────────────────────────────────────────────────────┤\n│ @glassbox-framework/mcp (npm) Node MCP server │\n│ 6 tools, Zod-validated I/O │\n│ ↳ verify_answer ↳ extract_claims ↳ score_ecs │\n│ ↳ red_team ↳ generate_trust_card │\n│ ↳ export_audit_report │\n└──────────────────────────────────────────────────────────┘\n```\n\nThe 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.\n\n## Use with Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"glass-box\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@glassbox-framework/mcp\"],\n \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-...\" }\n }\n }\n}\n```\n\n`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS.\n\n## Determinism\n\nAudit `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).\n\nVerifiable example, no API key needed:\n\n```bash\npip install glassbox-framework\npython -c \"\nimport json\nfrom glassbox_framework import Glassbox\nwith open('mcp/demo/raw-inputs.json') as f: i = json.load(f)\nwith Glassbox() as gb:\n c = gb.generate_trust_card(\n question=i['question'], answer=i['answer'],\n claims=i['claims'], red_team=i['red_team'], ecs=i['ecs'],\n constitution=i['constitution'])\nprint(c['audit']['log_id']) # glassbox-85cc09903bd4b3f8022a4087\n\"\n```\n\n## Project layout\n\n```\nmcp/ — the MCP server + Python client (this release)\n ├── src/ — TypeScript MCP server (6 tools)\n ├── python/ — Python pip package (glassbox-framework)\n ├── homebrew/ — Homebrew formula\n ├── assets/ — Launch video + reveal + title cards\n ├── demo/ — Live terminal demo with prebuilt Trust Card\n ├── Dockerfile — Container image\n ├── server.json — MCP Registry manifest\n ├── smithery.yaml — Smithery.ai manifest\n ├── LAUNCH.md — Launch kit\n └── DISTRIBUTION.md — Every channel's status + commands\nLICENSE — Apache 2.0\nROADMAP.md — Phase 5 (governor) plans for the broader framework\nCONTRIBUTING.md\nCHANGELOG.md\n```\n\n## Contributing\n\nGlassbox is open source under Apache 2.0 and **actively wants forks and PRs.** A few specific places we'd love help:\n\n- **More red-team probes** — `mcp/src/engines/redteam.ts` has `// v2:` placeholders for `alignment_faking`, `reasoning_trace_deception`, `eval_awareness_gaming`, `agentic_misalignment`, and `sustained_jailbreak`. Each is a tractable PR — same shape as the existing 7 probes, just a different angle. See [`.github/ISSUE_TEMPLATE/good_first_issue.md`](.github/ISSUE_TEMPLATE/good_first_issue.md).\n- **More language clients** — currently Python (`glassbox-framework`) and Node (`@glassbox-framework/mcp`). Go, Rust, Ruby, Swift, Kotlin would all be welcome as thin JSON-RPC clients that spawn the existing MCP server.\n- **More integrations** — Cursor / Cline / Continue / Roo Cline / Zed / Neovim — wherever MCP is read, Glassbox should be one paste away.\n- **Real-world Trust Card examples** — submit (Q, A) pairs from your own AI workflows so the test suite covers more terrain.\n\nProcess:\n1. Pick a `good first issue` or open one with your idea\n2. Fork, branch, work — the [PR template](.github/PULL_REQUEST_TEMPLATE.md) walks you through verification\n3. CI must pass ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) — TS strict mode, Python wheel build, **cross-language determinism on the canonical audit hash**\n4. Open the PR; we aim for review within 48 hours\n\nCode of conduct: [Contributor Covenant 2.1](CODE_OF_CONDUCT.md). Be kind, stay on substance, no harassment, contact `thebarmaeffect@gmail.com` for anything off-public-channel.\n\n## Star ⭐ this repo\n\nThe fastest way to help right now is to star the repo. Every star:\n- Surfaces Glassbox higher in GitHub's MCP topic listings\n- Pushes the project up on the MCP Registry and Smithery rankings\n- Tells the next developer evaluating AI-safety tooling that this is the one with eyes on it\n\n[**⭐ Star Glassbox**](https://github.com/TheBarmaEffect/glassbox/stargazers)\n\n## Author\n\n**Karthik Barma** · MS Artificial Intelligence · Northeastern University.\n\n**Powered by Aura.**\n\nIssues + PRs: \n",
"bytes": 10480,
"sha": "e4317f1ab726e958c7be507a8a93e2b9f9c855d4ff1383125efd81255d25cc8b",
"repo_slug": "thebarmaeffect/glassbox",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_thebarmaeffect_glassbox_framew_27f43b72/readme"
}
![\"Glassbox](\"mcp/assets/glassbox-walkthrough.gif\")
\n