Metadata-Version: 2.5
Name: agent-chaos-runner
Version: 0.1.0
Summary: Chaos engineering for autonomous AI agents
Project-URL: Homepage, https://github.com/Coroz2/agent-chaos
Project-URL: Documentation, https://github.com/Coroz2/agent-chaos#readme
Project-URL: Repository, https://github.com/Coroz2/agent-chaos
Project-URL: Issues, https://github.com/Coroz2/agent-chaos/issues
Project-URL: Changelog, https://github.com/Coroz2/agent-chaos/blob/main/CHANGELOG.md
Author: Carlos Orozco
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,chaos-engineering,resilience,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: starlette<1,>=0.38
Requires-Dist: typer<1,>=0.12
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Requires-Dist: twine<8,>=7; extra == 'dev'
Requires-Dist: types-pyyaml<7,>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Agent Chaos

**Chaos engineering for autonomous AI agents.**

AI agents increasingly depend on unreliable model APIs, tools, databases, and HTTP services.
Agent Chaos intentionally disrupts those dependencies so developers can measure whether an
agent-like workload tolerates a fault, retries successfully, or fails.

Agent Chaos v0.1 is an early open-source vertical slice. It is framework-independent and does
not require an OpenAI or Anthropic API key.

```mermaid
flowchart LR
    A["Agent workload"] --> C["Agent Chaos proxy"]
    C --> D["HTTP dependency"]
    C -. "inject fault" .-> C
```

## Install

The published Python distribution is named `agent-chaos-runner`; the product and installed
command remain Agent Chaos and `agentchaos`.

```bash
uv tool install agent-chaos-runner
agentchaos --version
```

Agent Chaos supports Python 3.12+ on macOS and Linux.

## Quick start

Clone the repository to run the deterministic local demo without API keys:

```bash
git clone https://github.com/Coroz2/agent-chaos.git
cd agent-chaos
uv sync --extra dev
uv run agentchaos run examples/scenarios/api_503_recovery.yaml
```

The scenario starts its deterministic fake dependency automatically. A successful run ends with
`RECOVERED` and writes its artifacts under `.agentchaos/runs/<run-id>/`.

Other examples:

```bash
uv run agentchaos run examples/scenarios/no_fault.yaml
uv run agentchaos run examples/scenarios/api_latency_recovery.yaml
uv run agentchaos run examples/scenarios/api_503_failure.yaml
```

The final command deliberately exits with status 1 because recovery is not observed.

## Scenario

```yaml
schema_version: 1
name: api-503-recovery

dependency:
  type: http
  base_url: http://127.0.0.1:19103
  start:
    command: [python, fake_api.py, --port, "19103"]
    cwd: ..
    readiness:
      path: /health

workload:
  name: demo-agent
  command: [python, demo_agent.py]
  cwd: ..
  proxy_url_env: CUSTOMER_API_URL

fault:
  type: http_error
  target:
    method: GET
    path: /customer/*
  trigger:
    occurrence: 2
  status_code: 503

success:
  exit_code: 0
```

The optional managed dependency is intended for local tests. Omit `dependency.start` when the
upstream already exists. Agent Chaos always exposes the generated proxy URL as
`AGENTCHAOS_PROXY_URL`; `proxy_url_env` maps it into the variable an existing workload expects.

## Results

- `PASSED`: a baseline succeeds, or the workload tolerates injected latency without failure.
- `RECOVERED`: a faulted operation fails, a matching retry succeeds, and the workload succeeds.
- `FAILED`: execution fails, the fault never fires, or no successful recovery is observed.

Successful and recovered experiments exit 0. Experiment failures exit 1, invalid scenarios exit
2, setup failures exit 3, and interruptions exit 130.

Every valid run contains:

```text
.agentchaos/runs/<run-id>/
├── scenario.yaml
├── events.jsonl
├── stdout.log
├── stderr.log
├── dependency.stdout.log
├── dependency.stderr.log
└── report.json
```

`events.jsonl` is a versioned, sequence-ordered event stream. `report.json` provides stable result
and reason codes plus workload, fault, recovery, timing, and artifact details.

## Commands

```bash
uv run agentchaos --help
uv run agentchaos --version
uv run agentchaos version
uv run agentchaos validate examples/scenarios/api_503_recovery.yaml
uv run agentchaos run examples/scenarios/api_503_recovery.yaml
```

Use `--output-dir PATH` to place run directories somewhere other than `.agentchaos/runs`.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
```

## Limitations

v0.1 supports one HTTP dependency and zero or one fault on macOS and Linux. It is a reverse proxy,
not transparent network interception: the workload must accept the proxy base URL through its
configuration. Request bodies and responses are buffered up to 10 MiB. Streaming, SSE,
WebSockets, CONNECT tunneling, TLS interception, multiple faults, probabilistic triggers, and
model-specific grading are not implemented.

Retry classification uses a deterministic fingerprint of method, path, hashed query, and body.
It is useful black-box evidence, not proof of the workload's internal intent.

## Roadmap

The next logical steps are richer HTTP failures such as 429s and connection resets, richer trigger
policies and multi-fault campaigns, then another dependency adapter such as MCP.

Licensed under Apache-2.0.
