Metadata-Version: 2.4
Name: agentbelt-loop
Version: 0.1.0
Summary: Detect repeat, cyclic, and stagnation loops in AI agent tool-call sequences, with cross-session pattern learning. Part of the agentbelt suite.
Author: Saptarshi Bhattacharjee
License-Expression: MIT
Project-URL: Homepage, https://github.com/bsaptarshi/agentbelt
Keywords: llm,agents,loop-detection,tool-calling,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentbelt-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# agentbelt-loop

Detect repeat, cyclic, and stagnation loops in AI agent tool-call sequences —
with cross-session pattern learning. Part of the
[agentbelt](https://github.com/bsaptarshi/agentbelt) suite.

```bash
pip install agentbelt-loop
```

## Quickstart

```python
from agentbelt_loop import LoopDetector, LoopPolicy, LoopDetected

detector = LoopDetector(LoopPolicy(max_exact_repeats=3))

detector.record("session-1", tool="search", args={"q": "foo"}, result=result)
try:
    detector.check("session-1")
except LoopDetected as e:
    print(e.kind, e.detail)   # "repeat" | "cycle" | "stagnation" | "known_pattern"
```

## The differentiator: cross-session pattern learning

Once a cyclic shape (e.g. `search → rephrase_query → search → rephrase_query`)
has been confirmed a loop in enough distinct sessions, new sessions matching
that shape trip *early* — after 2 local repeats instead of waiting out the
full threshold every time.

## What did this actually catch?

```python
print(detector.impact_report())
# 3 loop(s) detected across 5 check(s) (repeat=3)
```

Breaks down detections by kind, and calls out `known_pattern` catches
specifically since those are the cross-session differentiator in action —
loops caught early because another session already proved the shape.

See the [suite README](https://github.com/bsaptarshi/agentbelt)
for the full concept and how this fits with `agentbelt-budget` and
`agentbelt-sampler`.

## License

MIT
