Metadata-Version: 2.4
Name: agentchaos-tools
Version: 0.1.1
Summary: Chaos testing for agentic AI — fault injection hooks for openai-agents-python
License: MIT
Project-URL: Homepage, https://github.com/NithiN-1808/agentchaos
Project-URL: Repository, https://github.com/NithiN-1808/agentchaos
Keywords: ai,agents,chaos,testing,openai,llm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai-agents>=0.0.1

# agentchaos-tools

[![PyPI version](https://badge.fury.io/py/agentchaos-tools.svg)](https://pypi.org/project/agentchaos-tools/)

Chaos testing for agentic AI — fault injection hooks for [openai-agents-python](https://github.com/openai/openai-agents-python).

Simulate tool failures, latency, and corrupted outputs to verify your agent handles real-world conditions gracefully.

## Install
```bash
pip install agentchaos-tools
```

## Usage
```python
from agents import Agent, Runner, function_tool
from agentchaos import FaultInjectionHooks, ToolFault, FaultType

@function_tool
def web_search(query: str) -> str:
    return f"Results for {query}"

agent = Agent(name="assistant", tools=[web_search])

hooks = FaultInjectionHooks(
    faults=[
        ToolFault(tool_name="web_search", fault_type=FaultType.EXCEPTION, rate=0.5),
        ToolFault(tool_name="calculator", fault_type=FaultType.LATENCY, latency_seconds=2.0),
    ],
    seed=42,  # optional: reproducible fault patterns
)

result = await Runner.run(agent, "Search for something", hooks=hooks)
hooks.report()
# agentchaos-tools report — 1 fault(s) triggered:
#   1. [EXCEPTION] tool='web_search'
```

## Fault types

| Type | What it does |
|------|-------------|
| `EXCEPTION` | Raises `RuntimeError` before the tool runs |
| `LATENCY` | Injects `asyncio.sleep` delay before the tool runs |
| `CORRUPTION` | Records that output was corrupted (visible in report) |

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tool_name` | `str` | required | Name of the tool to target |
| `fault_type` | `FaultType` | required | Type of fault to inject |
| `rate` | `float` | `1.0` | Probability (0.0–1.0) that the fault fires |
| `latency_seconds` | `float` | `1.0` | Delay in seconds (LATENCY only) |
| `seed` | `int` | `None` | Random seed for reproducible tests |

## License

MIT
