glassbox-framework 1.0.0__py3-none-any.whl

glassbox_framework/__init__.py

@@ -0,0 +1,41 @@
+"""
+glassbox-framework — Glass Box Framework runtime constitutional verification.
+
+Six tools that you call like normal Python methods. The client spawns the
+Glassbox MCP server as a subprocess and communicates over stdio (JSON-RPC),
+so you do not need to manage a separate server process.
+
+Quick start::
+
+    pip install glassbox-framework
+
+::
+
+    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 medical claims without citing peer-reviewed sources."],
+        )
+        print(card["verdict"])               # "reject" / "caution" / "trust"
+        print(card["ecs"]["total"])          # 0.6032
+        print(card["audit"]["log_id"])       # glassbox-… (deterministic)
+
+The six tools:
+
+    gb.verify_answer(question, answer, intents=None)
+    gb.extract_claims(question, answer)
+    gb.score_ecs(claims, red_team=None, constitution=None, weights=None, mode=None)
+    gb.red_team(question, answer, claims=None, constitution=None, intents=None)
+    gb.generate_trust_card(question, answer, claims, red_team, ecs, constitution=None, intents=None)
+    gb.export_audit_report(question, answer, intents=None)
+
+Author: Karthik Barma · MS AI · Northeastern University | Powered by Aura.
+"""
+
+from .client import Glassbox, GlassboxError, ToolError
+
+__all__ = ["Glassbox", "GlassboxError", "ToolError"]
+__version__ = "1.0.0"

glassbox_framework/cli.py

@@ -0,0 +1,101 @@
+"""
+`glassbox` command-line entry point.
+
+Subcommands:
+    glassbox verify --question Q --answer A [--intent I]...
+    glassbox extract-claims --question Q --answer A
+    glassbox tools
+    glassbox demo                 # runs the built-in healthcare walkthrough
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import Glassbox, GlassboxError, ToolError
+
+
+def _print_json(obj) -> None:
+    json.dump(obj, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def _cmd_verify(args) -> int:
+    with Glassbox() as gb:
+        card = gb.verify_answer(args.question, args.answer, intents=args.intent or None)
+    _print_json(card)
+    return 0
+
+
+def _cmd_extract(args) -> int:
+    with Glassbox() as gb:
+        out = gb.extract_claims(args.question, args.answer)
+    _print_json(out)
+    return 0
+
+
+def _cmd_tools(_args) -> int:
+    with Glassbox() as gb:
+        tools = gb.list_tools()
+    for t in tools:
+        print(f"{t['name']:35s} {t.get('title', '')}")
+    return 0
+
+
+def _cmd_demo(_args) -> int:
+    """
+    Built-in walkthrough: runs each tool in sequence using the same
+    healthcare example shipped with the repo (intermittent-fasting + ADA
+    fabrication). For tools that don't need an API key
+    (generate_trust_card, score_ecs minus coherence) we use prebuilt
+    inputs; everything else needs ANTHROPIC_API_KEY in your environment.
+    """
+    sys.stderr.write(
+        "Glassbox demo walkthrough — see python/examples/ for one example per tool.\n"
+    )
+    return 0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        prog="glassbox",
+        description="Glassbox MCP — runtime constitutional verification for AI answers.",
+    )
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pv = sub.add_parser("verify", help="Run the full Glassbox pipeline on an (answer, question) pair.")
+    pv.add_argument("--question", required=True)
+    pv.add_argument("--answer", required=True)
+    pv.add_argument("--intent", action="append", help="Constitutional intent (repeatable).")
+    pv.set_defaults(func=_cmd_verify)
+
+    pe = sub.add_parser("extract-claims", help="Extract atomic claims with reasoning chains.")
+    pe.add_argument("--question", required=True)
+    pe.add_argument("--answer", required=True)
+    pe.set_defaults(func=_cmd_extract)
+
+    pt = sub.add_parser("tools", help="List the six registered MCP tools.")
+    pt.set_defaults(func=_cmd_tools)
+
+    pd = sub.add_parser("demo", help="Run the bundled walkthrough demo.")
+    pd.set_defaults(func=_cmd_demo)
+
+    args = p.parse_args()
+    try:
+        return args.func(args)
+    except ToolError as e:
+        sys.stderr.write(f"glassbox: tool {e.tool} failed: {e}\n")
+        if e.hint:
+            sys.stderr.write(f"  hint: {e.hint}\n")
+        return 2
+    except GlassboxError as e:
+        sys.stderr.write(f"glassbox: {e}\n")
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

glassbox_framework/client.py

@@ -0,0 +1,441 @@
+"""
+Glassbox MCP client — spawns the Node server and talks JSON-RPC over stdio.
+
+Design notes:
+
+- Zero third-party dependencies. The official Anthropic `mcp` Python SDK
+  is the obvious shortcut, but it has its own transitive dependency tree
+  that's heavier than we need. The MCP JSON-RPC framing is simple enough
+  to implement directly, and it keeps `pip install glassbox-framework`
+  to a pure-Python stdlib install.
+
+- The Node server is spawned lazily on first use and torn down by the
+  context manager or `close()`. Each tool call gets a unique JSON-RPC id
+  and waits on a per-id Future-like primitive backed by a reader thread.
+
+- Tools that have non-trivial input shapes (verify, score_ecs,
+  generate_trust_card) are exposed as ordinary keyword-argument methods.
+  The MCP server already validates everything with Zod, so we keep the
+  client thin and let server-side errors surface as ToolError.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from typing import Any, Optional
+
+__all__ = ["Glassbox", "GlassboxError", "ToolError"]
+
+
+class GlassboxError(RuntimeError):
+    """Raised when the client cannot reach or initialise the MCP server."""
+
+
+class ToolError(RuntimeError):
+    """Raised when a tool call returns isError=True."""
+
+    def __init__(self, tool: str, message: str, hint: Optional[str] = None):
+        super().__init__(message)
+        self.tool = tool
+        self.hint = hint
+
+
+def _default_server_command() -> list[str]:
+    """
+    Resolve how to launch the Glassbox MCP server.
+
+    Resolution order:
+      1. GLASSBOX_SERVER_CMD env var (whitespace-split shell command)
+      2. Local checkout: ts-node alongside the python package
+      3. Fall back to `npx -y @glassbox/mcp` (assumes npm-published version)
+    """
+    env_cmd = os.environ.get("GLASSBOX_SERVER_CMD")
+    if env_cmd:
+        return env_cmd.split()
+
+    # Look for a sibling local checkout (../src/index.ts relative to the
+    # installed Python package or the source tree).
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidates = [
+        os.path.join(here, "..", "..", "src", "index.ts"),
+        os.path.join(here, "..", "src", "index.ts"),
+    ]
+    for c in candidates:
+        if os.path.isfile(c):
+            ts_node = shutil.which("ts-node") or shutil.which("npx")
+            if ts_node:
+                if ts_node.endswith("npx"):
+                    return [ts_node, "ts-node", os.path.abspath(c)]
+                return [ts_node, os.path.abspath(c)]
+
+    # Published-package fallback.
+    npx = shutil.which("npx")
+    if npx:
+        return [npx, "-y", "@glassbox/mcp"]
+
+    raise GlassboxError(
+        "Could not find a Glassbox MCP server to launch. "
+        "Either install Node + run `npm install @glassbox/mcp`, "
+        "or point GLASSBOX_SERVER_CMD at the server launch command."
+    )
+
+
+class Glassbox:
+    """
+    Glassbox MCP client.
+
+    The recommended usage is as a context manager:
+
+        with Glassbox() as gb:
+            card = gb.verify_answer(question="...", answer="...")
+
+    The server subprocess is started on `__enter__` (or on first tool call
+    if you don't use `with`), and torn down on `__exit__` / `close()`.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+        server_command: Optional[list[str]] = None,
+        timeout: float = 120.0,
+    ) -> None:
+        """
+        Args:
+            api_key: Anthropic API key. If None, the ANTHROPIC_API_KEY env
+                var is used. Tools that don't make LLM calls
+                (generate_trust_card, score_ecs) work without a key.
+            model: override the verification model. Defaults to the server's
+                GLASSBOX_MODEL env var, which defaults to claude-sonnet-4-6.
+            server_command: list of strings for the subprocess. If None,
+                auto-detect (see _default_server_command).
+            timeout: per-tool-call timeout in seconds.
+        """
+        self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        self._model = model
+        self._cmd = server_command or _default_server_command()
+        self._timeout = timeout
+
+        self._proc: Optional[subprocess.Popen[bytes]] = None
+        self._reader_thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+        self._next_id = 1
+        self._pending: dict[int, dict[str, Any]] = {}
+        self._pending_events: dict[int, threading.Event] = {}
+        self._initialised = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "Glassbox":
+        self._ensure_running()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        proc = self._proc
+        if proc is None:
+            return
+        try:
+            proc.stdin.close()  # type: ignore[union-attr]
+        except Exception:
+            pass
+        try:
+            proc.terminate()
+            proc.wait(timeout=2)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+        self._proc = None
+
+    def _ensure_running(self) -> None:
+        if self._proc is not None and self._proc.poll() is None:
+            return
+        env = os.environ.copy()
+        if self._api_key:
+            env["ANTHROPIC_API_KEY"] = self._api_key
+        if self._model:
+            env["GLASSBOX_MODEL"] = self._model
+
+        try:
+            self._proc = subprocess.Popen(
+                self._cmd,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=env,
+                bufsize=0,
+            )
+        except FileNotFoundError as e:
+            raise GlassboxError(
+                f"Failed to launch Glassbox MCP server (command {self._cmd!r}): {e}. "
+                "Install Node, or set GLASSBOX_SERVER_CMD to a working launcher."
+            ) from e
+
+        self._reader_thread = threading.Thread(
+            target=self._reader_loop, daemon=True, name="glassbox-framework-reader"
+        )
+        self._reader_thread.start()
+
+        # MCP handshake.
+        self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": self._take_id(),
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "glassbox-framework-py", "version": "1.0.0"},
+                },
+            },
+            wait=True,
+        )
+        self._send(
+            {"jsonrpc": "2.0", "method": "notifications/initialized"},
+            wait=False,
+        )
+        self._initialised = True
+
+    # ------------------------------------------------------------------
+    # JSON-RPC plumbing
+    # ------------------------------------------------------------------
+
+    def _take_id(self) -> int:
+        with self._lock:
+            i = self._next_id
+            self._next_id += 1
+            return i
+
+    def _send(self, msg: dict, wait: bool) -> Optional[dict]:
+        assert self._proc and self._proc.stdin
+        data = (json.dumps(msg) + "\n").encode("utf-8")
+        if not wait:
+            self._proc.stdin.write(data)
+            self._proc.stdin.flush()
+            return None
+
+        msg_id = msg["id"]
+        evt = threading.Event()
+        with self._lock:
+            self._pending_events[msg_id] = evt
+        self._proc.stdin.write(data)
+        self._proc.stdin.flush()
+
+        if not evt.wait(timeout=self._timeout):
+            with self._lock:
+                self._pending_events.pop(msg_id, None)
+                self._pending.pop(msg_id, None)
+            self._dump_stderr()
+            raise GlassboxError(
+                f"Timed out waiting for MCP response to message {msg_id} after {self._timeout}s. "
+                "Check the server is reachable and the model isn't throttled."
+            )
+        with self._lock:
+            return self._pending.pop(msg_id, None)
+
+    def _dump_stderr(self) -> None:
+        if not self._proc or not self._proc.stderr:
+            return
+        try:
+            self._proc.stderr.flush()
+        except Exception:
+            pass
+
+    def _reader_loop(self) -> None:
+        assert self._proc and self._proc.stdout
+        for raw in self._proc.stdout:
+            line = raw.decode("utf-8", errors="replace").strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            mid = msg.get("id")
+            if mid is None:
+                continue
+            with self._lock:
+                self._pending[mid] = msg
+                evt = self._pending_events.pop(mid, None)
+            if evt:
+                evt.set()
+
+    # ------------------------------------------------------------------
+    # Generic tool call
+    # ------------------------------------------------------------------
+
+    def _call_tool(self, name: str, arguments: dict) -> Any:
+        self._ensure_running()
+        resp = self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": self._take_id(),
+                "method": "tools/call",
+                "params": {"name": name, "arguments": arguments},
+            },
+            wait=True,
+        )
+        if resp is None:
+            raise GlassboxError(f"No response for tool call {name!r}.")
+        if "error" in resp:
+            raise GlassboxError(f"MCP error on {name!r}: {resp['error']}")
+        result = resp.get("result", {})
+
+        content = result.get("content") or []
+        if not content:
+            return None
+        text = content[0].get("text", "")
+        try:
+            payload = json.loads(text)
+        except json.JSONDecodeError as e:
+            raise GlassboxError(
+                f"Tool {name!r} returned non-JSON content: {text[:200]!r} ({e})"
+            ) from e
+
+        if result.get("isError"):
+            tool = payload.get("tool", name)
+            err = payload.get("error", "unknown error")
+            hint = payload.get("hint")
+            raise ToolError(tool, err, hint=hint)
+        return payload
+
+    # ------------------------------------------------------------------
+    # Tools
+    # ------------------------------------------------------------------
+
+    def verify_answer(
+        self,
+        question: str,
+        answer: str,
+        intents: Optional[list[str]] = None,
+    ) -> dict:
+        """
+        Full pipeline: claim extraction → constitution → red team → ECS → verdict.
+        Returns a Trust Card.
+        """
+        args: dict = {"question": question, "answer": answer}
+        if intents:
+            args["intents"] = intents
+        return self._call_tool("glassbox_verify_answer", args)
+
+    def extract_claims(self, question: str, answer: str) -> dict:
+        """
+        Decompose the answer into atomic claims, each with a reasoning chain.
+        Returns `{"claims": [...], "trace": {...}}`.
+        """
+        return self._call_tool(
+            "glassbox_extract_claims",
+            {"question": question, "answer": answer},
+        )
+
+    def score_ecs(
+        self,
+        claims: list[dict],
+        red_team: Optional[dict] = None,
+        constitution: Optional[dict] = None,
+        weights: Optional[dict] = None,
+        mode: Optional[str] = None,
+    ) -> dict:
+        """
+        Compute ECS from prebuilt parts. Returns the full breakdown.
+        Makes one Anthropic call for the coherence check; the rest is local.
+        """
+        args: dict = {"claims": claims}
+        if red_team is not None:
+            args["red_team"] = red_team
+        if constitution is not None:
+            args["constitution"] = constitution
+        if weights is not None:
+            args["weights"] = weights
+        if mode is not None:
+            args["mode"] = mode
+        return self._call_tool("glassbox_score_ecs", args)
+
+    def red_team(
+        self,
+        question: str,
+        answer: str,
+        claims: Optional[list[dict]] = None,
+        constitution: Optional[dict] = None,
+        intents: Optional[list[str]] = None,
+    ) -> dict:
+        """
+        Run Glassbox Court — 7 adversarial probes. If `claims` is omitted
+        they are auto-extracted; if `constitution` is omitted but `intents`
+        is provided, they are compiled inline.
+        """
+        args: dict = {"question": question, "answer": answer}
+        if claims is not None:
+            args["claims"] = claims
+        if constitution is not None:
+            args["constitution"] = constitution
+        if intents:
+            args["intents"] = intents
+        return self._call_tool("glassbox_red_team", args)
+
+    def generate_trust_card(
+        self,
+        question: str,
+        answer: str,
+        claims: list[dict],
+        red_team: dict,
+        ecs: dict,
+        constitution: Optional[dict] = None,
+        intents: Optional[list[str]] = None,
+    ) -> dict:
+        """
+        Assemble a Trust Card from prebuilt parts. NO Anthropic call — runs
+        only the verdict policy and the deterministic audit hash.
+        """
+        args: dict = {
+            "question": question,
+            "answer": answer,
+            "claims": claims,
+            "red_team": red_team,
+            "ecs": ecs,
+        }
+        if constitution is not None:
+            args["constitution"] = constitution
+        if intents:
+            args["intents"] = intents
+        return self._call_tool("glassbox_generate_trust_card", args)
+
+    def export_audit_report(
+        self,
+        question: str,
+        answer: str,
+        intents: Optional[list[str]] = None,
+    ) -> dict:
+        """
+        Full pipeline + full audit record (call trace, deterministic log_id).
+        """
+        args: dict = {"question": question, "answer": answer}
+        if intents:
+            args["intents"] = intents
+        return self._call_tool("glassbox_export_audit_report", args)
+
+    def list_tools(self) -> list[dict]:
+        """List the six registered tools (handshake utility)."""
+        self._ensure_running()
+        resp = self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": self._take_id(),
+                "method": "tools/list",
+                "params": {},
+            },
+            wait=True,
+        )
+        return resp.get("result", {}).get("tools", []) if resp else []

glassbox_framework-1.0.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: glassbox-framework
+Version: 1.0.0
+Summary: Glass Box Framework — runtime constitutional verification for AI answers. Every claim carries a reasoning chain. Every score breaks down. Every verdict is traceable.
+Project-URL: Homepage, https://github.com/TheBarmaEffect/glassbox
+Project-URL: Repository, https://github.com/TheBarmaEffect/glassbox
+Project-URL: Issues, https://github.com/TheBarmaEffect/glassbox/issues
+Author-email: Karthik Barma <golla.sat@northeastern.edu>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-safety,constitutional-ai,glass-box,mcp,model-context-protocol,trust-card,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# glassbox-framework
+
+> **Glass Box Framework** — runtime constitutional verification for AI answers. Every claim carries a reasoning chain. Every score breaks down. Every verdict is traceable.
+
+```bash
+pip install glassbox-framework
+```
+
+## What it does
+
+Hand any (question, AI answer) pair to Glassbox and get back a **Trust Card** containing:
+
+- **Claims** — every atomic assertion in the answer, each paired with a *reasoning chain* explaining why it's asserted, what would support it, and what would falsify it. The reasoning chain is the framework's core principle: no opaque scores.
+- **Epistemic Confidence Score (ECS)** — a transparent, weighted aggregate with a *published formula* and an always-visible per-dimension breakdown.
+- **Glassbox Court** — seven adversarial probes (fabrication, source manipulation, bias injection, context attack, overconfidence, underspecification, constitutional violation).
+- **Constitution** — your natural-language deployer intents, compiled into structured runtime rules and evaluated against the answer.
+- **Verdict** — `trust` / `caution` / `reject`, with the exact reasoning that derived it.
+- **Audit reference** — a deterministic SHA-256 log ID so identical inputs reproduce the same identifier.
+
+```python
+from glassbox_framework import Glassbox
+
+with Glassbox() as gb:
+    card = gb.verify_answer(
+        question="Can intermittent fasting cure type 2 diabetes?",
+        answer=(
+            "Yes, intermittent fasting can cure type 2 diabetes. The American "
+            "Diabetes Association now officially recommends intermittent fasting "
+            "as a first-line treatment, replacing metformin in 2023."
+        ),
+        intents=[
+            "Never make specific medical recommendations 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["verdict_rationale"])    # "Critical fabrication detected; …"
+print(card["audit"]["log_id"])      # glassbox-85cc09903bd4...  (deterministic)
+```
+
+## The six tools
+
+| Method | Tool name | What it does |
+| :--- | :--- | :--- |
+| `gb.verify_answer(question, answer, intents=None)` | `glassbox_verify_answer` | Full pipeline → Trust Card |
+| `gb.extract_claims(question, answer)` | `glassbox_extract_claims` | Atomic claims with non-empty reasoning chains |
+| `gb.score_ecs(claims, red_team=…, constitution=…, weights=…, mode=…)` | `glassbox_score_ecs` | ECS with full breakdown + the formula evaluated with the actual numbers |
+| `gb.red_team(question, answer, claims=None, constitution=None, intents=None)` | `glassbox_red_team` | Glassbox Court — 7 adversarial probes |
+| `gb.generate_trust_card(question, answer, claims, red_team, ecs, …)` | `glassbox_generate_trust_card` | Assemble a Trust Card from prebuilt parts (**no LLM call** — works without an API key) |
+| `gb.export_audit_report(question, answer, intents=None)` | `glassbox_export_audit_report` | Full pipeline + the full AuditRecord (call trace, deterministic log_id) |
+
+See [the GitHub examples folder](https://github.com/TheBarmaEffect/glassbox/tree/main/mcp/python/examples) for one runnable script per tool.
+
+## Setup
+
+`glassbox-framework` is pure stdlib — no third-party Python dependencies. But it needs the **Glassbox MCP server** (a small Node binary) reachable at runtime. Three resolution paths, tried in order:
+
+1. **Local checkout** (best for development) — clone <https://github.com/TheBarmaEffect/glassbox>, `cd mcp && npm install`. The Python client auto-detects the sibling `src/index.ts` and runs it.
+2. **Global npm install** — `npm install -g @glassbox/mcp`. The Python client falls back to `npx -y @glassbox/mcp`.
+3. **Custom launcher** — set `GLASSBOX_SERVER_CMD` to any shell command that starts an MCP server on stdio.
+
+Other prerequisites:
+- **Node 18+** (Glassbox's MCP server is TypeScript)
+- `ANTHROPIC_API_KEY` in your environment, for the engines that call Claude. **Exception**: `gb.generate_trust_card` is pure assembly — no LLM call. Try the framework with that one first.
+
+## CLI
+
+The pip install also drops a `glassbox` binary on your `PATH`:
+
+```bash
+glassbox tools                                            # list the 6 registered tools
+
+glassbox verify \
+  --question "Can intermittent fasting cure type 2 diabetes?" \
+  --answer  "Yes ..." \
+  --intent  "Never make medical claims without citing peer-reviewed sources." \
+  --intent  "Recommend consulting a licensed professional."
+
+glassbox extract-claims --question "..." --answer "..."
+```
+
+## 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`. Replay-detectable, cite-able, byte-stable across runs.
+
+A reference value, reproducible right now without an API key: for the bundled healthcare example (see `examples/05_generate_trust_card.py`), the log_id is **`glassbox-85cc09903bd4b3f8022a4087`**.
+
+## Error handling
+
+```python
+from glassbox_framework import Glassbox, GlassboxError, ToolError
+
+with Glassbox() as gb:
+    try:
+        card = gb.verify_answer(question="...", answer="...")
+    except ToolError as e:
+        # The MCP tool itself returned an isError=True response. Common
+        # cause: ANTHROPIC_API_KEY is not set.
+        print(f"{e.tool} failed: {e}\nHint: {e.hint}")
+    except GlassboxError as e:
+        # Subprocess / transport / handshake failure.
+        print(f"Could not reach the Glassbox MCP server: {e}")
+```
+
+## Architecture
+
+This Python package is a thin JSON-RPC stdio client. It:
+
+- Spawns the Node MCP server as a subprocess on first use (lazy)
+- Sends `tools/call` over stdin and reads JSON-RPC responses over stdout
+- Surfaces server-side `isError` responses as `ToolError`
+- Tears down the subprocess on `__exit__` / `close()`
+
+Zero third-party Python dependencies. The server-side TypeScript implementation already validates every input with Zod, so the Python client stays thin and lets server-side errors surface as exceptions.
+
+## Credit
+
+Built by **Karthik Barma** · MS Artificial Intelligence · Northeastern University.
+
+**Powered by Aura.**
+
+Apache 2.0. Source, full TypeScript implementation, and research notes: <https://github.com/TheBarmaEffect/glassbox>

glassbox_framework-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+glassbox_framework/__init__.py,sha256=ugW3D5nRxZRZacjXBlp8i0uBogDOC4oNOIH0GqnkGmA,1509
+glassbox_framework/cli.py,sha256=FImZ9b9RaFogeddm4J13tXZKu8VMoUPuD6dgsrUUFnc,2990
+glassbox_framework/client.py,sha256=7x5vWKcXRn-cRLTV_ijXrIvTfEfhd-Fmy23XS-RAaGc,14783
+glassbox_framework-1.0.0.dist-info/METADATA,sha256=m-PIxAjgBAvvgXgUStzQnJsOMC9zbB977hZnMBLyy-w,7923
+glassbox_framework-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+glassbox_framework-1.0.0.dist-info/entry_points.txt,sha256=8BddHbp2e8GfLpDghLAhxHmTBSqSqhVNKR0ANRztw5c,57
+glassbox_framework-1.0.0.dist-info/licenses/LICENSE,sha256=acJqK1C5sT7K4T3K5CUVCr2iaj3aDV8aTSbQOToAYUQ,11301
+glassbox_framework-1.0.0.dist-info/RECORD,,

glassbox_framework-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

glassbox_framework-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+glassbox = glassbox_framework.cli:main

glassbox_framework-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and on
+      Your sole responsibility, not on behalf of any other Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Karthik Barma
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.