Metadata-Version: 2.4
Name: agent-loop-breaker-py
Version: 0.1.0
Summary: Detect repeated agent steps and stop runaway loops. Python port of @mukundakatta/agent-loop-breaker.
Project-URL: Homepage, https://github.com/MukundaKatta/agent-loop-breaker-py
Project-URL: Issues, https://github.com/MukundaKatta/agent-loop-breaker-py/issues
Project-URL: Source, https://github.com/MukundaKatta/agent-loop-breaker-py
Project-URL: JS sibling, https://www.npmjs.com/package/@mukundakatta/agent-loop-breaker
Author-email: Mukunda Katta <mukunda.vjcs6@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,detection,llm,loop,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# agent-loop-breaker-py

Detect repeated agent steps and stop runaway loops. Pure Python, zero deps. Python port of [`@mukundakatta/agent-loop-breaker`](https://www.npmjs.com/package/@mukundakatta/agent-loop-breaker).

```bash
pip install agent-loop-breaker-py
```

```python
from agent_loop_breaker import detect_loop, should_stop

events = [{"tool": "search"}, {"tool": "fetch"}] * 4
res = detect_loop(events, window=2, repeat_threshold=3)
# LoopDetection(looping=True, pattern="search>fetch", count=4)

if should_stop(events):
    raise RuntimeError("agent stuck in a loop")
```

## API

### `detect_loop(events, *, window=4, repeat_threshold=3) -> LoopDetection`

Scans `events` for a repeating window of length `window`. Returns the first window seen `repeat_threshold` times or more.

Each event is reduced to a signature via `event.get("tool") or event.get("name") or event.get("type")` (or `str(event)` for non-dicts).

### `should_stop(events, *, window=4, repeat_threshold=3) -> bool`

Convenience wrapper returning the `looping` flag.

## License

MIT
