longguard 0.1.2

Overview

"Why did my agent just burn $14 repeating the exact same search 20 times?" — now you have an in-flight circuit breaker that detects loops and recovers gracefully.

When autonomous LLM agents hit an unexpected hurdle, they often get trapped in repetitive reasoning loops: calling identical tools with the same parameters, oscillating between two conflicting thoughts, or drifting aimlessly while burning thousands of tokens.

LangGraph's built-in recursion_limit is a hard crash (GraphRecursionError). It drops state, discards user context, and provides zero opportunity for recovery.

LongGuard is an intelligent circuit breaker middleware. It monitors your agent's chain-of-thought in real time, catches loops early, injects a "Reflect & Pivot" prompt to guide the agent back on track, and only halts (kill) gracefully if recovery fails—preserving complete state and token analytics.

🌐 Part of the Long Suite

LongGuard is part of the EnDevSols Long Suite of open-source production AI tools:

• LongParser — High-speed, privacy-first local document ingestion & chunking (PDF, DOCX, PPTX, XLSX)
• LongTrainer — Production multi-tenant RAG chatbot and agent framework
• LongTracer — Post-generation hallucination detection via hybrid STS + NLI claim verification
• LongProbe — Sub-second RAG retrieval regression testing with pytest
• LongGuard — In-flight runtime agent circuit breaker & reasoning loop recovery ← You are here

Together, the Long Suite covers the full AI lifecycle from data ingestion and retrieval CI regression to runtime agent safety and post-generation verification.

💡 Why LongGuard?

• ⚡ Sub-millisecond overhead: Evaluates in-flight agent steps without slowing down LLM inference.
• 🔄 4 loop detectors: Catches tool repetition, semantic oscillation, dead-end drift, and token velocity spikes.
• 🧭 Reflect & Pivot prompt injection: Guides stuck agents back on track before giving up.
• 🛡️ Zero unhandled crashes: Gracefully terminates and preserves conversation state if recovery fails.
• 🔌 1-line integration: Drop-in wrapper for LangGraph 1.0+ (add_guard_to_graph) and LangChain (GuardedAgentExecutor).
• 📊 Full observability: Generates detailed GuardReport summaries with per-step token tracking.
• 🧪 100% test coverage: 179 passing unit/integration tests, strict MyPy typing, and Ruff linted.

🏗️ Architecture

⚡ Quick Start

Installation

# Core package (standalone, zero heavy dependencies)
pip install longguard

# With LangGraph integration (LangGraph 1.0+)
pip install longguard[langgraph]

# With LangChain integration
pip install longguard[langchain]

# With high-quality sentence embeddings
pip install longguard[embeddings]

# Everything
pip install longguard[all]

1. LangGraph Integration (1 Line)

Compatible with LangGraph 1.0+ and modern multimodal models (Claude 3.7, Gemini 2.5, GPT-4o):

from langgraph.graph import StateGraph
from longguard.integrations.langgraph import add_guard_to_graph
from longguard import GuardConfig

# 1. Build your LangGraph workflow as usual
workflow = StateGraph(AgentState)
workflow.add_node("agent", agent_node)
workflow.add_node("tools", tool_node)
workflow.add_edge("agent", "tools")
workflow.add_conditional_edges("tools", should_continue)

# 2. Add LongGuard in one line!
workflow = add_guard_to_graph(workflow, GuardConfig())
app = workflow.compile()

# 3. Read execution telemetry after run
guard = workflow.__longguard__
print(guard.get_report().summary())

2. Standalone / Custom Agent Loop

If you run a custom while loop or proprietary agent orchestrator:

from longguard import CircuitBreaker, GuardConfig, AgentStep

breaker = CircuitBreaker(GuardConfig(
    tool_repeat_threshold=3,    # 3 identical tool calls = trigger
    max_tokens_per_run=50_000,  # Hard token cap
))

for step in run_agent():
    decision = breaker.check(AgentStep(
        step_number=step.index,
        thought=step.thought,
        action=step.tool_name,
        action_input=step.arguments,
        observation=step.tool_output,
        tokens_used=step.tokens,
    ))

    if decision.action == "reflect":
        # Inject the recovery advice into your agent's context
        messages.append({"role": "user", "content": decision.inject_prompt})
    elif decision.action == "kill":
        print(f"Halted safely: {decision.reason}")
        break

# View summary report
print(breaker.report.summary())

🔍 The 4 Loop Detectors

📊 LongGuard vs. LangGraph recursion_limit

⚙️ Configuration at a Glance

All behavior is customizable through GuardConfig:

from longguard import GuardConfig

config = GuardConfig(
    # Loop Detection Sensitivity
    tool_repeat_threshold=3,          # Repeated tool calls before reflection
    tool_repeat_window=6,             # History window to examine
    dead_end_threshold=5,             # Steps with no progress before triggering
    token_velocity_multiplier=3.0,    # Spike multiplier vs rolling baseline

    # Hard Safety Guardrails
    max_tokens_per_run=50_000,        # Hard stop if agent burns > 50k tokens
    max_steps=30,                     # Maximum steps permitted
    max_reflections=2,                # Maximum recovery attempts before kill
)

👉 For detailed documentation on custom detectors, embedding backends, and LangSmith telemetry, see the Full Documentation.

🧪 CI/CD Ready

Run the test suite locally with uv or pytest:

# Run all 179 unit & integration tests
uv run pytest tests/ -v

# Run with coverage report
uv run pytest tests/ --cov=longguard --cov-report=term-missing

# Run code style & type checks
uv run ruff check src/ tests/
uv run mypy src/

Every push and pull request is automatically tested across Python 3.10, 3.11, and 3.12 on both Ubuntu and macOS via GitHub Actions.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on code formatting, running tests, and opening pull requests.

🛡️ Security

For vulnerability disclosures, please review SECURITY.md or contact technology@endevsols.com.

📄 License

LongGuard is open-source software released under the MIT License.