fragility-engine 0.6.0__py3-none-any.whl

fragility_engine/__init__.py

@@ -0,0 +1,3 @@
+"""Fragility Discovery Engine — deterministic adversarial simulation search."""
+
+__version__ = "0.6.0"

fragility_engine/adversary/__init__.py

@@ -0,0 +1,27 @@
+from fragility_engine.adversary.encoding import decode_schedule, random_genome, schedule_attack_cost
+from fragility_engine.adversary.fitness import fitness_phase_a, fitness_severity_minus_cost, severity_score
+from fragility_engine.adversary.pareto import (
+    ParetoPoint,
+    merge_pareto_points,
+    pareto_indices,
+    pareto_point_from_rollout,
+    rollout_cloud_to_pareto,
+)
+from fragility_engine.adversary.search import genetic_search, genetic_vector_search, monte_carlo_search
+
+__all__ = [
+    "decode_schedule",
+    "random_genome",
+    "schedule_attack_cost",
+    "genetic_search",
+    "genetic_vector_search",
+    "monte_carlo_search",
+    "fitness_phase_a",
+    "fitness_severity_minus_cost",
+    "severity_score",
+    "pareto_indices",
+    "merge_pareto_points",
+    "pareto_point_from_rollout",
+    "rollout_cloud_to_pareto",
+    "ParetoPoint",
+]

fragility_engine/adversary/encoding.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import numpy as np
+
+from fragility_engine.types import ExogenousEvent, ShockKind
+
+SHOCK_KINDS: tuple[ShockKind, ...] = ("none", "reserve_loss", "rumor")
+
+# Abstract attacker budget units (not calibrated currency); tunable for search behavior.
+DEFAULT_ATTACK_COST_WEIGHTS: dict[ShockKind, float] = {
+    "none": 0.0,
+    "reserve_loss": 2.5,
+    "rumor": 1.0,
+}
+
+
+def decode_kind(index: int) -> ShockKind:
+    return SHOCK_KINDS[int(index) % len(SHOCK_KINDS)]
+
+
+def decode_schedule(genome: np.ndarray) -> dict[int, tuple[ExogenousEvent, ...]]:
+    """
+    Each row is one timestep: [kind_selector, magnitude].
+
+    kind_selector in [0,1) maps evenly to ShockKind via bucketization.
+    """
+
+    if genome.ndim != 2 or genome.shape[1] != 2:
+        raise ValueError("Genome must have shape (horizon, 2).")
+    horizon = genome.shape[0]
+    events: dict[int, tuple[ExogenousEvent, ...]] = {}
+    for t in range(horizon):
+        sel = float(np.clip(genome[t, 0], 0.0, 1.0 - 1e-9))
+        bucket = int(sel * len(SHOCK_KINDS))
+        if bucket >= len(SHOCK_KINDS):
+            bucket = len(SHOCK_KINDS) - 1
+        kind = SHOCK_KINDS[bucket]
+        mag = float(np.clip(genome[t, 1], 0.0, 1.0))
+        if kind == "none" or mag <= 1e-6:
+            continue
+        events[t] = (ExogenousEvent(kind=kind, magnitude=mag),)
+    return events
+
+
+def schedule_attack_cost(
+    schedule: dict[int, tuple[ExogenousEvent, ...]],
+    *,
+    weights: dict[ShockKind, float] | None = None,
+) -> float:
+    """Sum marginal attack costs for decoded shocks (magnitude scales linearly)."""
+
+    wmap = weights or DEFAULT_ATTACK_COST_WEIGHTS
+    total = 0.0
+    for events in schedule.values():
+        for e in events:
+            total += float(wmap[e.kind]) * float(np.clip(e.magnitude, 0.0, 1.0))
+    return float(total)
+
+
+def random_genome(horizon: int, rng: np.random.Generator) -> np.ndarray:
+    return rng.uniform(size=(horizon, 2))
+
+
+def mutate_genome(genome: np.ndarray, rng: np.random.Generator, rate: float = 0.15, sigma: float = 0.12) -> np.ndarray:
+    child = genome.copy()
+    mask = rng.random(size=genome.shape) < rate
+    noise = rng.normal(scale=sigma, size=genome.shape)
+    child = np.clip(child + mask * noise, 0.0, 1.0)
+    return child
+
+
+def crossover_genome(a: np.ndarray, b: np.ndarray, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    h = a.shape[0]
+    if h <= 1:
+        return a.copy(), b.copy()
+    cut = int(rng.integers(1, h))
+    c1 = np.vstack([a[:cut], b[cut:]])
+    c2 = np.vstack([b[:cut], a[cut:]])
+    return c1, c2

fragility_engine/adversary/fitness.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from fragility_engine.types import RolloutResult
+
+
+def severity_score(r: RolloutResult) -> float:
+    """Instability peak plus early-collapse bonus (matches legacy Phase A scalar without attack economics)."""
+
+    speed_bonus = 0.0
+    if r.collapsed and r.collapse_timestep is not None:
+        speed_bonus = 10.0 / (1 + r.collapse_timestep)
+    return float(r.final_instability + speed_bonus)
+
+
+def fitness_phase_a(r: RolloutResult) -> float:
+    """Backward-compatible scalar: severity only (attack_cost ignored)."""
+
+    return severity_score(r)
+
+
+def fitness_severity_minus_cost(*, attack_cost_weight: float) -> Callable[[RolloutResult], float]:
+    """Phase C hook: penalize expensive schedules."""
+
+    w = float(attack_cost_weight)
+
+    def _score(r: RolloutResult) -> float:
+        return severity_score(r) - w * r.attack_cost
+
+    return _score

fragility_engine/adversary/pareto.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fragility_engine.adversary.fitness import severity_score
+from fragility_engine.types import RolloutResult
+
+
+@dataclass(frozen=True)
+class ParetoPoint:
+    genome: np.ndarray
+    severity: float
+    attack_cost: float
+    collapsed: bool
+    integral_instability: float = 0.0
+
+
+def pareto_indices(severity: np.ndarray, attack_cost: np.ndarray) -> list[int]:
+    """Maximize severity, minimize attack_cost (pairwise dominance in 2D)."""
+
+    n = severity.shape[0]
+    keep: list[int] = []
+    for i in range(n):
+        dominated = False
+        for j in range(n):
+            if i == j:
+                continue
+            better_or_equal = severity[j] >= severity[i] and attack_cost[j] <= attack_cost[i]
+            strictly_better = severity[j] > severity[i] or attack_cost[j] < attack_cost[i]
+            if better_or_equal and strictly_better:
+                dominated = True
+                break
+        if not dominated:
+            keep.append(i)
+    return keep
+
+
+def pareto_point_from_rollout(genome: np.ndarray, rollout: RolloutResult) -> ParetoPoint:
+    return ParetoPoint(
+        genome=genome.copy(),
+        severity=float(severity_score(rollout)),
+        attack_cost=float(rollout.attack_cost),
+        collapsed=bool(rollout.collapsed),
+        integral_instability=float(rollout.integral_instability),
+    )
+
+
+def merge_pareto_points(points: list[ParetoPoint]) -> list[ParetoPoint]:
+    if not points:
+        return []
+    sev = np.array([p.severity for p in points], dtype=np.float64)
+    cost = np.array([p.attack_cost for p in points], dtype=np.float64)
+    idx = pareto_indices(sev, cost)
+    return [points[i] for i in idx]
+
+
+def rollout_cloud_to_pareto(genomes: list[np.ndarray], rollouts: list[RolloutResult]) -> list[ParetoPoint]:
+    sev = np.array([severity_score(r) for r in rollouts], dtype=np.float64)
+    cost = np.array([r.attack_cost for r in rollouts], dtype=np.float64)
+    idx = pareto_indices(sev, cost)
+    out: list[ParetoPoint] = []
+    for i in idx:
+        out.append(
+            ParetoPoint(
+                genome=genomes[i].copy(),
+                severity=float(sev[i]),
+                attack_cost=float(cost[i]),
+                collapsed=rollouts[i].collapsed,
+                integral_instability=float(rollouts[i].integral_instability),
+            )
+        )
+    return out

fragility_engine/adversary/search.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import pickle
+from collections.abc import Callable
+from functools import partial
+from typing import Any, Literal
+
+import numpy as np
+
+from fragility_engine.adversary.encoding import crossover_genome, mutate_genome, random_genome
+from fragility_engine.adversary.fitness import fitness_phase_a
+from fragility_engine.adversary.pareto import ParetoPoint, merge_pareto_points, pareto_point_from_rollout
+from fragility_engine.parallel_rollouts import process_pool_map_ordered, thread_pool_map_ordered
+from fragility_engine.types import RolloutResult, SearchResult
+
+EvalPool = Literal["threads", "processes"]
+
+
+def _fitness_rollout_pair(
+    pair: tuple[np.ndarray, int],
+    *,
+    rollout_fn: Callable[[np.ndarray, int], RolloutResult],
+    score: Callable[[RolloutResult], float],
+) -> tuple[float, RolloutResult]:
+    ind, s = pair
+    rr = rollout_fn(ind, s)
+    return float(score(rr)), rr
+
+
+def _ordered_map(
+    pool: EvalPool,
+    fn: Callable[[tuple[np.ndarray, int]], tuple[float, RolloutResult]],
+    pairs: list[tuple[np.ndarray, int]],
+    *,
+    max_workers: int,
+) -> list[tuple[float, RolloutResult]]:
+    if max_workers <= 1:
+        return [fn(p) for p in pairs]
+    if pool == "processes":
+        try:
+            pickle.dumps(fn)
+        except Exception as e:
+            raise ValueError(
+                "eval_pool='processes' requires a picklable rollout_fn bound for workers "
+                "(e.g. functools.partial(fragility_engine.benchmarks.suite.rollout_bundle_with_genome, "
+                "<bundle_id>, isolate=True))."
+            ) from e
+        return list(process_pool_map_ordered(fn, pairs, max_workers=max_workers))
+    return list(thread_pool_map_ordered(fn, pairs, max_workers=max_workers))
+
+
+def monte_carlo_search(
+    rollout_fn: Callable[[np.ndarray, int], RolloutResult],
+    *,
+    horizon: int,
+    samples: int,
+    seed: int,
+    fitness_fn: Callable[[RolloutResult], float] | None = None,
+    collect_pareto: bool = False,
+    eval_workers: int = 1,
+    eval_pool: EvalPool = "threads",
+) -> SearchResult:
+    score = fitness_fn or fitness_phase_a
+    ew = int(eval_workers)
+    if ew < 1:
+        raise ValueError("eval_workers must be >= 1")
+    if eval_pool not in ("threads", "processes"):
+        raise ValueError("eval_pool must be 'threads' or 'processes'")
+    pool: EvalPool = eval_pool
+    rng = np.random.default_rng(seed)
+    best_genome = random_genome(horizon, rng)
+    best_rollout = rollout_fn(best_genome, seed + 1)
+    best_fitness = float(score(best_rollout))
+
+    history: list[dict[str, Any]] = []
+    archive: list[ParetoPoint] = []
+    if collect_pareto:
+        archive.append(pareto_point_from_rollout(best_genome, best_rollout))
+
+    trial_genomes = [random_genome(horizon, rng) for _ in range(samples)]
+    pairs: list[tuple[np.ndarray, int]] = [(trial_genomes[i], seed + 2 + i) for i in range(samples)]
+
+    _fn = partial(_fitness_rollout_pair, rollout_fn=rollout_fn, score=score)
+    mc_results = _ordered_map(pool, _fn, pairs, max_workers=ew)
+    for i in range(samples):
+        fitness, r = mc_results[i]
+        g = trial_genomes[i]
+        history.append({"sample": i, "fitness": fitness, "collapsed": r.collapsed})
+        if collect_pareto:
+            archive.append(pareto_point_from_rollout(g, r))
+        if fitness > best_fitness:
+            best_fitness = fitness
+            best_genome = g
+            best_rollout = r
+
+    pareto_archive = merge_pareto_points(archive) if collect_pareto else []
+    return SearchResult(
+        best_genome=best_genome,
+        best_fitness=best_fitness,
+        best_rollout=best_rollout,
+        history=history,
+        pareto_archive=pareto_archive,
+    )
+
+
+def genetic_search(
+    rollout_fn: Callable[[np.ndarray, int], RolloutResult],
+    *,
+    horizon: int,
+    generations: int,
+    population_size: int,
+    seed: int,
+    elite_frac: float = 0.2,
+    mutation_rate: float = 0.18,
+    mutation_sigma: float = 0.14,
+    fitness_fn: Callable[[RolloutResult], float] | None = None,
+    collect_pareto: bool = False,
+    eval_workers: int = 1,
+    eval_pool: EvalPool = "threads",
+) -> SearchResult:
+    score = fitness_fn or fitness_phase_a
+    ew = int(eval_workers)
+    if ew < 1:
+        raise ValueError("eval_workers must be >= 1")
+    if eval_pool not in ("threads", "processes"):
+        raise ValueError("eval_pool must be 'threads' or 'processes'")
+    pool: EvalPool = eval_pool
+    rng = np.random.default_rng(seed)
+    population = [random_genome(horizon, rng) for _ in range(population_size)]
+
+    best_rollout = rollout_fn(population[0], seed + 7)
+    best_fitness = float(score(best_rollout))
+    best_genome = population[0].copy()
+    history: list[dict[str, Any]] = []
+    archive: list[ParetoPoint] = []
+    if collect_pareto:
+        archive.append(pareto_point_from_rollout(population[0], best_rollout))
+
+    for gen in range(generations):
+        seed_base = seed + 1000 + gen * population_size
+        pairs: list[tuple[np.ndarray, int]] = [(population[idx], seed_base + idx) for idx in range(population_size)]
+
+        _fn = partial(_fitness_rollout_pair, rollout_fn=rollout_fn, score=score)
+        evaluated = _ordered_map(pool, _fn, pairs, max_workers=ew)
+        fitnesses = [e[0] for e in evaluated]
+        for idx, (fit, rr) in enumerate(evaluated):
+            individual = population[idx]
+            if collect_pareto:
+                archive.append(pareto_point_from_rollout(individual, rr))
+            if fit > best_fitness:
+                best_fitness = fit
+                best_genome = individual.copy()
+                best_rollout = rr
+
+        history.append(
+            {
+                "generation": gen,
+                "mean_fitness": float(np.mean(fitnesses)),
+                "max_fitness": float(np.max(fitnesses)),
+            }
+        )
+
+        elite_n = max(1, int(population_size * elite_frac))
+        ranked = sorted(range(population_size), key=lambda i: fitnesses[i], reverse=True)
+        elites = [population[i].copy() for i in ranked[:elite_n]]
+
+        next_pop: list[np.ndarray] = elites[:]
+        while len(next_pop) < population_size:
+            if elite_n >= 2:
+                i1, i2 = rng.choice(elite_n, size=2, replace=False)
+                parent_a, parent_b = elites[i1], elites[i2]
+            else:
+                parent_a = parent_b = elites[0]
+            c1, c2 = crossover_genome(parent_a, parent_b, rng)
+            c1 = mutate_genome(c1, rng, rate=mutation_rate, sigma=mutation_sigma)
+            c2 = mutate_genome(c2, rng, rate=mutation_rate, sigma=mutation_sigma)
+            next_pop.append(c1)
+            if len(next_pop) < population_size:
+                next_pop.append(c2)
+
+        population = next_pop[:population_size]
+
+    pareto_archive = merge_pareto_points(archive) if collect_pareto else []
+    return SearchResult(
+        best_genome=best_genome,
+        best_fitness=best_fitness,
+        best_rollout=best_rollout,
+        history=history,
+        pareto_archive=pareto_archive,
+    )
+
+
+def _random_vector(dim: int, rng: np.random.Generator) -> np.ndarray:
+    return rng.uniform(size=(dim,))
+
+
+def _mutate_vector(vec: np.ndarray, rng: np.random.Generator, *, rate: float, sigma: float) -> np.ndarray:
+    mask = rng.random(size=vec.shape) < rate
+    noise = rng.normal(scale=sigma, size=vec.shape)
+    return np.clip(vec + mask * noise, 0.0, 1.0)
+
+
+def _crossover_vector(a: np.ndarray, b: np.ndarray, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    dim = a.shape[0]
+    if dim <= 1:
+        return a.copy(), b.copy()
+    cut = int(rng.integers(1, dim))
+    c1 = np.concatenate([a[:cut], b[cut:]])
+    c2 = np.concatenate([b[:cut], a[cut:]])
+    return c1, c2
+
+
+def genetic_vector_search(
+    rollout_fn: Callable[[np.ndarray, int], RolloutResult],
+    *,
+    dim: int,
+    generations: int,
+    population_size: int,
+    seed: int,
+    elite_frac: float = 0.2,
+    mutation_rate: float = 0.28,
+    mutation_sigma: float = 0.18,
+    fitness_fn: Callable[[RolloutResult], float] | None = None,
+    collect_pareto: bool = False,
+    eval_workers: int = 1,
+    eval_pool: EvalPool = "threads",
+) -> SearchResult:
+    """Evolutionary search over a bounded ``[0, 1]^{dim}`` defender/policy vector."""
+
+    score = fitness_fn or fitness_phase_a
+    ew = int(eval_workers)
+    if ew < 1:
+        raise ValueError("eval_workers must be >= 1")
+    if eval_pool not in ("threads", "processes"):
+        raise ValueError("eval_pool must be 'threads' or 'processes'")
+    pool: EvalPool = eval_pool
+    rng = np.random.default_rng(seed)
+    population = [_random_vector(dim, rng) for _ in range(population_size)]
+
+    best_rollout = rollout_fn(population[0], seed + 7)
+    best_fitness = float(score(best_rollout))
+    best_genome = population[0].copy()
+    history: list[dict[str, Any]] = []
+    archive: list[ParetoPoint] = []
+    if collect_pareto:
+        archive.append(pareto_point_from_rollout(population[0], best_rollout))
+
+    for gen in range(generations):
+        seed_base = seed + 2000 + gen * population_size
+        pairs = [(population[idx], seed_base + idx) for idx in range(population_size)]
+
+        _fn = partial(_fitness_rollout_pair, rollout_fn=rollout_fn, score=score)
+        evaluated = _ordered_map(pool, _fn, pairs, max_workers=ew)
+        fitnesses = [e[0] for e in evaluated]
+        for idx, (fit, rr) in enumerate(evaluated):
+            individual = population[idx]
+            if collect_pareto:
+                archive.append(pareto_point_from_rollout(individual, rr))
+            if fit > best_fitness:
+                best_fitness = fit
+                best_genome = individual.copy()
+                best_rollout = rr
+
+        history.append(
+            {
+                "generation": gen,
+                "mean_fitness": float(np.mean(fitnesses)),
+                "max_fitness": float(np.max(fitnesses)),
+            }
+        )
+
+        elite_n = max(1, int(population_size * elite_frac))
+        ranked = sorted(range(population_size), key=lambda i: fitnesses[i], reverse=True)
+        elites = [population[i].copy() for i in ranked[:elite_n]]
+
+        next_pop: list[np.ndarray] = elites[:]
+        while len(next_pop) < population_size:
+            if elite_n >= 2:
+                i1, i2 = rng.choice(elite_n, size=2, replace=False)
+                pa, pb = elites[i1], elites[i2]
+            else:
+                pa = pb = elites[0]
+            c1, c2 = _crossover_vector(pa, pb, rng)
+            c1 = _mutate_vector(c1, rng, rate=mutation_rate, sigma=mutation_sigma)
+            c2 = _mutate_vector(c2, rng, rate=mutation_rate, sigma=mutation_sigma)
+            next_pop.append(c1)
+            if len(next_pop) < population_size:
+                next_pop.append(c2)
+
+        population = next_pop[:population_size]
+
+    pareto_archive = merge_pareto_points(archive) if collect_pareto else []
+    return SearchResult(
+        best_genome=best_genome,
+        best_fitness=best_fitness,
+        best_rollout=best_rollout,
+        history=history,
+        pareto_archive=pareto_archive,
+    )

fragility_engine/agents/__init__.py

@@ -0,0 +1,3 @@
+from fragility_engine.agents.stablecoin_agents import AgentPopulation
+
+__all__ = ["AgentPopulation"]

fragility_engine/agents/base.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+import numpy as np
+
+
+class BehaviorArchetype(Protocol):
+    """Small, fast response rules so search can run many rollouts."""
+
+    name: str
+
+    def redeem_fraction(self, observation: dict[str, float], rng: np.random.Generator) -> float:
+        """Return desired aggregate redemption pressure in [0, 1]."""

fragility_engine/agents/stablecoin_agents.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class RationalArchetype:
+    name: str = "rational"
+    backing_trigger: float = 0.97
+
+    def redeem_fraction(self, observation: dict[str, float], rng: np.random.Generator) -> float:
+        price = observation["price"]
+        if price < self.backing_trigger:
+            # Stronger response as backing deteriorates.
+            urgency = float(np.clip((self.backing_trigger - price) / 0.08, 0.0, 1.0))
+            return float(np.clip(0.15 + 0.85 * urgency, 0.0, 1.0))
+        return 0.03
+
+
+@dataclass
+class PanicArchetype:
+    name: str = "panic"
+    panic_slope: float = 1.4
+
+    def redeem_fraction(self, observation: dict[str, float], rng: np.random.Generator) -> float:
+        panic = observation["panic"]
+        price = observation["price"]
+        base = float(np.clip(self.panic_slope * panic, 0.0, 1.0))
+        if price < 0.99:
+            base = float(np.clip(base + 0.25, 0.0, 1.0))
+        return float(np.clip(base, 0.0, 1.0))
+
+
+@dataclass
+class WhaleArchetype:
+    name: str = "whale"
+    supply_fraction: float = 0.22
+    flee_backing: float = 0.985
+
+    def redeem_fraction(self, observation: dict[str, float], rng: np.random.Generator) -> float:
+        price = observation["price"]
+        panic = observation["panic"]
+        if price < self.flee_backing or panic > 0.55:
+            return float(np.clip(self.supply_fraction * 3.6, 0.0, 1.0))
+        return 0.02
+
+
+@dataclass
+class AgentPopulation:
+    """
+    Weighted mixture of archetypes producing aggregate redemption pressure.
+
+    This stays deterministic given `rng` — no LLM policies.
+    """
+
+    archetypes: list[tuple[float, RationalArchetype | PanicArchetype | WhaleArchetype]]
+    weights: np.ndarray | None = None
+
+    def reset(self, initial_supply: float, rng: np.random.Generator) -> None:
+        del initial_supply, rng  # hook for future heterogeneity
+        total = sum(w for w, _ in self.archetypes)
+        self.weights = np.array([w / total for w, _ in self.archetypes], dtype=np.float64)
+
+    def aggregate_redeem_fraction(self, observation: dict[str, float], rng: np.random.Generator) -> float:
+        if self.weights is None:
+            raise RuntimeError("Population not initialized; call reset().")
+        demands = np.array([a.redeem_fraction(observation, rng) for _, a in self.archetypes], dtype=np.float64)
+        return float(np.dot(self.weights, demands))
+
+
+def default_stablecoin_population() -> AgentPopulation:
+    return AgentPopulation(
+        archetypes=[
+            (0.62, RationalArchetype()),
+            (0.28, PanicArchetype()),
+            (0.10, WhaleArchetype()),
+        ]
+    )