chaos-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyas Kapale
+
+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.

package/README.md

@@ -0,0 +1,63 @@
+# chaos-agents
+
+**Chaos Monkey, but for AI agents.**
+
+`chaos-agents` injects controlled faults — latency, errors, corrupted /
+truncated / empty outputs — into your agent and tool functions, so you can find
+out how your system behaves *before* the real world does it for you.
+
+> ⚠️ Early alpha (v0.1.0). The API is small on purpose and will grow.
+
+## Install
+
+```bash
+pip install chaos-agents
+```
+
+## Usage
+
+```python
+from chaos_agents import ChaosMonkey
+
+# Roll the dice on every call.
+monkey = ChaosMonkey(
+    latency=0.3,      # 30% chance of an artificial delay
+    errors=0.1,       # 10% chance of raising ChaosError
+    corruption=0.1,   # 10% chance of scrambling the string output
+    truncation=0.05,  # 5%  chance of truncating the output
+    seed=42,          # reproducible chaos
+)
+
+@monkey.wrap
+def my_agent(prompt: str) -> str:
+    return call_llm(prompt)
+
+my_agent("summarize this document")
+print(monkey.report())   # {'latency': 1, 'errors': 0, ...}
+```
+
+You can also wrap inline:
+
+```python
+result = monkey.run(call_llm, prompt)
+```
+
+Disable chaos in production without touching call sites:
+
+```python
+monkey = ChaosMonkey(errors=0.1, enabled=False)
+```
+
+## Built-in faults
+
+| Fault        | What it simulates                                  |
+| ------------ | -------------------------------------------------- |
+| `latency`    | slow / hanging agents and tools                    |
+| `errors`     | crashes and tool failures (raises `ChaosError`)    |
+| `corruption` | hallucinated / garbled responses                   |
+| `truncation` | token-limit cutoffs and interrupted streams        |
+| `empty`      | silent / dropped responses                         |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "chaos-agents",
+  "version": "0.1.0",
+  "description": "Chaos engineering for AI agents — Chaos Monkey, but for your agents and tools.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/smoke.test.js"
+  },
+  "keywords": [
+    "chaos-engineering",
+    "ai-agents",
+    "llm",
+    "testing",
+    "resilience",
+    "fault-injection",
+    "chaos-monkey"
+  ],
+  "author": "Shreyas Kapale <shreyas@lyzr.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lyzr-ai/chaos-agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lyzr-ai/chaos-agents/issues"
+  },
+  "homepage": "https://github.com/lyzr-ai/chaos-agents#readme",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,58 @@
+export declare const VERSION: string;
+
+export declare class ChaosError extends Error {
+  constructor(message?: string);
+}
+
+export interface ChaosMonkeyOptions {
+  /** Probability [0,1] of injecting an artificial delay. */
+  latency?: number;
+  /** Probability [0,1] of throwing ChaosError instead of running. */
+  errors?: number;
+  /** Probability [0,1] of scrambling a string return value. */
+  corruption?: number;
+  /** Probability [0,1] of truncating a string return value. */
+  truncation?: number;
+  /** Probability [0,1] of blanking the return value. */
+  empty?: number;
+  /** Seed for reproducible chaos. */
+  seed?: number;
+  /** Master switch; when false, calls pass through untouched. Default true. */
+  enabled?: boolean;
+  /** Delay bounds in milliseconds for the latency fault. Default [100, 2000]. */
+  latencyRange?: [number, number];
+}
+
+export type FaultName =
+  | "latency"
+  | "errors"
+  | "corruption"
+  | "truncation"
+  | "empty";
+
+export declare class ChaosMonkey {
+  probabilities: Record<FaultName, number>;
+  enabled: boolean;
+  latencyRange: [number, number];
+  log: FaultName[];
+
+  constructor(opts?: ChaosMonkeyOptions);
+
+  /** Invoke `fn` once, applying any faults that trigger this call. */
+  run<T>(fn: (...args: any[]) => T | Promise<T>, ...args: any[]): Promise<T>;
+
+  /** Wrap a function so every call may have faults injected. */
+  wrap<F extends (...args: any[]) => any>(
+    fn: F
+  ): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+
+  /** Count how many times each fault has fired so far. */
+  report(): Record<FaultName, number>;
+}
+
+declare const _default: {
+  ChaosMonkey: typeof ChaosMonkey;
+  ChaosError: typeof ChaosError;
+  VERSION: string;
+};
+export default _default;

package/src/index.js

@@ -0,0 +1,148 @@
+/**
+ * chaos-agents: Chaos engineering for AI agents.
+ *
+ * Chaos Monkey, but for AI agents. Inject controlled faults — latency,
+ * errors, corrupted/truncated/empty outputs — into your agent or tool
+ * functions to test how resilient they really are.
+ *
+ * @example
+ *   import { ChaosMonkey } from "chaos-agents";
+ *
+ *   const monkey = new ChaosMonkey({ latency: 0.3, errors: 0.1, seed: 42 });
+ *   const agent = monkey.wrap(async (prompt) => callLLM(prompt));
+ *   await agent("hello"); // may be delayed, may throw, may return garbage
+ */
+
+export const VERSION = "0.1.0";
+
+/** Error thrown by the `errors` fault to simulate an agent/tool failure. */
+export class ChaosError extends Error {
+  constructor(message = "chaos-agents: injected failure") {
+    super(message);
+    this.name = "ChaosError";
+  }
+}
+
+/** Small seedable PRNG (mulberry32) so chaos can be made reproducible. */
+function makeRng(seed) {
+  if (seed === undefined || seed === null) {
+    return Math.random;
+  }
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Output-mangling faults, applied to the resolved return value. */
+const OUTPUT_FAULTS = {
+  corruption(rng, value) {
+    if (typeof value !== "string" || value.length === 0) return value;
+    const chars = value.split("");
+    const swaps = Math.max(1, Math.floor(chars.length / 10));
+    for (let n = 0; n < swaps; n++) {
+      const i = Math.floor(rng() * chars.length);
+      const j = Math.floor(rng() * chars.length);
+      [chars[i], chars[j]] = [chars[j], chars[i]];
+    }
+    return chars.join("");
+  },
+  truncation(rng, value) {
+    if (typeof value !== "string" || value.length === 0) return value;
+    return value.slice(0, Math.floor(rng() * (value.length + 1)));
+  },
+  empty(rng, value) {
+    if (typeof value === "string") return "";
+    if (Array.isArray(value)) return [];
+    if (value && typeof value === "object") return {};
+    return null;
+  },
+};
+
+/**
+ * Wrap agent/tool callables and randomly inject faults. Each fault has an
+ * independent probability in [0, 1]; on every call the monkey rolls per fault
+ * and applies the ones that trigger. The wrapped function is always async.
+ */
+export class ChaosMonkey {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.latency=0]    probability of an artificial delay
+   * @param {number} [opts.errors=0]     probability of throwing ChaosError
+   * @param {number} [opts.corruption=0] probability of scrambling a string result
+   * @param {number} [opts.truncation=0] probability of truncating a string result
+   * @param {number} [opts.empty=0]      probability of blanking the result
+   * @param {number} [opts.seed]         seed for reproducible chaos
+   * @param {boolean}[opts.enabled=true] master switch
+   * @param {[number,number]} [opts.latencyRange=[100,2000]] delay bounds in ms
+   */
+  constructor(opts = {}) {
+    this.probabilities = {
+      latency: opts.latency ?? 0,
+      errors: opts.errors ?? 0,
+      corruption: opts.corruption ?? 0,
+      truncation: opts.truncation ?? 0,
+      empty: opts.empty ?? 0,
+    };
+    this.enabled = opts.enabled ?? true;
+    this.latencyRange = opts.latencyRange ?? [100, 2000];
+    this._rng = makeRng(opts.seed);
+    this.log = [];
+  }
+
+  _fires(name) {
+    return this._rng() < (this.probabilities[name] ?? 0);
+  }
+
+  /** Invoke `fn` once, applying any faults that trigger this call. */
+  async run(fn, ...args) {
+    if (!this.enabled) return fn(...args);
+
+    if (this._fires("latency")) {
+      this.log.push("latency");
+      const [lo, hi] = this.latencyRange;
+      await sleep(lo + this._rng() * (hi - lo));
+    }
+
+    if (this._fires("errors")) {
+      this.log.push("errors");
+      throw new ChaosError();
+    }
+
+    const result = await fn(...args);
+
+    for (const name of ["corruption", "truncation", "empty"]) {
+      if (this._fires(name)) {
+        this.log.push(name);
+        return OUTPUT_FAULTS[name](this._rng, result);
+      }
+    }
+    return result;
+  }
+
+  /** Decorator/wrapper form of {@link run}. Returns an async function. */
+  wrap(fn) {
+    const self = this;
+    const wrapped = function (...args) {
+      return self.run(fn, ...args);
+    };
+    wrapped.__chaos__ = this;
+    return wrapped;
+  }
+
+  /** Count how many times each fault has fired so far. */
+  report() {
+    const counts = {};
+    for (const name of Object.keys(this.probabilities)) counts[name] = 0;
+    for (const name of this.log) counts[name] += 1;
+    return counts;
+  }
+}
+
+export default { ChaosMonkey, ChaosError, VERSION };