Metadata-Version: 2.4
Name: faultray
Version: 11.0.1
Summary: FaultRay — Zero-risk infrastructure and AI agent chaos engineering. Simulate agent resilience failures and prove your availability ceiling mathematically.
Project-URL: Homepage, https://faultray.com
Project-URL: Documentation, https://github.com/mattyopon/faultray/tree/main/docs
Project-URL: Repository, https://github.com/mattyopon/faultray
Project-URL: Issues, https://github.com/mattyopon/faultray/issues
Project-URL: Changelog, https://github.com/mattyopon/faultray/blob/main/CHANGELOG.md
Author-email: Yutaro Maeda <mattyopon@gmail.com>
License: BSL-1.1
License-File: LICENSE
Keywords: agentic-ai,ai-agent,availability,chaos-engineering,devops,disaster-recovery,dora-compliance,fault-injection,incident-response,infrastructure,prometheus,reliability,resilience-testing,simulation,slo,sre,terraform
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: jinja2>=3.1
Requires-Dist: networkx>=3.0
Requires-Dist: psutil>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: stripe>=8.0
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn>=0.34
Provides-Extra: all-clouds
Requires-Dist: azure-identity>=1.15; extra == 'all-clouds'
Requires-Dist: boto3>=1.28; extra == 'all-clouds'
Requires-Dist: google-cloud-compute>=1.0; extra == 'all-clouds'
Requires-Dist: kubernetes>=28.0; extra == 'all-clouds'
Provides-Extra: aws
Requires-Dist: boto3>=1.28; extra == 'aws'
Provides-Extra: azure
Requires-Dist: azure-identity>=1.15; extra == 'azure'
Requires-Dist: azure-mgmt-compute>=30.0; extra == 'azure'
Requires-Dist: azure-mgmt-redis>=14.0; extra == 'azure'
Requires-Dist: azure-mgmt-sql>=3.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: google-cloud-compute>=1.0; extra == 'gcp'
Requires-Dist: google-cloud-redis>=2.0; extra == 'gcp'
Requires-Dist: google-cloud-sql-admin>=1.0; extra == 'gcp'
Requires-Dist: google-cloud-storage>=2.0; extra == 'gcp'
Provides-Extra: k8s
Requires-Dist: kubernetes>=28.0; extra == 'k8s'
Provides-Extra: mcp
Requires-Dist: mcp<1.26,>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">FaultRay</h1>
  <p align="center"><strong>Zero-Risk Chaos Engineering — Simulate, Don't Break</strong></p>
</p>

<p align="center">
  <a href="https://pypi.org/project/faultray/"><img src="https://img.shields.io/pypi/v/faultray" alt="PyPI"></a>
  <a href="https://pypi.org/project/faultray/"><img src="https://img.shields.io/pypi/dm/faultray" alt="Downloads"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSL%201.1-orange.svg" alt="License"></a>
  <a href="https://doi.org/10.5281/zenodo.19139911"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19139911.svg" alt="DOI"></a>
  <a href="https://github.com/mattyopon/ai-agent-security-suite"><img src="https://img.shields.io/badge/Part%20of-AI%20Agent%20Security%20Suite-blueviolet" alt="Part of AI Agent Security Suite"></a>
</p>

---

FaultRay builds a mathematical model of your infrastructure and simulates **2,000+ failure scenarios** entirely in memory. Nothing gets touched. Nothing breaks. You just get answers.

```bash
pip install faultray
faultray demo
```

```
╭────────── FaultRay Chaos Simulation Report ──────────╮
│ Resilience Score: 36/100                             │
│ Scenarios tested: 2,000+                             │
│ Critical: 7  Warning: 66  Passed: 77                 │
╰──────────────────────────────────────────────────────╯
```

## Quick Start

### Terraform Safety Net (most common use case)

```bash
terraform plan -out=plan.out
terraform show -json plan.out > plan.json
faultray tf-check plan.json --fail-on-regression --min-score 60
```

```yaml
# .github/workflows/terraform.yml
- name: Check Terraform Plan
  run: |
    pip install faultray
    terraform show -json plan.out > plan.json
    faultray tf-check plan.json --fail-on-regression --min-score 60
```

### Define Your Infrastructure

```yaml
# infra.yaml
components:
  - id: nginx
    type: load_balancer
    replicas: 2
  - id: api
    type: app_server
    replicas: 3
  - id: postgres
    type: database
    replicas: 1   # ← FaultRay flags this as SPOF

dependencies:
  - source: nginx
    target: api
    type: requires
  - source: api
    target: postgres
    type: requires
```

```bash
faultray load infra.yaml
faultray simulate --html report.html
```

### AI Agent Testing

```bash
faultray agent assess ai-workflow.yaml    # Risk assessment
faultray agent scenarios ai-workflow.yaml # What could go wrong?
```

Simulates AI-specific failures: hallucination cascades, context overflow, LLM rate limiting, token exhaustion, tool failures, agent loops, prompt injection.

### Docker

```bash
docker compose up web                          # Web dashboard
docker compose --profile demo up demo          # Demo mode
```

## Key Features

| Feature | Description |
|---|---|
| **5 Simulation Engines** | Cascade, Dynamic, Ops, What-If, Capacity |
| **5-Layer Availability Model** | Mathematical proof of your uptime ceiling |
| **AI Agent Testing** | 7 agent-specific fault types (hallucination, loops, etc.) |
| **Terraform Integration** | Pre-apply impact analysis in CI/CD |
| **Compliance** | SOC 2, ISO 27001, PCI DSS, DORA, HIPAA, GDPR |
| **Security Feed** | Auto-generate scenarios from CVE/CISA advisories |
| **100+ CLI Commands** | From `faultray demo` to `faultray war-room` |

## How It Compares

| | Gremlin | Steadybit | AWS FIS | **FaultRay** |
|---|---|---|---|---|
| Approach | Breaks production | Breaks production | Breaks production | **Math simulation** |
| Risk | Medium-High | Medium | Medium | **Zero** |
| Setup | Agent per host | Agent per host | AWS only | **`pip install`** |
| AI agent testing | No | No | No | **Yes** |
| Cost | $$$$ | $$$ | $$ | **Free / OSS** |

## Research & Patent

FaultRay's core algorithms are described in a peer-reviewable paper and protected by a US patent application.

**Paper:**
> Maeda, Y. (2026). *FaultRay: In-Memory Infrastructure Resilience Simulation with Graph-Based Cascade Analysis, Multi-Layer Availability Limits, and AI Agent Failure Modeling.* Zenodo. [DOI: 10.5281/zenodo.19139911](https://doi.org/10.5281/zenodo.19139911)

**Patent:**
> US Provisional Patent Application No. 64/010,200 (filed March 19, 2026)
> Status: Provisional patent filed. Full utility patent filing deadline: March 19, 2027.

**Citation:**

```bibtex
@misc{maeda2026faultray,
  author    = {Maeda, Yutaro},
  title     = {FaultRay: In-Memory Infrastructure Resilience Simulation},
  year      = {2026},
  doi       = {10.5281/zenodo.19139911},
  publisher = {Zenodo}
}
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
```

## Community

- [Contributing Guide](CONTRIBUTING.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)

## License

BSL 1.1 — see [LICENSE](LICENSE). Converts to Apache 2.0 on 2030-03-17.
