tracerazor-langgraph 0.1.0__tar.gz

tracerazor_langgraph-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: tracerazor-langgraph
+Version: 0.1.0
+Summary: TraceRazor LangGraph/LangChain callback — token efficiency auditing
+Author: Zulfaqar Hafez
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Repository, https://github.com/ZulfaqarHafez/tracerazor
+Keywords: ai,agents,langgraph,langchain,token-efficiency,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
+Requires-Dist: langchain-core>=0.2
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Dynamic: requires-python
+
+# tracerazor-langgraph
+
+LangGraph/LangChain callback adapter for [TraceRazor](../../README.md).
+
+Automatically captures every LLM call and tool call from your LangGraph graph with zero manual instrumentation.
+
+## Install
+
+```bash
+pip install tracerazor-langgraph
+pip install tracerazor-langgraph[langgraph]  # includes langgraph
+```
+
+Requires the `tracerazor` binary:
+
+```bash
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+```
+
+## Usage
+
+```python
+from tracerazor_langgraph import TraceRazorCallback
+from langgraph.prebuilt import create_react_agent
+from langchain_openai import ChatOpenAI
+
+callback = TraceRazorCallback(
+    agent_name="support-agent",
+    threshold=70,
+)
+
+model = ChatOpenAI(model="gpt-4o-mini")
+agent = create_react_agent(model, tools=[...])
+
+result = agent.invoke(
+    {"messages": [HumanMessage(content="I want a refund")]},
+    config={"callbacks": [callback]},
+)
+
+# After the agent finishes:
+report = callback.analyse()
+print(report.markdown())
+
+# CI/CD gate — raises AssertionError if TAS < threshold:
+callback.assert_passes()
+```
+
+## API
+
+### `TraceRazorCallback(agent_name, framework, threshold, task_value_score, tracerazor_bin)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | `"langgraph-agent"` | shown in all reports |
+| `framework` | `"langgraph"` | framework label |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1) |
+| `tracerazor_bin` | auto | path to binary; falls back to `TRACERAZOR_BIN` env var |
+
+### `callback.analyse() → TraceRazorReport`
+
+Finalise and submit the trace. Returns the report.
+
+### `callback.assert_passes()`
+
+Raise `AssertionError` if TAS < threshold.
+
+### `callback.set_task_value_score(score: float)`
+
+Update quality score before calling `analyse()`.

tracerazor_langgraph-0.1.0/README.md

@@ -0,0 +1,71 @@
+# tracerazor-langgraph
+
+LangGraph/LangChain callback adapter for [TraceRazor](../../README.md).
+
+Automatically captures every LLM call and tool call from your LangGraph graph with zero manual instrumentation.
+
+## Install
+
+```bash
+pip install tracerazor-langgraph
+pip install tracerazor-langgraph[langgraph]  # includes langgraph
+```
+
+Requires the `tracerazor` binary:
+
+```bash
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+```
+
+## Usage
+
+```python
+from tracerazor_langgraph import TraceRazorCallback
+from langgraph.prebuilt import create_react_agent
+from langchain_openai import ChatOpenAI
+
+callback = TraceRazorCallback(
+    agent_name="support-agent",
+    threshold=70,
+)
+
+model = ChatOpenAI(model="gpt-4o-mini")
+agent = create_react_agent(model, tools=[...])
+
+result = agent.invoke(
+    {"messages": [HumanMessage(content="I want a refund")]},
+    config={"callbacks": [callback]},
+)
+
+# After the agent finishes:
+report = callback.analyse()
+print(report.markdown())
+
+# CI/CD gate — raises AssertionError if TAS < threshold:
+callback.assert_passes()
+```
+
+## API
+
+### `TraceRazorCallback(agent_name, framework, threshold, task_value_score, tracerazor_bin)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | `"langgraph-agent"` | shown in all reports |
+| `framework` | `"langgraph"` | framework label |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1) |
+| `tracerazor_bin` | auto | path to binary; falls back to `TRACERAZOR_BIN` env var |
+
+### `callback.analyse() → TraceRazorReport`
+
+Finalise and submit the trace. Returns the report.
+
+### `callback.assert_passes()`
+
+Raise `AssertionError` if TAS < threshold.
+
+### `callback.set_task_value_score(score: float)`
+
+Update quality score before calling `analyse()`.

tracerazor_langgraph-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tracerazor-langgraph"
+version = "0.1.0"
+description = "TraceRazor LangGraph/LangChain callback — token efficiency auditing"
+authors = [{ name = "Zulfaqar Hafez" }]
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["ai", "agents", "langgraph", "langchain", "token-efficiency", "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 = [
+    "langchain-core>=0.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/ZulfaqarHafez/tracerazor"
+Repository = "https://github.com/ZulfaqarHafez/tracerazor"
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=0.2"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tracerazor_langgraph*"]

tracerazor_langgraph-0.1.0/setup.cfg

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

tracerazor_langgraph-0.1.0/setup.py

@@ -0,0 +1,18 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="tracerazor-langgraph",
+    version="0.1.0",
+    description="TraceRazor LangGraph callback adapter",
+    author="Zulfaqar Hafez",
+    license="Apache-2.0",
+    packages=find_packages(),
+    python_requires=">=3.10",
+    install_requires=[
+        "langchain-core>=0.2",
+    ],
+    extras_require={
+        "langgraph": ["langgraph>=0.2"],
+        "openai": ["openai>=1.0"],
+    },
+)

tracerazor_langgraph-0.1.0/tracerazor_langgraph/__init__.py

@@ -0,0 +1,26 @@
+"""
+TraceRazor LangGraph integration.
+
+Provides a BaseCallbackHandler that captures LangGraph/LangChain execution events
+and streams them into the TraceRazor auditor for real-time and post-hoc analysis.
+
+Usage:
+    from tracerazor_langgraph import TraceRazorCallback
+
+    callback = TraceRazorCallback(agent_name="my-agent", threshold=75)
+
+    result = graph.invoke(inputs, config={"callbacks": [callback]})
+
+    # Get the efficiency report after execution
+    report = callback.analyse()
+    print(report.markdown())
+
+    # Or check inline during CI/CD
+    callback.assert_passes()  # raises AssertionError if TAS < threshold
+"""
+
+from .callback import TraceRazorCallback
+from .client import TraceRazorClient, TraceRazorReport
+
+__all__ = ["TraceRazorCallback", "TraceRazorClient", "TraceRazorReport"]
+__version__ = "0.1.0"

tracerazor_langgraph-0.1.0/tracerazor_langgraph/callback.py

@@ -0,0 +1,177 @@
+"""
+TraceRazor LangGraph callback handler.
+
+Captures LangGraph/LangChain execution events and serialises them into
+TraceRazor's raw JSON trace format for analysis.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.outputs import LLMResult
+
+from .client import TraceRazorClient, TraceRazorReport
+from .trace_builder import TraceBuilder
+
+
+class TraceRazorCallback(BaseCallbackHandler):
+    """
+    LangGraph/LangChain callback that builds a TraceRazor trace from
+    execution events and submits it for analysis when the run completes.
+
+    Args:
+        agent_name: Name of the agent (appears in the report header).
+        framework:  Framework name (default: "langgraph").
+        threshold:  Minimum TAS score for assertion checks (default: 70).
+        semantic:   If True, enable OpenAI embedding-based analysis (Phase 2).
+                    Requires OPENAI_API_KEY in environment.
+        cost_per_million: Token cost in USD for savings estimates.
+        tracerazor_bin: Path to the tracerazor CLI binary. Auto-detected if None.
+        task_value_score: Quality of the final answer (0.0–1.0). Set this
+                         after the run if you have ground-truth validation.
+    """
+
+    def __init__(
+        self,
+        agent_name: str = "langgraph-agent",
+        framework: str = "langgraph",
+        threshold: float = 70.0,
+        tracerazor_bin: Optional[str] = None,
+        task_value_score: float = 1.0,
+    ):
+        super().__init__()
+        self._builder = TraceBuilder(
+            agent_name=agent_name,
+            framework=framework,
+            task_value_score=task_value_score,
+        )
+        self._threshold = threshold
+        self._client = TraceRazorClient(bin_path=tracerazor_bin)
+        self._report: Optional[TraceRazorReport] = None
+
+    # ── LLM events ──────────────────────────────────────────────────────────
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        **kwargs: Any,
+    ) -> None:
+        """Called when an LLM starts generating."""
+        context = prompts[0] if prompts else ""
+        self._builder.start_reasoning_step(input_context=context)
+
+    def on_llm_end(self, response: LLMResult, **kwargs: Any) -> None:
+        """Called when an LLM finishes generating."""
+        output_text = ""
+        total_tokens = 0
+
+        if response.generations:
+            first = response.generations[0]
+            if first:
+                output_text = getattr(first[0], "text", "") or ""
+
+        # Extract token usage from LLMResult metadata.
+        if response.llm_output:
+            usage = response.llm_output.get("usage", response.llm_output.get("token_usage", {}))
+            total_tokens = (
+                usage.get("total_tokens")
+                or usage.get("prompt_tokens", 0) + usage.get("completion_tokens", 0)
+            )
+
+        self._builder.end_reasoning_step(output=output_text, tokens=total_tokens)
+
+    def on_llm_error(self, error: Exception, **kwargs: Any) -> None:
+        self._builder.abort_current_step(error=str(error))
+
+    # ── Tool events ──────────────────────────────────────────────────────────
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        **kwargs: Any,
+    ) -> None:
+        """Called when a tool starts executing."""
+        tool_name = serialized.get("name", "unknown_tool")
+        try:
+            params = json.loads(input_str) if input_str.strip().startswith("{") else {"input": input_str}
+        except json.JSONDecodeError:
+            params = {"input": input_str}
+        self._builder.start_tool_step(tool_name=tool_name, tool_params=params)
+
+    def on_tool_end(self, output: str, **kwargs: Any) -> None:
+        """Called when a tool finishes successfully."""
+        self._builder.end_tool_step(output=output, success=True)
+
+    def on_tool_error(self, error: Exception, **kwargs: Any) -> None:
+        """Called when a tool raises an error."""
+        self._builder.end_tool_step(
+            output="",
+            success=False,
+            error=str(error),
+        )
+
+    # ── Chain events (LangGraph node transitions) ────────────────────────────
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        **kwargs: Any,
+    ) -> None:
+        """LangGraph node start — we use this for agent handoffs."""
+        node_name = serialized.get("name", "")
+        # Top-level chain start = beginning of the run; skip.
+        if node_name and node_name not in ("RunnableSequence", "AgentExecutor", "CompiledGraph"):
+            self._builder.note_agent_transition(node_name)
+
+    def on_chain_end(self, outputs: Dict[str, Any], **kwargs: Any) -> None:
+        pass
+
+    # ── Analysis ─────────────────────────────────────────────────────────────
+
+    def analyse(self) -> TraceRazorReport:
+        """
+        Finalise the trace and submit it to the TraceRazor CLI for analysis.
+        Returns a TraceRazorReport with the TAS score and full report.
+
+        Call this after your LangGraph invocation completes.
+        """
+        trace_dict = self._builder.build()
+        self._report = self._client.analyse(
+            trace=trace_dict,
+            threshold=self._threshold,
+        )
+        return self._report
+
+    def assert_passes(self) -> None:
+        """
+        Analyse the trace (if not already done) and raise AssertionError
+        if TAS is below threshold. Useful for CI/CD and test assertions.
+        """
+        if self._report is None:
+            self.analyse()
+        assert self._report is not None
+        if not self._report.passes:
+            raise AssertionError(
+                f"TraceRazor: TAS {self._report.tas_score:.1f} is below "
+                f"threshold {self._threshold}.\n\n{self._report.summary()}"
+            )
+
+    @property
+    def report(self) -> Optional[TraceRazorReport]:
+        """The most recent analysis report, or None if not yet analysed."""
+        return self._report
+
+    def set_task_value_score(self, score: float) -> None:
+        """
+        Update the task value score (0.0–1.0) based on ground-truth validation.
+        Must be called before analyse() for it to take effect.
+        """
+        self._builder.task_value_score = max(0.0, min(1.0, score))

tracerazor_langgraph-0.1.0/tracerazor_langgraph/client.py

@@ -0,0 +1,178 @@
+"""
+TraceRazor CLI client.
+
+Serialises a trace dict to a temp JSON file and invokes the tracerazor
+CLI binary, then parses the resulting JSON report.
+"""
+
+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 output from a tracerazor audit run."""
+
+    trace_id: str
+    agent_name: str
+    framework: str
+    total_steps: int
+    total_tokens: int
+    tas_score: float
+    grade: str
+    vae_score: float
+    passes: bool
+    metrics: Dict[str, Any] = field(default_factory=dict)
+    diff: List[Dict] = field(default_factory=list)
+    savings: Dict[str, Any] = field(default_factory=dict)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    def markdown(self) -> str:
+        """Re-generate a concise markdown summary from the parsed report."""
+        sep = "-" * 54
+        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:.1f} / 100  [{self.grade.upper()}]",
+            f"VAE SCORE:        {self.vae_score:.2f}",
+            sep,
+        ]
+        if self.savings:
+            lines += [
+                "SAVINGS ESTIMATE",
+                f"  Tokens saved:  {self.savings.get('tokens_saved', 0)}  "
+                f"({self.savings.get('reduction_pct', 0):.1f}% reduction)",
+                f"  At 50K/month:  ${self.savings.get('monthly_savings_usd', 0):.2f}/month",
+            ]
+        return "\n".join(lines)
+
+    def summary(self) -> str:
+        return (
+            f"TAS {self.tas_score:.1f}/100 [{self.grade}] | "
+            f"VAE {self.vae_score:.2f} | "
+            f"Saved {self.savings.get('reduction_pct', 0):.0f}% tokens"
+        )
+
+
+class TraceRazorClient:
+    """
+    Thin wrapper around the tracerazor CLI binary.
+
+    Writes the trace to a temp file, invokes the binary, parses JSON output.
+    """
+
+    def __init__(self, bin_path: Optional[str] = None):
+        self._bin = bin_path or self._find_binary()
+
+    def analyse(
+        self,
+        trace: Dict[str, Any],
+        threshold: float = 70.0,
+    ) -> TraceRazorReport:
+        """
+        Write the trace to a temp file and run tracerazor audit on it.
+
+        Returns a TraceRazorReport with the full parsed result.
+        Raises RuntimeError if the binary fails unexpectedly.
+        """
+        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:
+            cmd = [
+                self._bin,
+                "audit",
+                tmp_path,
+                "--format", "json",
+                "--threshold", str(threshold),
+            ]
+
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+
+            # Exit code 1 = below threshold (still valid output). Other codes = error.
+            if result.returncode not in (0, 1):
+                raise RuntimeError(
+                    f"tracerazor exited with code {result.returncode}:\n{result.stderr}"
+                )
+
+            report_json = json.loads(result.stdout)
+            return self._parse_report(report_json, threshold)
+
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+
+    @staticmethod
+    def _parse_report(data: Dict[str, Any], threshold: float) -> TraceRazorReport:
+        score = data.get("score", {})
+        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=score.get("score", 0.0),
+            grade=score.get("grade", "Unknown"),
+            vae_score=score.get("vae", 0.0),
+            passes=score.get("score", 0.0) >= threshold,
+            metrics=score,
+            diff=data.get("diff", []),
+            savings=data.get("savings", {}),
+            raw=data,
+        )
+
+    @staticmethod
+    def _find_binary() -> str:
+        """
+        Locate the tracerazor binary.
+        Search order:
+          1. TRACERAZOR_BIN environment variable
+          2. PATH (system-wide install)
+          3. Relative paths from this file (dev repo layout)
+        """
+        env_path = os.environ.get("TRACERAZOR_BIN")
+        if env_path and os.path.isfile(env_path):
+            return env_path
+
+        path_bin = shutil.which("tracerazor") or shutil.which("tracerazor.exe")
+        if path_bin:
+            return path_bin
+
+        # Dev layout: integrations/langgraph/ → ../../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. Set TRACERAZOR_BIN environment variable "
+            "or add 'tracerazor' to PATH.\n"
+            "Build with: cargo build --release"
+        )

tracerazor_langgraph-0.1.0/tracerazor_langgraph/trace_builder.py

@@ -0,0 +1,170 @@
+"""
+Builds a TraceRazor-format trace dict from LangGraph callback events.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+
+class _PendingStep:
+    """Mutable step being built from start/end event pairs."""
+
+    def __init__(self, step_type: str, step_id: int, start_time: float):
+        self.step_id = step_id
+        self.step_type = step_type
+        self.start_time = start_time
+        self.content: str = ""
+        self.tokens: int = 0
+        self.tool_name: Optional[str] = None
+        self.tool_params: Optional[Dict] = None
+        self.tool_success: Optional[bool] = None
+        self.tool_error: Optional[str] = None
+        self.input_context: Optional[str] = None
+        self.output: Optional[str] = None
+        self.agent_id: Optional[str] = None
+
+
+class TraceBuilder:
+    """
+    Stateful builder that converts LangGraph callback events into a
+    TraceRazor raw JSON trace.
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        framework: str,
+        task_value_score: float = 1.0,
+    ):
+        self.agent_name = agent_name
+        self.framework = framework
+        self.task_value_score = task_value_score
+        self._trace_id: str = str(uuid.uuid4())
+        self._steps: List[Dict] = []
+        self._step_counter: int = 1
+        self._pending: Optional[_PendingStep] = None
+        self._current_agent: Optional[str] = None
+
+    # ── Step lifecycle ───────────────────────────────────────────────────────
+
+    def start_reasoning_step(self, input_context: str = "") -> None:
+        self._pending = _PendingStep("reasoning", self._step_counter, time.time())
+        self._pending.input_context = input_context or None
+        self._pending.agent_id = self._current_agent
+
+    def end_reasoning_step(self, output: str = "", tokens: int = 0) -> None:
+        if self._pending is None or self._pending.step_type != "reasoning":
+            return
+        p = self._pending
+        p.output = output or None
+        p.tokens = tokens or self._estimate_tokens(p.input_context or "", output)
+        p.content = self._extract_content(p.input_context or "", output)
+        self._commit(p)
+        self._pending = None
+
+    def start_tool_step(self, tool_name: str, tool_params: Dict) -> None:
+        self._pending = _PendingStep("tool_call", self._step_counter, time.time())
+        self._pending.tool_name = tool_name
+        self._pending.tool_params = tool_params
+        self._pending.content = f"Calling {tool_name}"
+        self._pending.agent_id = self._current_agent
+
+    def end_tool_step(
+        self, output: str, success: bool, error: Optional[str] = None
+    ) -> None:
+        if self._pending is None or self._pending.step_type != "tool_call":
+            return
+        p = self._pending
+        p.tool_success = success
+        p.tool_error = error
+        p.output = output or None
+        p.tokens = self._estimate_tokens(str(p.tool_params or ""), output)
+        self._commit(p)
+        self._pending = None
+
+    def abort_current_step(self, error: str) -> None:
+        """Called when an LLM or tool raises an error mid-step."""
+        if self._pending is None:
+            return
+        p = self._pending
+        if p.step_type == "tool_call":
+            p.tool_success = False
+            p.tool_error = error
+            p.tokens = p.tokens or 50
+        else:
+            p.content = f"[ERROR] {error}"
+            p.tokens = p.tokens or 50
+        self._commit(p)
+        self._pending = None
+
+    def note_agent_transition(self, agent_id: str) -> None:
+        """Record a LangGraph node transition (agent handoff)."""
+        self._current_agent = agent_id
+
+    # ── Build ────────────────────────────────────────────────────────────────
+
+    def build(self) -> Dict:
+        """Return the complete trace as a dict ready for JSON serialisation."""
+        # Commit any pending step.
+        if self._pending is not None:
+            p = self._pending
+            p.tokens = p.tokens or 100
+            p.content = p.content or "incomplete step"
+            self._commit(p)
+            self._pending = None
+
+        return {
+            "trace_id": self._trace_id,
+            "agent_name": self.agent_name,
+            "framework": self.framework,
+            "task_value_score": self.task_value_score,
+            "steps": self._steps,
+        }
+
+    # ── Helpers ──────────────────────────────────────────────────────────────
+
+    def _commit(self, p: _PendingStep) -> None:
+        step: Dict[str, Any] = {
+            "id": p.step_id,
+            "type": p.step_type,
+            "content": p.content or "",
+            "tokens": max(p.tokens, 1),
+        }
+        if p.tool_name is not None:
+            step["tool_name"] = p.tool_name
+        if p.tool_params is not None:
+            step["tool_params"] = p.tool_params
+        if p.tool_success is not None:
+            step["tool_success"] = p.tool_success
+        if p.tool_error is not None:
+            step["tool_error"] = p.tool_error
+        if p.input_context:
+            step["input_context"] = p.input_context
+        if p.output:
+            step["output"] = p.output
+        if p.agent_id:
+            step["agent_id"] = p.agent_id
+        self._steps.append(step)
+        self._step_counter += 1
+
+    @staticmethod
+    def _estimate_tokens(input_text: str, output_text: str) -> int:
+        """
+        Rough token estimate: ~4 characters per token.
+        Actual counts come from LLM usage metadata when available.
+        """
+        total_chars = len(input_text) + len(output_text)
+        return max(int(total_chars / 4), 10)
+
+    @staticmethod
+    def _extract_content(input_context: str, output: str) -> str:
+        """Build a concise content string from input/output."""
+        if output:
+            return output[:200]
+        if input_context:
+            # Use last 200 chars of input as the content summary.
+            return input_context[-200:]
+        return ""

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

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: tracerazor-langgraph
+Version: 0.1.0
+Summary: TraceRazor LangGraph/LangChain callback — token efficiency auditing
+Author: Zulfaqar Hafez
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ZulfaqarHafez/tracerazor
+Project-URL: Repository, https://github.com/ZulfaqarHafez/tracerazor
+Keywords: ai,agents,langgraph,langchain,token-efficiency,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
+Requires-Dist: langchain-core>=0.2
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Dynamic: requires-python
+
+# tracerazor-langgraph
+
+LangGraph/LangChain callback adapter for [TraceRazor](../../README.md).
+
+Automatically captures every LLM call and tool call from your LangGraph graph with zero manual instrumentation.
+
+## Install
+
+```bash
+pip install tracerazor-langgraph
+pip install tracerazor-langgraph[langgraph]  # includes langgraph
+```
+
+Requires the `tracerazor` binary:
+
+```bash
+cargo build --release
+export TRACERAZOR_BIN=/path/to/TraceRazor/target/release/tracerazor
+```
+
+## Usage
+
+```python
+from tracerazor_langgraph import TraceRazorCallback
+from langgraph.prebuilt import create_react_agent
+from langchain_openai import ChatOpenAI
+
+callback = TraceRazorCallback(
+    agent_name="support-agent",
+    threshold=70,
+)
+
+model = ChatOpenAI(model="gpt-4o-mini")
+agent = create_react_agent(model, tools=[...])
+
+result = agent.invoke(
+    {"messages": [HumanMessage(content="I want a refund")]},
+    config={"callbacks": [callback]},
+)
+
+# After the agent finishes:
+report = callback.analyse()
+print(report.markdown())
+
+# CI/CD gate — raises AssertionError if TAS < threshold:
+callback.assert_passes()
+```
+
+## API
+
+### `TraceRazorCallback(agent_name, framework, threshold, task_value_score, tracerazor_bin)`
+
+| param | default | description |
+|---|---|---|
+| `agent_name` | `"langgraph-agent"` | shown in all reports |
+| `framework` | `"langgraph"` | framework label |
+| `threshold` | `70.0` | minimum TAS for `assert_passes()` |
+| `task_value_score` | `1.0` | answer quality (0–1) |
+| `tracerazor_bin` | auto | path to binary; falls back to `TRACERAZOR_BIN` env var |
+
+### `callback.analyse() → TraceRazorReport`
+
+Finalise and submit the trace. Returns the report.
+
+### `callback.assert_passes()`
+
+Raise `AssertionError` if TAS < threshold.
+
+### `callback.set_task_value_score(score: float)`
+
+Update quality score before calling `analyse()`.

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+setup.py
+tracerazor_langgraph/__init__.py
+tracerazor_langgraph/callback.py
+tracerazor_langgraph/client.py
+tracerazor_langgraph/trace_builder.py
+tracerazor_langgraph.egg-info/PKG-INFO
+tracerazor_langgraph.egg-info/SOURCES.txt
+tracerazor_langgraph.egg-info/dependency_links.txt
+tracerazor_langgraph.egg-info/requires.txt
+tracerazor_langgraph.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,4 @@
+langchain-core>=0.2
+
+[langgraph]
+langgraph>=0.2

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

@@ -0,0 +1 @@
+tracerazor_langgraph