Metadata-Version: 2.4
Name: agentguard-kit
Version: 0.2.0
Summary: Detect loops and wasted calls in AI agents
Author: Rudra Mistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# AgentGuard

> Stop your agents from silently burning API credits.

AgentGuard is a lightweight runtime guard that detects loops, tracks repeated calls, and shows how many tokens your agent is wasting — in real time.

```bash
pip install agentguard-kit
```

---

## ⚠️ The Problem

LLM agents don't fail loudly.

They do this instead:

```text
search("python error")
→ read_file("log.txt")
→ search("python error")
→ read_file("log.txt")
→ search("python error")
```

No crash. No exception.
Just silent repetition… and a growing API bill.

---

## ✅ The Solution

Wrap your tools. Run your agent. Let AgentGuard track what's actually happening.

```python
from agentguard import Guard
from agentguard.decorators import track

g = Guard()
g.start()

@track
def search(query):
    return f"results for {query}"

for step in ["a", "b", "a", "b"]:
    search(step)

print(g.report())
```

Example output:

```text
AgentGuard Report

Verdict: BAD (Loop Detected)
Reason: Repeating step pattern detected
Severity: High
Confidence: 0.90

---

Total Calls: 4
Wasted Calls: 2
Waste Ratio: 50%

---

Signals:
- Loop Detected: Yes
- High Waste: No

---

Token Usage:

Total Tokens: 200
Wasted Tokens: 100
Token Waste: 50%

---

Suggestions:
- Possible infinite loop detected — verify stopping conditions
- Check repeated tool inputs
- Add guard conditions.
```

---

## ⚠️ About Repeated Calls

AgentGuard detects repeated and looping behavior based on execution patterns.

However, not all repetition is a bug.

Valid cases include:
- retries (network/API failures)
- pagination or iteration
- multi-step workflows

AgentGuard does NOT assume intent.

It highlights high-level inefficiency signals — you decide whether to act.

---

## 🧠 What It Detects

- Consecutive loops (hard stuck behavior)
- Frequent loops (error prone exploration)
- Repeated tool calls (waste ratio)
- Token waste (explicit or estimated)

---

## ⚙️ Token Tracking

AgentGuard works in two modes:

1. Automatic (no setup):
    ```python
    search("hello")
    ```
    Uses a deterministic estimate:
    ```text
    tokens ≈ len(payload) // 4
    ```

2. Explicit (recommended):
    ```python
    search("hello", tokens=120)
    ```
    Uses real token usage from your LLM provider.

---

## 🧪 Real-World Integrations

**Example 1 — Autopilot Loop (no tokens passed):**

```python
from agentguard import Guard
from agentguard.decorators import track

g = Guard()
g.start()

@track
def fallback_search(query):
    return f"retrying {query}"

for _ in range(3):
    fallback_search("python error")

print(g.report())
```

**Example 2 — OpenAI Integration (real tokens):**

```python
from agentguard import Guard
from agentguard.decorators import track
from openai import OpenAI

client = OpenAI()

g = Guard()
g.start()

@track
def ask_llm(prompt, tokens=None):
    return prompt

def call_llm(prompt):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )

    total_tokens = response.usage.total_tokens

    return ask_llm(prompt, tokens=total_tokens)

call_llm("Explain python loops")
call_llm("Explain python loops")
call_llm("Explain python loops")

print(g.report())
```

---

## 🎯 Why Use AgentGuard?

Because your agent might be:

- Looping without you noticing
- Repeating expensive calls
- Wasting 50–80% of tokens silently

AgentGuard makes that failure visible.

---

## Installation

```bash
pip install agentguard-kit
```

---

## Minimal Usage

```python
g = Guard()
g.start()

@track
def tool(x):
    return x

tool("a")
tool("a")

print(g.decision())
print(g.suggest())
```
