agentic-chaos 0.1.0__tar.gz

agentic_chaos-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # Proves agentic-chaos works with zero agenticlens installed: no sibling
+  # checkout, no [tool.uv.sources] override in play, just the core package.
+  test-core:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # --frozen: uv.lock resolves the agenticlens extra too (a local path
+      # source), so a normal `uv sync`/`uv run` tries to validate/refresh that
+      # entry even when the extra isn't requested -- and fails here since
+      # there's no sibling agenticlens checkout in this job. --frozen installs
+      # straight from the committed lock without touching it.
+      - name: Install dependencies (no agenticlens extra)
+        run: uv sync --extra dev --frozen --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff check)
+        run: uv run --frozen ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run --frozen ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run --frozen mypy
+
+      - name: Test (pytest) -- agenticlens integration tests auto-skip via importorskip
+        run: uv run --frozen pytest
+
+  # Covers agentic_chaos.integrations.agenticlens, which needs the optional
+  # extra installed. Both checkouts land as siblings under $GITHUB_WORKSPACE
+  # (.../agentic-chaos and .../agenticlens) so agentic-chaos's
+  # `[tool.uv.sources] agenticlens = { path = "../agenticlens" }` resolves
+  # correctly. actions/checkout refuses paths outside the workspace, so a
+  # literal `../agenticlens` path doesn't work here.
+  test-agenticlens-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out agentic-chaos
+        uses: actions/checkout@v4
+        with:
+          path: agentic-chaos
+
+      - name: Check out agenticlens (local dependency, not yet published with chaos_events support)
+        uses: actions/checkout@v4
+        with:
+          repository: DeepAgentLabs/agenticlens
+          path: agenticlens
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies (with the optional agenticlens extra)
+        working-directory: agentic-chaos
+        run: uv sync --extra dev --extra agenticlens --python 3.12
+
+      - name: Type check (mypy) -- exercises the integration module against the real package
+        working-directory: agentic-chaos
+        run: uv run mypy
+
+      - name: Test (pytest)
+        working-directory: agentic-chaos
+        run: uv run pytest
+
+  # Proves the built distribution's own metadata has no hard agenticlens
+  # dependency -- built with only the core dev extra, no sibling checkout.
+  package:
+    runs-on: ubuntu-latest
+    needs: [test-core, test-agenticlens-integration]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      # --frozen: see the comment on the same flag in test-core -- no sibling
+      # agenticlens checkout here, and the agenticlens extra isn't requested.
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen --python 3.12
+      - name: Build distributions
+        run: |
+          uv run --frozen python -m build
+          uv run --frozen python -m twine check dist/*

agentic_chaos-0.1.0/.github/workflows/release-pypi.yml

@@ -0,0 +1,46 @@
+name: publish-pypi
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC) -- no API token/secret needed
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentic_chaos-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+dist/
+build/
+site/
+.env
+*.chaos_run.json

agentic_chaos-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+### Added
+
+- `.github/workflows/release-pypi.yml`: publishes to PyPI on a `v*` tag push
+  or a published GitHub Release, via Trusted Publishing (OIDC) against the
+  `pypi` environment -- no stored API token.
+
+### Fixed
+
+- `uv sync --extra dev` (and CI) failed outright for anyone without a sibling
+  `agenticlens` checkout: `[tool.uv.sources]`'s local path override for the
+  optional `agenticlens` extra made `uv` try to validate/refresh that extra
+  on *every* sync, even when it wasn't requested. Fixed by using `--frozen`
+  wherever the sibling checkout isn't guaranteed (README's plain install
+  instructions, CI's `test-core` and `package` jobs) -- see README's
+  Installation/Development sections.
+
+### Changed
+
+- **`agenticlens` is no longer a required dependency.** `agentic_chaos.chaos`
+  (`chaos_call`, `chaos_session`, the fault types) and the CLI now work
+  standalone against any Python callable, no other package needed.
+  `chaos_call()` takes plain `step_id`/`step_name` strings instead of an
+  AgenticLens `StepHandle`.
+- `agentic-chaos chaos run --save` now writes this package's own standalone
+  `ChaosReport` (`id`, `name`, `start_time`, `end_time`, `chaos_events`)
+  instead of requiring the target script to build an AgenticLens `Workflow`
+  via `profile()`. A `ChaosReport`'s JSON is still valid AgenticLens
+  `Workflow` JSON (same field names, no `steps`), so `agenticlens analyze`
+  still works on it directly if you have AgenticLens installed -- interop
+  through a shared JSON shape, not a code dependency.
+- `agentic-chaos chaos run` now catches an uncaught exception from the target
+  script, still renders/saves whatever chaos events were recorded, and exits
+  non-zero -- previously an unhandled fault would crash the CLI before
+  `--save` ran.
+
+### Added
+
+- `examples/chaos_advanced_faults_demo.py`: `TokenTimeoutFault(mode="delay")`
+  and a custom `SilentDegradationFault(degrade_fn=...)`, the two fault
+  options that weren't demonstrated anywhere outside the tests. README's
+  Fault Types section links to it and the other examples now have an index
+  table.
+- `agentic_chaos.integrations.agenticlens` (optional, `pip install
+  agentic-chaos[agenticlens]`): `attach_events()` merges a chaos session's
+  events onto an AgenticLens `Workflow`; `step_kwargs()` extracts
+  `step_id`/`step_name` from a `StepHandle`. Neither `agentic_chaos`'s core
+  nor its CLI imports this module or `agenticlens`.
+  `examples/chaos_with_agenticlens_demo.py` shows the full round trip.
+- `agentic_chaos.chaos` — the LLM Chaos Toolkit (v0.1 milestone):
+  - `chaos_session()` / `chaos_call()` — explicit, contextvar-based fault
+    injection API.
+  - Three fault types: `TokenTimeoutFault`, `RateLimitStormFault`,
+    `SilentDegradationFault`.
+  - `agentic-chaos chaos run` CLI command.
+  - `chaos_events` schema (v1.1), documented in agenticlens's
+    `docs/workflow-schema-spec.md`.
+- `agenticlens.recommenders.ChaosImpactRecommender` — thin adapter (in the
+  agenticlens repo) that reads `chaos_events` and reports resilience findings
+  alongside AgenticLens's existing cost/latency recommendations.
+- Placeholder `agentic_chaos.agents` (v0.2) and `agentic_chaos.drift` (v0.3)
+  modules — not yet implemented.

agentic_chaos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepAgentLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_chaos-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: agentic-chaos
+Version: 0.1.0
+Summary: Standalone fault injection toolkit for LLM calls and agentic workflows, with an optional AgenticLens integration.
+Project-URL: Homepage, https://github.com/DeepAgentLabs/agentic-chaos
+Project-URL: Repository, https://github.com/DeepAgentLabs/agentic-chaos
+Project-URL: Issues, https://github.com/DeepAgentLabs/agentic-chaos/issues
+Project-URL: Changelog, https://github.com/DeepAgentLabs/agentic-chaos/blob/main/CHANGELOG.md
+Author: agentic-chaos Contributors
+License: MIT License
+        
+        Copyright (c) 2026 DeepAgentLabs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,chaos-engineering,fault-injection,llm,observability,resilience
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: agenticlens
+Requires-Dist: agenticlens>=0.1.3; extra == 'agenticlens'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentic-chaos
+
+`agentic-chaos` is a standalone fault-injection toolkit for LLM calls and
+agentic workflows. It deliberately breaks your app — hung completions,
+provider rate-limit storms, silently corrupted output — and reports what
+happened. It has **no required dependency on any other package**, including
+[AgenticLens](https://github.com/DeepAgentLabs/agenticlens): `pip install
+agentic-chaos` and use it against any plain Python callable.
+
+If you also use AgenticLens, an optional integration lets you merge chaos
+events straight into an AgenticLens `Workflow`, so `agenticlens analyze`
+reports on cost/latency and chaos impact together — see
+[Optional: AgenticLens Integration](#optional-agenticlens-integration) below.
+Neither package imports the other at the core level; the two are independent
+tools that happen to compose.
+
+## Status
+
+`agentic-chaos` is early-stage software (v0.1 — the **LLM Chaos Toolkit**).
+Two more modules are planned: an **Agent Failure Injector** for
+LangGraph/CrewAI/AutoGen (v0.2), and a **Prompt/Model Drift Detector** (v0.3).
+See [ROADMAP.md](ROADMAP.md) for the full plan.
+
+## Installation
+
+```bash
+pip install agentic-chaos
+```
+
+or, from source with `uv`:
+
+```bash
+git clone https://github.com/DeepAgentLabs/agentic-chaos.git
+cd agentic-chaos
+uv sync --extra dev --frozen
+```
+
+That's it — no other package required. (If you want the optional AgenticLens
+integration too, see [below](#optional-agenticlens-integration).)
+
+`--frozen` matters here: `pyproject.toml` points the (currently unpublished)
+`agenticlens` extra at a sibling checkout via `[tool.uv.sources]`, and `uv
+sync` without `--frozen` tries to validate/refresh the *entire* lock — every
+extra, including ones you didn't ask for — which fails if that sibling
+directory doesn't exist. `--frozen` installs straight from the committed
+`uv.lock` instead. Drop it (and check out `agenticlens` as a sibling
+directory) only if you're working on the optional integration itself — see
+[Development](#development).
+
+## Quickstart
+
+Wrap the calls you want to be fragile with `chaos_call()`:
+
+```python
+from agentic_chaos.chaos import chaos_call, TokenTimeoutError
+
+try:
+    chunks = chaos_call(retriever.search, user_question, faults=["token_timeout"])
+except TokenTimeoutError:
+    chunks = []  # no fallback handled it -- this is exactly what we want to find
+```
+
+Outside of a `chaos_session(...)`, `chaos_call()` is a transparent pass-through
+— `fn(*args, **kwargs)` runs exactly as if `agentic-chaos` weren't there. So
+the same instrumented code path is safe to ship; chaos only activates when you
+explicitly turn it on.
+
+Run the script under chaos from the CLI, choosing which faults are active
+without touching the code:
+
+```bash
+uv run agentic-chaos chaos run my_app.py --inject token_timeout,rate_limit_storm --save chaos_run.json
+```
+
+```text
+                                  Chaos Events
+  Step        Fault           Outcome    Message
+ ────────────────────────────────────────────────────────────────────────────
+  Retriever   token_timeout   errored    call hung for 2.0s then timed out
+
+1 chaos event(s) recorded.
+
+Saved chaos report to chaos_run.json
+```
+
+`chaos_run.json` is this package's own standalone report — no other library
+needed to produce or read it.
+
+## Fault Types (v0.1)
+
+| Fault | `--inject` name | What it does |
+| --- | --- | --- |
+| Token timeout | `token_timeout` | Hangs for `hang_seconds` (default 2.0s), then raises `TokenTimeoutError` — simulates a client-side timeout on a hung/slow completion. Pass `mode="delay"` to let the real call complete late instead of erroring. |
+| Rate-limit storm | `rate_limit_storm` | Raises `RateLimitStormError` (with a `retry_after` hint) for the first `burst_count` calls (default 3), then passes calls through normally — simulates a provider 429/backoff cascade that eventually clears. |
+| Silent degradation | `silent_degradation` | Calls the real function, then corrupts its text content (`.content`/`.text`/a raw string) while preserving latency and token counts. The hardest fault to detect and the highest-value one to catch — nothing in cost/latency telemetry looks wrong. |
+
+Every fault records a `ChaosEvent` (`fault_type`, `outcome`, and — when you
+pass `step_id`/`step_name` — the correlation you chose). Use the Python API
+to override defaults per fault:
+
+```python
+from agentic_chaos.chaos import chaos_session, TokenTimeoutFault, RateLimitStormFault
+
+with chaos_session([TokenTimeoutFault(hang_seconds=5.0), RateLimitStormFault(burst_count=1)]):
+    ...
+```
+
+When more than one fault is configured for a session, `chaos_call()` requires
+you to pass `faults=[...]` at each call site to say which one applies there —
+silently picking one for you would be surprising.
+
+Two options worth knowing about that don't show up in the table above (see
+[`examples/chaos_advanced_faults_demo.py`](examples/chaos_advanced_faults_demo.py)
+for both, runnable):
+
+- `TokenTimeoutFault(mode="delay")` — the call still succeeds, just late,
+  instead of raising `TokenTimeoutError`. Recorded outcome is `"delayed"`.
+  Useful for testing whether a slow-but-successful call degrades UX on its
+  own, separate from outright failure.
+- `SilentDegradationFault(degrade_fn=my_fn)` — swap in your own corruption
+  logic (`my_fn(result) -> corrupted_result`) instead of the built-in text
+  garbler, e.g. to simulate a narrower, more realistic bug than wholesale
+  noise.
+
+## CLI Reference
+
+```bash
+# Run a script with chaos active and print a chaos-events report.
+agentic-chaos chaos run my_app.py --inject token_timeout,rate_limit_storm
+
+# Same, saving the resulting standalone report for later inspection.
+agentic-chaos chaos run my_app.py --inject silent_degradation --save chaos_run.json
+
+# List available fault types.
+agentic-chaos chaos list-faults
+```
+
+`agentic-chaos agent ...` and `agentic-chaos drift ...` are placeholders for
+the v0.2 and v0.3 modules — running them today prints a pointer to
+[ROADMAP.md](ROADMAP.md).
+
+## Examples
+
+| Script | Needs | Shows |
+| --- | --- | --- |
+| [`examples/chaos_customer_support_demo.py`](examples/chaos_customer_support_demo.py) | nothing but `agentic_chaos` | All three faults' default behavior in one flow: a rate-limit storm the app retries through and recovers from, a token timeout it doesn't handle (fails outright), and a silent degradation (normal-looking call, corrupted output). |
+| [`examples/chaos_advanced_faults_demo.py`](examples/chaos_advanced_faults_demo.py) | nothing but `agentic_chaos` | `TokenTimeoutFault(mode="delay")` and a custom `SilentDegradationFault(degrade_fn=...)`. |
+| [`examples/chaos_with_agenticlens_demo.py`](examples/chaos_with_agenticlens_demo.py) | `agentic-chaos[agenticlens]` | The optional integration: `attach_events()` + `step_kwargs()` merging chaos events onto a real AgenticLens `Workflow`. |
+
+Run any of them directly (`uv run python examples/...`), or the first two
+under the CLI:
+
+```bash
+uv run agentic-chaos chaos run examples/chaos_customer_support_demo.py \
+    --inject rate_limit_storm,token_timeout,silent_degradation --save /tmp/chaos_run.json
+```
+
+## Optional: AgenticLens Integration
+
+If you *also* use [AgenticLens](https://github.com/DeepAgentLabs/agenticlens)
+to profile cost/latency, install the extra:
+
+```bash
+pip install agentic-chaos[agenticlens]
+```
+
+Then correlate chaos events to AgenticLens steps and merge them onto the
+`Workflow` yourself:
+
+```python
+from agenticlens import profile, step
+from agenticlens.exporters import JSONExporter
+from agentic_chaos.chaos import chaos_call, chaos_session, TokenTimeoutError
+from agentic_chaos.integrations.agenticlens import attach_events, step_kwargs
+
+with chaos_session(["token_timeout"]) as session:
+    with profile("Customer Support Agent") as workflow:
+        with step("Retriever", type="retriever", chunk_count=4) as s:
+            try:
+                chunks = chaos_call(retriever.search, user_question, **step_kwargs(s))
+            except TokenTimeoutError:
+                chunks = []
+    attach_events(session, workflow)
+
+JSONExporter().export(workflow, "workflow.json")
+```
+
+```bash
+agenticlens analyze workflow.json
+```
+
+```text
+Optimization Suggestions
+  * Chaos impact: token_timeout on 'Retriever'
+    -- Injected fault 'token_timeout' hit step 'Retriever' 1 time and the call
+       raised an error each time (call hung for 2.0s then timed out). ... (~0 tokens)
+```
+
+`agentic_chaos.chaos_call()`/`chaos_session()` and the CLI never import
+AgenticLens — only `agentic_chaos.integrations.agenticlens` does, and only
+when you import it yourself. See
+[`examples/chaos_with_agenticlens_demo.py`](examples/chaos_with_agenticlens_demo.py)
+for a runnable version of the above.
+
+This works because `agentic-chaos`'s own report format (`ChaosReport`) and
+AgenticLens's `chaos_events` field share a documented JSON shape (schema
+v1.1, see
+[`docs/workflow-schema-spec.md`](https://github.com/DeepAgentLabs/agenticlens/blob/main/docs/workflow-schema-spec.md)
+in the agenticlens repo) — interop through a shared file format, not a code
+dependency in either direction.
+
+## Development
+
+Without a sibling `agenticlens` checkout, use `--frozen` (see
+[Installation](#installation) for why):
+
+```bash
+uv sync --extra dev --frozen
+uv run --frozen pytest
+uv run --frozen ruff check .
+uv run --frozen ruff format .
+uv run --frozen mypy
+```
+
+Tests covering `agentic_chaos.integrations.agenticlens` skip automatically if
+`agenticlens` isn't installed. To run the full suite including those, clone
+`agenticlens` as a sibling directory and sync with the optional extra
+(dropping `--frozen`, since now you *want* the lock to pick it up):
+
+```bash
+git clone https://github.com/DeepAgentLabs/agenticlens.git ../agenticlens
+uv sync --extra dev --extra agenticlens
+uv run pytest
+```
+
+(see [`[tool.uv.sources]`](pyproject.toml) for the local sibling-checkout override
+used until `agenticlens` publishes a release with `chaos_events` support).
+
+## License
+
+MIT — see [LICENSE](LICENSE).