agentguard47 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

agentguard/__init__.py

@@ -9,6 +9,7 @@ from .guards import (
 )
 from .recording import Recorder, Replayer
 from .sinks import HttpSink
+from .evaluation import EvalSuite, EvalResult, AssertionResult
 
 __all__ = [
     "Tracer",
@@ -21,4 +22,7 @@ __all__ = [
     "Recorder",
     "Replayer",
     "HttpSink",
+    "EvalSuite",
+    "EvalResult",
+    "AssertionResult",
 ]

agentguard/cli.py

@@ -81,6 +81,21 @@ def _report(path: str) -> None:
         print("  Loop guard triggered: 0")
 
 
+def _eval(path: str) -> None:
+    from agentguard.evaluation import EvalSuite
+
+    result = (
+        EvalSuite(path)
+        .assert_no_loops()
+        .assert_no_errors()
+        .assert_completes_within(30.0)
+        .run()
+    )
+    print(result.summary)
+    if not result.passed:
+        raise SystemExit(1)
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(prog="agentguard")
     sub = parser.add_subparsers(dest="cmd")
@@ -96,6 +111,9 @@ def main() -> None:
     view.add_argument("--port", type=int, default=8080)
     view.add_argument("--no-open", action="store_true")
 
+    eval_cmd = sub.add_parser("eval", help="Run evaluation assertions on a trace")
+    eval_cmd.add_argument("path")
+
     args = parser.parse_args()
     if args.cmd == "summarize":
         _summarize(args.path)
@@ -105,6 +123,8 @@ def main() -> None:
         from agentguard.viewer import serve
 
         serve(args.path, port=args.port, open_browser=not args.no_open)
+    elif args.cmd == "eval":
+        _eval(args.path)
     else:
         parser.print_help()
 

agentguard/evaluation.py

@@ -0,0 +1,220 @@
+"""Evaluation as Code — assertion-based trace analysis."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class AssertionResult:
+    name: str
+    passed: bool
+    message: str
+
+
+@dataclass
+class EvalResult:
+    assertions: List[AssertionResult] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return all(a.passed for a in self.assertions)
+
+    @property
+    def summary(self) -> str:
+        total = len(self.assertions)
+        passed = sum(1 for a in self.assertions if a.passed)
+        failed = total - passed
+        lines = [f"EvalResult: {passed}/{total} passed, {failed} failed"]
+        for a in self.assertions:
+            status = "PASS" if a.passed else "FAIL"
+            lines.append(f"  [{status}] {a.name}: {a.message}")
+        return "\n".join(lines)
+
+
+class EvalSuite:
+    """Load a trace from JSONL and run assertions against it."""
+
+    def __init__(self, path: str) -> None:
+        self._events = _load_events(path)
+        self._assertions: List[_Assertion] = []
+
+    @property
+    def events(self) -> List[Dict[str, Any]]:
+        return list(self._events)
+
+    def assert_no_loops(self) -> "EvalSuite":
+        """Assert that no loop guard events were recorded."""
+        self._assertions.append(_Assertion(
+            name="no_loops",
+            check=_check_no_loops,
+        ))
+        return self
+
+    def assert_tool_called(self, name: str, min_times: int = 1) -> "EvalSuite":
+        """Assert a tool was called at least min_times."""
+        self._assertions.append(_Assertion(
+            name=f"tool_called:{name}>={min_times}",
+            check=lambda events, n=name, m=min_times: _check_tool_called(events, n, m),
+        ))
+        return self
+
+    def assert_budget_under(self, tokens: Optional[int] = None, calls: Optional[int] = None) -> "EvalSuite":
+        """Assert total token/call usage is under a limit."""
+        label_parts = []
+        if tokens is not None:
+            label_parts.append(f"tokens<{tokens}")
+        if calls is not None:
+            label_parts.append(f"calls<{calls}")
+        self._assertions.append(_Assertion(
+            name=f"budget_under:{','.join(label_parts)}",
+            check=lambda events, t=tokens, c=calls: _check_budget_under(events, t, c),
+        ))
+        return self
+
+    def assert_completes_within(self, seconds: float) -> "EvalSuite":
+        """Assert the longest span completed within a time limit."""
+        self._assertions.append(_Assertion(
+            name=f"completes_within:{seconds}s",
+            check=lambda events, s=seconds: _check_completes_within(events, s),
+        ))
+        return self
+
+    def assert_event_exists(self, name: str) -> "EvalSuite":
+        """Assert that at least one event with the given name exists."""
+        self._assertions.append(_Assertion(
+            name=f"event_exists:{name}",
+            check=lambda events, n=name: _check_event_exists(events, n),
+        ))
+        return self
+
+    def assert_no_errors(self) -> "EvalSuite":
+        """Assert no events have error data."""
+        self._assertions.append(_Assertion(
+            name="no_errors",
+            check=_check_no_errors,
+        ))
+        return self
+
+    def run(self) -> EvalResult:
+        result = EvalResult()
+        for assertion in self._assertions:
+            ar = assertion.check(self._events)
+            result.assertions.append(ar)
+        return result
+
+
+@dataclass
+class _Assertion:
+    name: str
+    check: Any  # Callable[[List[Dict]], AssertionResult]
+
+
+# --- check functions ---
+
+
+def _check_no_loops(events: List[Dict[str, Any]]) -> AssertionResult:
+    loop_events = [e for e in events if e.get("name") == "guard.loop_detected"]
+    if loop_events:
+        return AssertionResult(
+            name="no_loops",
+            passed=False,
+            message=f"Found {len(loop_events)} loop detection event(s)",
+        )
+    return AssertionResult(name="no_loops", passed=True, message="No loops detected")
+
+
+def _check_tool_called(events: List[Dict[str, Any]], tool_name: str, min_times: int) -> AssertionResult:
+    name = f"tool_called:{tool_name}>={min_times}"
+    # Count tool.result events or span events with matching tool name
+    count = 0
+    for e in events:
+        ename = e.get("name", "")
+        if ename == "tool.result":
+            count += 1
+        elif ename.startswith(f"tool.{tool_name}"):
+            if e.get("phase") == "start" or e.get("kind") == "event":
+                count += 1
+    if count >= min_times:
+        return AssertionResult(name=name, passed=True, message=f"Tool called {count} time(s)")
+    return AssertionResult(name=name, passed=False, message=f"Tool called {count} time(s), expected >= {min_times}")
+
+
+def _check_budget_under(events: List[Dict[str, Any]], max_tokens: Optional[int], max_calls: Optional[int]) -> AssertionResult:
+    parts = []
+    if max_tokens is not None:
+        parts.append(f"tokens<{max_tokens}")
+    if max_calls is not None:
+        parts.append(f"calls<{max_calls}")
+    name = f"budget_under:{','.join(parts)}"
+
+    total_tokens = 0
+    total_calls = 0
+    for e in events:
+        data = e.get("data", {})
+        if isinstance(data, dict):
+            usage = data.get("token_usage") or data.get("usage") or {}
+            if isinstance(usage, dict):
+                total_tokens += usage.get("total_tokens", 0)
+        if e.get("name", "").startswith("tool.") and e.get("kind") == "span" and e.get("phase") == "start":
+            total_calls += 1
+
+    failures = []
+    if max_tokens is not None and total_tokens >= max_tokens:
+        failures.append(f"tokens={total_tokens} >= {max_tokens}")
+    if max_calls is not None and total_calls >= max_calls:
+        failures.append(f"calls={total_calls} >= {max_calls}")
+
+    if failures:
+        return AssertionResult(name=name, passed=False, message="; ".join(failures))
+    return AssertionResult(name=name, passed=True, message=f"tokens={total_tokens}, calls={total_calls}")
+
+
+def _check_completes_within(events: List[Dict[str, Any]], max_seconds: float) -> AssertionResult:
+    name = f"completes_within:{max_seconds}s"
+    max_ms = 0.0
+    for e in events:
+        dur = e.get("duration_ms")
+        if isinstance(dur, (int, float)) and dur > max_ms:
+            max_ms = dur
+    actual_seconds = max_ms / 1000.0
+    if actual_seconds <= max_seconds:
+        return AssertionResult(name=name, passed=True, message=f"Completed in {actual_seconds:.3f}s")
+    return AssertionResult(name=name, passed=False, message=f"Took {actual_seconds:.3f}s, limit is {max_seconds}s")
+
+
+def _check_event_exists(events: List[Dict[str, Any]], event_name: str) -> AssertionResult:
+    name = f"event_exists:{event_name}"
+    found = any(e.get("name") == event_name for e in events)
+    if found:
+        return AssertionResult(name=name, passed=True, message="Event found")
+    return AssertionResult(name=name, passed=False, message="Event not found")
+
+
+def _check_no_errors(events: List[Dict[str, Any]]) -> AssertionResult:
+    errors = [e for e in events if e.get("error") is not None]
+    if errors:
+        return AssertionResult(
+            name="no_errors",
+            passed=False,
+            message=f"Found {len(errors)} event(s) with errors",
+        )
+    return AssertionResult(name="no_errors", passed=True, message="No errors found")
+
+
+# --- loader ---
+
+
+def _load_events(path: str) -> List[Dict[str, Any]]:
+    events: List[Dict[str, Any]] = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                events.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return events

agentguard/instrument.py

@@ -0,0 +1,183 @@
+"""Auto-instrumentation decorators and monkey-patches."""
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, Optional, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def trace_agent(tracer: Any, name: Optional[str] = None) -> Callable[[F], F]:
+    """Decorator that wraps a function in a top-level trace span.
+
+    Usage::
+
+        @trace_agent(tracer)
+        def my_agent(query: str) -> str:
+            ...
+    """
+
+    def decorator(fn: F) -> F:
+        span_name = name or f"agent.{fn.__name__}"
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with tracer.trace(span_name) as ctx:
+                kwargs["_trace_ctx"] = ctx
+                try:
+                    return fn(*args, **kwargs)
+                except Exception:
+                    raise
+                finally:
+                    kwargs.pop("_trace_ctx", None)
+
+        # If the function doesn't accept **kwargs, fall back to simple wrapping
+        @functools.wraps(fn)
+        def simple_wrapper(*args: Any, **kwargs: Any) -> Any:
+            with tracer.trace(span_name):
+                return fn(*args, **kwargs)
+
+        # Check if function can accept _trace_ctx kwarg
+        import inspect
+
+        sig = inspect.signature(fn)
+        has_var_keyword = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD
+            for p in sig.parameters.values()
+        )
+        has_trace_ctx = "_trace_ctx" in sig.parameters
+
+        if has_var_keyword or has_trace_ctx:
+            return wrapper  # type: ignore[return-value]
+        return simple_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def trace_tool(tracer: Any, name: Optional[str] = None) -> Callable[[F], F]:
+    """Decorator that wraps a function in a tool span.
+
+    Usage::
+
+        @trace_tool(tracer)
+        def search(query: str) -> str:
+            ...
+    """
+
+    def decorator(fn: F) -> F:
+        span_name = name or f"tool.{fn.__name__}"
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with tracer.trace(span_name) as ctx:
+                result = fn(*args, **kwargs)
+                ctx.event("tool.result", data={"result": str(result)[:500]})
+                return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def patch_openai(tracer: Any) -> None:
+    """Monkey-patch OpenAI's ChatCompletion.create to auto-trace calls.
+
+    Safe to call even if openai is not installed — silently returns.
+    """
+    try:
+        import openai  # noqa: F811
+    except ImportError:
+        return
+
+    _original = None
+
+    # Support openai >= 1.0 (client-based) and < 1.0 (module-based)
+    client_cls = getattr(openai, "OpenAI", None)
+    if client_cls is not None:
+        # openai >= 1.0: patch the completions create method on the class
+        chat_completions = getattr(
+            getattr(client_cls, "chat", None), "completions", None
+        )
+        if chat_completions is not None:
+            _original = getattr(chat_completions, "create", None)
+    else:
+        # openai < 1.0
+        chat = getattr(openai, "ChatCompletion", None)
+        if chat is not None:
+            _original = getattr(chat, "create", None)
+
+    if _original is None:
+        return
+
+    @functools.wraps(_original)
+    def traced_create(*args: Any, **kwargs: Any) -> Any:
+        model = kwargs.get("model", "unknown")
+        with tracer.trace(f"llm.openai.{model}") as ctx:
+            result = _original(*args, **kwargs)
+            # Try to extract usage
+            usage = getattr(result, "usage", None)
+            if usage is not None:
+                ctx.event(
+                    "llm.result",
+                    data={
+                        "model": model,
+                        "usage": {
+                            "prompt_tokens": getattr(usage, "prompt_tokens", 0),
+                            "completion_tokens": getattr(usage, "completion_tokens", 0),
+                            "total_tokens": getattr(usage, "total_tokens", 0),
+                        },
+                    },
+                )
+            return result
+
+    # Patch it back
+    if client_cls is not None and chat_completions is not None:
+        chat_completions.create = traced_create  # type: ignore[attr-defined]
+    else:
+        chat = getattr(openai, "ChatCompletion", None)
+        if chat is not None:
+            chat.create = traced_create  # type: ignore[attr-defined]
+
+
+def patch_anthropic(tracer: Any) -> None:
+    """Monkey-patch Anthropic's messages.create to auto-trace calls.
+
+    Safe to call even if anthropic is not installed — silently returns.
+    """
+    try:
+        import anthropic  # noqa: F811
+    except ImportError:
+        return
+
+    client_cls = getattr(anthropic, "Anthropic", None)
+    if client_cls is None:
+        return
+
+    messages = getattr(client_cls, "messages", None)
+    if messages is None:
+        return
+
+    _original = getattr(messages, "create", None)
+    if _original is None:
+        return
+
+    @functools.wraps(_original)
+    def traced_create(*args: Any, **kwargs: Any) -> Any:
+        model = kwargs.get("model", "unknown")
+        with tracer.trace(f"llm.anthropic.{model}") as ctx:
+            result = _original(*args, **kwargs)
+            usage = getattr(result, "usage", None)
+            if usage is not None:
+                ctx.event(
+                    "llm.result",
+                    data={
+                        "model": model,
+                        "usage": {
+                            "input_tokens": getattr(usage, "input_tokens", 0),
+                            "output_tokens": getattr(usage, "output_tokens", 0),
+                        },
+                    },
+                )
+            return result
+
+    messages.create = traced_create  # type: ignore[attr-defined]

agentguard/integrations/langchain.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import uuid
-from typing import Any, Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional
 
 from agentguard.guards import BudgetGuard, LoopGuard
 from agentguard.tracing import Tracer, TraceContext

agentguard/viewer.py

@@ -1,7 +1,7 @@
+"""Gantt-style trace viewer — self-contained HTML served via stdlib."""
 from __future__ import annotations
 
 import argparse
-import json
 import os
 import threading
 import webbrowser
@@ -10,82 +10,214 @@ from typing import Optional
 
 
 _HTML = """<!doctype html>
-<html lang=\"en\">
+<html lang="en">
   <head>
-    <meta charset=\"utf-8\" />
-    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>AgentGuard Trace Viewer</title>
     <style>
-      :root { --bg:#0f1115; --ink:#f1f5f9; --muted:#9aa4b2; --card:#171a21; --accent:#4ade80; }
-      body { margin:0; font-family: 'IBM Plex Sans', system-ui, sans-serif; background:var(--bg); color:var(--ink); }
-      header { padding:20px; border-bottom:1px solid #252a34; }
-      h1 { margin:0; font-size:22px; }
+      :root {
+        --bg:#0f1115; --ink:#f1f5f9; --muted:#9aa4b2; --card:#171a21;
+        --accent:#4ade80; --blue:#60a5fa; --purple:#a78bfa;
+        --green:#4ade80; --red:#f87171; --yellow:#fbbf24;
+        --border:#252a34;
+      }
+      * { box-sizing: border-box; }
+      body { margin:0; font-family:'IBM Plex Sans',system-ui,sans-serif; background:var(--bg); color:var(--ink); }
+      header { padding:16px 20px; border-bottom:1px solid var(--border); display:flex; align-items:center; gap:12px; }
+      h1 { margin:0; font-size:20px; font-weight:600; }
+      .badge { font-size:11px; background:#222833; padding:2px 8px; border-radius:10px; color:var(--muted); }
       .wrap { padding:20px; }
-      .stats { display:grid; grid-template-columns: repeat(auto-fit, minmax(180px,1fr)); gap:12px; }
-      .card { background:var(--card); padding:12px; border-radius:10px; border:1px solid #222833; }
-      .label { color:var(--muted); font-size:12px; }
-      table { width:100%; border-collapse: collapse; margin-top:16px; }
-      th, td { text-align:left; padding:8px; border-bottom:1px solid #222833; font-size:13px; }
-      code { color: var(--accent); }
+      .stats { display:grid; grid-template-columns:repeat(auto-fit,minmax(150px,1fr)); gap:10px; margin-bottom:20px; }
+      .card { background:var(--card); padding:10px 14px; border-radius:8px; border:1px solid var(--border); }
+      .card .label { color:var(--muted); font-size:11px; text-transform:uppercase; letter-spacing:.5px; }
+      .card .val { font-size:20px; font-weight:600; margin-top:2px; }
+      .card .val.green { color:var(--green); }
+
+      /* Gantt timeline */
+      .gantt { position:relative; margin-top:12px; }
+      .gantt-row { display:flex; align-items:center; height:28px; border-bottom:1px solid #1a1e27; cursor:pointer; }
+      .gantt-row:hover { background:#1a1e27; }
+      .gantt-label { width:220px; min-width:220px; padding:0 8px; font-size:12px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+      .gantt-track { flex:1; position:relative; height:100%; }
+      .gantt-bar { position:absolute; height:16px; top:6px; border-radius:3px; min-width:2px; transition: opacity .15s; }
+      .gantt-bar:hover { opacity:.85; }
+      .gantt-bar.reasoning { background:var(--blue); }
+      .gantt-bar.tool { background:var(--green); }
+      .gantt-bar.llm { background:var(--purple); }
+      .gantt-bar.guard { background:var(--yellow); }
+      .gantt-bar.error { background:var(--red); }
+      .gantt-bar.default { background:#64748b; }
+
+      /* Detail panel */
+      .detail { display:none; background:var(--card); border:1px solid var(--border); border-radius:8px; padding:16px; margin:12px 0; font-size:13px; }
+      .detail.open { display:block; }
+      .detail pre { background:#0f1115; padding:10px; border-radius:6px; overflow-x:auto; font-size:12px; color:var(--muted); }
+      .detail .dhead { font-weight:600; margin-bottom:8px; color:var(--accent); }
+
+      /* Legend */
+      .legend { display:flex; gap:16px; margin-bottom:14px; flex-wrap:wrap; }
+      .legend-item { display:flex; align-items:center; gap:5px; font-size:12px; color:var(--muted); }
+      .legend-dot { width:10px; height:10px; border-radius:2px; }
     </style>
   </head>
   <body>
     <header>
       <h1>AgentGuard Trace Viewer</h1>
-      <div class=\"label\">Loaded from local JSONL trace</div>
+      <span class="badge">Gantt Timeline</span>
     </header>
-    <div class=\"wrap\">
-      <div class=\"stats\" id=\"stats\"></div>
-      <table>
-        <thead>
-          <tr>
-            <th>ts</th>
-            <th>kind</th>
-            <th>name</th>
-            <th>trace_id</th>
-            <th>span_id</th>
-          </tr>
-        </thead>
-        <tbody id=\"rows\"></tbody>
-      </table>
+    <div class="wrap">
+      <div class="stats" id="stats"></div>
+      <div class="legend">
+        <div class="legend-item"><div class="legend-dot" style="background:var(--blue)"></div>Reasoning</div>
+        <div class="legend-item"><div class="legend-dot" style="background:var(--green)"></div>Tool</div>
+        <div class="legend-item"><div class="legend-dot" style="background:var(--purple)"></div>LLM</div>
+        <div class="legend-item"><div class="legend-dot" style="background:var(--yellow)"></div>Guard</div>
+        <div class="legend-item"><div class="legend-dot" style="background:var(--red)"></div>Error</div>
+      </div>
+      <div class="gantt" id="gantt"></div>
+      <div class="detail" id="detail"></div>
     </div>
     <script>
       async function load() {
         const res = await fetch('/trace');
         const text = await res.text();
-        const lines = text.split('\n').filter(Boolean);
+        const lines = text.split('\\n').filter(Boolean);
         const events = lines.map(l => JSON.parse(l));
 
-        const stats = {
-          total: events.length,
-          spans: events.filter(e => e.kind === 'span').length,
-          events: events.filter(e => e.kind === 'event').length,
-          reasoning: events.filter(e => e.name === 'reasoning.step').length,
-          loops: events.filter(e => e.name === 'guard.loop_detected').length,
-        };
+        if (!events.length) { document.getElementById('gantt').innerHTML = '<p style="color:var(--muted)">No events found.</p>'; return; }
+
+        // Stats
+        const totalEvents = events.length;
+        const spans = events.filter(e => e.kind === 'span');
+        const spanStarts = spans.filter(e => e.phase === 'start');
+        const spanEnds = spans.filter(e => e.phase === 'end');
+        const evts = events.filter(e => e.kind === 'event');
+        const reasoning = evts.filter(e => e.name === 'reasoning.step').length;
+        const toolResults = evts.filter(e => e.name === 'tool.result').length;
+        const llmResults = evts.filter(e => e.name === 'llm.result').length;
+        const loops = evts.filter(e => e.name === 'guard.loop_detected').length;
+        const errors = events.filter(e => e.error != null).length;
+
+        let totalMs = 0;
+        spanEnds.forEach(e => { if (e.duration_ms && e.duration_ms > totalMs) totalMs = e.duration_ms; });
+
+        const totalTokens = events.reduce((acc, e) => {
+          const d = e.data || {};
+          const u = d.token_usage || d.usage || {};
+          return acc + (u.total_tokens || 0);
+        }, 0);
 
         const statsEl = document.getElementById('stats');
-        statsEl.innerHTML = [
-          ['Total events', stats.total],
-          ['Spans', stats.spans],
-          ['Events', stats.events],
-          ['Reasoning steps', stats.reasoning],
-          ['Loop hits', stats.loops],
-        ].map(([k,v]) => `
-          <div class=\"card\"><div class=\"label\">${k}</div><div><code>${v}</code></div></div>
-        `).join('');
-
-        const rows = document.getElementById('rows');
-        rows.innerHTML = events.map(e => `
-          <tr>
-            <td>${new Date(e.ts * 1000).toISOString()}</td>
-            <td>${e.kind}</td>
-            <td>${e.name}</td>
-            <td>${e.trace_id}</td>
-            <td>${e.span_id}</td>
-          </tr>
-        `).join('');
+        const cards = [
+          ['Events', totalEvents, ''],
+          ['Spans', spanStarts.length, ''],
+          ['Run time', totalMs > 0 ? totalMs.toFixed(1) + ' ms' : '-', ''],
+          ['Reasoning', reasoning, ''],
+          ['Tool calls', toolResults, ''],
+          ['LLM calls', llmResults, ''],
+          ['Loop hits', loops, loops > 0 ? 'color:var(--red)' : ''],
+          ['Errors', errors, errors > 0 ? 'color:var(--red)' : ''],
+          ['Tokens', totalTokens || '-', ''],
+        ];
+        statsEl.innerHTML = cards.map(([k,v,s]) =>
+          `<div class="card"><div class="label">${k}</div><div class="val" style="${s}">${v}</div></div>`
+        ).join('');
+
+        // Build timeline rows
+        // Each event gets a row. Position = ts relative to min ts. Width = duration_ms or a small dot.
+        const minTs = Math.min(...events.map(e => e.ts));
+        const maxTs = Math.max(...events.map(e => e.ts));
+        const maxDur = Math.max(...spanEnds.map(e => e.duration_ms || 0), 1);
+        const timeRange = Math.max((maxTs - minTs) * 1000, maxDur, 1); // in ms
+
+        // Build span pairs: match start/end by span_id
+        const spanMap = {};
+        spans.forEach(e => {
+          if (!spanMap[e.span_id]) spanMap[e.span_id] = {};
+          if (e.phase === 'start') spanMap[e.span_id].start = e;
+          if (e.phase === 'end') spanMap[e.span_id].end = e;
+        });
+
+        // Build display rows: spans (paired) + standalone events
+        const rows = [];
+
+        // Add span rows
+        Object.values(spanMap).forEach(pair => {
+          const s = pair.start || pair.end;
+          const dur = pair.end ? (pair.end.duration_ms || 0) : 0;
+          const startMs = (s.ts - minTs) * 1000;
+          rows.push({
+            name: s.name,
+            startMs,
+            durMs: dur,
+            type: classifyName(s.name),
+            event: s,
+            endEvent: pair.end,
+            depth: s.parent_id ? 1 : 0,
+          });
+        });
+
+        // Add standalone events (not span start/end)
+        evts.forEach(e => {
+          const startMs = (e.ts - minTs) * 1000;
+          rows.push({
+            name: e.name,
+            startMs,
+            durMs: 0,
+            type: classifyName(e.name),
+            event: e,
+            endEvent: null,
+            depth: 1,
+          });
+        });
+
+        // Sort by startMs
+        rows.sort((a, b) => a.startMs - b.startMs || a.depth - b.depth);
+
+        const ganttEl = document.getElementById('gantt');
+        ganttEl.innerHTML = rows.map((r, i) => {
+          const left = (r.startMs / timeRange * 100).toFixed(4);
+          const width = r.durMs > 0 ? Math.max(r.durMs / timeRange * 100, 0.3).toFixed(4) : '0.3';
+          const indent = r.depth > 0 ? '&nbsp;&nbsp;' : '';
+          return `<div class="gantt-row" data-idx="${i}">
+            <div class="gantt-label" title="${r.name}">${indent}${r.name}</div>
+            <div class="gantt-track">
+              <div class="gantt-bar ${r.type}" style="left:${left}%;width:${width}%" title="${r.name} ${r.durMs > 0 ? r.durMs.toFixed(1)+'ms' : 'event'}"></div>
+            </div>
+          </div>`;
+        }).join('');
+
+        // Click to expand detail
+        const detailEl = document.getElementById('detail');
+        ganttEl.addEventListener('click', e => {
+          const row = e.target.closest('.gantt-row');
+          if (!row) return;
+          const idx = parseInt(row.dataset.idx);
+          const r = rows[idx];
+          const ev = r.endEvent || r.event;
+          detailEl.className = 'detail open';
+          detailEl.innerHTML = `
+            <div class="dhead">${r.name}</div>
+            <p><strong>Kind:</strong> ${ev.kind} &nbsp; <strong>Phase:</strong> ${ev.phase}
+            ${r.durMs > 0 ? '&nbsp; <strong>Duration:</strong> ' + r.durMs.toFixed(3) + ' ms' : ''}
+            ${ev.error ? '&nbsp; <strong style="color:var(--red)">Error:</strong> ' + ev.error.message : ''}
+            </p>
+            <p><strong>trace_id:</strong> ${ev.trace_id}<br><strong>span_id:</strong> ${ev.span_id}${ev.parent_id ? '<br><strong>parent_id:</strong> '+ev.parent_id : ''}</p>
+            <pre>${JSON.stringify(ev.data || {}, null, 2)}</pre>
+          `;
+        });
+      }
+
+      function classifyName(name) {
+        if (name.startsWith('reasoning')) return 'reasoning';
+        if (name.startsWith('tool')) return 'tool';
+        if (name.startsWith('llm')) return 'llm';
+        if (name.startsWith('guard')) return 'guard';
+        if (name.includes('error')) return 'error';
+        return 'default';
       }
+
       load();
     </script>
   </body>

{agentguard47-0.2.0.dist-info → agentguard47-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentguard47
-Version: 0.2.0
+Version: 0.3.0
 Summary: Lightweight observability and evaluation primitives for multi-agent systems
 Author: AgentGuard
 License-Expression: MIT
@@ -105,6 +105,45 @@ replayer = Replayer("runs.jsonl")
 resp = replayer.replay_call("llm", {"prompt": "hi"})
 ```
 
+## Evaluation as Code
+
+```python
+from agentguard import EvalSuite
+
+result = (
+    EvalSuite("traces.jsonl")
+    .assert_no_loops()
+    .assert_tool_called("search", min_times=1)
+    .assert_budget_under(tokens=50000)
+    .assert_completes_within(30.0)
+    .assert_no_errors()
+    .run()
+)
+print(result.summary)
+```
+
+## Auto-Instrumentation
+
+```python
+from agentguard import Tracer
+from agentguard.instrument import trace_agent, trace_tool
+
+tracer = Tracer()
+
+@trace_agent(tracer)
+def my_agent(query):
+    return search(query)
+
+@trace_tool(tracer)
+def search(q):
+    return f"results for {q}"
+
+# Monkey-patch OpenAI/Anthropic (safe if not installed)
+from agentguard.instrument import patch_openai, patch_anthropic
+patch_openai(tracer)
+patch_anthropic(tracer)
+```
+
 ## CLI
 
 ```bash
@@ -114,8 +153,11 @@ agentguard summarize traces.jsonl
 # Human-readable report
 agentguard report traces.jsonl
 
-# Open trace viewer in browser
+# Open Gantt trace viewer in browser
 agentguard view traces.jsonl
+
+# Run evaluation assertions
+agentguard eval traces.jsonl
 ```
 
 ## Trace Viewer
@@ -124,6 +166,8 @@ agentguard view traces.jsonl
 agentguard view traces.jsonl --port 8080
 ```
 
+Gantt-style timeline with color-coded spans (reasoning, tool, LLM, guard, error), click-to-expand detail panel, and aggregate stats.
+
 ## Integrations
 
 - LangChain: `agentguard.integrations.langchain`

agentguard47-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agentguard/__init__.py,sha256=l-c9Ub0P2AMc-h3DFGgLtUgpDSui3oM8ixwCGsuhjBE,550
+agentguard/cli.py,sha256=a9GYss-iRa8f70tOQ94FstNjPT4PJhMX-hy9WIacYfs,3972
+agentguard/evaluation.py,sha256=wsRHHxAJ6wh-_4q0axcZxWL8T8fvfJnIal14SIwI9jU,7858
+agentguard/guards.py,sha256=8GS3lHtr-pGwbbBSsBYKxsla02ipwCNoTj6kMRO_v6o,3147
+agentguard/instrument.py,sha256=EJguaWqrZGG3xGMt2NyR4lgTm7TERUPLnlOOxywQwKk,5891
+agentguard/recording.py,sha256=rOpO_kfVyh4StY0WKLJx_ZNjHYtadO48JgLNZwouFzE,2003
+agentguard/tracing.py,sha256=7yI4H3Q3ndbD7B7F4AOtnnYy-kZ7cbLMn1t_dXTVrQI,4133
+agentguard/viewer.py,sha256=vpqPUGGNHKYHThcIYcafWxh5epOh-x_BuqOB6z3p_Jw,12074
+agentguard/integrations/__init__.py,sha256=4UjBWIi91ESzy_0qwmo2ha5ZhhGGd3-2i8SOq9H9gwU,126
+agentguard/integrations/langchain.py,sha256=ioqfWfsSaNOeQdwBcmd1ik0YdMsZZUW85dB-IqwKofI,7649
+agentguard/sinks/__init__.py,sha256=PAgY0Y3tptapbNhnXEUYojTldfGokGZTJWVf-b58Qu0,51
+agentguard/sinks/http.py,sha256=TRmgZWd9kl3JEEZh9ppRRbcjuW-yXznYDRrQQGgdQ1Y,2615
+agentguard47-0.3.0.dist-info/METADATA,sha256=vQPyMg7MMUI8Two7fpxfmexLWYR0kWYvh8PenrN-ABU,4703
+agentguard47-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+agentguard47-0.3.0.dist-info/entry_points.txt,sha256=ubpnBAHVcWmjkLmnv-gIH0-GSPofUlZfoviZ4R9i5I0,51
+agentguard47-0.3.0.dist-info/top_level.txt,sha256=rEW5sAnjxXRs63ja2psmsMRMJJfi_3EAxf7crl1nHyw,11
+agentguard47-0.3.0.dist-info/RECORD,,

agentguard47-0.2.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-agentguard/__init__.py,sha256=r2lM31udiHzasnZFRCSnLwDbQDohUCG-5GKyMPeC6Z8,429
-agentguard/cli.py,sha256=GgCl7Q9VpZPMX-PsW3UYnNrC_1iy_bAcdiSa2qW685U,3485
-agentguard/guards.py,sha256=8GS3lHtr-pGwbbBSsBYKxsla02ipwCNoTj6kMRO_v6o,3147
-agentguard/recording.py,sha256=rOpO_kfVyh4StY0WKLJx_ZNjHYtadO48JgLNZwouFzE,2003
-agentguard/tracing.py,sha256=7yI4H3Q3ndbD7B7F4AOtnnYy-kZ7cbLMn1t_dXTVrQI,4133
-agentguard/viewer.py,sha256=uM21TYTXhq5zHu2tQP52bI5PFO9mmXzkP8z_m3sCkfY,4997
-agentguard/integrations/__init__.py,sha256=4UjBWIi91ESzy_0qwmo2ha5ZhhGGd3-2i8SOq9H9gwU,126
-agentguard/integrations/langchain.py,sha256=ppc27W6zFM2TYAQ1a2JI6bjNVWWMLmP5OapWfHQEP2o,7659
-agentguard/sinks/__init__.py,sha256=PAgY0Y3tptapbNhnXEUYojTldfGokGZTJWVf-b58Qu0,51
-agentguard/sinks/http.py,sha256=TRmgZWd9kl3JEEZh9ppRRbcjuW-yXznYDRrQQGgdQ1Y,2615
-agentguard47-0.2.0.dist-info/METADATA,sha256=uvTKR_RyZrB9yxKuAuz9x1NWZ7rQnE-U3H4b9ozQvks,3742
-agentguard47-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-agentguard47-0.2.0.dist-info/entry_points.txt,sha256=ubpnBAHVcWmjkLmnv-gIH0-GSPofUlZfoviZ4R9i5I0,51
-agentguard47-0.2.0.dist-info/top_level.txt,sha256=rEW5sAnjxXRs63ja2psmsMRMJJfi_3EAxf7crl1nHyw,11
-agentguard47-0.2.0.dist-info/RECORD,,