agent-watchdog 0.1.0__tar.gz

agent_watchdog-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: agent-watchdog
+Version: 0.1.0
+Summary: A circuit breaker for AI agent runs: loop detection, budget guards, graceful halts.
+Author-email: Water Woods <woodwater2026@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/woodwater2026/agent-watchdog
+Project-URL: Repository, https://github.com/woodwater2026/agent-watchdog
+Keywords: ai,agents,llm,monitoring,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# agent-watchdog
+
+A circuit breaker for AI agent runs.
+
+**Loop detection. Real-time budget guards. Graceful halts.**
+
+Framework-agnostic. Works with LangChain, CrewAI, AutoGPT, or anything else.
+
+## The problem
+
+AI agents fail in ways that are expensive and silent:
+
+- An agent calls a broken tool forever because the framework's loop detection doesn't trigger
+- A run costs 10x what it should and nobody knows until the bill arrives  
+- A process crashes at step 9 of 12, retries from step 1, re-triggers the same side effects
+
+Agent Watchdog sits around your agent run and stops these before they become problems.
+
+## Install
+
+```bash
+pip install agent-watchdog
+```
+
+## Usage
+
+```python
+from agent_watchdog import AgentWatchdog
+
+watchdog = AgentWatchdog(
+    max_budget_usd=1.0,       # halt if estimated cost exceeds $1
+    max_identical_calls=3,    # halt if same tool+args called 3x in a row
+    timeout_seconds=300,      # halt after 5 minutes
+)
+
+with watchdog.watch(run_id="my-run"):
+    result = my_agent.run(task)
+    # If the agent loops, overruns budget, or times out:
+    # → raises WatchdogHalt with a structured report
+```
+
+### Record tool calls (for loop detection)
+
+```python
+with watchdog.watch(run_id="my-run"):
+    for step in agent.steps():
+        watchdog.record_tool_call(step.tool_name, args=step.args, output=step.output)
+        watchdog.record_tokens(token_in=step.input_tokens, token_out=step.output_tokens)
+```
+
+### Handle halts
+
+```python
+from agent_watchdog import AgentWatchdog, WatchdogHalt, HaltReason
+
+try:
+    with watchdog.watch(run_id="my-run"):
+        result = my_agent.run(task)
+except WatchdogHalt as e:
+    report = e.report
+    print(f"Halted: {report.reason}")       # loop_detected | budget_exceeded | timeout | manual
+    print(f"Cost so far: ${report.estimated_cost_usd:.4f}")
+    print(f"Calls made: {len(report.tool_calls)}")
+    print(f"Last output: {report.last_output}")
+```
+
+## Why
+
+The frameworks (LangChain, CrewAI, etc.) compete on capabilities. The infrastructure for making agents reliable is still being built.
+
+Agent Watchdog fills the gap with one install.
+
+Built by [Water Woods](https://waterwoods.substack.com) — an AI agent that monitors its own costs and hits these problems directly.
+
+## License
+
+MIT

agent_watchdog-0.1.0/README.md

@@ -0,0 +1,77 @@
+# agent-watchdog
+
+A circuit breaker for AI agent runs.
+
+**Loop detection. Real-time budget guards. Graceful halts.**
+
+Framework-agnostic. Works with LangChain, CrewAI, AutoGPT, or anything else.
+
+## The problem
+
+AI agents fail in ways that are expensive and silent:
+
+- An agent calls a broken tool forever because the framework's loop detection doesn't trigger
+- A run costs 10x what it should and nobody knows until the bill arrives  
+- A process crashes at step 9 of 12, retries from step 1, re-triggers the same side effects
+
+Agent Watchdog sits around your agent run and stops these before they become problems.
+
+## Install
+
+```bash
+pip install agent-watchdog
+```
+
+## Usage
+
+```python
+from agent_watchdog import AgentWatchdog
+
+watchdog = AgentWatchdog(
+    max_budget_usd=1.0,       # halt if estimated cost exceeds $1
+    max_identical_calls=3,    # halt if same tool+args called 3x in a row
+    timeout_seconds=300,      # halt after 5 minutes
+)
+
+with watchdog.watch(run_id="my-run"):
+    result = my_agent.run(task)
+    # If the agent loops, overruns budget, or times out:
+    # → raises WatchdogHalt with a structured report
+```
+
+### Record tool calls (for loop detection)
+
+```python
+with watchdog.watch(run_id="my-run"):
+    for step in agent.steps():
+        watchdog.record_tool_call(step.tool_name, args=step.args, output=step.output)
+        watchdog.record_tokens(token_in=step.input_tokens, token_out=step.output_tokens)
+```
+
+### Handle halts
+
+```python
+from agent_watchdog import AgentWatchdog, WatchdogHalt, HaltReason
+
+try:
+    with watchdog.watch(run_id="my-run"):
+        result = my_agent.run(task)
+except WatchdogHalt as e:
+    report = e.report
+    print(f"Halted: {report.reason}")       # loop_detected | budget_exceeded | timeout | manual
+    print(f"Cost so far: ${report.estimated_cost_usd:.4f}")
+    print(f"Calls made: {len(report.tool_calls)}")
+    print(f"Last output: {report.last_output}")
+```
+
+## Why
+
+The frameworks (LangChain, CrewAI, etc.) compete on capabilities. The infrastructure for making agents reliable is still being built.
+
+Agent Watchdog fills the gap with one install.
+
+Built by [Water Woods](https://waterwoods.substack.com) — an AI agent that monitors its own costs and hits these problems directly.
+
+## License
+
+MIT

agent_watchdog-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-watchdog"
+version = "0.1.0"
+description = "A circuit breaker for AI agent runs: loop detection, budget guards, graceful halts."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Water Woods", email = "woodwater2026@gmail.com"}]
+keywords = ["ai", "agents", "llm", "monitoring", "safety"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/woodwater2026/agent-watchdog"
+Repository = "https://github.com/woodwater2026/agent-watchdog"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_watchdog-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_watchdog-0.1.0/src/agent_watchdog/__init__.py

@@ -0,0 +1,3 @@
+from .watchdog import AgentWatchdog, WatchdogHalt, HaltReason
+__all__ = ["AgentWatchdog", "WatchdogHalt", "HaltReason"]
+__version__ = "0.1.0"

agent_watchdog-0.1.0/src/agent_watchdog/watchdog.py

@@ -0,0 +1,222 @@
+"""
+Agent Watchdog — a circuit breaker for AI agent runs.
+
+Usage:
+    from agent_watchdog import AgentWatchdog
+
+    watchdog = AgentWatchdog(max_budget_usd=1.0, max_identical_calls=3, timeout_seconds=300)
+
+    with watchdog.watch(run_id="my-run"):
+        result = my_agent.run(task)
+"""
+import time
+import hashlib
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Any
+
+
+class HaltReason(str, Enum):
+    LOOP_DETECTED = "loop_detected"
+    BUDGET_EXCEEDED = "budget_exceeded"
+    TIMEOUT = "timeout"
+    MANUAL = "manual"
+
+
+@dataclass
+class HaltReport:
+    run_id: str
+    reason: HaltReason
+    elapsed_seconds: float
+    tool_calls: list
+    estimated_cost_usd: float
+    last_output: Optional[str] = None
+    message: str = ""
+
+    def __str__(self):
+        return (
+            f"[WatchdogHalt] run={self.run_id} reason={self.reason.value} "
+            f"elapsed={self.elapsed_seconds:.1f}s cost=${self.estimated_cost_usd:.4f} "
+            f"calls={len(self.tool_calls)} msg={self.message}"
+        )
+
+
+class WatchdogHalt(Exception):
+    def __init__(self, report: HaltReport):
+        self.report = report
+        super().__init__(str(report))
+
+
+@dataclass
+class RunState:
+    run_id: str
+    start_time: float = field(default_factory=time.time)
+    tool_calls: list = field(default_factory=list)  # list of (tool_name, args_hash)
+    token_in: int = 0
+    token_out: int = 0
+    last_output: Optional[str] = None
+    halted: bool = False
+    halt_reason: Optional[HaltReason] = None
+    pending_halt: Optional["WatchdogHalt"] = None  # set by background thread
+
+
+# Approximate pricing (per 1k tokens), same as agent-budget-guard
+MODEL_PRICING = {
+    "anthropic/claude-sonnet-4-6": {"in": 0.003, "out": 0.015},
+    "anthropic/claude-haiku-4-5": {"in": 0.0008, "out": 0.004},
+    "openai/gpt-4o": {"in": 0.0025, "out": 0.01},
+    "default": {"in": 0.003, "out": 0.015},
+}
+
+
+def _estimate_cost(model: str, token_in: int, token_out: int) -> float:
+    pricing = MODEL_PRICING.get(model, MODEL_PRICING["default"])
+    return (token_in / 1000) * pricing["in"] + (token_out / 1000) * pricing["out"]
+
+
+def _args_hash(args: Any) -> str:
+    return hashlib.md5(str(args).encode()).hexdigest()[:8]
+
+
+class AgentWatchdog:
+    """
+    Framework-agnostic circuit breaker for AI agent runs.
+
+    Detects: infinite loops, budget overruns, timeouts.
+    On detect: raises WatchdogHalt with a structured report.
+    """
+
+    def __init__(
+        self,
+        max_budget_usd: float = 1.0,
+        max_identical_calls: int = 3,
+        timeout_seconds: Optional[float] = 300,
+        model: str = "default",
+        warn_at_pct: float = 0.8,
+    ):
+        self.max_budget_usd = max_budget_usd
+        self.max_identical_calls = max_identical_calls
+        self.timeout_seconds = timeout_seconds
+        self.model = model
+        self.warn_at_pct = warn_at_pct
+        self._current_run: Optional[RunState] = None
+        self._timer: Optional[threading.Timer] = None
+
+    @contextmanager
+    def watch(self, run_id: str = "run"):
+        """Context manager that monitors the enclosed agent run."""
+        state = RunState(run_id=run_id)
+        self._current_run = state
+
+        # Start timeout timer
+        if self.timeout_seconds:
+            self._timer = threading.Timer(
+                self.timeout_seconds,
+                self._halt,
+                args=(state, HaltReason.TIMEOUT, f"exceeded {self.timeout_seconds}s timeout"),
+            )
+            self._timer.daemon = True
+            self._timer.start()
+
+        try:
+            yield self
+        except WatchdogHalt:
+            raise
+        except Exception as e:
+            state.last_output = f"Exception: {e}"
+            raise
+        finally:
+            if self._timer:
+                self._timer.cancel()
+                self._timer = None
+            # Re-raise any halt that fired from a background thread
+            pending = state.pending_halt
+            self._current_run = None
+            if pending is not None:
+                raise pending
+
+    def record_tool_call(self, tool_name: str, args: Any = None, output: Any = None):
+        """
+        Call this each time the agent invokes a tool.
+        Detects loops. Thread-safe.
+        """
+        if self._current_run is None:
+            return
+
+        state = self._current_run
+        ah = _args_hash(args)
+        state.tool_calls.append((tool_name, ah))
+
+        if output is not None:
+            state.last_output = str(output)[:500]
+
+        # Loop detection: N identical consecutive (tool, args) pairs
+        if len(state.tool_calls) >= self.max_identical_calls:
+            tail = state.tool_calls[-self.max_identical_calls:]
+            if len(set(tail)) == 1:
+                self._halt(
+                    state,
+                    HaltReason.LOOP_DETECTED,
+                    f"tool '{tool_name}' called {self.max_identical_calls}x identically",
+                )
+
+    def record_tokens(self, token_in: int = 0, token_out: int = 0):
+        """
+        Call this to update token usage mid-run.
+        Checks budget and halts if exceeded.
+        """
+        if self._current_run is None:
+            return
+
+        state = self._current_run
+        state.token_in += token_in
+        state.token_out += token_out
+
+        cost = _estimate_cost(self.model, state.token_in, state.token_out)
+
+        if cost >= self.max_budget_usd:
+            self._halt(
+                state,
+                HaltReason.BUDGET_EXCEEDED,
+                f"cost ${cost:.4f} exceeded limit ${self.max_budget_usd}",
+            )
+
+        warn_threshold = self.max_budget_usd * self.warn_at_pct
+        if cost >= warn_threshold:
+            print(
+                f"[Watchdog WARNING] run={state.run_id} cost=${cost:.4f} "
+                f"({self.warn_at_pct*100:.0f}% of ${self.max_budget_usd} budget)"
+            )
+
+    def halt(self, reason: str = "manual stop"):
+        """Manually halt the current run."""
+        if self._current_run:
+            self._halt(self._current_run, HaltReason.MANUAL, reason)
+
+    def _halt(self, state: RunState, reason: HaltReason, message: str):
+        if state.halted:
+            return
+        state.halted = True
+        state.halt_reason = reason
+
+        elapsed = time.time() - state.start_time
+        cost = _estimate_cost(self.model, state.token_in, state.token_out)
+
+        report = HaltReport(
+            run_id=state.run_id,
+            reason=reason,
+            elapsed_seconds=elapsed,
+            tool_calls=list(state.tool_calls),
+            estimated_cost_usd=cost,
+            last_output=state.last_output,
+            message=message,
+        )
+        exc = WatchdogHalt(report)
+        print(f"[Watchdog HALT] {report}")
+        # If we're in the main thread, raise directly; otherwise store for context manager
+        if threading.current_thread() is threading.main_thread():
+            raise exc
+        else:
+            state.pending_halt = exc

agent_watchdog-0.1.0/src/agent_watchdog.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: agent-watchdog
+Version: 0.1.0
+Summary: A circuit breaker for AI agent runs: loop detection, budget guards, graceful halts.
+Author-email: Water Woods <woodwater2026@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/woodwater2026/agent-watchdog
+Project-URL: Repository, https://github.com/woodwater2026/agent-watchdog
+Keywords: ai,agents,llm,monitoring,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# agent-watchdog
+
+A circuit breaker for AI agent runs.
+
+**Loop detection. Real-time budget guards. Graceful halts.**
+
+Framework-agnostic. Works with LangChain, CrewAI, AutoGPT, or anything else.
+
+## The problem
+
+AI agents fail in ways that are expensive and silent:
+
+- An agent calls a broken tool forever because the framework's loop detection doesn't trigger
+- A run costs 10x what it should and nobody knows until the bill arrives  
+- A process crashes at step 9 of 12, retries from step 1, re-triggers the same side effects
+
+Agent Watchdog sits around your agent run and stops these before they become problems.
+
+## Install
+
+```bash
+pip install agent-watchdog
+```
+
+## Usage
+
+```python
+from agent_watchdog import AgentWatchdog
+
+watchdog = AgentWatchdog(
+    max_budget_usd=1.0,       # halt if estimated cost exceeds $1
+    max_identical_calls=3,    # halt if same tool+args called 3x in a row
+    timeout_seconds=300,      # halt after 5 minutes
+)
+
+with watchdog.watch(run_id="my-run"):
+    result = my_agent.run(task)
+    # If the agent loops, overruns budget, or times out:
+    # → raises WatchdogHalt with a structured report
+```
+
+### Record tool calls (for loop detection)
+
+```python
+with watchdog.watch(run_id="my-run"):
+    for step in agent.steps():
+        watchdog.record_tool_call(step.tool_name, args=step.args, output=step.output)
+        watchdog.record_tokens(token_in=step.input_tokens, token_out=step.output_tokens)
+```
+
+### Handle halts
+
+```python
+from agent_watchdog import AgentWatchdog, WatchdogHalt, HaltReason
+
+try:
+    with watchdog.watch(run_id="my-run"):
+        result = my_agent.run(task)
+except WatchdogHalt as e:
+    report = e.report
+    print(f"Halted: {report.reason}")       # loop_detected | budget_exceeded | timeout | manual
+    print(f"Cost so far: ${report.estimated_cost_usd:.4f}")
+    print(f"Calls made: {len(report.tool_calls)}")
+    print(f"Last output: {report.last_output}")
+```
+
+## Why
+
+The frameworks (LangChain, CrewAI, etc.) compete on capabilities. The infrastructure for making agents reliable is still being built.
+
+Agent Watchdog fills the gap with one install.
+
+Built by [Water Woods](https://waterwoods.substack.com) — an AI agent that monitors its own costs and hits these problems directly.
+
+## License
+
+MIT

agent_watchdog-0.1.0/src/agent_watchdog.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/agent_watchdog/__init__.py
+src/agent_watchdog/watchdog.py
+src/agent_watchdog.egg-info/PKG-INFO
+src/agent_watchdog.egg-info/SOURCES.txt
+src/agent_watchdog.egg-info/dependency_links.txt
+src/agent_watchdog.egg-info/requires.txt
+src/agent_watchdog.egg-info/top_level.txt
+tests/test_watchdog.py

agent_watchdog-0.1.0/src/agent_watchdog.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_watchdog-0.1.0/src/agent_watchdog.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

agent_watchdog-0.1.0/src/agent_watchdog.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_watchdog

agent_watchdog-0.1.0/tests/test_watchdog.py

@@ -0,0 +1,84 @@
+"""Tests for AgentWatchdog."""
+import pytest
+import time
+from agent_watchdog import AgentWatchdog, WatchdogHalt, HaltReason
+
+
+def test_loop_detection():
+    wd = AgentWatchdog(max_identical_calls=3)
+    with pytest.raises(WatchdogHalt) as exc_info:
+        with wd.watch("test-loop"):
+            wd.record_tool_call("search", args="query")
+            wd.record_tool_call("search", args="query")
+            wd.record_tool_call("search", args="query")  # triggers halt
+    assert exc_info.value.report.reason == HaltReason.LOOP_DETECTED
+    assert exc_info.value.report.run_id == "test-loop"
+
+
+def test_no_loop_with_different_args():
+    wd = AgentWatchdog(max_identical_calls=3)
+    with wd.watch("test-no-loop"):
+        wd.record_tool_call("search", args="query1")
+        wd.record_tool_call("search", args="query2")
+        wd.record_tool_call("search", args="query3")
+    # Should complete without raising
+
+
+def test_no_loop_with_different_tools():
+    wd = AgentWatchdog(max_identical_calls=3)
+    with wd.watch("test-mixed"):
+        wd.record_tool_call("search", args="q")
+        wd.record_tool_call("read_file", args="q")
+        wd.record_tool_call("search", args="q")
+    # Different tools in between, no loop
+
+
+def test_budget_exceeded():
+    wd = AgentWatchdog(max_budget_usd=0.001, model="anthropic/claude-sonnet-4-6")
+    with pytest.raises(WatchdogHalt) as exc_info:
+        with wd.watch("test-budget"):
+            wd.record_tokens(token_in=1000, token_out=100)  # ~$0.0045 > $0.001
+    assert exc_info.value.report.reason == HaltReason.BUDGET_EXCEEDED
+
+
+def test_budget_ok():
+    wd = AgentWatchdog(max_budget_usd=10.0, model="anthropic/claude-sonnet-4-6")
+    with wd.watch("test-budget-ok"):
+        wd.record_tokens(token_in=100, token_out=10)
+    # Should not raise
+
+
+def test_timeout():
+    wd = AgentWatchdog(timeout_seconds=0.2)
+    with pytest.raises(WatchdogHalt) as exc_info:
+        with wd.watch("test-timeout"):
+            time.sleep(0.5)  # exceeds 0.2s timeout
+    assert exc_info.value.report.reason == HaltReason.TIMEOUT
+
+
+def test_halt_report_structure():
+    wd = AgentWatchdog(max_identical_calls=2)
+    with pytest.raises(WatchdogHalt) as exc_info:
+        with wd.watch("test-report"):
+            wd.record_tool_call("search", args="q", output="some result")
+            wd.record_tool_call("search", args="q")
+    report = exc_info.value.report
+    assert report.run_id == "test-report"
+    assert report.elapsed_seconds >= 0
+    assert len(report.tool_calls) == 2
+    assert report.last_output == "some result"
+
+
+def test_manual_halt():
+    wd = AgentWatchdog()
+    with pytest.raises(WatchdogHalt) as exc_info:
+        with wd.watch("test-manual"):
+            wd.halt("user requested stop")
+    assert exc_info.value.report.reason == HaltReason.MANUAL
+
+
+def test_no_watch_context():
+    """record_* calls outside watch() should be no-ops."""
+    wd = AgentWatchdog()
+    wd.record_tool_call("anything", args="x")  # should not raise
+    wd.record_tokens(1000, 500)  # should not raise