Metadata-Version: 2.4
Name: chaos-agents
Version: 0.1.0
Summary: Chaos engineering for AI agents — Chaos Monkey, but for your agents and tools.
Project-URL: Homepage, https://github.com/lyzr-ai/chaos-agents
Project-URL: Source, https://github.com/lyzr-ai/chaos-agents
Project-URL: Issues, https://github.com/lyzr-ai/chaos-agents/issues
Author-email: Shreyas Kapale <shreyas@lyzr.ai>
License: MIT
License-File: LICENSE
Keywords: ai-agents,chaos-engineering,chaos-monkey,fault-injection,llm,resilience,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# chaos-agents

**Chaos Monkey, but for AI agents.**

`chaos-agents` injects controlled faults — latency, errors, corrupted /
truncated / empty outputs — into your agent and tool functions, so you can find
out how your system behaves *before* the real world does it for you.

> ⚠️ Early alpha (v0.1.0). The API is small on purpose and will grow.

## Install

```bash
pip install chaos-agents
```

## Usage

```python
from chaos_agents import ChaosMonkey

# Roll the dice on every call.
monkey = ChaosMonkey(
    latency=0.3,      # 30% chance of an artificial delay
    errors=0.1,       # 10% chance of raising ChaosError
    corruption=0.1,   # 10% chance of scrambling the string output
    truncation=0.05,  # 5%  chance of truncating the output
    seed=42,          # reproducible chaos
)

@monkey.wrap
def my_agent(prompt: str) -> str:
    return call_llm(prompt)

my_agent("summarize this document")
print(monkey.report())   # {'latency': 1, 'errors': 0, ...}
```

You can also wrap inline:

```python
result = monkey.run(call_llm, prompt)
```

Disable chaos in production without touching call sites:

```python
monkey = ChaosMonkey(errors=0.1, enabled=False)
```

## Built-in faults

| Fault        | What it simulates                                  |
| ------------ | -------------------------------------------------- |
| `latency`    | slow / hanging agents and tools                    |
| `errors`     | crashes and tool failures (raises `ChaosError`)    |
| `corruption` | hallucinated / garbled responses                   |
| `truncation` | token-limit cutoffs and interrupted streams        |
| `empty`      | silent / dropped responses                         |

## License

MIT
