pyagent-trace 0.1.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyagent_trace/__init__.py,sha256=hG7qwzYIFma6GmjlaPzTmI07KAS7ABPDg8PTF9mNrwA,930
+pyagent_trace/attributes.py,sha256=Gn5G50XJ_TriB_QmXc5fkY3XX4vWLrY96W5hqf5OeaM,1669
+pyagent_trace/cost.py,sha256=i8qQQXoXaOWHGp4JcMNdZ4LE2Nfp5LXB-g-BaN-Xz9Q,2589
+pyagent_trace/decorators.py,sha256=JCZxmtDnpe4Ncj4-4Q5OXvCMhwqTVPKDKz1hFwuXMDc,3066
+pyagent_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyagent_trace/recorder.py,sha256=fPCV-ACt_6-bq_u6RKc02gUiS8KEp_oq5YMSiBvNIlo,3389
+pyagent_trace/spans.py,sha256=ioQiZ3dl2Jr4sLEQHNxZYbHafQHtLJYWH02j1i-eYVE,3924
+pyagent_trace-0.1.0.dist-info/METADATA,sha256=JJB-SZwnWqcAXufztxvUggRGcUY83OaUR67TuBFmUSc,2241
+pyagent_trace-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pyagent_trace-0.1.0.dist-info/RECORD,,

pyagent_trace-0.1.0.dist-info/WHEEL

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