wallras 0.20.1__py3-none-any.whl

wallras-0.20.1.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: wallras
+Version: 0.20.1
+Summary: Clients for Wallras, the AI monitoring proxy: an MCP server for AI agents and a zero-dependency Python SDK
+License-Expression: MIT
+Project-URL: Homepage, https://wallras.com
+Project-URL: Documentation, https://wallras.com/docs
+Project-URL: Issues, https://github.com/wallras/wallras-python/issues
+Keywords: llm,monitoring,mcp,observability,drift,ai-agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Wallras clients for Python
+
+Two single-file, zero-dependency clients for [Wallras](https://wallras.com), the AI monitoring proxy you run next to your app:
+
+- **`wallras_mcp.py`**: an MCP server, so Claude Desktop, Claude Code, Cursor or your own agent can check drift, read requests and agent runs, work the review queue, fetch prompts and run regression sets. Read-only unless you pass `--enable-writes`.
+- **`wallras_sdk.py`**: report what Wallras can't see on its own: a self-hosted model's token probabilities and decision records, agent steps (tool runs, lookups), and feedback; fetch prompt versions.
+
+Both talk only to your own Wallras with your token. The Wallras engine itself ships as a Docker image (`ghcr.io/wallras/wallras-engine`); this repository holds the open-source clients.
+
+## Install
+
+```bash
+pip install git+https://github.com/wallras/wallras-python
+```
+
+Or run the MCP server without installing anything:
+
+```bash
+uvx --from git+https://github.com/wallras/wallras-python wallras-mcp
+```
+
+Each file also works on its own: copy it next to your code.
+
+## MCP server
+
+```json
+{"mcpServers": {"wallras": {
+  "command": "uvx", "args": ["--from", "git+https://github.com/wallras/wallras-python", "wallras-mcp"],
+  "env": {"WALLRAS_URL": "http://localhost:8080", "WALLRAS_TOKEN": "a viewer or admin token"}}}}
+```
+
+Add `"--enable-writes"` to `args` for the tools that change something (feedback, review decisions, saving or promoting prompts, regression runs, optionally graded by a `judge_model`). Those need an admin token; regression runs call your provider with `WALLRAS_PROVIDER_KEY` (and `WALLRAS_ANTHROPIC_KEY` / `WALLRAS_GEMINI_KEY`), which stay on your machine.
+
+## SDK
+
+```python
+from wallras_sdk import Wallras
+w = Wallras("http://localhost:8080", token="your WALLRAS_APP_TOKEN")
+w.report(model="llama-3.1-8b", prompt=prompt, answer=text,
+         tokens=Wallras.tokens_from_openai(response["choices"][0]["logprobs"]["content"]))
+```
+
+Reports go in the background and never raise into your code. See the [docs](https://wallras.com/docs.html) for traces, decision records and prompts.
+
+## Try a hub with two nodes
+
+[`examples/docker-compose.hub.yml`](examples/docker-compose.hub.yml) starts one hub and two nodes on your machine:
+
+```bash
+docker compose -f examples/docker-compose.hub.yml up -d
+```
+
+Send requests to a node (`http://localhost:8081/v1` or `:8082`, with your provider key), then open `http://localhost:8080/wallras/ui` and the Nodes tab.
+
+## Try active-active
+
+[`examples/docker-compose.active.yml`](examples/docker-compose.active.yml) starts Postgres, three Wallras containers and a load balancer. Any container answers any request, and together they keep one tamper-evident record:
+
+```bash
+docker compose -f examples/docker-compose.active.yml up -d
+```
+
+Send requests to `http://localhost:8080/v1`, then ask the MCP server's `wallras_fleet` tool (or `GET /wallras/fleet`) which containers answered.
+
+## Issues
+
+Bugs and ideas for the clients, or for Wallras itself: [open an issue](https://github.com/wallras/wallras-python/issues). Security reports: see [SECURITY.md](https://wallras.com/security.html), not public issues.
+
+MIT licensed. The files here are copies of the ones published with each Wallras release.

wallras-0.20.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+wallras_mcp.py,sha256=1DqCJkghltjsr38KxOggnycejuWF7-elR4_i_ixY-OI,17729
+wallras_sdk.py,sha256=jtgkwjAwGU-uvTUMa3lxkMPgwRD5unQU_34Wan7sAxM,14863
+wallras-0.20.1.dist-info/licenses/LICENSE,sha256=YLWvEOlXY8gW3uechPY87uVviR7gqkOxEWJn54CEYvA,1064
+wallras-0.20.1.dist-info/METADATA,sha256=RaAPtmGn2XEpxpONkAMNrelscJX2aiy7hYlqECWCnSM,4007
+wallras-0.20.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+wallras-0.20.1.dist-info/entry_points.txt,sha256=Y7mOHFUoiWaVyhfVENQnzHORfBtvJtfS6LoW1n0dIyI,49
+wallras-0.20.1.dist-info/top_level.txt,sha256=E-S-v2M6NfWM_-3MPSCJU7-wh7ELhMtd_PRQpTZxZJo,24
+wallras-0.20.1.dist-info/RECORD,,

wallras-0.20.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wallras-0.20.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wallras-mcp = wallras_mcp:main

wallras-0.20.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wallras
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wallras-0.20.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+wallras_mcp
+wallras_sdk

wallras_mcp.py

@@ -0,0 +1,259 @@
+"""Wallras for AI agents: an MCP server, so assistants such as Claude, Cursor or your own agent can
+check drift, read requests and traces, run regression sets, fetch prompts and work the review queue.
+
+No dependencies (Python 3.9+). It talks to your own Wallras over HTTP with your token; nothing goes
+anywhere else.
+
+    WALLRAS_URL=http://localhost:8080 WALLRAS_TOKEN=<a viewer or admin token> python wallras_mcp.py
+    python wallras_mcp.py --enable-writes      # also the tools that change something (admin token)
+
+In an MCP client configuration (Claude Desktop, Claude Code, Cursor...):
+
+    {"mcpServers": {"wallras": {"command": "python", "args": ["/path/to/wallras_mcp.py"],
+        "env": {"WALLRAS_URL": "http://localhost:8080", "WALLRAS_TOKEN": "..."}}}}
+
+Read-only by default. Tools that change something (feedback, review decisions, saving or promoting
+prompts, regression runs that call your provider) appear only with --enable-writes (or
+WALLRAS_MCP_WRITE=1), and still need an admin token. WALLRAS_ADMIN_TOKEN works in place of WALLRAS_TOKEN. Regression runs and gated releases call your provider with WALLRAS_PROVIDER_KEY (and
+WALLRAS_ANTHROPIC_KEY / WALLRAS_GEMINI_KEY for that traffic), which stay on this machine.
+"""
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+VERSION = "0.20.1"
+PROTOCOLS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+
+
+def _schema(props=None, required=()):
+    return {"type": "object", "properties": props or {}, "required": list(required), "additionalProperties": False}
+
+
+S, N, B = {"type": "string"}, {"type": "number"}, {"type": "boolean"}
+
+# name -> (description, input schema, method, path template, how arguments are sent, writes?)
+TOOLS = {
+    "wallras_overview": ("What needs attention now: drift, failing agent runs, broken regression sets, review items, "
+                         "each with the call to look closer.", _schema({"days": N}), "GET", "/wallras/overview", "query", False),
+    "wallras_judge": ("Live judge scores: the pass rate of real answers a judge model scored, per model and per prompt "
+                      "version, and recent failures.", _schema({"days": N, "model": S}), "GET", "/wallras/judge", "query", False),
+    "wallras_fleet": ("Active-active: every Wallras container and worker on this database, its version, when it last "
+                      "checked in and what it served; flags different versions running at once.", _schema({}), "GET",
+                      "/wallras/fleet", "query", False),
+    "wallras_hub": ("On a hub: every node in one view: models drifting on several nodes at once, silent nodes, "
+                    "each node's next actions, request totals.", _schema(), "GET", "/wallras/hub/overview", "query", False),
+    "wallras_hub_nodes": ("On a hub: each node's status, engine version, last report, usage and drift.", _schema(),
+                          "GET", "/wallras/hub/nodes", "query", False),
+    "wallras_status": ("Mode, provider, models seen, silent model swaps and plan.", _schema(), "GET", "/wallras/status", "query", False),
+    "wallras_drift": ("Drift per model against its own baseline: answer length, wording, refusals, certainty, served model.",
+                      _schema(), "GET", "/wallras/drift", "query", False),
+    "wallras_requests": ("The request log, newest first. Filter by model, app_name, status (ok or error) or text q.",
+                         _schema({"model": S, "app_name": S, "status": {"type": "string", "enum": ["ok", "error"]},
+                                  "q": S, "hours": N, "limit": N}), "GET", "/wallras/requests", "query", False),
+    "wallras_request": ("One recorded request: question, answer, served model, confidence, feedback, consistency check.",
+                        _schema({"event_id": S}, ["event_id"]), "GET", "/wallras/events/{event_id}", "path", False),
+    "wallras_usage": ("Requests, errors, tokens, cost and latency, by model or app.",
+                      _schema({"hours": N, "by": {"type": "string", "enum": ["model", "app"]}}), "GET", "/wallras/usage",
+                      "query", False),
+    "wallras_traces": ("Agent runs: steps, tool calls, tokens, cost and problems found (loops, tool errors).",
+                       _schema({"days": N, "status": {"type": "string", "enum": ["ok", "check", "failed"]}, "model": S,
+                                "limit": N}), "GET", "/wallras/traces", "query", False),
+    "wallras_trace": ("One agent run, step by step, with each answer, tool call and tool result.",
+                      _schema({"trace_id": S}, ["trace_id"]), "GET", "/wallras/traces/{trace_id}", "path", False),
+    "wallras_consistency": ("How often answers change when the same question is asked again or reworded.",
+                            _schema({"days": N}), "GET", "/wallras/consistency", "query", False),
+    "wallras_blind_spots": ("Topics and kinds of task where the AI is wrong more often than elsewhere.",
+                            _schema({"days": N}), "GET", "/wallras/blind-spots", "query", False),
+    "wallras_datasets": ("Regression test sets and their last results.", _schema(), "GET", "/wallras/datasets", "query", False),
+    "wallras_dataset": ("One regression set: its items and run history.", _schema({"name": S}, ["name"]), "GET",
+                        "/wallras/datasets/{name}", "path", False),
+    "wallras_experiments": ("Saved side-by-side comparisons of models or prompt versions.", _schema({"dataset": S}),
+                            "GET", "/wallras/experiments", "query", False),
+    "wallras_prompts": ("Saved prompts with their labels (production, staging...) and latest version.", _schema(),
+                        "GET", "/wallras/prompts", "query", False),
+    "wallras_prompt": ("One prompt: every version, who saved it, and the history of each label.",
+                       _schema({"name": S}, ["name"]), "GET", "/wallras/prompts/{name}", "path", False),
+    "wallras_prompt_diff": ("What changed between two versions of a prompt.",
+                            _schema({"name": S, "a": N, "b": N}, ["name", "a", "b"]), "GET",
+                            "/wallras/prompts/{name}/diff", "path+query", False),
+    "wallras_prompt_usage": ("Live results per prompt version: requests, errors, latency, tokens, feedback accuracy.",
+                             _schema({"name": S, "days": N}, ["name"]), "GET", "/wallras/prompts/{name}/usage",
+                             "path+query", False),
+    "wallras_review_queue": ("Answers waiting for a person: regression close calls and answers that contradicted "
+                             "themselves.", _schema({"status": {"type": "string", "enum": ["open", "decided", "all"]},
+                                                     "kind": S}), "GET", "/wallras/review", "query", False),
+    # ---- changes (WALLRAS_MCP_WRITE=1)
+    "wallras_feedback": ("Record whether an answer was correct.",
+                         _schema({"event_id": S, "correct": B, "note": S}, ["event_id", "correct"]), "POST",
+                         "/wallras/feedback", "json", True),
+    "wallras_decide_review": ("Decide a review item: correct or wrong, optionally accepting the answer as the new "
+                              "expected one.", _schema({"id": N, "verdict": {"type": "string", "enum": ["correct", "wrong"]},
+                                                        "note": S, "accept_answer": B}, ["id", "verdict"]), "POST",
+                              "/wallras/review/{id}", "path+json", True),
+    "wallras_run_dataset": ("Run a regression set on a model (calls your provider once per item) and get pass/fail, what "
+                            "newly broke and what got fixed. Pass judge_model to have a separate model grade each answer (needed for sets "
+                            "made with check \"judge\").",
+                            _schema({"name": S, "model": S, "fail_below": N, "system": S, "judge_model": S,
+                                     "calibrate": B, "provider": {"type": "string", "enum": ["openai", "anthropic", "gemini"]}},
+                                                                       ["name"]), "POST", "/wallras/datasets/{name}/run",
+                            "path+json", True),
+    "wallras_save_prompt": ("Save a new prompt version (system text or messages, optional model and note).",
+                            _schema({"name": S, "system": S, "messages": {"type": "array", "items": {"type": "object"}},
+                                     "model": S, "note": S}, ["name"]), "POST", "/wallras/prompts", "json", True),
+    "wallras_promote_prompt": ("Point a label at a prompt version. With gate_dataset, the version must pass that "
+                               "regression set first, or nothing changes.",
+                               _schema({"name": S, "version": N, "label": S, "gate_dataset": S, "fail_below": N, "reason": S, "gate_judge_model": S,
+                                        "gate_vars": {"type": "object", "additionalProperties": {"type": "string"}}},
+                                       ["name", "version"]), "POST", "/wallras/prompts/{name}/promote", "path+json", True),
+}
+
+
+def _clean(args):
+    return {k: v for k, v in (args or {}).items() if v is not None}
+
+
+class Server:
+    def __init__(self, env=None, out=None, enable_writes=False):
+        env = os.environ if env is None else env
+        self.url = (env.get("WALLRAS_URL") or "http://localhost:8080").rstrip("/")
+        if not self.url.lower().startswith(("http://", "https://")):
+            raise SystemExit("WALLRAS_URL must start with http:// or https://")
+        self.token = env.get("WALLRAS_TOKEN") or env.get("WALLRAS_ADMIN_TOKEN") or ""
+        self.write = enable_writes or env.get("WALLRAS_MCP_WRITE", "") in ("1", "true", "yes")
+        self.keys = {"authorization": f"Bearer {env['WALLRAS_PROVIDER_KEY']}" if env.get("WALLRAS_PROVIDER_KEY") else None,
+                     "x-api-key": env.get("WALLRAS_ANTHROPIC_KEY"), "x-goog-api-key": env.get("WALLRAS_GEMINI_KEY")}
+        self.out = out or sys.stdout
+
+    def tools(self):
+        """The most useful read tools first, then the rest, then (with --enable-writes) the changes."""
+        first = ["wallras_overview", "wallras_drift", "wallras_traces", "wallras_requests", "wallras_review_queue"]
+        order = first + [n for n, t in TOOLS.items() if n not in first and not t[5]] + \
+            [n for n, t in TOOLS.items() if t[5]]
+        return [{"name": n, "description": TOOLS[n][0], "inputSchema": TOOLS[n][1],
+                 "annotations": {"readOnlyHint": not TOOLS[n][5], "destructiveHint": False, "openWorldHint": False}}
+                for n in order if self.write or not TOOLS[n][5]]
+
+    def _keys_for(self, args):
+        """Only the keys a run needs: the named provider's (plus the OpenAI-style key when a judge model grades
+        the answers). With no provider named, a set can mix providers, so each configured key goes along; the
+        engine uses each only with its own provider."""
+        header = {"openai": "authorization", "anthropic": "x-api-key", "gemini": "x-goog-api-key"}
+        want = {header[args["provider"]]} if args.get("provider") in header else set(header.values())
+        if args.get("judge_model") or args.get("gate_judge_model"):
+            want.add("authorization")
+        return {k: v for k, v in self.keys.items() if v and k in want}
+
+    def _http(self, method, path, query=None, body=None, keys=None):
+        url = self.url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        headers = {"x-wallras-token": self.token, "accept": "application/json"}
+        headers.update(keys or {})
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["content-type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            # Reviewed: the URL is the configured http(s) Wallras address (checked in __init__).
+            with urllib.request.urlopen(req, timeout=180) as r:  # nosemgrep # nosec B310
+                return r.status, json.loads(r.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            try:
+                detail = json.loads(e.read() or b"{}")
+            except ValueError:
+                detail = {}
+            return e.code, detail
+        except Exception as exc:
+            return 0, {"detail": f"Wallras could not be reached at {self.url}: {type(exc).__name__}"}
+
+    def call(self, name, args):
+        if name not in TOOLS or (TOOLS[name][5] and not self.write):
+            return {"isError": True, "content": [{"type": "text", "text": f"Unknown tool {name}"}]}
+        _d, schema, method, path, how, _w = TOOLS[name]
+        args = _clean(args)
+        keys = self._keys_for(args) if name in ("wallras_run_dataset", "wallras_promote_prompt") else None
+        missing = [k for k in schema["required"] if k not in args]
+        if missing:
+            return {"isError": True, "content": [{"type": "text", "text": f"Missing: {', '.join(missing)}"}]}
+        unknown = [k for k in args if k not in schema["properties"]]
+        if unknown:
+            return {"isError": True, "content": [{"type": "text", "text": f"Unknown arguments: {', '.join(unknown)}"}]}
+        if name == "wallras_promote_prompt":   # the friendly shape -> the API's
+            gate = {"dataset": args.pop("gate_dataset"), "fail_below": args.pop("fail_below", 1.0)} \
+                if "gate_dataset" in args else None
+            if gate and "gate_vars" in args:
+                gate["vars"] = args["gate_vars"]
+            if gate and "gate_judge_model" in args:
+                gate["judge_model"] = args["gate_judge_model"]
+            for k in ("fail_below", "gate_vars", "gate_judge_model"):
+                args.pop(k, None)
+            args = {**args, "label": args.get("label", "production"), **({"gate": gate} if gate else {})}
+        for k in [k for k in args if "{" + k + "}" in path]:
+            path = path.replace("{" + k + "}", urllib.parse.quote(str(args.pop(k)), safe=""))
+        if "id" in args and name == "wallras_decide_review":
+            args.pop("id")
+        query = args if how in ("query", "path+query") else None
+        body = args if how in ("json", "path+json") else None
+        status, data = self._http(method, path, query, body, keys=keys)
+        text = json.dumps(data, ensure_ascii=False, indent=1)
+        if len(text) > 60_000:
+            text = text[:60_000] + "\n... (cut; narrow the request with filters)"
+        if status == 200:
+            return {"content": [{"type": "text", "text": text}], "structuredContent": data if isinstance(data, dict) else {"result": data}}
+        why = data.get("detail") if isinstance(data, dict) else None
+        return {"isError": True, "content": [{"type": "text", "text": f"Wallras answered {status}: "
+                                                                     f"{why if isinstance(why, str) else json.dumps(why or data)[:2000]}"}]}
+
+    def handle(self, msg):
+        mid, method, params = msg.get("id"), msg.get("method"), msg.get("params") or {}
+        if method == "initialize":
+            asked = params.get("protocolVersion")
+            result = {"protocolVersion": asked if asked in PROTOCOLS else PROTOCOLS[0],
+                      "capabilities": {"tools": {"listChanged": False}},
+                      "serverInfo": {"name": "wallras", "title": "Wallras", "version": VERSION},
+                      "instructions": "Start with wallras_overview: it says what needs attention and which tool "
+                                      "to call next. Answers and prompts can hold customer data; quote them only "
+                                      "as needed." + ("" if self.write else " This server is read-only.")}
+        elif method == "ping":
+            result = {}
+        elif method == "tools/list":
+            result = {"tools": self.tools()}
+        elif method == "tools/call":
+            result = self.call(params.get("name"), params.get("arguments"))
+        elif mid is None:
+            return None   # a notification (initialized, cancelled...): nothing to answer
+        else:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"Method not found: {method}"}}
+        return None if mid is None else {"jsonrpc": "2.0", "id": mid, "result": result}
+
+    def serve(self, stdin=None):
+        for line in (stdin or sys.stdin):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                reply = {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}}
+            else:
+                reply = self.handle(msg) if isinstance(msg, dict) else \
+                    {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "Invalid request"}}
+            if reply is not None:
+                self.out.write(json.dumps(reply, ensure_ascii=False) + "\n")
+                self.out.flush()
+
+
+def main():
+    """The wallras-mcp command (pip install git+https://github.com/wallras/wallras-python, or
+    uvx --from git+https://github.com/wallras/wallras-python wallras-mcp)."""
+    unknown = [a for a in sys.argv[1:] if a not in ("--enable-writes", "--help", "-h")]
+    if unknown or any(a in ("--help", "-h") for a in sys.argv[1:]):
+        sys.stderr.write(__doc__)
+        sys.exit(2 if unknown else 0)
+    Server(enable_writes="--enable-writes" in sys.argv[1:]).serve()
+
+
+if __name__ == "__main__":
+    main()

wallras_sdk.py

@@ -0,0 +1,263 @@
+"""Wallras SDK: send a self-hosted model's internal signals to Wallras (inside-out mode).
+
+No dependencies. Reports are sent in the background by default, so they never slow your app,
+and a failure to report never raises into your code.
+
+    from wallras_sdk import Wallras
+    w = Wallras("http://localhost:8080", token="your WALLRAS_APP_TOKEN")
+
+    # Hugging Face transformers
+    out = model.generate(**inputs, max_new_tokens=256, output_logits=True, output_scores=True,
+                         return_dict_in_generate=True)
+    w.report_transformers(out, inputs["input_ids"].shape[1], tokenizer, model="llama-3.1-8b", prompt=prompt)
+
+    # Any runtime that returns OpenAI-style logprobs (vLLM, llama.cpp server, Ollama...)
+    w.report(model="llama-3.1-8b", prompt=prompt, answer=text,
+             tokens=Wallras.tokens_from_openai(response["choices"][0]["logprobs"]["content"]))
+
+    # Your own probe on hidden states (0 = the model doesn't believe it, 1 = it does)
+    w.report(model="...", answer=text, probe_score=0.31)
+
+    # A request that already went through the Wallras proxy: attach to it
+    w.report(event_id=resp.headers["X-Wallras-Event-Id"], tokens=tokens)
+
+    # Decision record: how a self-hosted model reached its answer, read from the network itself
+    out = model.generate(**inputs, max_new_tokens=128, return_dict_in_generate=True, output_logits=True,
+                         output_hidden_states=True, output_attentions=True)   # load with attn_implementation="eager"
+    w.explain_transformers(model, tokenizer, inputs, out, model_name="llama-3.1-8b", prompt=prompt)
+
+    # Agent traces: report steps Wallras can't see (tool runs, lookups, API calls) into the
+    # same run as your model calls (send X-Wallras-Trace: run_id on those calls too).
+    with w.step(run_id, "search_flights", kind="api"):
+        results = search(...)   # timed; an exception is recorded as a failed step and re-raised
+
+    # Prompt management: fetch the version labelled production, with variables filled in. Send
+    # p["header"] with the model call so the request is filed under that version.
+    p = w.prompt("support-agent", customer="Asha", fallback={"messages": [...]})
+    client.chat.completions.create(model=p["model"] or "gpt-5-mini", messages=p["messages"],
+                                   extra_headers=p["header"])
+"""
+import contextlib
+import json
+import threading
+import time
+import urllib.request
+
+__all__ = ["Wallras"]
+
+
+class Wallras:
+    def __init__(self, url="http://localhost:8080", token=None, timeout=5.0, background=True):
+        if not str(url).lower().startswith(("http://", "https://")):
+            raise ValueError("Wallras url must start with http:// or https://")   # never file:// or other schemes
+        self.url = url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.background = background
+        self._prompts = {}
+
+    # ------------------------------------------------------------ prompts
+
+    def prompt(self, name, label="production", version=None, cache_seconds=60, fallback=None, **variables):
+        """The messages for a saved prompt, with variables filled in. Cached for cache_seconds. If Wallras
+        can't be reached, the last good copy is used, then `fallback` (a dict with "messages"), so an
+        outage never stops your app; with neither, it raises RuntimeError."""
+        q = {"label": label} if version is None else {"version": str(int(version))}
+        q.update({f"var.{k}": str(v) for k, v in variables.items()})
+        key = (name, tuple(sorted(q.items())))
+        hit = self._prompts.get(key)
+        if hit and time.time() - hit[0] < cache_seconds:
+            return hit[1]
+        path = f"/wallras/prompts/{urllib.request.quote(str(name), safe='')}/resolve?" + \
+            "&".join(f"{urllib.request.quote(k, safe='.')}={urllib.request.quote(v, safe='')}" for k, v in q.items())
+        req = urllib.request.Request(f"{self.url}{path}",
+                                     headers={**({"x-wallras-token": self.token} if self.token else {})})
+        try:
+            # Reviewed: only http(s) URLs reach here (checked in __init__).
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:  # nosemgrep # nosec B310
+                got = json.loads(r.read())
+            self._prompts[key] = (time.time(), got)
+            return got
+        except Exception as exc:
+            if hit:
+                return hit[1]
+            if fallback is not None:
+                return {"name": name, "version": None, "model": None, "params": {}, "header": {}, **fallback}
+            raise RuntimeError(f"Wallras prompt {name!r} unavailable ({type(exc).__name__}) and no fallback given")
+
+    # ------------------------------------------------------------ converters
+
+    @staticmethod
+    def tokens_from_openai(content):
+        """OpenAI-style `logprobs.content` list -> Wallras token list."""
+        out = []
+        for t in content or []:
+            if not isinstance(t, dict) or "logprob" not in t:
+                continue
+            alts = [x for x in t.get("top_logprobs") or [] if isinstance(x, dict) and "logprob" in x]
+            out.append({"logprob": float(t["logprob"]), "text": t.get("token", ""),
+                        "top": [float(x["logprob"]) for x in alts],
+                        "alts": [[x.get("token", ""), float(x["logprob"])] for x in alts]})
+        return out
+
+    @staticmethod
+    def tokens_from_steps(step_logprobs, chosen_ids, top_k=5):
+        """Per generated token: the full log-probability vector (any sequence of floats) and the
+        id that was chosen. Pure Python, so it works with lists from any framework."""
+        out = []
+        for row, tok in zip(step_logprobs, chosen_ids):
+            row = list(row)
+            top = sorted(row, reverse=True)[:top_k]
+            out.append({"logprob": float(row[int(tok)]), "top": [float(x) for x in top]})
+        return out
+
+    def report_transformers(self, generate_output, prompt_length, tokenizer=None, top_k=5, **kw):
+        """`model.generate(..., output_logits=True, return_dict_in_generate=True)` output, for
+        decoder-only models, first sequence of the batch.
+
+        Uses the raw logits when present (transformers 4.38+). `scores` are reshaped by sampling
+        settings: temperature, top-k and top-p all change them, which would misstate how sure the
+        model really was. Without raw logits, report with greedy decoding for accurate numbers."""
+        seq = generate_output.sequences[0][prompt_length:]
+        steps = getattr(generate_output, "logits", None) or generate_output.scores
+        tokens = []
+        for step, tok in zip(steps, seq):
+            lp = step[0].float().log_softmax(-1)
+            tokens.append({"logprob": float(lp[int(tok)]), "top": [float(x) for x in lp.topk(top_k).values.tolist()]})
+        if tokenizer is not None and "answer" not in kw:
+            kw["answer"] = tokenizer.decode(seq, skip_special_tokens=True)
+        return self.report(tokens=tokens, **kw)
+
+    def explain_transformers(self, model, tokenizer, inputs, generate_output, *, model_name=None,
+                             prompt=None, event_id=None, top_k=5, layers=True, attention=True, **kw):
+        """Read how a Hugging Face model reached its answer and send a decision record.
+
+        Call model.generate(..., return_dict_in_generate=True, output_logits=True,
+        output_hidden_states=True, output_attentions=True). Attention weights need the model
+        loaded with attn_implementation="eager". Decoder-only models, first sequence of the batch.
+        Per generated token it records: the token, its probability and the top alternatives
+        (from raw logits, so sampling settings don't distort them), the layer from which the
+        network kept it as its top choice (logit lens: each layer's hidden state through the
+        final norm and output head), and the prompt tokens the last layer attended to most."""
+        import torch  # only needed here
+        ids = inputs["input_ids"]
+        plen = ids.shape[1]
+        seq = generate_output.sequences[0][plen:]
+        steps = getattr(generate_output, "logits", None) or generate_output.scores
+        hidden = getattr(generate_output, "hidden_states", None) if layers else None
+        attns = getattr(generate_output, "attentions", None) if attention else None
+        head = model.get_output_embeddings()
+        norm = _final_norm(model)
+        dec = lambda t: tokenizer.decode([int(t)])
+        tokens, n_layers = [], None
+        if not bool(torch.isfinite(steps[0][0]).any()):
+            # Usually a half-precision model running on CPU: load it with torch_dtype=torch.float32.
+            return {"recorded": False, "error": "the model's outputs are NaN or infinite; nothing to explain"}
+        with torch.no_grad():
+            for i, (step, tok) in enumerate(zip(steps, seq)):
+                tok = int(tok)
+                lp = step[0].float().log_softmax(-1)
+                top = lp.topk(top_k)
+                rec = {"text": dec(tok), "logprob": _finite(lp[tok]),
+                       "top": [v for v in (_finite(x) for x in top.values.tolist()) if v is not None],
+                       "alts": [[dec(j), _finite(v)] for v, j in zip(top.values.tolist(), top.indices.tolist())
+                                if _finite(v) is not None]}
+                if hidden is not None and i < len(hidden) and head is not None:
+                    states = hidden[i][1:]          # skip the embedding layer
+                    n_layers = len(states)
+                    picks = []
+                    for li, h in enumerate(states):
+                        x = h[0, -1]
+                        if norm is not None and li < n_layers - 1:  # the last layer is already normed
+                            x = norm(x)
+                        picks.append(int(head(x.to(head.weight.dtype)).argmax()))
+                    settle = n_layers
+                    for li in range(n_layers - 1, -1, -1):
+                        if picks[li] != tok:
+                            break
+                        settle = li + 1
+                    rec["layer"] = settle if picks[-1] == tok else n_layers
+                if attns is not None and i < len(attns) and attns[i]:
+                    a = attns[i][-1][0].float().mean(0)[-1][:plen]   # last layer, heads averaged
+                    if bool(torch.isfinite(a).all()) and a.sum() > 0:
+                        a = a / a.sum()
+                        w, j = a.topk(min(3, plen))
+                        rec["attn"] = [[int(x), float(y)] for x, y in zip(j.tolist(), w.tolist())]
+                tokens.append(rec)
+        prompt_tokens = [dec(t) for t in ids[0].tolist()] if attns is not None else None
+        answer = tokenizer.decode(seq, skip_special_tokens=True)
+        return self.report(tokens=tokens, model=model_name, answer=kw.pop("answer", answer),
+                           prompt=prompt, event_id=event_id, prompt_tokens=prompt_tokens,
+                           layers=n_layers, **kw)
+
+    # ------------------------------------------------------------ sending
+
+    def report(self, *, model=None, answer=None, prompt=None, event_id=None, tokens=None,
+               probe_score=None, topic=None, prompt_tokens=None, layers=None, reasoning=None):
+        body = {k: v for k, v in {"model": model, "answer": answer, "prompt": prompt, "event_id": event_id,
+                                  "tokens": tokens or [], "probe_score": probe_score, "topic": topic,
+                                  "prompt_tokens": prompt_tokens, "layers": layers,
+                                  "reasoning": reasoning}.items()
+                if v is not None}
+        if self.background:
+            threading.Thread(target=self._send, args=(body,), daemon=True).start()
+            return None
+        return self._send(body)
+
+    @contextlib.contextmanager
+    def step(self, trace_id, name, kind="tool"):
+        """Time a step of an agent run and report it. Only the name, kind, timing, outcome and
+        error type are sent, never inputs or outputs."""
+        started, status, error = time.time(), "ok", None
+        try:
+            yield
+        except BaseException as exc:
+            status, error = "error", type(exc).__name__
+            raise
+        finally:
+            body = {"name": str(name)[:80], "kind": kind, "started": started, "status": status,
+                    "duration_ms": round((time.time() - started) * 1000, 1),
+                    **({"error": error} if error else {})}
+            path = f"/wallras/traces/{urllib.request.quote(str(trace_id), safe='')}/steps"
+            if self.background:
+                threading.Thread(target=self._send, args=(body, path), daemon=True).start()
+            else:
+                self._send(body, path)
+
+    def _send(self, body, path="/wallras/internals"):
+        try:  # never send NaN or infinity: the server would reject the whole report
+            data = json.dumps(body, allow_nan=False).encode()
+        except ValueError:
+            return {"recorded": False, "error": "report contained NaN or infinite numbers"}
+        req = urllib.request.Request(f"{self.url}{path}", data=data,
+                                     headers={"content-type": "application/json",
+                                              **({"x-wallras-token": self.token} if self.token else {})})
+        try:
+            # Reviewed: only http(s) URLs reach here (checked in __init__).
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:  # nosemgrep # nosec B310
+                return json.loads(r.read() or b"{}")
+        except Exception as exc:  # monitoring must never break your app
+            return {"recorded": False, "error": type(exc).__name__}
+
+
+def _final_norm(model):
+    """The norm applied before the output head, for the logit lens. None if not found."""
+    for path in ("model.norm", "transformer.ln_f", "gpt_neox.final_layer_norm", "model.decoder.final_layer_norm",
+                 "transformer.norm_f", "backbone.norm_f"):
+        obj = model
+        for part in path.split("."):
+            obj = getattr(obj, part, None)
+            if obj is None:
+                break
+        if obj is not None:
+            return obj
+    return None
+
+
+def _finite(x):
+    """A plain float, or None for NaN and infinity (from broken or half-precision models)."""
+    try:
+        f = float(x)
+    except (TypeError, ValueError):
+        return None
+    return f if f == f and f not in (float("inf"), float("-inf")) else None