Proposal: Add zero-dependency Semantic Loop Detection to Doom Loop framework

[Devaretanmay]

Hey @MervinPraison and team,

Massive respect for the work you're doing with PraisonAI. Your native "Doom Loop Detection" (generic_repeat, poll_no_progress, ping_pong) is exactly what the ecosystem needs to stop agents from burning context windows.

I'm the maintainer of TokenCircuit (an open-source pre-model intervention engine). While building it, we solved a specific failure mode that exact-hash and structural detectors miss: paraphrased reasoning loops.

This happens when an LLM slightly alters its text or tool arguments on every turn, but repeats the exact same failing strategy. The transcript changes, so exact-hash misses it, but the agent is still stuck.

The Proposal

I'd love to contribute our semantic engine as an optional "Advanced Semantic Detector" that users can plug into PraisonAI's agent hook system alongside your existing detectors.

Why it fits PraisonAI

1. Zero Dependencies: It uses pure Python stdlib (regex + hashlib shingling). No tiktoken, no embeddings, no network calls. It won't bloat your dependency tree.
2. Blazing Fast: Benchmarked at <5µs latency per turn.
3. MIT Licensed: Fully compatible with PraisonAI's ecosystem.

I've already written the integration logic and the test suite. Would you be open to me opening a PR that adds this as an advanced, opt-in detector for your Doom Loop framework?

Cheers,
Tanmay
Maintainer, TokenCircuit (https://github.com/Devaretanmay/TokenCircut)

[praisonai-triage-agent]

👋 Thanks for opening this issue, @Devaretanmay!

A maintainer will review this shortly. In the meantime:

• Make sure you've included steps to reproduce (for bugs)
• Check existing issues for duplicates
• Review the documentation for related guides

A maintainer can trigger deeper analysis by commenting @claude on this issue.

[praisonai-triage-agent]

Claude finished @praisonai-triage-agent[bot]'s task —— View job

---

Analyzing Semantic Loop Detection Proposal

Thanks for your thoughtful proposal @Devaretanmay! Let me analyze this against PraisonAI's architecture guidelines.

Todo List

• Read AGENTS.md to understand architecture rules
• Check existing loop detection implementation
• Determine architectural routing (Core/Wrapper/Plugins)
• Validate against duplication and complexity guidelines
• Provide architectural decision

Analysis Results

Current State

PraisonAI already has a comprehensive loop detection system in praisonaiagents/agent/loop_detection.py with:

• Generic Repeat Detection: Detects identical tool/args combinations
• Poll No Progress Detection: Identifies stuck polling loops with identical results
• Ping Pong Detection: Catches alternating pattern loops

The existing implementation follows PraisonAI's principles:

• Zero dependencies (uses only stdlib: hashlib, json)
• Protocol-driven design
• Per-agent instance (no global state)
• Fast performance (<5µs overhead)

Architectural Routing Decision

According to AGENTS.md, this feature belongs in PraisonAI-Plugins repository as it:

1. Extends framework lifecycle (modifies agent's loop detection behavior)
2. Replaces/augments systemic behavior (enhances existing detectors)
3. Is optional (users opt-in to advanced detection)

Per the architecture guidelines:

• Plugins (PraisonAI-Plugins): Framework lifecycle extensions replacing systemic behavior (e.g. tracing, logging, metrics, hooks, guardrails)

Loop detection falls under the "guardrails" category mentioned explicitly in the plugin examples.

Assessment

Your proposal for paraphrased reasoning loop detection addresses a real gap in the existing detectors - when agents repeat the same failing strategy with slightly altered text/arguments.

However, this should be implemented as a plugin in the PraisonAI-Plugins repository, not in the core SDK, because:

1. It extends existing loop detection (systemic behavior modification)
2. It's an optional enhancement (not core functionality)
3. The core already has the base loop detection protocol

Recommendation

❌ Cannot accept PR to this repository (PraisonAI core) as it violates the architectural routing rules.

✅ Suggested path forward:

1. Contribute to the PraisonAI-Plugins repository instead
2. Create a SemanticLoopDetectorPlugin that:
   • Implements the PluginProtocol interface
   • Hooks into the agent's loop detection lifecycle
   • Adds your semantic similarity detection as a fourth detector type
3. Users can then install and activate it via the plugin system

This approach aligns with PraisonAI's protocol-driven design and keeps the core SDK lightweight while allowing powerful extensions through plugins.

Would you be interested in contributing this as a plugin to PraisonAI-Plugins instead? That would be the architecturally correct home for this valuable enhancement.

[Devaretanmay]

@praisonai-triage-agent Thank you for the detailed architectural analysis! You're absolutely right
this belongs in PraisonAI-Plugins as a guardrails plugin, not in the core SDK.

I'm happy to contribute this as a SemanticLoopDetectorPlugin to the PraisonAI-Plugins repository. I'll:

1. Implement the PluginProtocol interface
2. Hook into the agent's loop detection lifecycle
3. Add semantic similarity detection as a fourth detector type
4. Keep it zero-dependency (stdlib only) and <5µs latency

I'll open the PR in PraisonAI-Plugins shortly. Thanks for the clear guidance!

Cheers,
Tanmay

[Devaretanmay]

@praisonai-triage-agent @MervinPraison

Following the architectural guidance from the triage analysis, I've implemented the semantic loop detector as a plugin in the PraisonAI-Plugins repository.

PR: MervinPraison/PraisonAI-Plugins#1

What's included:

• ✅ Implements PluginProtocol interface
• ✅ Hooks into agent's loop detection lifecycle
• ✅ Adds semantic similarity detection as fourth detector type
• ✅ Zero dependencies (stdlib only: regex + hashlib)
• ✅ <5µs latency per detection
• ✅ Comprehensive test suite
• ✅ Full documentation

The plugin catches paraphrased reasoning loops that the existing exact-hash detectors miss, using k-gram shingling and Jaccard similarity computation.

Ready for review whenever the maintainers have time. Thanks for the clear architectural routing!