agent-loop-guard 0.1.0__tar.gz

agent_loop_guard-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.eggs/
+
+CLAUDE.md
+PLAN.txt
+.env
+.env.local

agent_loop_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuartzUnit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_loop_guard-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: agent-loop-guard
+Version: 0.1.0
+Summary: Framework-agnostic agent loop detection — sliding window similarity scoring to catch stuck agents
+Project-URL: Homepage, https://github.com/QuartzUnit/agent-loop-guard
+Project-URL: Repository, https://github.com/QuartzUnit/agent-loop-guard
+Project-URL: Issues, https://github.com/QuartzUnit/agent-loop-guard/issues
+Author-email: hmj <hmj@quartzunit.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai-agent,detection,guardrail,llm,loop,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# agent-loop-guard
+
+Framework-agnostic agent loop detection — sliding window similarity scoring to catch stuck agents.
+
+## Install
+
+```bash
+pip install agent-loop-guard
+```
+
+## Quick Start
+
+```python
+from loop_guard import LoopGuard, Action
+
+guard = LoopGuard()
+
+for action in agent_actions:
+    decision = guard.check(tool=action.name, args=action.args)
+    if decision.action == Action.STOP:
+        print(f"Loop detected: {decision.reason}")
+        break
+```
+
+## Why not just `max_iter`?
+
+| Approach | What it catches | Limitation |
+|----------|----------------|------------|
+| `max_iter=10` | Runaway agents | Kills long *legitimate* tasks; misses 3-step loops at step 9 |
+| **agent-loop-guard** | Exact repeats, fuzzy repeats, A→B→C→A cycles, output stagnation | — |
+
+`max_iter` is a blunt timeout. `agent-loop-guard` detects *behavioral patterns* — the agent doing the same thing over and over, even with slight variations.
+
+## Detection Strategies
+
+| Strategy | What it detects | Confidence signal |
+|----------|----------------|-------------------|
+| **Exact Repeat** | Same `(tool, args)` called repeatedly | Consecutive identical calls |
+| **Fuzzy Repeat** | Near-identical args (Jaccard + edit distance) | Similarity > threshold |
+| **Cycle Detection** | A→B→C→A→B→C repeating sequences | Pattern repetition count |
+| **Output Stagnation** | Tool returns same output repeatedly | Output similarity > threshold |
+
+All four strategies run on every call. The highest confidence wins.
+
+## API
+
+```python
+guard = LoopGuard(
+    window_size=10,             # actions to keep in memory
+    similarity_threshold=0.85,  # fuzzy match threshold
+)
+
+decision = guard.check(
+    tool="web_search",          # tool/function name
+    args={"query": "python"},   # arguments (dict or str)
+    output="Results: ...",      # optional: enables stagnation detection
+)
+
+decision.action       # Action.CONTINUE | WARN | STOP | ESCALATE
+decision.reason       # "Cycle detected: [search → parse → search] repeated 3 times"
+decision.strategy     # "cycle_detection"
+decision.confidence   # 0.0 ~ 1.0
+decision.is_loop      # True if STOP or ESCALATE
+decision.should_warn  # True if WARN
+
+guard.reset()         # reuse for next session
+```
+
+## Action Escalation
+
+Actions escalate with consecutive detections:
+
+```python
+from loop_guard import ActionConfig
+
+config = ActionConfig(
+    warn_threshold=2,      # 2 consecutive hits → WARN
+    stop_threshold=4,      # 4 consecutive hits → STOP
+    escalate_threshold=6,  # 6 consecutive hits → ESCALATE
+)
+
+guard = LoopGuard(action_config=config)
+```
+
+## Generic Callback
+
+```python
+from loop_guard.integrations.generic import LoopGuardCallback
+
+callback = LoopGuardCallback(
+    on_warn=lambda d: logger.warning(f"Loop warning: {d.reason}"),
+    on_stop=lambda d: raise_stop_error(d),
+)
+
+# In your agent loop:
+decision = callback.before_tool_call("search", {"query": "test"})
+```
+
+## License
+
+MIT

agent_loop_guard-0.1.0/README.md

@@ -0,0 +1,101 @@
+# agent-loop-guard
+
+Framework-agnostic agent loop detection — sliding window similarity scoring to catch stuck agents.
+
+## Install
+
+```bash
+pip install agent-loop-guard
+```
+
+## Quick Start
+
+```python
+from loop_guard import LoopGuard, Action
+
+guard = LoopGuard()
+
+for action in agent_actions:
+    decision = guard.check(tool=action.name, args=action.args)
+    if decision.action == Action.STOP:
+        print(f"Loop detected: {decision.reason}")
+        break
+```
+
+## Why not just `max_iter`?
+
+| Approach | What it catches | Limitation |
+|----------|----------------|------------|
+| `max_iter=10` | Runaway agents | Kills long *legitimate* tasks; misses 3-step loops at step 9 |
+| **agent-loop-guard** | Exact repeats, fuzzy repeats, A→B→C→A cycles, output stagnation | — |
+
+`max_iter` is a blunt timeout. `agent-loop-guard` detects *behavioral patterns* — the agent doing the same thing over and over, even with slight variations.
+
+## Detection Strategies
+
+| Strategy | What it detects | Confidence signal |
+|----------|----------------|-------------------|
+| **Exact Repeat** | Same `(tool, args)` called repeatedly | Consecutive identical calls |
+| **Fuzzy Repeat** | Near-identical args (Jaccard + edit distance) | Similarity > threshold |
+| **Cycle Detection** | A→B→C→A→B→C repeating sequences | Pattern repetition count |
+| **Output Stagnation** | Tool returns same output repeatedly | Output similarity > threshold |
+
+All four strategies run on every call. The highest confidence wins.
+
+## API
+
+```python
+guard = LoopGuard(
+    window_size=10,             # actions to keep in memory
+    similarity_threshold=0.85,  # fuzzy match threshold
+)
+
+decision = guard.check(
+    tool="web_search",          # tool/function name
+    args={"query": "python"},   # arguments (dict or str)
+    output="Results: ...",      # optional: enables stagnation detection
+)
+
+decision.action       # Action.CONTINUE | WARN | STOP | ESCALATE
+decision.reason       # "Cycle detected: [search → parse → search] repeated 3 times"
+decision.strategy     # "cycle_detection"
+decision.confidence   # 0.0 ~ 1.0
+decision.is_loop      # True if STOP or ESCALATE
+decision.should_warn  # True if WARN
+
+guard.reset()         # reuse for next session
+```
+
+## Action Escalation
+
+Actions escalate with consecutive detections:
+
+```python
+from loop_guard import ActionConfig
+
+config = ActionConfig(
+    warn_threshold=2,      # 2 consecutive hits → WARN
+    stop_threshold=4,      # 4 consecutive hits → STOP
+    escalate_threshold=6,  # 6 consecutive hits → ESCALATE
+)
+
+guard = LoopGuard(action_config=config)
+```
+
+## Generic Callback
+
+```python
+from loop_guard.integrations.generic import LoopGuardCallback
+
+callback = LoopGuardCallback(
+    on_warn=lambda d: logger.warning(f"Loop warning: {d.reason}"),
+    on_stop=lambda d: raise_stop_error(d),
+)
+
+# In your agent loop:
+decision = callback.before_tool_call("search", {"query": "test"})
+```
+
+## License
+
+MIT

agent_loop_guard-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-loop-guard"
+version = "0.1.0"
+description = "Framework-agnostic agent loop detection — sliding window similarity scoring to catch stuck agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "hmj", email = "hmj@quartzunit.com" }]
+keywords = [
+    "agent",
+    "loop",
+    "detection",
+    "guardrail",
+    "safety",
+    "llm",
+    "ai-agent",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/QuartzUnit/agent-loop-guard"
+Repository = "https://github.com/QuartzUnit/agent-loop-guard"
+Issues = "https://github.com/QuartzUnit/agent-loop-guard/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loop_guard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]

agent_loop_guard-0.1.0/src/loop_guard/__init__.py

@@ -0,0 +1,11 @@
+"""agent-loop-guard — Framework-agnostic agent loop detection.
+
+Sliding window similarity scoring to catch stuck agents.
+"""
+
+from loop_guard.decision import Action, ActionConfig, Decision
+from loop_guard.guard import LoopGuard
+from loop_guard.strategies import ActionRecord
+
+__all__ = ["LoopGuard", "Action", "ActionConfig", "Decision", "ActionRecord"]
+__version__ = "0.1.0"

agent_loop_guard-0.1.0/src/loop_guard/decision.py

@@ -0,0 +1,54 @@
+"""Decision types and action configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class Action(Enum):
+    """What to do when a loop pattern is detected."""
+
+    CONTINUE = auto()
+    WARN = auto()
+    STOP = auto()
+    ESCALATE = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """Result of a loop guard check."""
+
+    action: Action
+    reason: str = ""
+    strategy: str = ""  # which strategy triggered
+    confidence: float = 0.0  # 0.0 ~ 1.0
+    step_number: int = 0
+
+    @property
+    def is_loop(self) -> bool:
+        return self.action in (Action.STOP, Action.ESCALATE)
+
+    @property
+    def should_warn(self) -> bool:
+        return self.action == Action.WARN
+
+
+@dataclass
+class ActionConfig:
+    """Configure how many warnings before escalation."""
+
+    warn_threshold: int = 2
+    stop_threshold: int = 4
+    escalate_threshold: int = 6
+    reflection_message: str = "You appear to be stuck in a loop. Try a different approach."
+
+    def resolve_action(self, consecutive_hits: int) -> Action:
+        """Map hit count to action."""
+        if consecutive_hits >= self.escalate_threshold:
+            return Action.ESCALATE
+        if consecutive_hits >= self.stop_threshold:
+            return Action.STOP
+        if consecutive_hits >= self.warn_threshold:
+            return Action.WARN
+        return Action.CONTINUE

agent_loop_guard-0.1.0/src/loop_guard/guard.py

@@ -0,0 +1,129 @@
+"""Core LoopGuard — orchestrates detection strategies."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from loop_guard.decision import ActionConfig, Decision
+from loop_guard.strategies import (
+    ActionRecord,
+    CycleDetectionStrategy,
+    ExactRepeatStrategy,
+    FuzzyRepeatStrategy,
+    OutputStagnationStrategy,
+)
+
+
+@dataclass
+class LoopGuard:
+    """Framework-agnostic agent loop detector.
+
+    Usage:
+        guard = LoopGuard()
+
+        for action in agent_actions:
+            decision = guard.check(action.tool, action.args, action.output)
+            if decision.action == Action.STOP:
+                break
+            if decision.should_warn:
+                print(f"Warning: {decision.reason}")
+    """
+
+    window_size: int = 10
+    similarity_threshold: float = 0.85
+    action_config: ActionConfig = field(default_factory=ActionConfig)
+
+    # Strategy instances (auto-created)
+    _exact: ExactRepeatStrategy = field(init=False, repr=False)
+    _fuzzy: FuzzyRepeatStrategy = field(init=False, repr=False)
+    _cycle: CycleDetectionStrategy = field(init=False, repr=False)
+    _stagnation: OutputStagnationStrategy = field(init=False, repr=False)
+
+    # State
+    _step: int = field(default=0, init=False, repr=False)
+    _consecutive_hits: int = field(default=0, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._exact = ExactRepeatStrategy(window_size=self.window_size)
+        self._fuzzy = FuzzyRepeatStrategy(
+            window_size=self.window_size,
+            similarity_threshold=self.similarity_threshold,
+        )
+        self._cycle = CycleDetectionStrategy(max_cycle_length=min(self.window_size, 5))
+        self._stagnation = OutputStagnationStrategy(
+            window_size=self.window_size,
+            similarity_threshold=self.similarity_threshold,
+        )
+
+    def check(
+        self,
+        tool: str,
+        args: dict[str, Any] | str | None = None,
+        output: str | None = None,
+    ) -> Decision:
+        """Check an agent action for loop patterns.
+
+        Args:
+            tool: Name of the tool/function being called.
+            args: Arguments passed to the tool.
+            output: Output/result of the tool call (optional, enables stagnation detection).
+
+        Returns:
+            Decision with action (CONTINUE/WARN/STOP/ESCALATE), reason, and confidence.
+        """
+        self._step += 1
+        record = ActionRecord(tool=tool, args=args, output=output, step=self._step)
+
+        # Run all strategies and take the highest confidence
+        results = [
+            ("exact_repeat", *self._exact.check(record)),
+            ("fuzzy_repeat", *self._fuzzy.check(record)),
+            ("cycle_detection", *self._cycle.check(record)),
+            ("output_stagnation", *self._stagnation.check(record)),
+        ]
+
+        # Find highest confidence detection
+        best_strategy = ""
+        best_confidence = 0.0
+        best_reason = ""
+
+        for strategy_name, confidence, reason in results:
+            if confidence > best_confidence:
+                best_strategy = strategy_name
+                best_confidence = confidence
+                best_reason = reason
+
+        # Update consecutive hit counter
+        if best_confidence > 0.3:
+            self._consecutive_hits += 1
+        else:
+            self._consecutive_hits = 0
+
+        # Determine action based on consecutive hits
+        action = self.action_config.resolve_action(self._consecutive_hits)
+
+        return Decision(
+            action=action,
+            reason=best_reason,
+            strategy=best_strategy,
+            confidence=best_confidence,
+            step_number=self._step,
+        )
+
+    def reset(self) -> None:
+        """Reset all state for reuse."""
+        self._step = 0
+        self._consecutive_hits = 0
+        self._exact.reset()
+        self._fuzzy.reset()
+        self._cycle.reset()
+        self._stagnation.reset()
+
+    @property
+    def step_count(self) -> int:
+        return self._step
+
+    @property
+    def consecutive_hits(self) -> int:
+        return self._consecutive_hits

agent_loop_guard-0.1.0/src/loop_guard/integrations/generic.py

@@ -0,0 +1,56 @@
+"""Generic callback adapter for any agent framework."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from loop_guard.decision import Action, Decision
+from loop_guard.guard import LoopGuard
+
+
+class LoopGuardCallback:
+    """Wrap LoopGuard as a callback for any agent framework.
+
+    Usage:
+        callback = LoopGuardCallback(
+            on_warn=lambda d: print(f"Warning: {d.reason}"),
+            on_stop=lambda d: raise StopIteration(),
+        )
+
+        # In your agent loop:
+        decision = callback.before_tool_call("search", {"query": "test"})
+    """
+
+    def __init__(
+        self,
+        guard: LoopGuard | None = None,
+        on_warn: Callable[[Decision], None] | None = None,
+        on_stop: Callable[[Decision], Any] | None = None,
+        on_escalate: Callable[[Decision], Any] | None = None,
+        **guard_kwargs: Any,
+    ):
+        self.guard = guard or LoopGuard(**guard_kwargs)
+        self._on_warn = on_warn
+        self._on_stop = on_stop
+        self._on_escalate = on_escalate
+
+    def before_tool_call(
+        self,
+        tool: str,
+        args: dict | str | None = None,
+        output: str | None = None,
+    ) -> Decision:
+        """Check and dispatch callbacks. Returns the Decision."""
+        decision = self.guard.check(tool, args, output)
+
+        if decision.action == Action.WARN and self._on_warn:
+            self._on_warn(decision)
+        elif decision.action == Action.STOP and self._on_stop:
+            self._on_stop(decision)
+        elif decision.action == Action.ESCALATE and self._on_escalate:
+            self._on_escalate(decision)
+
+        return decision
+
+    def reset(self) -> None:
+        self.guard.reset()

agent_loop_guard-0.1.0/src/loop_guard/similarity.py

@@ -0,0 +1,83 @@
+"""Similarity functions for comparing agent actions."""
+
+from __future__ import annotations
+
+
+def jaccard_similarity(a: set, b: set) -> float:
+    """Jaccard index between two sets. Returns 0.0 ~ 1.0."""
+    if not a and not b:
+        return 1.0
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def token_jaccard(s1: str, s2: str) -> float:
+    """Jaccard similarity on whitespace-split tokens."""
+    return jaccard_similarity(set(s1.split()), set(s2.split()))
+
+
+def normalized_edit_distance(s1: str, s2: str) -> float:
+    """Normalized Levenshtein distance. Returns 0.0 (identical) ~ 1.0 (totally different).
+
+    Uses O(min(m,n)) space dynamic programming.
+    """
+    if s1 == s2:
+        return 0.0
+    n, m = len(s1), len(s2)
+    if n == 0 or m == 0:
+        return 1.0
+
+    # Ensure s1 is the shorter string for O(min) space
+    if n > m:
+        s1, s2, n, m = s2, s1, m, n
+
+    prev = list(range(n + 1))
+    curr = [0] * (n + 1)
+
+    for j in range(1, m + 1):
+        curr[0] = j
+        for i in range(1, n + 1):
+            if s1[i - 1] == s2[j - 1]:
+                curr[i] = prev[i - 1]
+            else:
+                curr[i] = 1 + min(prev[i - 1], prev[i], curr[i - 1])
+        prev, curr = curr, prev
+
+    return prev[n] / max(n, m)
+
+
+def edit_similarity(s1: str, s2: str) -> float:
+    """Edit-distance-based similarity. Returns 0.0 (different) ~ 1.0 (identical)."""
+    return 1.0 - normalized_edit_distance(s1, s2)
+
+
+def args_similarity(args1: dict | str | None, args2: dict | str | None) -> float:
+    """Compare two action args. Supports dict and str."""
+    s1 = _normalize_args(args1)
+    s2 = _normalize_args(args2)
+    if s1 == s2:
+        return 1.0
+    # Blend Jaccard (fast, structural) and edit (precise, sequential)
+    j = token_jaccard(s1, s2)
+    # Only compute edit distance for shorter strings (performance)
+    if max(len(s1), len(s2)) <= 2000:
+        e = edit_similarity(s1, s2)
+        return 0.5 * j + 0.5 * e
+    return j
+
+
+def _normalize_args(args: dict | str | None) -> str:
+    """Convert args to a normalized string for comparison."""
+    if args is None:
+        return ""
+    if isinstance(args, str):
+        return args
+    if isinstance(args, dict):
+        # Sort keys for deterministic comparison
+        parts = []
+        for k in sorted(args.keys()):
+            v = args[k]
+            parts.append(f"{k}={v}")
+        return " ".join(parts)
+    return str(args)