datadoom 0.1.0.dev0__py3-none-any.whl

datadoom/engine/spec/validate.py

@@ -0,0 +1,345 @@
+"""Cross-field spec validation (04 §9).
+
+Pydantic handles shape/type. This module enforces semantic rules that span
+multiple parts of the spec — references, acyclicity, derived-vs-sampled
+consistency — raising :class:`SpecValidationError` with a ``locator`` pointing
+at the offending control.
+"""
+
+from __future__ import annotations
+
+from ..errors import SpecValidationError
+from .models import (
+    BooleanFeature,
+    CategoricalFeature,
+    NumericFeature,
+    Spec,
+    TextFeature,
+    TimeseriesFeature,
+)
+
+SUPPORTED_SPEC_VERSIONS = {"1"}
+
+
+def validate_spec(spec: Spec) -> None:
+    """Run all cross-field checks. Raises on the first violation."""
+    _check_version(spec)
+    _check_features(spec)
+    _check_causal(spec)
+    _check_difficulty(spec)
+    _check_failures(spec)
+    _check_export(spec)
+
+
+def _check_version(spec: Spec) -> None:
+    if spec.datadoom_version not in SUPPORTED_SPEC_VERSIONS:
+        raise SpecValidationError(
+            f"unsupported datadoom_version {spec.datadoom_version!r} "
+            f"(supported: {sorted(SUPPORTED_SPEC_VERSIONS)})",
+            locator="datadoom_version",
+        )
+
+
+def _check_features(spec: Spec) -> None:
+    # Lazy import to keep the dist layer optional at module load time.
+    from ..dist.builtins import REGISTRY
+    from ..dist.providers import is_realistic_generator, resolve_locale
+
+    derived = _derived_names(spec)
+    for name, feat in spec.features.items():
+        loc = f"features.{name}"
+        if isinstance(feat, NumericFeature):
+            if feat.min is not None and feat.max is not None and feat.min > feat.max:
+                raise SpecValidationError("min > max", locator=loc)
+            if feat.dist is not None:
+                dist = REGISTRY.get(feat.dist)
+                if dist is None:
+                    raise SpecValidationError(
+                        f"unknown distribution {feat.dist!r}", locator=f"{loc}.dist"
+                    )
+                dist.validate(feat.params, locator=f"{loc}.params")
+            elif name not in derived:
+                # No dist and not produced by the causal layer → unsamplable.
+                raise SpecValidationError(
+                    f"numeric feature {name!r} has no 'dist' and is not a causal target "
+                    "(it cannot be sampled or derived)",
+                    locator=loc,
+                )
+        elif isinstance(feat, CategoricalFeature):
+            if feat.weights is not None and len(feat.weights) != len(feat.categories):
+                raise SpecValidationError(
+                    "weights length must match categories length", locator=f"{loc}.weights"
+                )
+        elif isinstance(feat, TextFeature):
+            if feat.generator != "lorem" and not is_realistic_generator(feat.generator):
+                raise SpecValidationError(
+                    f"unknown text generator {feat.generator!r}", locator=f"{loc}.generator"
+                )
+            resolve_locale(feat.locale, locator=f"{loc}.locale")
+        elif isinstance(feat, TimeseriesFeature):
+            if feat.min is not None and feat.max is not None and feat.min > feat.max:
+                raise SpecValidationError("min > max", locator=loc)
+            # AR stationarity: Σ|φᵢ| < 1 is a conservative sufficient condition that
+            # keeps the recursion bounded (a true unit-root/explosive series drifts
+            # without bound and isn't reproducibly meaningful). Reject otherwise.
+            if feat.ar and sum(abs(c) for c in feat.ar) >= 1.0:
+                raise SpecValidationError(
+                    "time-series AR is non-stationary: sum(|ar coefficients|) must be "
+                    f"< 1 (got {sum(abs(c) for c in feat.ar):.3f})",
+                    locator=f"{loc}.ar",
+                )
+
+
+def _derived_names(spec: Spec) -> set[str]:
+    if spec.causal is None:
+        return set()
+    return {edge.dst for edge in spec.causal.edges}
+
+
+def _check_causal(spec: Spec) -> None:
+    if spec.causal is None:
+        return
+    # Lazy imports keep the dist/causal layers optional at module load time.
+    from ..causal.functions import STRUCTURAL_FNS
+    from ..dist.builtins import REGISTRY
+
+    feature_names = set(spec.features)
+    targets: set[str] = set()
+    adjacency: dict[str, list[str]] = {n: [] for n in feature_names}
+
+    for i, edge in enumerate(spec.causal.edges):
+        loc = f"causal.edges[{i}]"
+        if edge.src not in feature_names:
+            raise SpecValidationError(f"unknown 'from' feature {edge.src!r}", locator=loc)
+        if edge.dst not in feature_names:
+            raise SpecValidationError(f"unknown 'to' feature {edge.dst!r}", locator=loc)
+        fn = STRUCTURAL_FNS.get(edge.fn)
+        if fn is None:
+            raise SpecValidationError(
+                f"unknown structural function {edge.fn!r}", locator=f"{loc}.fn"
+            )
+        fn.validate(edge, locator=loc)
+        # The structural function must be compatible with the parent's type, or
+        # execution would hit a raw coercion error. `map` consumes a categorical
+        # parent; the numeric fns need a numeric/boolean (float-coercible) parent.
+        parent = spec.features[edge.src]
+        if edge.fn == "map":
+            if not isinstance(parent, CategoricalFeature):
+                raise SpecValidationError(
+                    f"map edge requires a categorical 'from' feature; {edge.src!r} is "
+                    f"type {parent.type!r}",
+                    locator=f"{loc}.fn",
+                )
+            missing = [c for c in parent.categories if c not in (edge.mapping or {})]
+            if missing:
+                raise SpecValidationError(
+                    f"map edge is missing mappings for categories {missing}",
+                    locator=f"{loc}.mapping",
+                )
+        elif not isinstance(parent, (NumericFeature, BooleanFeature, TimeseriesFeature)):
+            raise SpecValidationError(
+                f"{edge.fn!r} edge requires a numeric/boolean 'from' feature; {edge.src!r} "
+                f"is type {parent.type!r} (use fn 'map' for categorical parents)",
+                locator=f"{loc}.fn",
+            )
+        adjacency[edge.src].append(edge.dst)
+        targets.add(edge.dst)
+
+    for name in targets:
+        feat = spec.features[name]
+        # A feature that is both directly sampled and a causal target is ambiguous.
+        if isinstance(feat, NumericFeature) and feat.dist is not None:
+            raise SpecValidationError(
+                f"feature {name!r} is both sampled (has dist) and derived (causal target)",
+                locator=f"features.{name}",
+            )
+        # Only numeric/boolean targets can be derived by the SEM.
+        if not isinstance(feat, (NumericFeature, BooleanFeature)):
+            raise SpecValidationError(
+                f"causal target {name!r} has type {feat.type!r}; only numeric and boolean "
+                "features can be derived",
+                locator=f"features.{name}",
+            )
+
+    # Per-node noise must reference a known distribution (or be 'none').
+    for node, noise in spec.causal.noise.items():
+        loc = f"causal.noise.{node}"
+        if node not in feature_names:
+            raise SpecValidationError(f"noise references unknown feature {node!r}", locator=loc)
+        dist_name = noise.get("dist")
+        if dist_name not in (None, "none") and dist_name not in REGISTRY:
+            raise SpecValidationError(
+                f"unknown noise distribution {dist_name!r}", locator=f"{loc}.dist"
+            )
+
+    # Interventions must reference real features.
+    for i, item in enumerate(spec.causal.interventions):
+        do = item.get("do", {})
+        for node in do:
+            if node not in feature_names:
+                raise SpecValidationError(
+                    f"intervention references unknown feature {node!r}",
+                    locator=f"causal.interventions[{i}].do",
+                )
+
+    _reject_cycles(adjacency)
+
+
+def _reject_cycles(adjacency: dict[str, list[str]]) -> None:
+    """Kahn's algorithm; if not all nodes are emitted, a cycle exists."""
+    indegree = {n: 0 for n in adjacency}
+    for _, children in sorted(adjacency.items()):
+        for child in children:
+            indegree[child] += 1
+    queue = sorted(n for n, d in indegree.items() if d == 0)
+    emitted = 0
+    while queue:
+        node = queue.pop(0)
+        emitted += 1
+        for child in sorted(adjacency[node]):
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                queue.append(child)
+        queue.sort()
+    if emitted != len(adjacency):
+        raise SpecValidationError("causal graph is not acyclic", locator="causal.edges")
+
+
+def _check_difficulty(spec: Spec) -> None:
+    if spec.difficulty is None:
+        return
+    # Lazy imports keep the difficulty layer optional at module load time.
+    from ..difficulty import PROBES, TIER_BANDS
+    from ..difficulty.knobs import ACTIVE_KNOBS
+
+    cfg = spec.difficulty
+
+    # The probe predicts the label; it must be a declared, classification-able
+    # feature. v0.1 calibrates binary-classification AUROC only.
+    label_feat = spec.features.get(cfg.label)
+    if label_feat is None:
+        raise SpecValidationError(
+            f"difficulty.label {cfg.label!r} is not a declared feature",
+            locator="difficulty.label",
+        )
+    if label_feat.emit is False:
+        raise SpecValidationError(
+            f"difficulty.label {cfg.label!r} is latent (emit: false) and is not shipped; "
+            "the probe can only predict an observable label",
+            locator="difficulty.label",
+        )
+    if isinstance(label_feat, BooleanFeature):
+        pass
+    elif isinstance(label_feat, CategoricalFeature):
+        if len(label_feat.categories) != 2:
+            raise SpecValidationError(
+                f"difficulty.label {cfg.label!r} is categorical with "
+                f"{len(label_feat.categories)} classes; v0.1 calibrates binary "
+                "classification only (use a boolean or 2-class categorical label)",
+                locator="difficulty.label",
+            )
+    else:
+        raise SpecValidationError(
+            f"difficulty.label {cfg.label!r} has type {label_feat.type!r}; v0.1 "
+            "supports binary-classification targets only (boolean or 2-class "
+            "categorical)",
+            locator="difficulty.label",
+        )
+
+    if cfg.probe not in PROBES:
+        raise SpecValidationError(
+            f"unknown difficulty probe {cfg.probe!r} (known: {sorted(PROBES)})",
+            locator="difficulty.probe",
+        )
+
+    # Target is either a named tier or an explicit band dict.
+    if isinstance(cfg.target, str):
+        if cfg.target not in TIER_BANDS:
+            raise SpecValidationError(
+                f"unknown difficulty tier {cfg.target!r} (known: {sorted(TIER_BANDS)})",
+                locator="difficulty.target",
+            )
+    elif isinstance(cfg.target, dict):
+        band = cfg.target.get("band")
+        if not (isinstance(band, (list, tuple)) and len(band) == 2):
+            raise SpecValidationError(
+                "difficulty.target must name a tier or carry a 'band': [lo, hi]",
+                locator="difficulty.target.band",
+            )
+        lo, hi = float(band[0]), float(band[1])
+        if not (0.0 <= lo <= hi <= 1.0):
+            raise SpecValidationError(
+                f"difficulty band must satisfy 0 <= lo <= hi <= 1 (got [{lo}, {hi}])",
+                locator="difficulty.target.band",
+            )
+        metric = cfg.target.get("metric", "auroc")
+        if metric != "auroc":
+            raise SpecValidationError(
+                f"unsupported difficulty metric {metric!r}; v0.1 supports 'auroc'",
+                locator="difficulty.target.metric",
+            )
+    else:
+        raise SpecValidationError(
+            "difficulty.target must be a tier name or an explicit-band object",
+            locator="difficulty.target",
+        )
+
+    # Only the actively-implemented knobs are accepted — no silently-ignored
+    # config. `causal` shrink and `imbalance` are planned (see status.md backlog).
+    unknown = [k for k in cfg.knobs if k not in ACTIVE_KNOBS]
+    if unknown:
+        raise SpecValidationError(
+            f"unsupported difficulty knob(s) {unknown}; v0.1 implements "
+            f"{list(ACTIVE_KNOBS)} (causal shrink and imbalance are planned)",
+            locator="difficulty.knobs",
+        )
+
+
+def _check_failures(spec: Spec) -> None:
+    # Lazy import keeps the failure layer optional at module load time.
+    from ..failure.modes import FAILURE_MODES
+
+    latent = spec.latent_names()
+    for i, failure in enumerate(spec.failures):
+        loc = f"failures[{i}]"
+        mode = FAILURE_MODES.get(failure.type)
+        if mode is None:
+            raise SpecValidationError(
+                f"unknown failure type {failure.type!r} "
+                f"(known: {sorted(FAILURE_MODES)})",
+                locator=f"{loc}.type",
+            )
+        params = failure.model_dump()
+        params.pop("type", None)
+        mode.validate(params, spec.features, loc)
+        # Failures corrupt the *shipped* frame; a latent column was already
+        # dropped, so referencing one would fail at runtime — reject it early.
+        for val in (*params.values(),):
+            refs = val if isinstance(val, list) else [val]
+            for ref in refs:
+                if isinstance(ref, str) and ref in latent:
+                    raise SpecValidationError(
+                        f"failure references latent feature {ref!r} (emit: false), "
+                        "which is not shipped and cannot be corrupted",
+                        locator=loc,
+                    )
+
+
+def _check_export(spec: Spec) -> None:
+    from ..export import EXPORTERS
+
+    for fmt in spec.export.formats:
+        if fmt not in EXPORTERS:
+            known = ", ".join(sorted(EXPORTERS))
+            raise SpecValidationError(
+                f"unknown export format {fmt!r}; known formats: {known}",
+                locator="export.formats",
+            )
+
+    splits = spec.export.splits
+    if splits is not None:
+        total = sum(splits.values())
+        if abs(total - 1.0) > 1e-9:
+            raise SpecValidationError(
+                f"export.splits ratios must sum to 1.0 (got {total})", locator="export.splits"
+            )

datadoom/engine/timeseries.py

@@ -0,0 +1,88 @@
+"""Time-series generation — additive decomposition (05 §6).
+
+A time-series feature realizes an ordered series over the row index ``t = 0 … n−1``:
+
+    Xₜ = T(t) + S(t) + AR(p) + εₜ
+    T(t) = slope·t + intercept                          # linear trend
+    S(t) = Σ Aⱼ·sin(2π·t/periodⱼ + phaseⱼ)             # (multi-)seasonality
+    AR(p): Yₜ = Σ_{i=1}^p φᵢ·Y_{t−i} + εₜ               # autoregressive residual
+    εₜ ~ Normal(0, σ²)  from RNG(noise:<series>)
+
+The deterministic mean ``T(t)+S(t)`` is vectorised; the AR residual is an inherent
+sequential recursion (each term depends on its predecessors) seeded with
+``Y_{t<0} = 0`` — a fixed, reproducible warm-start (no hidden burn-in draws). With
+no ``ar`` coefficients the residual is plain i.i.d. noise ``εₜ``.
+
+This module is pure and frawework-free; all randomness flows through the injected
+``numpy.random.Generator`` so the series is byte-reproducible on the pinned path.
+Multivariate / hierarchical series are deferred (plugin / post-v1), per 05 §6.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Trend:
+    slope: float = 0.0
+    intercept: float = 0.0
+
+
+@dataclass(frozen=True)
+class Seasonality:
+    amplitude: float
+    period: float
+    phase: float = 0.0
+
+
+def generate_series(
+    rng: np.random.Generator,
+    n: int,
+    *,
+    trend: Trend | None = None,
+    seasonality: Sequence[Seasonality] = (),
+    ar: Sequence[float] = (),
+    noise_std: float = 1.0,
+) -> np.ndarray:
+    """Realize one additive time-series of length ``n`` (05 §6).
+
+    Args:
+        rng: the per-series noise generator (``RNG(noise:<name>)``).
+        n: series length (row count).
+        trend: linear ``slope·t + intercept`` component (or ``None``).
+        seasonality: zero or more sinusoidal components, summed.
+        ar: autoregressive coefficients ``[φ₁ … φ_p]`` on the residual.
+        noise_std: σ of the Gaussian innovations ``εₜ``.
+
+    Returns:
+        A float ``ndarray`` of length ``n`` in row order.
+    """
+    t = np.arange(n, dtype=float)
+
+    mean = np.zeros(n, dtype=float)
+    if trend is not None:
+        mean += trend.slope * t + trend.intercept
+    for s in seasonality:
+        mean += s.amplitude * np.sin(2.0 * np.pi * t / s.period + s.phase)
+
+    eps = rng.normal(0.0, noise_std, size=n) if noise_std > 0 else np.zeros(n, dtype=float)
+
+    coeffs = list(ar)
+    if not coeffs:
+        return mean + eps
+
+    # Zero-mean AR(p) residual: Yₜ = Σ φᵢ·Y_{t−i} + εₜ, warm-started at Y_{<0}=0.
+    p = len(coeffs)
+    y = np.zeros(n, dtype=float)
+    for i in range(n):
+        acc = eps[i]
+        for j in range(p):
+            k = i - j - 1
+            if k >= 0:
+                acc += coeffs[j] * y[k]
+        y[i] = acc
+    return mean + y

datadoom/jobs/__init__.py

@@ -0,0 +1,14 @@
+"""Job execution layer (03 §3.3).
+
+The default backend is an **in-process** thread-pool worker that drives
+``engine.pipeline`` and fans out progress events to the WebSocket hub. It may
+import ``engine`` and ``store`` but nothing from ``api``/``cli`` (the hub lives
+here so ``api`` can subscribe without ``jobs`` reaching upward).
+"""
+
+from __future__ import annotations
+
+from .progress import EventHub, HubProgressEmitter, RunCancelled
+from .worker import WorkerPool
+
+__all__ = ["EventHub", "HubProgressEmitter", "RunCancelled", "WorkerPool"]

datadoom/jobs/progress.py

@@ -0,0 +1,155 @@
+"""Progress fan-out: engine ``ProgressEmitter`` -> WebSocket hub (08 §7).
+
+The :class:`EventHub` is an in-process async pub/sub keyed by ``run_id``. The
+worker thread publishes events; the API's WebSocket/SSE handlers subscribe. The
+hub keeps a per-run **replay buffer** so a late subscriber (the browser opening
+the tracker after the run started) receives the stages so far, then live updates.
+
+Cross-thread safety: the worker runs in a thread pool, so ``publish`` marshals
+queue writes onto the API event loop via ``call_soon_threadsafe``. With no loop
+registered (library/test use) it still records history and serves replay.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import threading
+from collections.abc import AsyncIterator
+from typing import Any
+
+from datadoom.engine.progress import ProgressEmitter
+
+# Canonical pipeline stages (08 §7 / 03 §4). Optional stages appear only when the
+# spec enables them; in P1 the engine emits the headless subset.
+CANONICAL_STAGES = (
+    "intake",
+    "snapshot",
+    "seed",
+    "base_generation",
+    "causal",
+    "failure_injection",
+    "difficulty",
+    "compliance",
+    "packaging",
+)
+
+
+class RunCancelled(Exception):
+    """Raised inside the pipeline when a cooperative cancel was requested."""
+
+
+Event = dict[str, Any]
+
+
+class EventHub:
+    """Per-run pub/sub with replay. One instance per server process."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, set[asyncio.Queue[Event]]] = {}
+        self._history: dict[str, list[Event]] = {}
+        self._terminal: dict[str, bool] = {}
+        self._cancels: dict[str, threading.Event] = {}
+        self._lock = threading.Lock()
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    # --- loop wiring (called once by the API on startup) --------------------------
+    def bind_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+
+    # --- cancellation -------------------------------------------------------------
+    def cancel_flag(self, run_id: str) -> threading.Event:
+        with self._lock:
+            return self._cancels.setdefault(run_id, threading.Event())
+
+    def request_cancel(self, run_id: str) -> None:
+        self.cancel_flag(run_id).set()
+
+    def is_cancelled(self, run_id: str) -> bool:
+        return self.cancel_flag(run_id).is_set()
+
+    # --- publishing ---------------------------------------------------------------
+    def publish(self, run_id: str, event: Event) -> None:
+        with self._lock:
+            self._history.setdefault(run_id, []).append(event)
+            if event.get("type") in {"completed", "failed", "cancelled"}:
+                self._terminal[run_id] = True
+            queues = list(self._subscribers.get(run_id, ()))
+        for q in queues:
+            self._enqueue(q, event)
+
+    def _enqueue(self, q: asyncio.Queue[Event], event: Event) -> None:
+        loop = self._loop
+        if loop is None:
+            # No API loop (library/test); history still records for replay.
+            return
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(q.put_nowait, event)
+
+    # --- subscription -------------------------------------------------------------
+    async def subscribe(self, run_id: str) -> AsyncIterator[Event]:
+        """Yield replay of events so far, then live events until a terminal one."""
+        q: asyncio.Queue[Event] = asyncio.Queue()
+        with self._lock:
+            replay = list(self._history.get(run_id, ()))
+            already_terminal = self._terminal.get(run_id, False)
+            self._subscribers.setdefault(run_id, set()).add(q)
+        try:
+            for ev in replay:
+                yield ev
+            if already_terminal:
+                return
+            while True:
+                ev = await q.get()
+                yield ev
+                if ev.get("type") in {"completed", "failed", "cancelled"}:
+                    return
+        finally:
+            with self._lock:
+                subs = self._subscribers.get(run_id)
+                if subs is not None:
+                    subs.discard(q)
+
+    def history(self, run_id: str) -> list[Event]:
+        with self._lock:
+            return list(self._history.get(run_id, ()))
+
+
+class HubProgressEmitter(ProgressEmitter):
+    """Engine progress sink that republishes to an :class:`EventHub`.
+
+    Translates the engine's per-stage ``emit(stage, pct, message)`` calls into the
+    WS event shapes of 08 §7, synthesizing a ``done`` for the previous stage when
+    a new one begins, and checking the cooperative cancel flag at every boundary.
+    """
+
+    def __init__(self, hub: EventHub, run_id: str) -> None:
+        self.hub = hub
+        self.run_id = run_id
+        self._prev_stage: str | None = None
+
+    def emit(self, stage: str, pct: int, message: str = "") -> None:
+        if self.hub.is_cancelled(self.run_id):
+            raise RunCancelled(stage)
+        if self._prev_stage is not None and self._prev_stage != stage:
+            self.hub.publish(
+                self.run_id,
+                {"type": "stage", "stage": self._prev_stage, "status": "done", "pct": pct},
+            )
+        self.hub.publish(
+            self.run_id,
+            {"type": "stage", "stage": stage, "status": "running", "pct": pct},
+        )
+        if message:
+            self.hub.publish(
+                self.run_id, {"type": "log", "level": "info", "message": message}
+            )
+        self._prev_stage = stage
+
+    def finish(self, pct: int = 100) -> None:
+        """Mark the final stage done once the pipeline returns."""
+        if self._prev_stage is not None:
+            self.hub.publish(
+                self.run_id,
+                {"type": "stage", "stage": self._prev_stage, "status": "done", "pct": pct},
+            )