Metadata-Version: 2.4
Name: loki-chaos-agent
Version: 1.11.0
Summary: Autonomous AI Testing & Synthetic Chaos Agent
Author: Elabsurdo984
License: MIT
Keywords: testing,chaos-engineering,playwright,ai-agent,qa,synthetic-testing,quality-assurance,devops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: shellingham>=1.5.4
Requires-Dist: playwright>=1.45.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: litellm>=1.40.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt_toolkit>=3.0.36
Requires-Dist: psutil>=5.9.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/logo.png" alt="LOKI Logo" width="160" />
</p>

<h1 align="center">LOKI Chaos</h1>

<p align="center">
  <strong>Autonomous AI Testing & Synthetic Chaos Agent</strong>
</p>

<p align="center">
  <a href="https://loki-agent.pages.dev"><img src="https://img.shields.io/badge/Docs-loki--agent.pages.dev-22c55e?logo=readthedocs&logoColor=white" alt="Documentation" /></a>
  <a href="https://github.com/Elabsurdo984/loki-agent/actions"><img src="https://img.shields.io/github/actions/workflow/status/Elabsurdo984/loki-agent/loki.yml?branch=main&label=CI%2FCD%20Gate&logo=github" alt="CI Gate" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python" alt="Python Version" /></a>
  <a href="https://playwright.dev/"><img src="https://img.shields.io/badge/Playwright-Chromium%20%7C%20Firefox%20%7C%20WebKit-green?logo=playwright" alt="Playwright" /></a>
  <a href="https://litellm.ai/"><img src="https://img.shields.io/badge/AI%20Brain-Gemini%20%2F%20LiteLLM-purple" alt="LiteLLM" /></a>
  <a href="#license"><img src="https://img.shields.io/badge/License-MIT-orange.svg" alt="License" /></a>
</p>

<p align="center">
  <a href="https://loki-agent.pages.dev"><strong>📘 Full Documentation</strong></a> •
  <a href="https://loki-agent.pages.dev/docs/installation">Installation</a> •
  <a href="https://loki-agent.pages.dev/docs/loki-run">CLI Reference</a> •
  <a href="https://github.com/Elabsurdo984/loki-agent/releases/latest">Releases</a>
</p>

---

## ⚡ Overview

**LOKI Chaos** (`loki` / `loki-chaos`) is a standalone CLI testing agent that breaks, explores, and verifies web applications before your users do. Instead of only testing "happy paths", LOKI unleashes synthetic chaos personas, in-flight API mutations, client state corruption, and multi-tab race probes—then packages every failure into a deterministic Playwright reproduction script (`repro_test.py`), video replay, sanitized `.har` trace, and standalone HTML report.

## 🌟 Highlights

- **🐝 Chaos Personas & Swarm Mode (`--swarm`)**: `RageClicker`, `NoviceChaotic`, `NetworkTormentor`, and `Adversary` across Chromium, Firefox, WebKit, and mobile viewports (`--device`).
- **⚡ Ghost in the Wire (`--api-chaos`)**: In-flight HTTP 500/502/503/429 injection, JSON schema stripping, and 401 auth token invalidation.
- **🧪 Poisoned Well (`--state-chaos`)**: `localStorage` / `sessionStorage` JSON rot, `QuotaExceededError` simulation, temporal clock drift (`Date.now`), and poisoned reload survival checks.
- **🔀 Concurrency & Infra Chaos**: Synchronized multi-tab race condition probes (`--concurrency`) and local process/container fault injection (`loki infra`).
- **🧠 AI Rules & Autonomous Self-Healing**: Evaluates plain-English business rules (`.loki/rules.md`) via any LiteLLM provider (Gemini, OpenAI, Anthropic, Ollama, etc.) and synthesizes verified surgical patches (`loki fix --apply`, `--auto-heal`).
- **💬 Interactive QA Terminal (`loki` / `loki chat`)**: Built-in REPL to inspect runs, switch AI models (`/model`), and dispatch `/run`, `/fix`, and `/report`.

---

## 🚀 Quickstart

### 1. Install

- **Precompiled Binaries & Windows Installer** *(no Python required)*: Download `loki-setup-windows-amd64.exe` or standalone binaries for Windows, Linux, and macOS from [**GitHub Releases**](https://github.com/Elabsurdo984/loki-agent/releases/latest).
- **Via `uv` (recommended for Python users)**:
  ```bash
  uv tool install loki-chaos-agent
  # Or run without installing:
  uvx --from loki-chaos-agent loki run http://localhost:8000 --swarm
  ```
- **Via `pipx`**:
  ```bash
  pipx install loki-chaos-agent
  ```

### 2. Run

```bash
# 1. Initialize workspace (.loki/config.yaml & .loki/rules.md)
loki init

# 2. Launch a multi-persona chaos assault and open the HTML dashboard
loki run http://localhost:8000 --swarm --open

# 3. Replay the failure deterministically or synthesize a verified code fix
loki replay
loki fix --apply

# 4. Open the interactive QA terminal assistant
loki
```

---

## 📘 Documentation

Full guides, configuration references, and examples live at **[loki-agent.pages.dev](https://loki-agent.pages.dev)** (available in English & Spanish):

- **[Getting Started & Installation](https://loki-agent.pages.dev/docs/installation)** — Binaries, `uv`, AI provider setup (`.loki/config.yaml`), and first run.
- **[Core Concepts](https://loki-agent.pages.dev/docs/chaos-personas)** — Chaos personas, Swarm mode, journey recording (`loki record`), and mobile emulation.
- **[CLI Reference](https://loki-agent.pages.dev/docs/loki-run)** — Complete flag reference for `run`, `fix`, `replay`, `report`, `chat`, `infra`, and `auth`.
- **[AI Brain & Self-Healing](https://loki-agent.pages.dev/docs/ai-providers-litellm)** — LiteLLM providers, `rules.md` assertions, and closed-loop code healing.
- **[Advanced Chaos](https://loki-agent.pages.dev/docs/api-and-auth-chaos)** — API chaos (*Ghost in the Wire*), state chaos (*Poisoned Well*), concurrency lanes, and infrastructure faults.
- **[Security & CI/CD](https://loki-agent.pages.dev/docs/security-policy)** — Authorization gate, HAR token scrubbing, and GitHub Actions quality gates (`--ci`).

---

## 🛡️ Security & Authorization Guardrail

Targeting `localhost` works out of the box. Against any remote host, LOKI blocks until you explicitly confirm ownership or written authorization (stored locally in `.loki/authorized_targets.json`, managed via `loki auth`). All captured network traces and recorded journeys automatically scrub credentials, cookies, and tokens. See [**`SECURITY.md`**](SECURITY.md) for details.

## 🤝 Contributing

Contributions and Pull Requests are welcome! You do not need an open issue to submit a PR.
- Read [**`CONTRIBUTING.md`**](CONTRIBUTING.md) for development setup and testing (`pytest`, `ruff`).
- Check [**`AGENTS.md`**](AGENTS.md) if working with AI coding agents.
- Browse open [`good first issue`](https://github.com/Elabsurdo984/loki-agent/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) tasks.

## 📄 License

Licensed under the [MIT License](LICENSE).
