tracerazor 0.1.0__tar.gz

tracerazor-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tracerazor
+Version: 0.1.0
+Summary: TraceRazor Python SDK — token efficiency auditing for AI agents
+Author: Zulfaqar Hafez
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Repository, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Issues, https://github.com/ZulfaqarHafez/tracerazor/issues
+Keywords: ai,agents,llm,token-efficiency,observability,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: http
+Requires-Dist: requests>=2.28; extra == "http"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+
+# tracerazor
+
+Python SDK for [TraceRazor](../../README.md) — token efficiency auditing for AI agents.
+
+Works with any Python agent: OpenAI, Anthropic, LangGraph, CrewAI, AutoGen, or raw code.
+
+## Install
+
+```bash
+pip install tracerazor
+```
+
+Requires the `tracerazor` binary to be built and accessible. Either:
+
+```bash
+# Option A: build from source (one-time)
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+
+# Option B: use HTTP mode against a running server (no binary on client)
+# docker compose up  (in the TraceRazor repo)
+```
+
+## Quickstart
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(agent_name="my-agent", framework="openai")
+
+# After each LLM call, record the reasoning step:
+tracer.reasoning(
+    content=llm_response.text,
+    tokens=llm_response.usage.total_tokens,
+    input_context=prompt,  # optional, improves CCE detection
+)
+
+# After each tool call:
+tracer.tool(
+    name="get_order_details",
+    params={"order_id": "ORD-9182"},
+    output=tool_result,
+    success=True,
+    tokens=120,
+)
+
+# After the agent finishes:
+report = tracer.analyse()
+print(report.summary())
+# → TAS 74.3/100 [Good] | 6 steps, 3200 tokens | Saved 1100 tokens (34%)
+
+print(report.markdown())  # full formatted report
+report.assert_passes()    # raises AssertionError if TAS < threshold (CI use)
+```
+
+## HTTP mode
+
+If you'd rather not put the binary on every machine, run the server once and POST from anywhere:
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(
+    agent_name="my-agent",
+    server="http://localhost:8080",  # tracerazor-server URL
+)
+# Record steps the same way, then:
+report = tracer.analyse()
+```
+
+Install with HTTP support:
+
+```bash
+pip install tracerazor[http]
+```
+
+## Context manager
+
+```python
+with Tracer(agent_name="my-agent") as t:
+    t.reasoning("...", tokens=500)
+    t.tool("search", params={}, output="...", success=True, tokens=100)
+
+report = t.analyse()
+```
+
+## API
+
+### `Tracer(agent_name, framework, threshold, task_value_score, bin_path, server)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | required | shown in reports and used for baseline tracking |
+| `framework` | `"custom"` | any string: `"openai"`, `"anthropic"`, `"crewai"`, etc. |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1), update with `set_task_value()` |
+| `bin_path` | auto | path to `tracerazor` binary; falls back to `TRACERAZOR_BIN` env var |
+| `server` | `None` | if set, use HTTP mode |
+
+### `tracer.reasoning(content, tokens, input_context, output)`
+
+Record one LLM reasoning step. `input_context` is the full prompt — include it for accurate CCE bloat detection.
+
+### `tracer.tool(name, params, output, success, error, tokens, input_context)`
+
+Record one tool call. `success=False` triggers misfire detection (TCA) and auto-fix generation.
+
+### `tracer.set_task_value(score: float)`
+
+Update the task quality score after validating the agent's answer. Call before `analyse()`.
+
+### `tracer.analyse() → TraceRazorReport`
+
+Submit the trace and return the report.
+
+### `TraceRazorReport`
+
+| attribute | type | description |
+|---|---|---|
+| `tas_score` | `float` | 0–100 composite score |
+| `grade` | `str` | `Excellent`, `Good`, `Fair`, `Poor` |
+| `passes` | `bool` | `tas_score >= threshold` |
+| `savings` | `dict` | `tokens_saved`, `reduction_pct`, `monthly_savings_usd` |
+| `fixes` | `list` | auto-generated fix patches |
+| `anomalies` | `list` | z-score alerts vs. agent baseline (after 5+ runs) |
+| `metrics` | `dict` | raw per-metric scores (SRR, LDI, TCA, RDA, ISR, TUR, CCE, DBO) |
+| `.summary()` | method | one-line string |
+| `.markdown()` | method | full formatted report |
+| `.assert_passes()` | method | raises `AssertionError` if TAS < threshold |

tracerazor-0.1.0/README.md

@@ -0,0 +1,129 @@
+# tracerazor
+
+Python SDK for [TraceRazor](../../README.md) — token efficiency auditing for AI agents.
+
+Works with any Python agent: OpenAI, Anthropic, LangGraph, CrewAI, AutoGen, or raw code.
+
+## Install
+
+```bash
+pip install tracerazor
+```
+
+Requires the `tracerazor` binary to be built and accessible. Either:
+
+```bash
+# Option A: build from source (one-time)
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+
+# Option B: use HTTP mode against a running server (no binary on client)
+# docker compose up  (in the TraceRazor repo)
+```
+
+## Quickstart
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(agent_name="my-agent", framework="openai")
+
+# After each LLM call, record the reasoning step:
+tracer.reasoning(
+    content=llm_response.text,
+    tokens=llm_response.usage.total_tokens,
+    input_context=prompt,  # optional, improves CCE detection
+)
+
+# After each tool call:
+tracer.tool(
+    name="get_order_details",
+    params={"order_id": "ORD-9182"},
+    output=tool_result,
+    success=True,
+    tokens=120,
+)
+
+# After the agent finishes:
+report = tracer.analyse()
+print(report.summary())
+# → TAS 74.3/100 [Good] | 6 steps, 3200 tokens | Saved 1100 tokens (34%)
+
+print(report.markdown())  # full formatted report
+report.assert_passes()    # raises AssertionError if TAS < threshold (CI use)
+```
+
+## HTTP mode
+
+If you'd rather not put the binary on every machine, run the server once and POST from anywhere:
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(
+    agent_name="my-agent",
+    server="http://localhost:8080",  # tracerazor-server URL
+)
+# Record steps the same way, then:
+report = tracer.analyse()
+```
+
+Install with HTTP support:
+
+```bash
+pip install tracerazor[http]
+```
+
+## Context manager
+
+```python
+with Tracer(agent_name="my-agent") as t:
+    t.reasoning("...", tokens=500)
+    t.tool("search", params={}, output="...", success=True, tokens=100)
+
+report = t.analyse()
+```
+
+## API
+
+### `Tracer(agent_name, framework, threshold, task_value_score, bin_path, server)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | required | shown in reports and used for baseline tracking |
+| `framework` | `"custom"` | any string: `"openai"`, `"anthropic"`, `"crewai"`, etc. |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1), update with `set_task_value()` |
+| `bin_path` | auto | path to `tracerazor` binary; falls back to `TRACERAZOR_BIN` env var |
+| `server` | `None` | if set, use HTTP mode |
+
+### `tracer.reasoning(content, tokens, input_context, output)`
+
+Record one LLM reasoning step. `input_context` is the full prompt — include it for accurate CCE bloat detection.
+
+### `tracer.tool(name, params, output, success, error, tokens, input_context)`
+
+Record one tool call. `success=False` triggers misfire detection (TCA) and auto-fix generation.
+
+### `tracer.set_task_value(score: float)`
+
+Update the task quality score after validating the agent's answer. Call before `analyse()`.
+
+### `tracer.analyse() → TraceRazorReport`
+
+Submit the trace and return the report.
+
+### `TraceRazorReport`
+
+| attribute | type | description |
+|---|---|---|
+| `tas_score` | `float` | 0–100 composite score |
+| `grade` | `str` | `Excellent`, `Good`, `Fair`, `Poor` |
+| `passes` | `bool` | `tas_score >= threshold` |
+| `savings` | `dict` | `tokens_saved`, `reduction_pct`, `monthly_savings_usd` |
+| `fixes` | `list` | auto-generated fix patches |
+| `anomalies` | `list` | z-score alerts vs. agent baseline (after 5+ runs) |
+| `metrics` | `dict` | raw per-metric scores (SRR, LDI, TCA, RDA, ISR, TUR, CCE, DBO) |
+| `.summary()` | method | one-line string |
+| `.markdown()` | method | full formatted report |
+| `.assert_passes()` | method | raises `AssertionError` if TAS < threshold |

tracerazor-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tracerazor"
+version = "0.1.0"
+description = "TraceRazor Python SDK — token efficiency auditing for AI agents"
+authors = [{ name = "Zulfaqar Hafez" }]
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["ai", "agents", "llm", "token-efficiency", "observability", "tracing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ZulfaqarHafez/tracerazor"
+Repository = "https://github.com/ZulfaqarHafez/tracerazor"
+Issues = "https://github.com/ZulfaqarHafez/tracerazor/issues"
+
+[project.optional-dependencies]
+http = ["requests>=2.28"]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.20"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tracerazor_sdk*"]

tracerazor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tracerazor-0.1.0/tracerazor.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: tracerazor
+Version: 0.1.0
+Summary: TraceRazor Python SDK — token efficiency auditing for AI agents
+Author: Zulfaqar Hafez
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Repository, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Issues, https://github.com/ZulfaqarHafez/tracerazor/issues
+Keywords: ai,agents,llm,token-efficiency,observability,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: http
+Requires-Dist: requests>=2.28; extra == "http"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+
+# tracerazor
+
+Python SDK for [TraceRazor](../../README.md) — token efficiency auditing for AI agents.
+
+Works with any Python agent: OpenAI, Anthropic, LangGraph, CrewAI, AutoGen, or raw code.
+
+## Install
+
+```bash
+pip install tracerazor
+```
+
+Requires the `tracerazor` binary to be built and accessible. Either:
+
+```bash
+# Option A: build from source (one-time)
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+
+# Option B: use HTTP mode against a running server (no binary on client)
+# docker compose up  (in the TraceRazor repo)
+```
+
+## Quickstart
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(agent_name="my-agent", framework="openai")
+
+# After each LLM call, record the reasoning step:
+tracer.reasoning(
+    content=llm_response.text,
+    tokens=llm_response.usage.total_tokens,
+    input_context=prompt,  # optional, improves CCE detection
+)
+
+# After each tool call:
+tracer.tool(
+    name="get_order_details",
+    params={"order_id": "ORD-9182"},
+    output=tool_result,
+    success=True,
+    tokens=120,
+)
+
+# After the agent finishes:
+report = tracer.analyse()
+print(report.summary())
+# → TAS 74.3/100 [Good] | 6 steps, 3200 tokens | Saved 1100 tokens (34%)
+
+print(report.markdown())  # full formatted report
+report.assert_passes()    # raises AssertionError if TAS < threshold (CI use)
+```
+
+## HTTP mode
+
+If you'd rather not put the binary on every machine, run the server once and POST from anywhere:
+
+```python
+from tracerazor_sdk import Tracer
+
+tracer = Tracer(
+    agent_name="my-agent",
+    server="http://localhost:8080",  # tracerazor-server URL
+)
+# Record steps the same way, then:
+report = tracer.analyse()
+```
+
+Install with HTTP support:
+
+```bash
+pip install tracerazor[http]
+```
+
+## Context manager
+
+```python
+with Tracer(agent_name="my-agent") as t:
+    t.reasoning("...", tokens=500)
+    t.tool("search", params={}, output="...", success=True, tokens=100)
+
+report = t.analyse()
+```
+
+## API
+
+### `Tracer(agent_name, framework, threshold, task_value_score, bin_path, server)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | required | shown in reports and used for baseline tracking |
+| `framework` | `"custom"` | any string: `"openai"`, `"anthropic"`, `"crewai"`, etc. |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1), update with `set_task_value()` |
+| `bin_path` | auto | path to `tracerazor` binary; falls back to `TRACERAZOR_BIN` env var |
+| `server` | `None` | if set, use HTTP mode |
+
+### `tracer.reasoning(content, tokens, input_context, output)`
+
+Record one LLM reasoning step. `input_context` is the full prompt — include it for accurate CCE bloat detection.
+
+### `tracer.tool(name, params, output, success, error, tokens, input_context)`
+
+Record one tool call. `success=False` triggers misfire detection (TCA) and auto-fix generation.
+
+### `tracer.set_task_value(score: float)`
+
+Update the task quality score after validating the agent's answer. Call before `analyse()`.
+
+### `tracer.analyse() → TraceRazorReport`
+
+Submit the trace and return the report.
+
+### `TraceRazorReport`
+
+| attribute | type | description |
+|---|---|---|
+| `tas_score` | `float` | 0–100 composite score |
+| `grade` | `str` | `Excellent`, `Good`, `Fair`, `Poor` |
+| `passes` | `bool` | `tas_score >= threshold` |
+| `savings` | `dict` | `tokens_saved`, `reduction_pct`, `monthly_savings_usd` |
+| `fixes` | `list` | auto-generated fix patches |
+| `anomalies` | `list` | z-score alerts vs. agent baseline (after 5+ runs) |
+| `metrics` | `dict` | raw per-metric scores (SRR, LDI, TCA, RDA, ISR, TUR, CCE, DBO) |
+| `.summary()` | method | one-line string |
+| `.markdown()` | method | full formatted report |
+| `.assert_passes()` | method | raises `AssertionError` if TAS < threshold |

tracerazor-0.1.0/tracerazor.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+tracerazor.egg-info/PKG-INFO
+tracerazor.egg-info/SOURCES.txt
+tracerazor.egg-info/dependency_links.txt
+tracerazor.egg-info/requires.txt
+tracerazor.egg-info/top_level.txt
+tracerazor_sdk/__init__.py
+tracerazor_sdk/client.py
+tracerazor_sdk/trace.py
+tracerazor_sdk/tracer.py

tracerazor-0.1.0/tracerazor.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tracerazor-0.1.0/tracerazor.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[anthropic]
+anthropic>=0.20
+
+[http]
+requests>=2.28
+
+[openai]
+openai>=1.0

tracerazor-0.1.0/tracerazor.egg-info/top_level.txt

@@ -0,0 +1 @@
+tracerazor_sdk

tracerazor-0.1.0/tracerazor_sdk/__init__.py

@@ -0,0 +1,37 @@
+"""
+TraceRazor Python SDK — framework-agnostic token efficiency auditing.
+
+Works with any Python agent: OpenAI, Anthropic, CrewAI, AutoGen, or raw code.
+
+Two modes:
+  - CLI mode (default): calls the local tracerazor binary — no server needed.
+  - HTTP mode: POSTs to a running tracerazor-server — no binary needed.
+
+Quickstart (CLI mode):
+    from tracerazor_sdk import Tracer
+
+    with Tracer(agent_name="my-agent") as t:
+        response = llm.invoke(prompt)
+        t.reasoning(response.text, tokens=response.usage.total_tokens)
+
+        result = my_tool(arg)
+        t.tool("my_tool", params={"arg": arg}, output=result, success=True, tokens=120)
+
+    report = t.analyse()
+    print(report.summary())
+
+Quickstart (HTTP mode):
+    from tracerazor_sdk import Tracer
+
+    with Tracer(agent_name="my-agent", server="http://localhost:8080") as t:
+        ...
+
+    report = t.analyse()
+"""
+
+from .tracer import Tracer
+from .client import TraceRazorClient, TraceRazorReport
+from .trace import TraceStep
+
+__all__ = ["Tracer", "TraceRazorClient", "TraceRazorReport", "TraceStep"]
+__version__ = "0.1.0"

tracerazor-0.1.0/tracerazor_sdk/client.py

@@ -0,0 +1,264 @@
+"""
+TraceRazor client — CLI subprocess mode and HTTP mode.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class TraceRazorReport:
+    """Parsed result of a tracerazor audit."""
+
+    trace_id: str
+    agent_name: str
+    framework: str
+    total_steps: int
+    total_tokens: int
+    tas_score: float
+    grade: str
+    passes: bool
+    threshold: float
+    metrics: Dict[str, Any] = field(default_factory=dict)
+    savings: Dict[str, Any] = field(default_factory=dict)
+    fixes: List[Dict] = field(default_factory=list)
+    anomalies: List[Dict] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def summary(self) -> str:
+        """One-line summary."""
+        saved = self.savings.get("tokens_saved", 0)
+        pct = self.savings.get("reduction_pct", 0.0)
+        return (
+            f"TAS {self.tas_score:.1f}/100 [{self.grade}] | "
+            f"{self.total_steps} steps, {self.total_tokens} tokens | "
+            f"Saved {saved} tokens ({pct:.0f}%)"
+        )
+
+    def markdown(self) -> str:
+        """Full markdown report (same as CLI output)."""
+        return self.raw.get("report_markdown") or self._build_markdown()
+
+    def _build_markdown(self) -> str:
+        sep = "-" * 54
+        s = self.metrics
+        lines = [
+            "TRACERAZOR REPORT",
+            sep,
+            f"Trace:   {self.trace_id}",
+            f"Agent:   {self.agent_name}",
+            f"Steps:   {self.total_steps}   Tokens: {self.total_tokens}",
+            sep,
+            f"TRACERAZOR SCORE:  {self.tas_score:.0f} / 100  [{self.grade.upper()}]",
+            sep,
+        ]
+        for code in ("srr", "ldi", "tca", "rda", "isr", "tur", "cce", "dbo"):
+            m = s.get(code, {})
+            if m:
+                status = "PASS" if m.get("pass") else "FAIL"
+                lines.append(f"{code.upper():<6} {m.get('score', 0):.3f}   {status}")
+        if self.savings:
+            lines += [
+                sep,
+                "SAVINGS ESTIMATE",
+                f"  Tokens saved:  {self.savings.get('tokens_saved', 0)}  "
+                f"({self.savings.get('reduction_pct', 0):.1f}% reduction)",
+                f"  Cost saved:    ${self.savings.get('cost_saved_per_run_usd', 0):.4f}/run",
+                f"  At 50K/month:  ${self.savings.get('monthly_savings_usd', 0):.2f}/month",
+            ]
+        if self.fixes:
+            lines += [sep, "AUTO-GENERATED FIXES"]
+            for i, fix in enumerate(self.fixes, 1):
+                lines.append(
+                    f"  Fix {i}: [{fix.get('fix_type')}] → {fix.get('target')}\n"
+                    f"    Patch: {fix.get('patch', '')[:120]}\n"
+                    f"    Est. savings: {fix.get('estimated_token_savings', 0)} tokens/run"
+                )
+        if self.anomalies:
+            lines += [sep, "ANOMALY ALERTS"]
+            for a in self.anomalies:
+                direction = "REGRESSION" if a.get("z_score", 0) < 0 else "IMPROVEMENT"
+                lines.append(
+                    f"  [{direction}] {a.get('metric')}: {a.get('value'):.1f} "
+                    f"(z={a.get('z_score'):.1f})"
+                )
+        lines.append(sep)
+        return "\n".join(lines)
+
+    def assert_passes(self) -> None:
+        """Raise AssertionError if TAS is below threshold. Use in CI/CD."""
+        if not self.passes:
+            raise AssertionError(
+                f"TraceRazor: TAS {self.tas_score:.1f} is below "
+                f"threshold {self.threshold}.\n\n{self.summary()}"
+            )
+
+
+class TraceRazorClient:
+    """
+    Submit a trace for analysis.
+
+    CLI mode (default): calls the local tracerazor binary.
+      - No server needed.
+      - Requires the binary to be built or installed.
+
+    HTTP mode: POSTs to a running tracerazor-server.
+      - No binary needed on the machine running your agent.
+      - Start the server once: ./tracerazor-server
+
+    Args:
+        bin_path:  Path to the tracerazor binary. Auto-detected if None.
+                   Ignored when `server` is set.
+        server:    Base URL of a running tracerazor-server, e.g.
+                   "http://localhost:8080". When set, HTTP mode is used.
+        threshold: Minimum TAS score for assert_passes() (default 70).
+    """
+
+    def __init__(
+        self,
+        bin_path: Optional[str] = None,
+        server: Optional[str] = None,
+        threshold: float = 70.0,
+    ):
+        self._server = server.rstrip("/") if server else None
+        self._bin = None if self._server else (bin_path or self._find_binary())
+        self._threshold = threshold
+
+    def analyse(self, trace: Dict[str, Any]) -> TraceRazorReport:
+        """Submit the trace and return a TraceRazorReport."""
+        if self._server:
+            return self._analyse_http(trace)
+        return self._analyse_cli(trace)
+
+    # ── CLI mode ──────────────────────────────────────────────────────────────
+
+    def _analyse_cli(self, trace: Dict[str, Any]) -> TraceRazorReport:
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", delete=False, encoding="utf-8"
+        ) as f:
+            json.dump(trace, f, indent=2)
+            tmp_path = f.name
+
+        try:
+            result = subprocess.run(
+                [
+                    self._bin,
+                    "audit",
+                    tmp_path,
+                    "--format", "json",
+                    "--threshold", str(self._threshold),
+                ],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            # Exit code 1 = below threshold (still valid JSON output).
+            if result.returncode not in (0, 1):
+                raise RuntimeError(
+                    f"tracerazor exited with code {result.returncode}:\n{result.stderr}"
+                )
+            data = json.loads(result.stdout)
+            return self._parse_cli_report(data)
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+
+    def _parse_cli_report(self, data: Dict[str, Any]) -> TraceRazorReport:
+        score = data.get("score", {})
+        tas = score.get("score", 0.0)
+        return TraceRazorReport(
+            trace_id=data.get("trace_id", ""),
+            agent_name=data.get("agent_name", ""),
+            framework=data.get("framework", ""),
+            total_steps=data.get("total_steps", 0),
+            total_tokens=data.get("total_tokens", 0),
+            tas_score=tas,
+            grade=str(score.get("grade", "Unknown")),
+            passes=tas >= self._threshold,
+            threshold=self._threshold,
+            metrics=score,
+            savings=data.get("savings", {}),
+            fixes=data.get("fixes", []),
+            anomalies=data.get("anomalies", []),
+            raw=data,
+        )
+
+    # ── HTTP mode ─────────────────────────────────────────────────────────────
+
+    def _analyse_http(self, trace: Dict[str, Any]) -> TraceRazorReport:
+        try:
+            import requests
+        except ImportError:
+            raise ImportError(
+                "HTTP mode requires the 'requests' library.\n"
+                "Install with: pip install tracerazor[http]"
+            )
+
+        resp = requests.post(
+            f"{self._server}/api/audit",
+            json={"trace": trace},
+            timeout=60,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return self._parse_http_report(data)
+
+    def _parse_http_report(self, data: Dict[str, Any]) -> TraceRazorReport:
+        tas = data.get("tas_score", 0.0)
+        return TraceRazorReport(
+            trace_id=data.get("trace_id", ""),
+            agent_name=data.get("agent_name", ""),
+            framework=data.get("framework", ""),
+            total_steps=0,   # not in HTTP response top-level
+            total_tokens=0,
+            tas_score=tas,
+            grade=data.get("grade", "Unknown"),
+            passes=tas >= self._threshold,
+            threshold=self._threshold,
+            metrics={},
+            savings={},
+            fixes=[],
+            anomalies=data.get("anomalies", []),
+            raw=data,
+        )
+
+    # ── Binary discovery ──────────────────────────────────────────────────────
+
+    @staticmethod
+    def _find_binary() -> str:
+        env_path = os.environ.get("TRACERAZOR_BIN")
+        if env_path and os.path.isfile(env_path):
+            return env_path
+
+        found = shutil.which("tracerazor") or shutil.which("tracerazor.exe")
+        if found:
+            return found
+
+        # Dev layout: integrations/tracerazor/tracerazor_sdk/ → ../../../target/release/
+        here = os.path.dirname(os.path.abspath(__file__))
+        for rel in [
+            "../../../../target/release/tracerazor.exe",
+            "../../../../target/release/tracerazor",
+            "../../../../target/debug/tracerazor.exe",
+            "../../../../target/debug/tracerazor",
+        ]:
+            candidate = os.path.normpath(os.path.join(here, rel))
+            if os.path.isfile(candidate):
+                return candidate
+
+        raise FileNotFoundError(
+            "tracerazor binary not found.\n"
+            "Options:\n"
+            "  1. Set TRACERAZOR_BIN=/path/to/tracerazor\n"
+            "  2. Build from source: cargo build --release\n"
+            "  3. Use HTTP mode: Tracer(server='http://localhost:8080')"
+        )

tracerazor-0.1.0/tracerazor_sdk/trace.py

@@ -0,0 +1,68 @@
+"""
+Lightweight trace data structures. No external dependencies.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class TraceStep:
+    id: int
+    type: str                          # "reasoning" or "tool_call"
+    content: str
+    tokens: int
+    tool_name: Optional[str] = None
+    tool_params: Optional[Dict[str, Any]] = None
+    tool_success: Optional[bool] = None
+    tool_error: Optional[str] = None
+    input_context: Optional[str] = None
+    output: Optional[str] = None
+    agent_id: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "id": self.id,
+            "type": self.type,
+            "content": self.content,
+            "tokens": self.tokens,
+        }
+        if self.tool_name is not None:
+            d["tool_name"] = self.tool_name
+        if self.tool_params is not None:
+            d["tool_params"] = self.tool_params
+        if self.tool_success is not None:
+            d["tool_success"] = self.tool_success
+        if self.tool_error is not None:
+            d["tool_error"] = self.tool_error
+        if self.input_context is not None:
+            d["input_context"] = self.input_context
+        if self.output is not None:
+            d["output"] = self.output
+        if self.agent_id is not None:
+            d["agent_id"] = self.agent_id
+        return d
+
+
+@dataclass
+class Trace:
+    agent_name: str
+    framework: str
+    task_value_score: float = 1.0
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    steps: List[TraceStep] = field(default_factory=list)
+
+    def add_step(self, step: TraceStep) -> None:
+        self.steps.append(step)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "trace_id": self.trace_id,
+            "agent_name": self.agent_name,
+            "framework": self.framework,
+            "task_value_score": self.task_value_score,
+            "steps": [s.to_dict() for s in self.steps],
+        }

tracerazor-0.1.0/tracerazor_sdk/tracer.py

@@ -0,0 +1,180 @@
+"""
+Tracer — the main entry point for manual instrumentation.
+
+Use as a context manager or call step methods directly.
+
+Example:
+    from tracerazor_sdk import Tracer
+
+    with Tracer(agent_name="my-agent") as t:
+        # After each LLM call:
+        t.reasoning("model output text", tokens=820, input_context="full prompt")
+
+        # After each tool call:
+        t.tool("search_web", params={"q": "..."}, output="results", success=True, tokens=200)
+
+    report = t.analyse()
+    print(report.summary())
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .client import TraceRazorClient, TraceRazorReport
+from .trace import Trace, TraceStep
+
+
+class Tracer:
+    """
+    Manual instrumentation wrapper. Records reasoning steps and tool calls,
+    then submits the trace for analysis.
+
+    Args:
+        agent_name:        Name of the agent (appears in all reports).
+        framework:         Framework identifier, e.g. "openai", "anthropic",
+                           "crewai", "autogen", "custom".
+        threshold:         Minimum TAS score for assert_passes() (default 70).
+        task_value_score:  Quality of the final answer (0.0–1.0). Update via
+                           set_task_value() after ground-truth validation.
+        bin_path:          Path to tracerazor binary (CLI mode). Auto-detected.
+        server:            URL of tracerazor-server (HTTP mode). When set,
+                           bin_path is ignored.
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        framework: str = "custom",
+        threshold: float = 70.0,
+        task_value_score: float = 1.0,
+        bin_path: Optional[str] = None,
+        server: Optional[str] = None,
+    ):
+        self._trace = Trace(
+            agent_name=agent_name,
+            framework=framework,
+            task_value_score=task_value_score,
+        )
+        self._client = TraceRazorClient(
+            bin_path=bin_path,
+            server=server,
+            threshold=threshold,
+        )
+        self._report: Optional[TraceRazorReport] = None
+
+    # ── Context manager ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> "Tracer":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        # Don't auto-analyse on exception — the trace may be incomplete.
+        pass
+
+    # ── Step recording ────────────────────────────────────────────────────────
+
+    def reasoning(
+        self,
+        content: str,
+        tokens: int,
+        input_context: Optional[str] = None,
+        output: Optional[str] = None,
+    ) -> None:
+        """
+        Record one LLM reasoning step.
+
+        Args:
+            content:       The model's output text (or a summary of it).
+            tokens:        Total token count for this LLM call.
+            input_context: The full prompt sent to the LLM (optional but
+                           improves CCE and SRR accuracy).
+            output:        The model's raw output (optional).
+        """
+        step = TraceStep(
+            id=len(self._trace.steps) + 1,
+            type="reasoning",
+            content=content[:500],
+            tokens=max(tokens, 1),
+            input_context=input_context,
+            output=output,
+        )
+        self._trace.add_step(step)
+
+    def tool(
+        self,
+        name: str,
+        params: Optional[Dict[str, Any]] = None,
+        output: Optional[str] = None,
+        success: bool = True,
+        error: Optional[str] = None,
+        tokens: int = 0,
+        input_context: Optional[str] = None,
+    ) -> None:
+        """
+        Record one tool call step.
+
+        Args:
+            name:     Tool name (e.g. "search_web", "get_order_details").
+            params:   Dict of parameters passed to the tool.
+            output:   String output returned by the tool.
+            success:  False if the tool raised an error or returned a failure.
+                      Setting this accurately enables TCA misfire detection.
+            error:    Error message if success=False.
+            tokens:   Token count. If unknown, omit and a rough estimate is used.
+            input_context: The LLM input that triggered this tool call.
+        """
+        estimated = tokens or self._estimate_tool_tokens(params, output)
+        step = TraceStep(
+            id=len(self._trace.steps) + 1,
+            type="tool_call",
+            content=f"Calling {name}",
+            tokens=max(estimated, 1),
+            tool_name=name,
+            tool_params=params,
+            tool_success=success,
+            tool_error=error if not success else None,
+            output=output,
+            input_context=input_context,
+        )
+        self._trace.add_step(step)
+
+    def set_task_value(self, score: float) -> None:
+        """
+        Set the task value score (0.0–1.0) based on outcome quality.
+        Call this after you have validated the agent's answer.
+        1.0 = correct answer, 0.0 = wrong answer.
+        """
+        self._trace.task_value_score = max(0.0, min(1.0, score))
+
+    # ── Analysis ──────────────────────────────────────────────────────────────
+
+    def analyse(self) -> TraceRazorReport:
+        """
+        Submit the collected trace for analysis and return the report.
+        Call this after your agent finishes.
+        """
+        self._report = self._client.analyse(self._trace.to_dict())
+        return self._report
+
+    def assert_passes(self) -> None:
+        """Analyse (if not done) and raise AssertionError if TAS < threshold."""
+        if self._report is None:
+            self.analyse()
+        assert self._report is not None
+        self._report.assert_passes()
+
+    @property
+    def report(self) -> Optional[TraceRazorReport]:
+        """The most recent report, or None if analyse() hasn't been called."""
+        return self._report
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _estimate_tool_tokens(
+        params: Optional[Dict], output: Optional[str]
+    ) -> int:
+        param_chars = len(str(params)) if params else 0
+        output_chars = len(output) if output else 0
+        return max(int((param_chars + output_chars) / 4), 10)