datadoom 0.1.0.dev0__py3-none-any.whl

datadoom/engine/causal/execute.py

@@ -0,0 +1,116 @@
+"""SEM execution: topological walk applying structural equations (05 §3).
+
+Runs after base (root) features are sampled. For each derived node in
+topological order:
+
+    v = Σ_e  fn_e(parent_e)  +  ε_v          (ε_v ~ noise[v] via RNG(noise:v))
+
+Boolean children interpret the summed contribution as a probability and draw a
+Bernoulli outcome from ``RNG(feature:v)`` (05 §3). Interventions ``do(X=x₀)``
+fix a node to a constant and skip its equation; because the walk is topological,
+descendants automatically see the intervened value.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ..errors import SpecValidationError
+from ..spec.models import BooleanFeature, NumericFeature
+from .functions import STRUCTURAL_FNS
+from .graph import CausalDag
+
+if TYPE_CHECKING:  # avoid a runtime import cycle with pipeline
+    from ..pipeline import RunContext
+
+
+def resolve_interventions(interventions: list[dict[str, Any]]) -> dict[str, float]:
+    """Flatten ``[{do: {X: x0}}, ...]`` into ``{X: x0}`` (last wins)."""
+    fixed: dict[str, float] = {}
+    for item in interventions:
+        do = item.get("do", {})
+        for node, value in do.items():
+            fixed[node] = float(value)
+    return fixed
+
+
+def build_dag(ctx: RunContext) -> CausalDag:
+    assert ctx.spec.causal is not None
+    return CausalDag(ctx.spec.causal.edges, list(ctx.spec.features))
+
+
+def execute_causal(ctx: RunContext, columns: dict[str, np.ndarray]) -> CausalDag:
+    """Fill derived columns in-place; return the DAG (for the report's true graph)."""
+    spec = ctx.spec
+    assert spec.causal is not None
+    n = spec.rows
+    dag = build_dag(ctx)
+    interventions = resolve_interventions(spec.causal.interventions)
+
+    for node in dag.topological_order():
+        if node in interventions:
+            columns[node] = _materialize_constant(spec.features[node], interventions[node], n)
+            continue
+        in_edges = dag.in_edges(node)
+        if not in_edges:
+            continue  # root feature — already sampled in base_generation
+
+        contrib = np.zeros(n, dtype=float)
+        for edge in in_edges:
+            fn = STRUCTURAL_FNS[edge.fn]
+            contrib = contrib + fn.contribution(columns[edge.src], edge)
+
+        eps = _draw_noise(ctx, node, n)
+        if eps is not None:
+            contrib = contrib + eps
+
+        columns[node] = _finalize(ctx, node, spec.features[node], contrib)
+
+    return dag
+
+
+def _draw_noise(ctx: RunContext, node: str, n: int) -> np.ndarray | None:
+    """Node noise ε_v from RNG(noise:v); ``None`` when noise is absent/``none``."""
+    from ..dist.builtins import REGISTRY
+
+    assert ctx.spec.causal is not None
+    spec = ctx.spec.causal.noise.get(node)
+    if spec is None:
+        return None
+    dist_name = spec.get("dist")
+    if dist_name is None or dist_name == "none":
+        return None
+    dist = REGISTRY[dist_name]
+    ctx.used_namespaces.append(f"noise:{node}")
+    return dist.sample(ctx.rng.noise(node), n, spec.get("params", {}))
+
+
+def _finalize(ctx: RunContext, node: str, feat: Any, contrib: np.ndarray) -> np.ndarray:
+    if isinstance(feat, BooleanFeature):
+        p = np.clip(contrib, 0.0, 1.0)
+        ctx.used_namespaces.append(f"feature:{node}")
+        return ctx.rng.feature(node).random(size=len(contrib)) < p
+    if isinstance(feat, NumericFeature):
+        values = contrib
+        if feat.min is not None or feat.max is not None:
+            lo = -np.inf if feat.min is None else feat.min
+            hi = np.inf if feat.max is None else feat.max
+            values = np.clip(values, lo, hi)
+        if feat.dtype == "int":
+            values = np.rint(values).astype("int64")
+        return values
+    raise SpecValidationError(
+        f"feature {node!r} is a causal target but type {feat.type!r} cannot be derived "
+        "(only numeric and boolean targets are supported)",
+        locator=f"features.{node}",
+    )
+
+
+def _materialize_constant(feat: Any, value: float, n: int) -> np.ndarray:
+    if isinstance(feat, BooleanFeature):
+        return np.full(n, bool(value))
+    if isinstance(feat, NumericFeature) and feat.dtype == "int":
+        return np.full(n, int(round(value)), dtype="int64")
+    return np.full(n, float(value))

datadoom/engine/causal/functions.py

@@ -0,0 +1,116 @@
+"""Structural functions for SEM edges (05 §3, 04 §5).
+
+Each edge carries a structural function ``fn`` that maps a parent's values to a
+numeric *contribution*. A derived node sums the contributions of its incoming
+edges and adds node noise (see ``execute.py``). Functions are pure and operate
+on numpy arrays so they stay deterministic on the pinned path.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+
+import numpy as np
+
+from ..errors import SpecValidationError
+from ..spec.models import CausalEdge
+
+
+def _as_float(parent: np.ndarray) -> np.ndarray:
+    """Coerce a parent column to float (booleans → 0/1)."""
+    return np.asarray(parent, dtype=float)
+
+
+class StructuralFn(ABC):
+    """ABC for an edge's structural function."""
+
+    name: str
+    # Optional JSON-schema fragment for the edge params (09 §6); ``None`` for
+    # built-ins (the Graph inspector renders their native controls).
+    param_schema: Mapping[str, object] | None = None
+
+    @abstractmethod
+    def contribution(self, parent: np.ndarray, edge: CausalEdge) -> np.ndarray:
+        """Return this edge's additive contribution to the child node."""
+
+    def validate(self, edge: CausalEdge, locator: str) -> None:
+        """Check the edge carries the params this function needs."""
+        return None
+
+
+class Linear(StructuralFn):
+    name = "linear"
+
+    def contribution(self, parent, edge):
+        bias = edge.bias or 0.0
+        return edge.weight * _as_float(parent) + bias
+
+    def validate(self, edge, locator):
+        if edge.weight is None:
+            raise SpecValidationError("linear edge requires 'weight'", locator=locator)
+
+
+class Logistic(StructuralFn):
+    name = "logistic"
+
+    def contribution(self, parent, edge):
+        bias = edge.bias or 0.0
+        z = edge.weight * _as_float(parent) + bias
+        return 1.0 / (1.0 + np.exp(-z))
+
+    def validate(self, edge, locator):
+        if edge.weight is None:
+            raise SpecValidationError("logistic edge requires 'weight'", locator=locator)
+
+
+class Polynomial(StructuralFn):
+    name = "polynomial"
+
+    def contribution(self, parent, edge):
+        p = _as_float(parent)
+        out = np.zeros_like(p)
+        for i, c in enumerate(edge.coeffs or ()):
+            out = out + c * (p**i)
+        return out
+
+    def validate(self, edge, locator):
+        if not edge.coeffs:
+            raise SpecValidationError(
+                "polynomial edge requires a non-empty 'coeffs' list", locator=locator
+            )
+
+
+class Map(StructuralFn):
+    name = "map"
+
+    def contribution(self, parent, edge):
+        mapping = edge.mapping or {}
+        out = np.empty(len(parent), dtype=float)
+        for i, v in enumerate(parent):
+            key = str(v)
+            if key not in mapping:
+                raise SpecValidationError(
+                    f"map edge has no mapping for category {key!r}",
+                    locator=f"causal edge {edge.src}->{edge.dst}",
+                )
+            out[i] = mapping[key]
+        return out
+
+    def validate(self, edge, locator):
+        if not edge.mapping:
+            raise SpecValidationError(
+                "map edge requires a non-empty 'mapping'", locator=locator
+            )
+
+
+class Identity(StructuralFn):
+    name = "identity"
+
+    def contribution(self, parent, edge):
+        return _as_float(parent)
+
+
+STRUCTURAL_FNS: dict[str, StructuralFn] = {
+    fn.name: fn for fn in (Linear(), Logistic(), Polynomial(), Map(), Identity())
+}

datadoom/engine/causal/graph.py

@@ -0,0 +1,54 @@
+"""Causal DAG construction & deterministic traversal (05 §3, 17 step 11).
+
+Wraps a ``networkx.DiGraph`` built from the spec's causal edges. The engine is
+pure, so graph operations are deterministic: nodes iterate in **sorted** order
+and the topological walk is **lexicographical**, so the SEM execution order is a
+function of the spec alone (never of dict/hash iteration order).
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from ..errors import SpecValidationError
+from ..spec.models import CausalEdge
+
+
+class CausalDag:
+    """A validated causal DAG over the spec's feature names.
+
+    Cycle detection is defensive — ``validate_spec`` already rejects cycles, but
+    constructing the graph re-checks so the engine never executes a bad walk.
+    """
+
+    def __init__(self, edges: list[CausalEdge], feature_names: list[str]) -> None:
+        self._graph: nx.DiGraph = nx.DiGraph()
+        self._graph.add_nodes_from(sorted(feature_names))
+        # Author order is preserved per destination so summation order (and thus
+        # floating-point results) is a stable function of the spec.
+        self._in_edges: dict[str, list[CausalEdge]] = {n: [] for n in feature_names}
+        for edge in edges:
+            self._graph.add_edge(edge.src, edge.dst)
+            self._in_edges[edge.dst].append(edge)
+        if not nx.is_directed_acyclic_graph(self._graph):
+            raise SpecValidationError("causal graph is not acyclic", locator="causal.edges")
+
+    def topological_order(self) -> list[str]:
+        """Deterministic topological order (lexicographical tie-breaking)."""
+        return list(nx.lexicographical_topological_sort(self._graph))
+
+    def in_edges(self, node: str) -> list[CausalEdge]:
+        """Incoming edges for ``node`` in author order (empty for roots)."""
+        return self._in_edges.get(node, [])
+
+    def parents(self, node: str) -> list[str]:
+        """Sorted parent feature names of ``node``."""
+        return sorted(self._graph.predecessors(node))
+
+    def is_derived(self, node: str) -> bool:
+        """True if ``node`` has at least one incoming edge (computed, not sampled)."""
+        return bool(self._in_edges.get(node))
+
+    def derived_nodes(self) -> set[str]:
+        """All nodes that are causal targets (have ≥1 incoming edge)."""
+        return {n for n, e in self._in_edges.items() if e}

datadoom/engine/difficulty/__init__.py

@@ -0,0 +1,36 @@
+"""Difficulty targeting: empirical calibration to a baseline-metric band (05 §5).
+
+A dataset's difficulty is defined *operationally* by the score a standard probe
+model achieves on it. ``calibrate_difficulty`` runs an adaptive bisection over a
+single :class:`~datadoom.engine.difficulty.knobs.DifficultyDial` until the probe
+metric lands in the target band, then returns the calibrated frame to ship and a
+report of what was achieved (honestly, including misses).
+"""
+
+from __future__ import annotations
+
+from .calibrate import (
+    TIER_BANDS,
+    DifficultyResult,
+    Target,
+    calibrate_difficulty,
+    resolve_target,
+)
+from .knobs import ACTIVE_KNOBS, DIAL_MAX, DifficultyDial, KnobState
+from .probes import PROBES, ProbeModel, ProbeResult, evaluate
+
+__all__ = [
+    "ACTIVE_KNOBS",
+    "DIAL_MAX",
+    "DifficultyDial",
+    "DifficultyResult",
+    "KnobState",
+    "PROBES",
+    "ProbeModel",
+    "ProbeResult",
+    "TIER_BANDS",
+    "Target",
+    "calibrate_difficulty",
+    "evaluate",
+    "resolve_target",
+]

datadoom/engine/difficulty/calibrate.py

@@ -0,0 +1,235 @@
+"""Adaptive difficulty calibration: bisection on the dial (05 §5.2, 17 step 15).
+
+The loop measures the probe metric μ on the realized frame and turns the single
+:class:`DifficultyDial` until μ lands in the target band ``[a, b]`` (from an
+explicit band or a named tier). Because μ(d) is monotone non-increasing in the
+dial, the search is a clean bisection:
+
+    generate → evaluate μ
+    μ ∈ [a, b]   → success
+    μ > b        → too easy  → turn the dial up (more noise)
+    μ < a        → too hard  → turn the dial down
+
+Honest failure (invariant #3): if even the pristine data is already below the
+band (no easing knob exists) or the maximum dial can't push μ down into the band
+(signal too strong for the available knobs), the loop returns the *closest*
+achieved point and flags ``band_met = False`` with a plain-language note — never
+a silent miss.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+
+from .knobs import ACTIVE_KNOBS, DIAL_MAX, DifficultyDial
+from .probes import PROBES, ProbeResult, evaluate
+
+if TYPE_CHECKING:
+    from ..pipeline import RunContext
+
+# Named tiers → validated AUROC bands for binary classification (05 §5.3). These
+# are calibration *targets*, kept honest by the calibration test in tests/.
+TIER_BANDS: dict[str, tuple[float, float]] = {
+    "beginner": (0.90, 0.99),
+    "intermediate": (0.80, 0.90),
+    "advanced": (0.72, 0.80),
+    "kaggle": (0.62, 0.72),
+}
+
+
+@dataclass
+class Target:
+    task: str
+    metric: str
+    band: tuple[float, float]
+    tier: str | None = None
+
+
+@dataclass
+class DifficultyResult:
+    target: dict[str, Any]
+    achieved_metric: float
+    metric_name: str
+    probe: str
+    iterations: int
+    band_met: bool
+    dial: float
+    feature_noise: float
+    label_flip: float
+    knobs_requested: list[str]
+    knobs_active: list[str]
+    reference: dict[str, Any]
+    trace: list[dict[str, float]]
+    note: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "achieved_metric": self.achieved_metric,
+            "metric_name": self.metric_name,
+            "probe": self.probe,
+            "iterations": self.iterations,
+            "band_met": self.band_met,
+            "dial": self.dial,
+            "feature_noise": self.feature_noise,
+            "label_flip": self.label_flip,
+            "knobs_requested": self.knobs_requested,
+            "knobs_active": self.knobs_active,
+            "reference": self.reference,
+            "trace": self.trace,
+            "note": self.note,
+        }
+
+
+@dataclass
+class _Best:
+    """Tracks the closest-to-band point seen, for honest fallback reporting."""
+
+    dial: float = 0.0
+    result: ProbeResult | None = None
+    distance: float = float("inf")
+
+    def offer(self, dial: float, result: ProbeResult, band: tuple[float, float]) -> None:
+        a, b = band
+        m = result.metric
+        dist = 0.0 if a <= m <= b else min(abs(m - a), abs(m - b))
+        if dist < self.distance:
+            self.distance, self.dial, self.result = dist, dial, result
+
+
+def resolve_target(target: str | dict[str, Any]) -> Target:
+    """Map a tier name or explicit-band dict to a concrete :class:`Target`."""
+    if isinstance(target, str):
+        band = TIER_BANDS[target]  # validated upstream
+        return Target(task="classification", metric="auroc", band=band, tier=target)
+    band_raw = target["band"]
+    band = (float(band_raw[0]), float(band_raw[1]))
+    return Target(
+        task=str(target.get("task", "classification")),
+        metric=str(target.get("metric", "auroc")),
+        band=band,
+        tier=None,
+    )
+
+
+def calibrate_difficulty(
+    ctx: RunContext, base_frame: pd.DataFrame
+) -> tuple[DifficultyResult, pd.DataFrame]:
+    """Run the adaptive loop; return the report + the calibrated frame to ship."""
+    spec = ctx.spec
+    assert spec.difficulty is not None
+    cfg = spec.difficulty
+    target = resolve_target(cfg.target)
+    band = target.band
+    probe = PROBES[cfg.probe]
+
+    requested = list(cfg.knobs)
+    active = [k for k in requested if k in ACTIVE_KNOBS]
+    dial_obj = DifficultyDial(base_frame, cfg.label, ctx.rng, active, ctx.used_namespaces)
+
+    # Probe seeds are derived from the run's RNG so the split/estimator are
+    # reproducible without touching the data namespaces.
+    split_seed = int(ctx.rng.probe("split").integers(0, 2**31 - 1))
+    est_seed = int(ctx.rng.probe("estimator").integers(0, 2**31 - 1))
+    ctx.used_namespaces.extend(["probe:split", "probe:estimator"])
+
+    trace: list[dict[str, float]] = []
+
+    def mu(dial: float) -> tuple[ProbeResult, pd.DataFrame]:
+        frame, _ = dial_obj.realize(dial)
+        result = evaluate(probe, frame, cfg.label, split_seed=split_seed, est_seed=est_seed)
+        trace.append({"dial": round(dial, 6), "metric": round(result.metric, 6)})
+        return result, frame
+
+    a, b = band
+    best = _Best()
+
+    r0, frame0 = mu(0.0)
+    best.offer(0.0, r0, band)
+    note: str | None = None
+    band_met = False
+    final_dial = 0.0
+    final_result = r0
+    final_frame = frame0
+
+    if r0.metric <= b:
+        # Pristine data is already at or below the upper bound.
+        final_dial, final_result, final_frame = 0.0, r0, frame0
+        if r0.metric >= a:
+            band_met = True
+        else:
+            note = (
+                "clean data is already harder than the target band; v0.1 has no "
+                "easing knob, so the pristine dataset is shipped as-is"
+            )
+    else:
+        # Too easy → push the dial up. Probe the hard end to bracket the root.
+        rmax, framemax = mu(DIAL_MAX)
+        best.offer(DIAL_MAX, rmax, band)
+        if rmax.metric > b:
+            note = (
+                "maximum difficulty is still too easy for the target band; the "
+                "label is too separable for the active knobs to obscure"
+            )
+            final_dial, final_result, final_frame = DIAL_MAX, rmax, framemax
+        elif a <= rmax.metric <= b:
+            band_met = True
+            final_dial, final_result, final_frame = DIAL_MAX, rmax, framemax
+        else:
+            # Bracketed: μ(0) > b and μ(DIAL_MAX) < a. Bisect for the band.
+            lo, hi = 0.0, DIAL_MAX
+            for _ in range(cfg.max_iters):
+                mid = (lo + hi) / 2.0
+                rmid, framemid = mu(mid)
+                best.offer(mid, rmid, band)
+                if a <= rmid.metric <= b:
+                    band_met = True
+                    final_dial, final_result, final_frame = mid, rmid, framemid
+                    break
+                if rmid.metric > b:
+                    lo = mid  # still too easy → harder
+                else:
+                    hi = mid  # too hard → easier
+            else:
+                # Exhausted iterations without landing in the band: ship closest.
+                final_dial = best.dial
+                final_result = best.result if best.result is not None else r0
+                final_frame, _ = dial_obj.realize(final_dial)
+                note = (
+                    f"target band not reached within max_iters={cfg.max_iters}; "
+                    "shipping the closest achieved difficulty"
+                )
+
+    state = dial_obj.realize(final_dial)[1]
+    reference = {
+        "linear_separability": final_result.linear_separability,
+        "class_balance": final_result.class_balance,
+        "noise_to_signal": dial_obj.noise_to_signal(state.feature_noise),
+        "probe_features": final_result.n_features,
+        "rows": dial_obj.n,
+    }
+    result = DifficultyResult(
+        target={
+            "tier": target.tier,
+            "task": target.task,
+            "metric": target.metric,
+            "band": [a, b],
+        },
+        achieved_metric=final_result.metric,
+        metric_name=final_result.metric_name,
+        probe=cfg.probe,
+        iterations=len(trace),
+        band_met=band_met,
+        dial=final_dial,
+        feature_noise=state.feature_noise,
+        label_flip=state.label_flip,
+        knobs_requested=requested,
+        knobs_active=active,
+        reference=reference,
+        trace=trace,
+        note=note,
+    )
+    return result, final_frame