agentguard47 0.2.0__tar.gz

agentguard47-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/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",
+]

agentguard47-0.2.0/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()

agentguard47-0.2.0/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=(",", ":"))

agentguard47-0.2.0/agentguard/integrations/__init__.py

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