from loopbuster import LoopBuster

# Basic usage
buster = LoopBuster(similarity_threshold=0.85)

for step in agent_loop():
    decision = buster.check(tool=step.tool, args=step.args, output=step.output)
    if decision.is_loop:
        print(f"🛑 Loop detected: {decision.reason}")
        break

from loopbuster import LoopBuster

with LoopBuster(
    budget_usd=5.0,                 # Dollar cap on LLM spend
    max_repeats=5,                  # Hard limit on exact (tool, args) repeats
    stasis_steps=10,                # Agent state hasn't changed for N steps
) as lb:
    for step in agent_loop():
        # Track spend
        lb.record_tokens("gpt-4o", input=500, output=200)

        # Check for loops
        decision = lb.check(tool=step.tool, args=step.args, output=step.output)
        if decision.should_stop:
            lb.record_state(step.state)
            break

from loopbuster import LoopBuster
from loopbuster.types import AdaptiveActionConfig

with LoopBuster(action_config=AdaptiveActionConfig()) as lb:
    for step in agent_loop():
        decision = lb.check(tool=step.tool, args=step.args)
        # Diverse actions → relaxed thresholds (fewer false positives)
        # Repetitive actions → tightened thresholds (faster intervention)

from loopbuster import AsyncLoopBuster

async with AsyncLoopBuster(action_timeout=30.0, max_slow_actions=3) as lb:
    async for action in agent_async_loop(task):
        decision = await lb.acheck(tool=action.tool, args=action.args)
        if decision.should_stop:
            break

async for tool, args, decision in AsyncLoopBuster.watch(
    my_agent_async_gen(task),
    budget_usd=5.0,
):
    if decision.should_stop:
        break
    # process action...

from loopbuster import CircuitBreaker, BreakerAction

breaker = CircuitBreaker(max_repeats=3, action=BreakerAction.BLOCK)
lb = LoopBuster(circuit_breaker=breaker)

for step in agent_loop():
    # Pre-flight check
    pre = lb.breaker_check(tool=step.tool, args=step.args)
    if pre.blocked:
        suggestion = pre.alternative_suggestion
        # Try a different approach
        break

    decision = lb.check(tool=step.tool, args=step.args)

with LoopBuster() as lb:
    for step in agent_loop():
        decision = lb.check(tool=step.tool, args=step.args)
        if decision.should_stop:
            break

report = lb.report()
# {
#   "total_actions": 15,
#   "diversity_ratio": 0.33,
#   "redundant_actions": 8,
#   "top_repeated_patterns": [("search:{q=same...}", 6), ...],
#   "token_waste_estimate": "$0.42",
#   "recommendations": [...]
# }

from loopbuster.integrations import langgraph_guard

# Use as a conditional edge node
graph.add_conditional_edges(
    "agent",
    langgraph_guard(similarity_threshold=0.85),
    {True: "fallback", False: "continue"}
)

from loopbuster.integrations import CrewAIGuardTool

guard = CrewAIGuardTool(budget_usd=5.0)
# Add guard to your Crew's tool list

from loopbuster.integrations import AutogenGuardAgent

guard_agent = AutogenGuardAgent(
    name="loop_guard",
    system_message="I monitor for infinite loops."
)

from loopbuster import LoopBuster
>>>>>>> codex/deep-detection-v0.3.0

with LoopBuster(budget_usd=5.0) as lb:
    for step in agent_loop(task):
        decision = lb.check(
            tool=step.tool,
            args=step.args,
            output=step.output,
        )
        if decision.should_stop:
            # React: break, log, ask user
            expl = decision.explain(lb.action_history)
            print(f"🛑 {expl.summary}")
            print(f"💡 {expl.suggestion}")
            break

from loopbuster import ProgressSignal

ps = ProgressSignal(window=5)

# Good cycle: each call produces new information
ps.record("Paris population: 2.1M")
ps.record("Tokyo population: 14M")       # gain ≈ 0.85 (new info)
ps.record("London population: 8.9M")      # gain ≈ 0.85

# Bad cycle: same output repeatedly
ps.record("Paris population: 2.1M")
ps.record("Paris population: 2.1M")       # gain < 0.1 (stagnation)
ps.record("Paris population: 2.1M")       # gain ≈ 0.0

from loopbuster import LoopBuster, Action

lb = LoopBuster()
for step in agent_loop:
    decision = lb.check(step.tool, step.args, step.output)

    # Check risk BEFORE any strategy fires
    risk = lb.risk_score
    if risk and risk.is_warning:
        print(f"⚠️ {risk.summary}")
        # entropy=0.8 → tool set collapsing
        # revisitation=0.7 → revisiting same states

decision = lb.check(tool="search", args={"q": "python"})
if decision.is_loop:
    expl = decision.explain(lb.action_history)
    # expl.root_cause_label = "Exact Tool Repeat"
    # expl.suggestion = "Consider adding a termination condition..."
    print(f"🔍 {expl.detail}")
    print(f"💡 {expl.suggestion}")

if decision.is_loop:
    expl = decision.explain(lb.action_history)
    print(expl.summary)       # High-level summary
    print(expl.detail)        # Detailed analysis
    print(expl.suggestion)    # Actionable next step
    print(expl.root_cause)    # RootCause enum

lb = LoopBuster(
    budget_usd=5.0,       # BudgetCeiling
    max_repeats=3,        # RepeatCallGuard
    stasis_steps=5,       # StateStasis
)

from loopbuster import AdaptiveActionConfig, LoopBuster

config = AdaptiveActionConfig(
    base_warn=3, base_stop=5, base_escalate=8,
)
with LoopBuster(action_config=config) as lb:
    ...

from loopbuster import LoopBuster
from loopbuster.integrations.langchain import LoopBusterCallback

lb = LoopBuster(budget_usd=5.0)
callback = LoopBusterCallback(lb)
agent_executor = AgentExecutor.from_agent_and_tools(
    agent=agent, tools=tools, callbacks=[callback],
)

from loopbuster import LoopBuster
from loopbuster.integrations.llamaindex import LoopBusterCallback

lb = LoopBuster(budget_usd=5.0)
callback = LoopBusterCallback(lb)
from llama_index.core import Settings
Settings.callback_manager.add_handler(callback)

from loopbuster.integrations import LoopBusterCallback

callback = LoopBusterCallback(on_stop=lambda d: raise StopException(d))
for action in agent_loop:
    decision = callback.before_tool_call(action.tool, action.args)
    if not decision.should_stop:
        result = execute_tool(action.tool, action.args)

from loopbuster import AsyncLoopBuster

async with AsyncLoopBuster(budget_usd=5.0) as lb:
    async for step in agent_async_loop():
        decision = await lb.acheck(tool=step.tool, args=step.args)
        if decision.should_stop:
            break

async with AsyncLoopBuster(action_timeout=30.0, max_slow_actions=3) as lb:
    # If an action takes >30s, it's flagged as hung
    # After 3 consecutive hangs → ESCALATE
    ...

from loopbuster import buster

@buster(budget_usd=5.0, max_repeats=3)
def run_my_agent(task):
    from loopbuster import current
    for step in agent_loop(task):
        decision = current().check(tool=step.tool, args=step.args)
        if decision.should_stop:
            break

from loopbuster import LoopBuster

lb = LoopBuster()
# ... run agent ...
lb.start_dashboard(port=8080)

with LoopBuster(budget_usd=5.0) as lb:
    for step in agent_loop():
        lb.check(tool=step.tool, args=step.args)

report = lb.report()
print(report["risk_score"]["summary"])
print(report["recommendations"])