pyagent-trace 0.1.0__tar.gz

pyagent_trace-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+site/
+.env
+*.log

pyagent_trace-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pyagent-trace
+Version: 0.1.0
+Summary: Pattern-aware OpenTelemetry tracing for multi-agent LLM systems
+License: MIT
+Keywords: LLM,OpenTelemetry,agents,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.25
+Requires-Dist: opentelemetry-sdk>=1.25
+Requires-Dist: pyagent-patterns>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=2.0; extra == 'langfuse'
+Description-Content-Type: text/markdown
+
+# pyagent-trace
+
+**Pattern-aware OpenTelemetry tracing** for multi-agent LLM systems. Track costs, record interactions, debug with replay.
+
+## Install
+
+```bash
+pip install pyagent-trace              # Core (CostTracker, Recorder work without OTel)
+pip install pyagent-trace[otel]        # With OpenTelemetry spans
+```
+
+## Components
+
+- **CostTracker** — Accumulate costs by pattern, agent, and model (no OTel required)
+- **Recorder** — Record all messages + LLM responses to JSONL for replay/debug
+- **PatternSpanEmitter** — Create OTel spans for pattern executions (requires OTel)
+- **traced_pattern / traced_agent** — Decorators for automatic tracing (requires OTel)
+- **PyAgentAttributes** — Custom `pyagent.*` attribute constants
+
+## Quick Example (no OTel required)
+
+```python
+from pyagent_trace import CostTracker, Recorder
+
+tracker = CostTracker()
+tracker.record("debate", "bull_agent", "gpt-4o", 500, 200, 0.003)
+print(f"Total: ${tracker.total_cost:.4f}")
+print(f"By model: {tracker.by_model()}")
+
+recorder = Recorder()
+recorder.start("debate")
+recorder.record_llm_call("bull", messages, "Bull case: ...")
+recorder.end("Final decision")
+recorder.save("traces/debug.jsonl")
+```

pyagent_trace-0.1.0/README.md

@@ -0,0 +1,35 @@
+# pyagent-trace
+
+**Pattern-aware OpenTelemetry tracing** for multi-agent LLM systems. Track costs, record interactions, debug with replay.
+
+## Install
+
+```bash
+pip install pyagent-trace              # Core (CostTracker, Recorder work without OTel)
+pip install pyagent-trace[otel]        # With OpenTelemetry spans
+```
+
+## Components
+
+- **CostTracker** — Accumulate costs by pattern, agent, and model (no OTel required)
+- **Recorder** — Record all messages + LLM responses to JSONL for replay/debug
+- **PatternSpanEmitter** — Create OTel spans for pattern executions (requires OTel)
+- **traced_pattern / traced_agent** — Decorators for automatic tracing (requires OTel)
+- **PyAgentAttributes** — Custom `pyagent.*` attribute constants
+
+## Quick Example (no OTel required)
+
+```python
+from pyagent_trace import CostTracker, Recorder
+
+tracker = CostTracker()
+tracker.record("debate", "bull_agent", "gpt-4o", 500, 200, 0.003)
+print(f"Total: ${tracker.total_cost:.4f}")
+print(f"By model: {tracker.by_model()}")
+
+recorder = Recorder()
+recorder.start("debate")
+recorder.record_llm_call("bull", messages, "Bull case: ...")
+recorder.end("Final decision")
+recorder.save("traces/debug.jsonl")
+```

pyagent_trace-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyagent-trace"
+version = "0.1.0"
+description = "Pattern-aware OpenTelemetry tracing for multi-agent LLM systems"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+keywords = ["agents", "tracing", "OpenTelemetry", "observability", "LLM"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyagent-patterns>=0.1.0",
+    "opentelemetry-api>=1.25",
+    "opentelemetry-sdk>=1.25",
+]
+
+[project.optional-dependencies]
+langfuse = ["langfuse>=2.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.5", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyagent_trace"]

pyagent_trace-0.1.0/src/pyagent_trace/__init__.py

@@ -0,0 +1,28 @@
+"""PyAgent Trace — pattern-aware OpenTelemetry tracing for multi-agent LLM systems."""
+
+from pyagent_trace.attributes import PyAgentAttributes
+from pyagent_trace.cost import CostTracker
+from pyagent_trace.recorder import Recorder
+
+# OTel-dependent imports are lazy to avoid hard dependency
+def __getattr__(name: str):
+    if name == "traced_agent":
+        from pyagent_trace.decorators import traced_agent
+        return traced_agent
+    if name == "traced_pattern":
+        from pyagent_trace.decorators import traced_pattern
+        return traced_pattern
+    if name == "PatternSpanEmitter":
+        from pyagent_trace.spans import PatternSpanEmitter
+        return PatternSpanEmitter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = [
+    "traced_pattern",
+    "traced_agent",
+    "PatternSpanEmitter",
+    "PyAgentAttributes",
+    "CostTracker",
+    "Recorder",
+]
+__version__ = "0.1.0"

pyagent_trace-0.1.0/src/pyagent_trace/attributes.py

@@ -0,0 +1,46 @@
+"""Custom OTel attributes for pyagent spans.
+
+All attributes are namespaced under `pyagent.*` to avoid collisions.
+Follows OpenTelemetry GenAI semantic conventions where applicable.
+"""
+
+from __future__ import annotations
+
+
+class PyAgentAttributes:
+    """Attribute key constants for pyagent OTel spans."""
+
+    # Pattern attributes
+    PATTERN_TYPE = "pyagent.pattern.type"
+    PATTERN_ROUNDS = "pyagent.pattern.rounds"
+    PATTERN_CONSENSUS = "pyagent.pattern.consensus"
+    PATTERN_ESCALATED = "pyagent.pattern.escalated"
+    PATTERN_ESCALATION_LEVEL = "pyagent.pattern.escalation_level"
+
+    # Router attributes
+    ROUTER_DIFFICULTY = "pyagent.router.difficulty"
+    ROUTER_DIFFICULTY_CATEGORY = "pyagent.router.difficulty_category"
+    ROUTER_SELECTED_MODEL = "pyagent.router.selected_model"
+    ROUTER_COST_ESTIMATE = "pyagent.router.cost_estimate"
+    ROUTER_ALTERNATIVES = "pyagent.router.alternatives"
+
+    # Compression attributes
+    COMPRESS_INPUT_TOKENS = "pyagent.compress.input_tokens"
+    COMPRESS_OUTPUT_TOKENS = "pyagent.compress.output_tokens"
+    COMPRESS_SAVINGS_PCT = "pyagent.compress.savings_pct"
+
+    # Agent attributes
+    AGENT_NAME = "pyagent.agent.name"
+    AGENT_ROLE = "pyagent.agent.role"
+    AGENT_CONTRIBUTION = "pyagent.agent.contribution"
+
+    # Cost attributes
+    COST_TOTAL_USD = "pyagent.cost.total_usd"
+    COST_INPUT_TOKENS = "pyagent.cost.input_tokens"
+    COST_OUTPUT_TOKENS = "pyagent.cost.output_tokens"
+    COST_MODEL = "pyagent.cost.model"
+
+    # Execution attributes
+    EXEC_DURATION_MS = "pyagent.exec.duration_ms"
+    EXEC_TOKEN_ESTIMATE = "pyagent.exec.token_estimate"
+    EXEC_LLM_CALLS = "pyagent.exec.llm_calls"

pyagent_trace-0.1.0/src/pyagent_trace/cost.py

@@ -0,0 +1,90 @@
+"""CostTracker: accumulate and attribute costs by pattern, agent, and model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CostEntry:
+    """A single cost record."""
+
+    pattern_type: str
+    agent_name: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+
+
+class CostTracker:
+    """Track costs across an entire workflow.
+
+    Usage:
+        tracker = CostTracker()
+        tracker.record("debate", "bull_agent", "gpt-4o", 500, 200, 0.003)
+        tracker.record("debate", "bear_agent", "gpt-4o-mini", 500, 200, 0.0004)
+        print(tracker.summary())
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[CostEntry] = []
+
+    def record(
+        self,
+        pattern_type: str,
+        agent_name: str,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cost_usd: float,
+    ) -> None:
+        """Record a cost entry."""
+        self._entries.append(CostEntry(
+            pattern_type=pattern_type,
+            agent_name=agent_name,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost_usd,
+        ))
+
+    @property
+    def total_cost(self) -> float:
+        return sum(e.cost_usd for e in self._entries)
+
+    @property
+    def total_tokens(self) -> int:
+        return sum(e.input_tokens + e.output_tokens for e in self._entries)
+
+    def by_pattern(self) -> dict[str, float]:
+        """Cost breakdown by pattern type."""
+        result: dict[str, float] = {}
+        for e in self._entries:
+            result[e.pattern_type] = result.get(e.pattern_type, 0.0) + e.cost_usd
+        return result
+
+    def by_agent(self) -> dict[str, float]:
+        """Cost breakdown by agent name."""
+        result: dict[str, float] = {}
+        for e in self._entries:
+            result[e.agent_name] = result.get(e.agent_name, 0.0) + e.cost_usd
+        return result
+
+    def by_model(self) -> dict[str, float]:
+        """Cost breakdown by model."""
+        result: dict[str, float] = {}
+        for e in self._entries:
+            result[e.model] = result.get(e.model, 0.0) + e.cost_usd
+        return result
+
+    def summary(self) -> dict[str, object]:
+        """Full cost summary."""
+        return {
+            "total_cost_usd": self.total_cost,
+            "total_tokens": self.total_tokens,
+            "entries": len(self._entries),
+            "by_pattern": self.by_pattern(),
+            "by_agent": self.by_agent(),
+            "by_model": self.by_model(),
+        }

pyagent_trace-0.1.0/src/pyagent_trace/decorators.py

@@ -0,0 +1,87 @@
+"""Decorators for automatic tracing of patterns and agents.
+
+@traced_pattern: wraps a Pattern subclass to emit spans on every run().
+@traced_agent: wraps an Agent to emit spans on every run().
+"""
+
+from __future__ import annotations
+
+import functools
+import time
+from typing import Any
+
+from opentelemetry import trace
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+from pyagent_trace.attributes import PyAgentAttributes
+
+_tracer = trace.get_tracer("pyagent", "0.1.0")
+
+
+def traced_pattern(cls: type[Pattern]) -> type[Pattern]:
+    """Class decorator: auto-emit OTel spans for every pattern.run() call.
+
+    Usage:
+        @traced_pattern
+        class MyPattern(Pattern):
+            ...
+    """
+    original_run = cls.run
+
+    @functools.wraps(original_run)
+    async def traced_run(self: Pattern, task: str, context: Context | None = None) -> Result:
+        with _tracer.start_as_current_span(
+            f"pyagent.pattern.{self.pattern_type}",
+            attributes={PyAgentAttributes.PATTERN_TYPE: self.pattern_type},
+        ) as span:
+            start = time.perf_counter()
+            try:
+                result = await original_run(self, task, context)
+
+                duration_ms = (time.perf_counter() - start) * 1000
+                span.set_attribute(PyAgentAttributes.EXEC_DURATION_MS, duration_ms)
+                span.set_attribute(PyAgentAttributes.EXEC_TOKEN_ESTIMATE, result.token_estimate)
+                span.set_attribute(PyAgentAttributes.COST_TOTAL_USD, result.cost_estimate)
+
+                if "rounds" in result.metadata:
+                    span.set_attribute(PyAgentAttributes.PATTERN_ROUNDS, result.metadata["rounds"])
+
+                span.set_status(trace.StatusCode.OK)
+                return result
+            except Exception as e:
+                span.set_status(trace.StatusCode.ERROR, str(e))
+                span.record_exception(e)
+                raise
+
+    cls.run = traced_run  # type: ignore[assignment]
+    return cls
+
+
+def traced_agent(agent: Agent) -> Agent:
+    """Wrap an Agent instance to emit OTel spans on every run() call.
+
+    Usage:
+        agent = traced_agent(Agent("my_agent", llm))
+    """
+    original_run = agent.run
+
+    @functools.wraps(original_run)
+    async def traced_run(messages: list[Message]) -> Message:
+        with _tracer.start_as_current_span(
+            f"pyagent.agent.{agent.name}",
+            attributes={PyAgentAttributes.AGENT_NAME: agent.name},
+        ) as span:
+            start = time.perf_counter()
+            try:
+                result = await original_run(messages)
+                duration_ms = (time.perf_counter() - start) * 1000
+                span.set_attribute(PyAgentAttributes.EXEC_DURATION_MS, duration_ms)
+                span.set_status(trace.StatusCode.OK)
+                return result
+            except Exception as e:
+                span.set_status(trace.StatusCode.ERROR, str(e))
+                span.record_exception(e)
+                raise
+
+    agent.run = traced_run  # type: ignore[assignment]
+    return agent

pyagent_trace-0.1.0/src/pyagent_trace/recorder.py

@@ -0,0 +1,111 @@
+"""Recorder: serialize all pattern messages and LLM responses for replay/debug.
+
+Record mode: saves all messages + LLM responses to a JSONL file.
+Replay mode: re-runs pattern with recorded LLM responses (deterministic).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from pyagent_patterns.base import Message, Role
+
+
+@dataclass
+class RecordEntry:
+    """A single recorded event."""
+
+    timestamp: float
+    event_type: str  # "llm_call", "message", "pattern_start", "pattern_end"
+    agent_name: str
+    messages_in: list[dict[str, Any]]
+    response: str
+    metadata: dict[str, Any]
+
+
+class Recorder:
+    """Record pattern executions for debugging and replay.
+
+    Usage:
+        recorder = Recorder()
+        recorder.start("debate")
+        recorder.record_llm_call("bull", messages, response)
+        recorder.save("debug_trace.jsonl")
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[RecordEntry] = []
+        self._start_time: float = 0.0
+
+    def start(self, pattern_type: str) -> None:
+        """Mark the start of a pattern execution."""
+        self._start_time = time.time()
+        self._entries.append(RecordEntry(
+            timestamp=self._start_time,
+            event_type="pattern_start",
+            agent_name="",
+            messages_in=[],
+            response="",
+            metadata={"pattern_type": pattern_type},
+        ))
+
+    def record_llm_call(
+        self,
+        agent_name: str,
+        messages: list[Message],
+        response: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Record an LLM call and its response."""
+        self._entries.append(RecordEntry(
+            timestamp=time.time(),
+            event_type="llm_call",
+            agent_name=agent_name,
+            messages_in=[
+                {"role": m.role.value, "content": m.content, "name": m.name}
+                for m in messages
+            ],
+            response=response,
+            metadata=metadata or {},
+        ))
+
+    def end(self, result_output: str) -> None:
+        """Mark the end of a pattern execution."""
+        self._entries.append(RecordEntry(
+            timestamp=time.time(),
+            event_type="pattern_end",
+            agent_name="",
+            messages_in=[],
+            response=result_output,
+            metadata={"duration_seconds": time.time() - self._start_time},
+        ))
+
+    def save(self, path: str | Path) -> None:
+        """Save recorded entries to a JSONL file."""
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("w") as f:
+            for entry in self._entries:
+                f.write(json.dumps(asdict(entry), default=str) + "\n")
+
+    @classmethod
+    def load(cls, path: str | Path) -> list[RecordEntry]:
+        """Load recorded entries from a JSONL file."""
+        entries: list[RecordEntry] = []
+        with Path(path).open() as f:
+            for line in f:
+                data = json.loads(line.strip())
+                entries.append(RecordEntry(**data))
+        return entries
+
+    @property
+    def entries(self) -> list[RecordEntry]:
+        return list(self._entries)
+
+    @property
+    def llm_calls(self) -> list[RecordEntry]:
+        return [e for e in self._entries if e.event_type == "llm_call"]

pyagent_trace-0.1.0/src/pyagent_trace/spans.py

@@ -0,0 +1,115 @@
+"""PatternSpanEmitter: create OTel spans for pattern executions.
+
+Emits structured spans with pyagent.* attributes for every pattern run,
+agent call, and routing/compression decision.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.trace import Span, StatusCode
+
+from pyagent_trace.attributes import PyAgentAttributes
+
+_tracer = trace.get_tracer("pyagent", "0.1.0")
+
+
+class PatternSpanEmitter:
+    """Emit OTel spans for pattern executions.
+
+    Usage:
+        emitter = PatternSpanEmitter()
+        with emitter.pattern_span("debate", {"rounds": 3}) as span:
+            # ... pattern logic ...
+            emitter.set_result(span, result)
+    """
+
+    def pattern_span(
+        self,
+        pattern_type: str,
+        attributes: dict[str, Any] | None = None,
+    ) -> Span:
+        """Start a span for a pattern execution."""
+        span = _tracer.start_span(
+            f"pyagent.pattern.{pattern_type}",
+            attributes={
+                PyAgentAttributes.PATTERN_TYPE: pattern_type,
+                **(attributes or {}),
+            },
+        )
+        return span
+
+    def agent_span(
+        self,
+        agent_name: str,
+        parent_span: Span | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> Span:
+        """Start a span for an individual agent call."""
+        ctx = trace.set_span_in_context(parent_span) if parent_span else None
+        span = _tracer.start_span(
+            f"pyagent.agent.{agent_name}",
+            context=ctx,
+            attributes={
+                PyAgentAttributes.AGENT_NAME: agent_name,
+                **(attributes or {}),
+            },
+        )
+        return span
+
+    @staticmethod
+    def set_pattern_result(
+        span: Span,
+        output_length: int,
+        rounds: int | None = None,
+        consensus: float | None = None,
+        escalated: bool = False,
+        duration_ms: float = 0.0,
+        token_estimate: int = 0,
+        cost_estimate: float = 0.0,
+    ) -> None:
+        """Set result attributes on a pattern span."""
+        if rounds is not None:
+            span.set_attribute(PyAgentAttributes.PATTERN_ROUNDS, rounds)
+        if consensus is not None:
+            span.set_attribute(PyAgentAttributes.PATTERN_CONSENSUS, consensus)
+        span.set_attribute(PyAgentAttributes.PATTERN_ESCALATED, escalated)
+        span.set_attribute(PyAgentAttributes.EXEC_DURATION_MS, duration_ms)
+        span.set_attribute(PyAgentAttributes.EXEC_TOKEN_ESTIMATE, token_estimate)
+        span.set_attribute(PyAgentAttributes.COST_TOTAL_USD, cost_estimate)
+        span.set_status(StatusCode.OK)
+
+    @staticmethod
+    def set_routing_info(
+        span: Span,
+        difficulty: int,
+        selected_model: str,
+        cost_estimate: float,
+        category: str = "",
+    ) -> None:
+        """Set routing attributes on a span."""
+        span.set_attribute(PyAgentAttributes.ROUTER_DIFFICULTY, difficulty)
+        span.set_attribute(PyAgentAttributes.ROUTER_SELECTED_MODEL, selected_model)
+        span.set_attribute(PyAgentAttributes.ROUTER_COST_ESTIMATE, cost_estimate)
+        if category:
+            span.set_attribute(PyAgentAttributes.ROUTER_DIFFICULTY_CATEGORY, category)
+
+    @staticmethod
+    def set_compression_info(
+        span: Span,
+        input_tokens: int,
+        output_tokens: int,
+        savings_pct: float,
+    ) -> None:
+        """Set compression attributes on a span."""
+        span.set_attribute(PyAgentAttributes.COMPRESS_INPUT_TOKENS, input_tokens)
+        span.set_attribute(PyAgentAttributes.COMPRESS_OUTPUT_TOKENS, output_tokens)
+        span.set_attribute(PyAgentAttributes.COMPRESS_SAVINGS_PCT, savings_pct)
+
+    @staticmethod
+    def set_error(span: Span, error: Exception) -> None:
+        """Record an error on a span."""
+        span.set_status(StatusCode.ERROR, str(error))
+        span.record_exception(error)

pyagent_trace-0.1.0/tests/test_trace.py

@@ -0,0 +1,181 @@
+"""Tests for pyagent-trace: CostTracker, Recorder, PyAgentAttributes."""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from pyagent_patterns.base import Message, Role
+from pyagent_trace.attributes import PyAgentAttributes
+from pyagent_trace.cost import CostTracker
+from pyagent_trace.recorder import Recorder
+
+
+# --- PyAgentAttributes ---
+
+def test_attributes_pattern_keys():
+    assert PyAgentAttributes.PATTERN_TYPE == "pyagent.pattern.type"
+    assert PyAgentAttributes.PATTERN_ROUNDS == "pyagent.pattern.rounds"
+    assert PyAgentAttributes.PATTERN_ESCALATED == "pyagent.pattern.escalated"
+
+
+def test_attributes_router_keys():
+    assert PyAgentAttributes.ROUTER_DIFFICULTY == "pyagent.router.difficulty"
+    assert PyAgentAttributes.ROUTER_SELECTED_MODEL == "pyagent.router.selected_model"
+
+
+def test_attributes_compress_keys():
+    assert PyAgentAttributes.COMPRESS_SAVINGS_PCT == "pyagent.compress.savings_pct"
+
+
+def test_attributes_cost_keys():
+    assert PyAgentAttributes.COST_TOTAL_USD == "pyagent.cost.total_usd"
+    assert PyAgentAttributes.COST_MODEL == "pyagent.cost.model"
+
+
+def test_attributes_exec_keys():
+    assert PyAgentAttributes.EXEC_DURATION_MS == "pyagent.exec.duration_ms"
+    assert PyAgentAttributes.EXEC_LLM_CALLS == "pyagent.exec.llm_calls"
+
+
+# --- CostTracker ---
+
+def test_cost_tracker_empty():
+    tracker = CostTracker()
+    assert tracker.total_cost == 0.0
+    assert tracker.total_tokens == 0
+    assert tracker.by_pattern() == {}
+    assert tracker.by_agent() == {}
+    assert tracker.by_model() == {}
+
+
+def test_cost_tracker_record_and_totals():
+    tracker = CostTracker()
+    tracker.record("debate", "bull", "gpt-4o", 500, 200, 0.003)
+    tracker.record("debate", "bear", "gpt-4o-mini", 500, 200, 0.0004)
+    tracker.record("debate", "judge", "gpt-4o", 1000, 300, 0.0055)
+
+    assert tracker.total_cost == pytest.approx(0.0089, abs=1e-6)
+    assert tracker.total_tokens == 2700
+
+
+def test_cost_tracker_by_pattern():
+    tracker = CostTracker()
+    tracker.record("debate", "bull", "gpt-4o", 100, 50, 0.002)
+    tracker.record("pipeline", "stage1", "gpt-4o-mini", 100, 50, 0.0005)
+
+    by_p = tracker.by_pattern()
+    assert "debate" in by_p
+    assert "pipeline" in by_p
+    assert by_p["debate"] == pytest.approx(0.002)
+    assert by_p["pipeline"] == pytest.approx(0.0005)
+
+
+def test_cost_tracker_by_agent():
+    tracker = CostTracker()
+    tracker.record("debate", "bull", "gpt-4o", 100, 50, 0.002)
+    tracker.record("debate", "bull", "gpt-4o", 100, 50, 0.002)
+    tracker.record("debate", "bear", "gpt-4o", 100, 50, 0.001)
+
+    by_a = tracker.by_agent()
+    assert by_a["bull"] == pytest.approx(0.004)
+    assert by_a["bear"] == pytest.approx(0.001)
+
+
+def test_cost_tracker_by_model():
+    tracker = CostTracker()
+    tracker.record("p", "a", "gpt-4o", 100, 50, 0.003)
+    tracker.record("p", "b", "gpt-4o-mini", 100, 50, 0.0003)
+
+    by_m = tracker.by_model()
+    assert "gpt-4o" in by_m
+    assert "gpt-4o-mini" in by_m
+
+
+def test_cost_tracker_summary():
+    tracker = CostTracker()
+    tracker.record("debate", "bull", "gpt-4o", 500, 200, 0.003)
+    s = tracker.summary()
+    assert s["total_cost_usd"] == pytest.approx(0.003)
+    assert s["total_tokens"] == 700
+    assert s["entries"] == 1
+
+
+# --- Recorder ---
+
+def test_recorder_start_end():
+    rec = Recorder()
+    rec.start("debate")
+    rec.end("Final output")
+    assert len(rec.entries) == 2
+    assert rec.entries[0].event_type == "pattern_start"
+    assert rec.entries[1].event_type == "pattern_end"
+    assert rec.entries[1].response == "Final output"
+
+
+def test_recorder_record_llm_call():
+    rec = Recorder()
+    rec.start("pipeline")
+    messages = [Message(role=Role.USER, content="Hello")]
+    rec.record_llm_call("agent1", messages, "Response text")
+    rec.end("done")
+
+    assert len(rec.llm_calls) == 1
+    call = rec.llm_calls[0]
+    assert call.agent_name == "agent1"
+    assert call.response == "Response text"
+    assert call.messages_in[0]["role"] == "user"
+    assert call.messages_in[0]["content"] == "Hello"
+
+
+def test_recorder_save_and_load():
+    rec = Recorder()
+    rec.start("voting")
+    messages = [Message(role=Role.USER, content="Vote please")]
+    rec.record_llm_call("voter1", messages, "YES")
+    rec.record_llm_call("voter2", messages, "NO")
+    rec.end("YES wins")
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        path = Path(tmpdir) / "trace.jsonl"
+        rec.save(path)
+
+        # Verify file exists and is valid JSONL
+        lines = path.read_text().strip().split("\n")
+        assert len(lines) == 4  # start + 2 calls + end
+
+        for line in lines:
+            data = json.loads(line)
+            assert "event_type" in data
+            assert "timestamp" in data
+
+        # Load and verify
+        loaded = Recorder.load(path)
+        assert len(loaded) == 4
+        assert loaded[0].event_type == "pattern_start"
+        assert loaded[1].event_type == "llm_call"
+        assert loaded[1].agent_name == "voter1"
+        assert loaded[2].agent_name == "voter2"
+        assert loaded[3].event_type == "pattern_end"
+        assert loaded[3].response == "YES wins"
+
+
+def test_recorder_metadata():
+    rec = Recorder()
+    rec.start("debate")
+    messages = [Message(role=Role.USER, content="test")]
+    rec.record_llm_call("bull", messages, "Bull case", metadata={"round": 1, "position": "BUY"})
+    rec.end("done")
+
+    call = rec.llm_calls[0]
+    assert call.metadata["round"] == 1
+    assert call.metadata["position"] == "BUY"
+
+
+def test_recorder_empty():
+    rec = Recorder()
+    assert rec.entries == []
+    assert rec.llm_calls == []