agentguard47 0.2.0__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1,24 @@
+from .tracing import Tracer
+from .guards import (
+    LoopGuard,
+    BudgetGuard,
+    TimeoutGuard,
+    LoopDetected,
+    BudgetExceeded,
+    TimeoutExceeded,
+)
+from .recording import Recorder, Replayer
+from .sinks import HttpSink
+
+__all__ = [
+    "Tracer",
+    "LoopGuard",
+    "BudgetGuard",
+    "TimeoutGuard",
+    "LoopDetected",
+    "BudgetExceeded",
+    "TimeoutExceeded",
+    "Recorder",
+    "Replayer",
+    "HttpSink",
+]

agentguard/cli.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter
+from typing import Any, Dict, List, Optional
+
+
+def _summarize(path: str) -> None:
+    total = 0
+    name_counts = Counter()
+    kind_counts = Counter()
+
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event: Dict[str, Any] = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            total += 1
+            name = event.get("name", "(unknown)")
+            kind = event.get("kind", "(unknown)")
+            name_counts[name] += 1
+            kind_counts[kind] += 1
+
+    print(f"events: {total}")
+    print("kinds:")
+    for kind, count in kind_counts.most_common():
+        print(f"  {kind}: {count}")
+    print("names:")
+    for name, count in name_counts.most_common(10):
+        print(f"  {name}: {count}")
+
+
+def _report(path: str) -> None:
+    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
+
+    if not events:
+        print("No events found.")
+        return
+
+    total = len(events)
+    kinds = Counter(e.get("kind", "(unknown)") for e in events)
+    names = Counter(e.get("name", "(unknown)") for e in events)
+    loop_hits = names.get("guard.loop_detected", 0)
+
+    span_durations: List[float] = []
+    for e in events:
+        if e.get("kind") == "span" and e.get("phase") == "end":
+            dur = e.get("duration_ms")
+            if isinstance(dur, (int, float)):
+                span_durations.append(float(dur))
+
+    total_ms: Optional[float] = None
+    if span_durations:
+        total_ms = max(span_durations)
+
+    print("AgentGuard report")
+    print(f"  Total events: {total}")
+    print(f"  Spans: {kinds.get('span', 0)}  Events: {kinds.get('event', 0)}")
+    if total_ms is not None:
+        print(f"  Approx run time: {total_ms:.1f} ms")
+    print(f"  Reasoning steps: {names.get('reasoning.step', 0)}")
+    print(f"  Tool results: {names.get('tool.result', 0)}")
+    print(f"  LLM results: {names.get('llm.result', 0)}")
+    if loop_hits:
+        print(f"  Loop guard triggered: {loop_hits} time(s)")
+    else:
+        print("  Loop guard triggered: 0")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="agentguard")
+    sub = parser.add_subparsers(dest="cmd")
+
+    summarize = sub.add_parser("summarize", help="Summarize a JSONL trace file")
+    summarize.add_argument("path")
+
+    report = sub.add_parser("report", help="Human-readable report for a JSONL trace file")
+    report.add_argument("path")
+
+    view = sub.add_parser("view", help="Open a local trace viewer in the browser")
+    view.add_argument("path")
+    view.add_argument("--port", type=int, default=8080)
+    view.add_argument("--no-open", action="store_true")
+
+    args = parser.parse_args()
+    if args.cmd == "summarize":
+        _summarize(args.path)
+    elif args.cmd == "report":
+        _report(args.path)
+    elif args.cmd == "view":
+        from agentguard.viewer import serve
+
+        serve(args.path, port=args.port, open_browser=not args.no_open)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

agentguard/guards.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Any, Deque, Dict, Optional, Tuple
+import json
+import time
+
+
+class LoopDetected(RuntimeError):
+    pass
+
+
+class BudgetExceeded(RuntimeError):
+    pass
+
+
+class TimeoutExceeded(RuntimeError):
+    pass
+
+
+class LoopGuard:
+    def __init__(self, max_repeats: int = 3, window: int = 6) -> None:
+        if max_repeats < 2:
+            raise ValueError("max_repeats must be >= 2")
+        if window < max_repeats:
+            raise ValueError("window must be >= max_repeats")
+        self._max_repeats = max_repeats
+        self._history: Deque[Tuple[str, str]] = deque(maxlen=window)
+
+    def check(self, tool_name: str, tool_args: Optional[Dict[str, Any]] = None) -> None:
+        args = tool_args or {}
+        signature = (tool_name, _stable_json(args))
+        self._history.append(signature)
+        if len(self._history) < self._max_repeats:
+            return
+        last_n = list(self._history)[-self._max_repeats :]
+        if len(set(last_n)) == 1:
+            raise LoopDetected(
+                f"Detected repeated tool call {tool_name} {self._max_repeats} times"
+            )
+
+    def reset(self) -> None:
+        self._history.clear()
+
+
+@dataclass
+class BudgetState:
+    tokens_used: int = 0
+    calls_used: int = 0
+
+
+class BudgetGuard:
+    def __init__(self, max_tokens: Optional[int] = None, max_calls: Optional[int] = None) -> None:
+        if max_tokens is None and max_calls is None:
+            raise ValueError("Provide max_tokens or max_calls")
+        self._max_tokens = max_tokens
+        self._max_calls = max_calls
+        self.state = BudgetState()
+
+    def consume(self, tokens: int = 0, calls: int = 0) -> None:
+        self.state.tokens_used += tokens
+        self.state.calls_used += calls
+        if self._max_tokens is not None and self.state.tokens_used > self._max_tokens:
+            raise BudgetExceeded(
+                f"Token budget exceeded: {self.state.tokens_used} > {self._max_tokens}"
+            )
+        if self._max_calls is not None and self.state.calls_used > self._max_calls:
+            raise BudgetExceeded(
+                f"Call budget exceeded: {self.state.calls_used} > {self._max_calls}"
+            )
+
+    def reset(self) -> None:
+        self.state = BudgetState()
+
+
+class TimeoutGuard:
+    def __init__(self, max_seconds: float) -> None:
+        if max_seconds <= 0:
+            raise ValueError("max_seconds must be > 0")
+        self._max_seconds = max_seconds
+        self._start: Optional[float] = None
+
+    def start(self) -> None:
+        self._start = time.monotonic()
+
+    def check(self) -> None:
+        if self._start is None:
+            raise RuntimeError("TimeoutGuard.start() must be called before check()")
+        if (time.monotonic() - self._start) > self._max_seconds:
+            raise TimeoutExceeded(
+                f"Run exceeded {self._max_seconds}s timeout"
+            )
+
+    def reset(self) -> None:
+        self._start = None
+
+
+def _stable_json(data: Dict[str, Any]) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"))

agentguard/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""Framework integration stubs."""
+
+from .langchain import AgentGuardCallbackHandler
+
+__all__ = ["AgentGuardCallbackHandler"]

agentguard/integrations/langchain.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, List, Optional, Sequence
+
+from agentguard.guards import BudgetGuard, LoopGuard
+from agentguard.tracing import Tracer, TraceContext
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler as _Base
+
+    _HAS_LANGCHAIN = True
+except ImportError:
+    _Base = object  # type: ignore[assignment,misc]
+    _HAS_LANGCHAIN = False
+
+
+class AgentGuardCallbackHandler(_Base):  # type: ignore[misc]
+    """LangChain callback handler that emits AgentGuard traces.
+
+    Tracks nested chains/tool calls as a span stack, optionally wiring
+    LoopGuard and BudgetGuard checks into tool invocations.
+
+    Works with ``langchain-core >= 0.1``. Install via::
+
+        pip install agentguard47[langchain]
+    """
+
+    def __init__(
+        self,
+        tracer: Optional[Tracer] = None,
+        loop_guard: Optional[LoopGuard] = None,
+        budget_guard: Optional[BudgetGuard] = None,
+    ) -> None:
+        if _HAS_LANGCHAIN:
+            super().__init__()
+        self._tracer = tracer or Tracer()
+        self._loop_guard = loop_guard
+        self._budget_guard = budget_guard
+        self._root_ctx: Optional[Any] = None
+        self._span_stack: List[TraceContext] = []
+        self._run_to_span: Dict[str, TraceContext] = {}
+
+    # -- chains ---------------------------------------------------------------
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        name = serialized.get("name") or serialized.get("id", ["chain"])[-1] if isinstance(serialized.get("id"), list) else serialized.get("name") or "chain"
+        if not self._span_stack:
+            ctx_mgr = self._tracer.trace(f"chain.{name}", data={"inputs": _safe_dict(inputs)})
+            ctx = ctx_mgr.__enter__()
+            self._root_ctx = ctx_mgr
+            self._span_stack.append(ctx)
+        else:
+            parent = self._span_stack[-1]
+            ctx = parent.span(f"chain.{name}", data={"inputs": _safe_dict(inputs)})
+            ctx.__enter__()
+            self._span_stack.append(ctx)
+        if run_id:
+            self._run_to_span[str(run_id)] = ctx
+
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        ctx.event("chain.outputs", data={"outputs": _safe_dict(outputs)})
+        ctx.__exit__(None, None, None)
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        ctx.__exit__(type(error), error, error.__traceback__)
+
+    # -- llm ------------------------------------------------------------------
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        parent = self._span_stack[-1] if self._span_stack else None
+        if parent is None:
+            self.on_chain_start({"name": "llm"}, {"prompts": prompts}, run_id=run_id)
+            return
+        ctx = parent.span("llm.call", data={"prompts": prompts})
+        ctx.__enter__()
+        self._span_stack.append(ctx)
+        if run_id:
+            self._run_to_span[str(run_id)] = ctx
+
+    def on_llm_end(
+        self,
+        response: Any,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        usage = _extract_token_usage(response)
+        payload: Dict[str, Any] = {"response": _safe_response(response)}
+        if usage:
+            payload["token_usage"] = usage
+            if self._budget_guard and "total_tokens" in usage:
+                self._budget_guard.consume(tokens=usage["total_tokens"])
+        ctx.event("llm.end", data=payload)
+        ctx.__exit__(None, None, None)
+
+    def on_llm_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        ctx.__exit__(type(error), error, error.__traceback__)
+
+    # -- tools ----------------------------------------------------------------
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        tool_name = serialized.get("name") or serialized.get("id", "tool")
+        if isinstance(tool_name, list):
+            tool_name = tool_name[-1]
+        if self._loop_guard:
+            self._loop_guard.check(tool_name=tool_name, tool_args={"input": input_str})
+        if self._budget_guard:
+            self._budget_guard.consume(calls=1)
+        parent = self._span_stack[-1] if self._span_stack else None
+        if parent is None:
+            self.on_chain_start({"name": "tool"}, {"input": input_str}, run_id=run_id)
+            return
+        ctx = parent.span(f"tool.{tool_name}", data={"input": input_str})
+        ctx.__enter__()
+        self._span_stack.append(ctx)
+        if run_id:
+            self._run_to_span[str(run_id)] = ctx
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        ctx.event("tool.result", data={"output": str(output)})
+        ctx.__exit__(None, None, None)
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: Optional[uuid.UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        ctx = self._pop_span(run_id)
+        if ctx is None:
+            return
+        ctx.__exit__(type(error), error, error.__traceback__)
+
+    # -- helpers --------------------------------------------------------------
+
+    def _pop_span(self, run_id: Optional[uuid.UUID]) -> Optional[TraceContext]:
+        if run_id and str(run_id) in self._run_to_span:
+            ctx = self._run_to_span.pop(str(run_id))
+            if ctx in self._span_stack:
+                self._span_stack.remove(ctx)
+            return ctx
+        if self._span_stack:
+            return self._span_stack.pop()
+        return None
+
+
+# -- utility functions --------------------------------------------------------
+
+
+def _safe_dict(d: Any) -> Dict[str, Any]:
+    if isinstance(d, dict):
+        return d
+    return {"value": repr(d)}
+
+
+def _safe_response(response: Any) -> Dict[str, Any]:
+    try:
+        if hasattr(response, "dict"):
+            return response.dict()
+        if hasattr(response, "model_dump"):
+            return response.model_dump()
+    except Exception:
+        pass
+    return {"repr": repr(response)}
+
+
+def _extract_token_usage(response: Any) -> Optional[Dict[str, Any]]:
+    for attr in ("llm_output", "response_metadata", "metadata"):
+        if hasattr(response, attr):
+            try:
+                data = getattr(response, attr)
+                if isinstance(data, dict):
+                    usage = data.get("token_usage") or data.get("usage")
+                    if isinstance(usage, dict):
+                        return usage
+            except Exception:
+                continue
+    return None

agentguard/recording.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+import json
+import time
+
+
+class Recorder:
+    def __init__(self, path: str) -> None:
+        self._path = path
+
+    def record_call(
+        self,
+        name: str,
+        request: Dict[str, Any],
+        response: Dict[str, Any],
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        event = {
+            "ts": time.time(),
+            "name": name,
+            "request": request,
+            "response": response,
+            "meta": meta or {},
+        }
+        with open(self._path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(event, sort_keys=True) + "\n")
+
+
+@dataclass
+class ReplayEntry:
+    name: str
+    request_key: str
+    response: Dict[str, Any]
+
+
+class Replayer:
+    def __init__(self, path: str) -> None:
+        self._entries = _load_entries(path)
+
+    def replay_call(self, name: str, request: Dict[str, Any]) -> Dict[str, Any]:
+        key = (name, _stable_json(request))
+        if key not in self._entries:
+            raise KeyError(f"No replay entry for {name}")
+        return self._entries[key]
+
+
+def _load_entries(path: str) -> Dict[Tuple[str, str], Dict[str, Any]]:
+    entries: Dict[Tuple[str, str], Dict[str, Any]] = {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                data = json.loads(line)
+                name = data.get("name")
+                request = data.get("request")
+                response = data.get("response")
+                if not name or request is None or response is None:
+                    continue
+                entries[(name, _stable_json(request))] = response
+    except FileNotFoundError:
+        return {}
+    return entries
+
+
+def _stable_json(data: Dict[str, Any]) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"))

agentguard/sinks/__init__.py

@@ -0,0 +1,3 @@
+from .http import HttpSink
+
+__all__ = ["HttpSink"]

agentguard/sinks/http.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from agentguard.tracing import TraceSink
+
+logger = logging.getLogger("agentguard.sinks.http")
+
+
+class HttpSink(TraceSink):
+    """Batched HTTP sink that POSTs JSONL trace events to a remote endpoint.
+
+    Uses only stdlib (urllib.request). Events are buffered and flushed
+    periodically in a background thread. Network failures are logged
+    but never crash the calling agent.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        api_key: Optional[str] = None,
+        batch_size: int = 10,
+        flush_interval: float = 5.0,
+    ) -> None:
+        self._url = url
+        self._api_key = api_key
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+
+        self._buffer: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        atexit.register(self.shutdown)
+
+    def emit(self, event: Dict[str, Any]) -> None:
+        batch = None
+        with self._lock:
+            self._buffer.append(event)
+            if len(self._buffer) >= self._batch_size:
+                batch = self._buffer[:]
+                self._buffer.clear()
+        if batch:
+            self._send(batch)
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._flush_interval):
+            self._flush()
+
+    def _flush(self) -> None:
+        with self._lock:
+            if not self._buffer:
+                return
+            batch = self._buffer[:]
+            self._buffer.clear()
+        self._send(batch)
+
+    def _send(self, batch: List[Dict[str, Any]]) -> None:
+        if not batch:
+            return
+        body = "\n".join(json.dumps(e, sort_keys=True) for e in batch).encode("utf-8")
+        headers: Dict[str, str] = {"Content-Type": "application/x-ndjson"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        req = urllib.request.Request(self._url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+        except Exception:
+            logger.warning("Failed to send trace batch to %s", self._url, exc_info=True)
+
+    def shutdown(self) -> None:
+        """Flush remaining events and stop the background thread."""
+        self._stop.set()
+        self._flush()
+        self._thread.join(timeout=5)

agentguard/tracing.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+import json
+import threading
+import time
+import uuid
+
+
+class TraceSink:
+    def emit(self, event: Dict[str, Any]) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class StdoutSink(TraceSink):
+    def emit(self, event: Dict[str, Any]) -> None:
+        print(json.dumps(event, sort_keys=True))
+
+
+class JsonlFileSink(TraceSink):
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+
+    def emit(self, event: Dict[str, Any]) -> None:
+        line = json.dumps(event, sort_keys=True)
+        with self._lock:
+            with open(self._path, "a", encoding="utf-8") as f:
+                f.write(line + "\n")
+
+
+@dataclass
+class TraceContext:
+    tracer: "Tracer"
+    trace_id: str
+    span_id: str
+    parent_id: Optional[str]
+    name: str
+    data: Optional[Dict[str, Any]]
+    _start_time: Optional[float] = None
+
+    def __enter__(self) -> "TraceContext":
+        self._start_time = time.perf_counter()
+        self.tracer._emit(
+            kind="span",
+            phase="start",
+            trace_id=self.trace_id,
+            span_id=self.span_id,
+            parent_id=self.parent_id,
+            name=self.name,
+            data=self.data,
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        end = time.perf_counter()
+        duration_ms = None
+        if self._start_time is not None:
+            duration_ms = (end - self._start_time) * 1000.0
+        error = None
+        if exc is not None:
+            error = {
+                "type": getattr(exc_type, "__name__", "Exception"),
+                "message": str(exc),
+            }
+        self.tracer._emit(
+            kind="span",
+            phase="end",
+            trace_id=self.trace_id,
+            span_id=self.span_id,
+            parent_id=self.parent_id,
+            name=self.name,
+            data=self.data,
+            duration_ms=duration_ms,
+            error=error,
+        )
+        # Do not suppress exceptions
+        return False
+
+    def span(self, name: str, data: Optional[Dict[str, Any]] = None) -> "TraceContext":
+        return TraceContext(
+            tracer=self.tracer,
+            trace_id=self.trace_id,
+            span_id=_new_id(),
+            parent_id=self.span_id,
+            name=name,
+            data=data,
+        )
+
+    def event(self, name: str, data: Optional[Dict[str, Any]] = None) -> None:
+        self.tracer._emit(
+            kind="event",
+            phase="emit",
+            trace_id=self.trace_id,
+            span_id=self.span_id,
+            parent_id=self.parent_id,
+            name=name,
+            data=data,
+        )
+
+
+class Tracer:
+    def __init__(self, sink: Optional[TraceSink] = None, service: str = "app") -> None:
+        self._sink = sink or StdoutSink()
+        self._service = service
+
+    @contextmanager
+    def trace(self, name: str, data: Optional[Dict[str, Any]] = None) -> TraceContext:
+        ctx = TraceContext(
+            tracer=self,
+            trace_id=_new_id(),
+            span_id=_new_id(),
+            parent_id=None,
+            name=name,
+            data=data,
+        )
+        with ctx:
+            yield ctx
+
+    def _emit(
+        self,
+        *,
+        kind: str,
+        phase: str,
+        trace_id: str,
+        span_id: str,
+        parent_id: Optional[str],
+        name: str,
+        data: Optional[Dict[str, Any]] = None,
+        duration_ms: Optional[float] = None,
+        error: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        event = {
+            "service": self._service,
+            "kind": kind,
+            "phase": phase,
+            "trace_id": trace_id,
+            "span_id": span_id,
+            "parent_id": parent_id,
+            "name": name,
+            "ts": time.time(),
+            "duration_ms": duration_ms,
+            "data": data or {},
+            "error": error,
+        }
+        self._sink.emit(event)
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex

agentguard/viewer.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Optional
+
+
+_HTML = """<!doctype html>
+<html lang=\"en\">
+  <head>
+    <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; }
+      .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); }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>AgentGuard Trace Viewer</h1>
+      <div class=\"label\">Loaded from local JSONL trace</div>
+    </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>
+    <script>
+      async function load() {
+        const res = await fetch('/trace');
+        const text = await res.text();
+        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,
+        };
+
+        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('');
+      }
+      load();
+    </script>
+  </body>
+</html>
+"""
+
+
+class _Handler(BaseHTTPRequestHandler):
+    trace_path: Optional[str] = None
+
+    def do_GET(self) -> None:  # noqa: N802
+        if self.path == "/":
+            self._send(200, _HTML, content_type="text/html")
+            return
+        if self.path == "/trace":
+            if not self.trace_path or not os.path.exists(self.trace_path):
+                self._send(404, "trace not found")
+                return
+            with open(self.trace_path, "r", encoding="utf-8") as f:
+                data = f.read()
+            self._send(200, data, content_type="text/plain")
+            return
+        self._send(404, "not found")
+
+    def log_message(self, format: str, *args) -> None:  # noqa: A003
+        return
+
+    def _send(self, status: int, body: str, content_type: str = "text/plain") -> None:
+        encoded = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+
+def serve(trace_path: str, port: int = 8080, open_browser: bool = True) -> None:
+    handler = _Handler
+    handler.trace_path = trace_path
+
+    server = HTTPServer(("127.0.0.1", port), handler)
+
+    if open_browser:
+        threading.Timer(0.4, lambda: webbrowser.open(f"http://127.0.0.1:{port}")).start()
+
+    print(f"Viewer running at http://127.0.0.1:{port}")
+    server.serve_forever()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="agentguard-view")
+    parser.add_argument("path", help="Path to JSONL trace")
+    parser.add_argument("--port", type=int, default=8080)
+    parser.add_argument("--no-open", action="store_true")
+    args = parser.parse_args()
+
+    serve(args.path, port=args.port, open_browser=not args.no_open)
+
+
+if __name__ == "__main__":
+    main()

agentguard47-0.2.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: agentguard47
+Version: 0.2.0
+Summary: Lightweight observability and evaluation primitives for multi-agent systems
+Author: AgentGuard
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bmdhodl/agent47
+Project-URL: Repository, https://github.com/bmdhodl/agent47
+Project-URL: Issues, https://github.com/bmdhodl/agent47/issues
+Keywords: agents,observability,tracing,multi-agent,llm,guardrails,replay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+
+# AgentGuard SDK (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/agentguard47)](https://pypi.org/project/agentguard47/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/bmdhodl/agent47/blob/main/LICENSE)
+
+Lightweight, zero-dependency observability for multi-agent AI systems. Trace reasoning steps, catch loops, guard budgets, and replay runs deterministically.
+
+## Install
+
+```bash
+pip install agentguard47
+```
+
+With LangChain support:
+```bash
+pip install agentguard47[langchain]
+```
+
+## Quickstart
+
+```python
+from agentguard import Tracer, LoopGuard, BudgetGuard
+
+tracer = Tracer()
+loop_guard = LoopGuard(max_repeats=3)
+budget_guard = BudgetGuard(max_tokens=10000)
+
+with tracer.trace("agent.run") as span:
+    span.event("reasoning.step", data={"thought": "search docs"})
+
+    loop_guard.check(tool_name="search", tool_args={"query": "agent loops"})
+    budget_guard.record_tokens(150)
+
+    with span.span("tool.call", data={"tool": "search"}):
+        pass  # call your tool here
+```
+
+## Tracing
+
+```python
+from agentguard.tracing import Tracer
+
+tracer = Tracer()
+
+with tracer.trace("agent.run", data={"user_id": "u123"}) as span:
+    span.event("reasoning.step", data={"step": 1, "thought": "search docs"})
+    with span.span("tool.call", data={"tool": "search", "query": "agent loops"}):
+        pass
+```
+
+## Guards
+
+```python
+from agentguard.guards import LoopGuard, BudgetGuard, TimeoutGuard
+
+# Detect repeated tool calls
+guard = LoopGuard(max_repeats=3)
+guard.check(tool_name="search", tool_args={"query": "agent loops"})
+
+# Track token and call budgets
+budget = BudgetGuard(max_tokens=50000, max_calls=100)
+budget.record_tokens(150)
+budget.record_call()
+
+# Enforce wall-clock time limits
+timeout = TimeoutGuard(max_seconds=30)
+timeout.start()
+timeout.check()  # raises TimeoutExceeded if over limit
+```
+
+## Replay
+
+```python
+from agentguard.recording import Recorder, Replayer
+
+recorder = Recorder("runs.jsonl")
+recorder.record_call("llm", {"prompt": "hi"}, {"text": "hello"})
+
+replayer = Replayer("runs.jsonl")
+resp = replayer.replay_call("llm", {"prompt": "hi"})
+```
+
+## CLI
+
+```bash
+# Summarize trace events
+agentguard summarize traces.jsonl
+
+# Human-readable report
+agentguard report traces.jsonl
+
+# Open trace viewer in browser
+agentguard view traces.jsonl
+```
+
+## Trace Viewer
+
+```bash
+agentguard view traces.jsonl --port 8080
+```
+
+## Integrations
+
+- LangChain: `agentguard.integrations.langchain`
+
+## Links
+
+- [GitHub](https://github.com/bmdhodl/agent47)
+- [Trace Schema](https://github.com/bmdhodl/agent47/blob/main/docs/trace_schema.md)
+- [Examples](https://github.com/bmdhodl/agent47/tree/main/sdk/examples)

agentguard47-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+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,,

agentguard47-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentguard47-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentguard = agentguard.cli:main

agentguard47-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentguard