datadoom 0.1.0.dev0__py3-none-any.whl

datadoom/store/repositories.py

@@ -0,0 +1,279 @@
+"""Repositories — the only way the app reads/writes metadata rows.
+
+Each repository wraps a live :class:`~sqlalchemy.orm.Session`. They enforce the
+domain invariants from doc 06 §5 — most importantly **spec immutability**: an
+edit never updates a spec row, it creates a new version and repoints the
+dataset's ``current_spec_id``.
+
+UUID PKs are generated here with ``uuid4``. This is the persistence layer, NOT
+the engine data path, so the determinism ban on ``uuid4`` does not apply (DB
+identity has no bearing on reproducible artifact bytes).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from .db import utcnow_iso
+from .models import (
+    ArtifactRow,
+    DatasetRow,
+    GenerationRunRow,
+    ReportRow,
+    SpecRow,
+)
+
+
+def _uid() -> str:
+    return str(uuid.uuid4())
+
+
+class DatasetRepository:
+    def __init__(self, session: Session) -> None:
+        self.s = session
+
+    def create(
+        self, name: str, description: str | None = None, owner_id: str | None = None
+    ) -> DatasetRow:
+        now = utcnow_iso()
+        row = DatasetRow(
+            dataset_id=_uid(),
+            name=name,
+            description=description,
+            status="draft",
+            owner_id=owner_id,
+            created_at=now,
+            updated_at=now,
+        )
+        self.s.add(row)
+        self.s.flush()
+        return row
+
+    def get(self, dataset_id: str) -> DatasetRow | None:
+        return self.s.get(DatasetRow, dataset_id)
+
+    def get_by_name(self, name: str, owner_id: str | None = None) -> DatasetRow | None:
+        stmt = select(DatasetRow).where(
+            DatasetRow.name == name, DatasetRow.owner_id.is_(owner_id)
+        )
+        return self.s.scalars(stmt).first()
+
+    def list(
+        self,
+        status: str | None = None,
+        q: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> tuple[list[DatasetRow], int]:
+        stmt = select(DatasetRow)
+        count_stmt = select(func.count()).select_from(DatasetRow)
+        if status:
+            stmt = stmt.where(DatasetRow.status == status)
+            count_stmt = count_stmt.where(DatasetRow.status == status)
+        if q:
+            like = f"%{q}%"
+            stmt = stmt.where(DatasetRow.name.like(like))
+            count_stmt = count_stmt.where(DatasetRow.name.like(like))
+        total = self.s.scalar(count_stmt) or 0
+        stmt = stmt.order_by(DatasetRow.updated_at.desc()).limit(limit).offset(offset)
+        return list(self.s.scalars(stmt).all()), int(total)
+
+    def touch(self, row: DatasetRow) -> None:
+        row.updated_at = utcnow_iso()
+
+    def update(
+        self, row: DatasetRow, name: str | None = None, description: str | None = None
+    ) -> DatasetRow:
+        if name is not None:
+            row.name = name
+        if description is not None:
+            row.description = description
+        self.touch(row)
+        return row
+
+    def set_status(self, row: DatasetRow, status: str) -> None:
+        row.status = status
+        self.touch(row)
+
+    def delete(self, row: DatasetRow) -> None:
+        # ORM cascade removes specs/runs/artifacts/reports rows.
+        self.s.delete(row)
+
+
+class SpecRepository:
+    def __init__(self, session: Session) -> None:
+        self.s = session
+
+    def create_version(
+        self,
+        dataset: DatasetRow,
+        body: dict[str, Any],
+        spec_hash: str,
+        datadoom_version: str,
+    ) -> SpecRow:
+        """Create the next immutable spec snapshot and repoint the dataset."""
+        next_version = (
+            self.s.scalar(
+                select(func.coalesce(func.max(SpecRow.version), 0)).where(
+                    SpecRow.dataset_id == dataset.dataset_id
+                )
+            )
+            or 0
+        ) + 1
+        row = SpecRow(
+            spec_id=_uid(),
+            dataset_id=dataset.dataset_id,
+            spec_hash=spec_hash,
+            body=body,
+            datadoom_version=datadoom_version,
+            version=next_version,
+            created_at=utcnow_iso(),
+        )
+        self.s.add(row)
+        self.s.flush()
+        dataset.current_spec_id = row.spec_id
+        dataset.updated_at = utcnow_iso()
+        return row
+
+    def get(self, spec_id: str) -> SpecRow | None:
+        return self.s.get(SpecRow, spec_id)
+
+    def current(self, dataset: DatasetRow) -> SpecRow | None:
+        if dataset.current_spec_id is None:
+            return None
+        return self.s.get(SpecRow, dataset.current_spec_id)
+
+    def history(self, dataset_id: str) -> list[SpecRow]:
+        stmt = (
+            select(SpecRow)
+            .where(SpecRow.dataset_id == dataset_id)
+            .order_by(SpecRow.version.desc())
+        )
+        return list(self.s.scalars(stmt).all())
+
+    def by_version(self, dataset_id: str, version: int) -> SpecRow | None:
+        stmt = select(SpecRow).where(
+            SpecRow.dataset_id == dataset_id, SpecRow.version == version
+        )
+        return self.s.scalars(stmt).first()
+
+
+class RunRepository:
+    def __init__(self, session: Session) -> None:
+        self.s = session
+
+    def create(
+        self, dataset_id: str, spec_id: str, seed: int, name: str | None = None
+    ) -> GenerationRunRow:
+        row = GenerationRunRow(
+            run_id=_uid(),
+            dataset_id=dataset_id,
+            spec_id=spec_id,
+            name=name,
+            seed=seed,
+            status="queued",
+            progress_pct=0,
+            created_at=utcnow_iso(),
+        )
+        self.s.add(row)
+        self.s.flush()
+        return row
+
+    def get(self, run_id: str) -> GenerationRunRow | None:
+        return self.s.get(GenerationRunRow, run_id)
+
+    def set_name(self, row: GenerationRunRow, name: str) -> GenerationRunRow:
+        row.name = name
+        return row
+
+    def delete(self, row: GenerationRunRow) -> None:
+        # Clear the dataset's recorded latest-run pointer if it referenced this run
+        # (it's a soft reference, so the cascade won't touch it).
+        dataset = self.s.get(DatasetRow, row.dataset_id)
+        if dataset is not None and dataset.latest_run_id == row.run_id:
+            dataset.latest_run_id = None
+        # ORM cascade removes artifact/report rows.
+        self.s.delete(row)
+
+    def list_for_dataset(self, dataset_id: str) -> list[GenerationRunRow]:
+        stmt = (
+            select(GenerationRunRow)
+            .where(GenerationRunRow.dataset_id == dataset_id)
+            .order_by(GenerationRunRow.created_at.desc())
+        )
+        return list(self.s.scalars(stmt).all())
+
+    def find_repro(self, spec_id: str, seed: int) -> GenerationRunRow | None:
+        stmt = (
+            select(GenerationRunRow)
+            .where(GenerationRunRow.spec_id == spec_id, GenerationRunRow.seed == seed)
+            .order_by(GenerationRunRow.created_at.desc())
+        )
+        return self.s.scalars(stmt).first()
+
+
+class ArtifactRepository:
+    def __init__(self, session: Session) -> None:
+        self.s = session
+
+    def add(
+        self,
+        run_id: str,
+        version: str,
+        fmt: str,
+        storage_uri: str,
+        checksum_sha256: str,
+        size_bytes: int,
+        split: str | None = None,
+    ) -> ArtifactRow:
+        row = ArtifactRow(
+            artifact_id=_uid(),
+            run_id=run_id,
+            version=version,
+            split=split,
+            format=fmt,
+            storage_uri=storage_uri,
+            checksum_sha256=checksum_sha256,
+            size_bytes=size_bytes,
+            created_at=utcnow_iso(),
+        )
+        self.s.add(row)
+        self.s.flush()
+        return row
+
+    def get(self, artifact_id: str) -> ArtifactRow | None:
+        return self.s.get(ArtifactRow, artifact_id)
+
+    def list_for_run(self, run_id: str) -> list[ArtifactRow]:
+        stmt = select(ArtifactRow).where(ArtifactRow.run_id == run_id)
+        return list(self.s.scalars(stmt).all())
+
+
+class ReportRepository:
+    def __init__(self, session: Session) -> None:
+        self.s = session
+
+    def upsert(self, run_id: str, sections: dict[str, Any]) -> ReportRow:
+        existing = self.get_for_run(run_id)
+        if existing is None:
+            existing = ReportRow(report_id=_uid(), run_id=run_id, created_at=utcnow_iso())
+            self.s.add(existing)
+        existing.compliance_score = sections.get("compliance_score")
+        existing.distribution = sections.get("distribution")
+        existing.correlation = sections.get("correlation")
+        existing.mutual_information = sections.get("mutual_information")
+        existing.causal_truth = sections.get("causal_truth")
+        existing.difficulty = sections.get("difficulty")
+        existing.failures = sections.get("failures")
+        existing.profile = sections.get("profile")
+        existing.determinism = sections.get("determinism")
+        self.s.flush()
+        return existing
+
+    def get_for_run(self, run_id: str) -> ReportRow | None:
+        stmt = select(ReportRow).where(ReportRow.run_id == run_id)
+        return self.s.scalars(stmt).first()

datadoom/templates/__init__.py

@@ -0,0 +1,239 @@
+"""Built-in domain templates (17 step 18, 09 §4.6).
+
+A template is a curated, ready-to-run spec plus catalog metadata. The web gallery
+and ``datadoom template`` surface them so a user can start from a realistic
+domain dataset in one click. Templates are *data only* (no code); this module is
+a thin loader that reads the bundled YAML via :mod:`importlib.resources`, so it
+works the same from the source tree and an installed wheel.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class TemplateMeta:
+    """Catalog entry for one built-in template."""
+
+    id: str
+    name: str
+    domain: str
+    description: str
+    tags: tuple[str, ...]
+    filename: str
+    features: tuple[str, ...] = ()  # showcased engine features (causal/failures/…)
+    level: str = "starter"  # "starter" (learn one feature) | "hackathon" (full enterprise challenge)
+
+    def to_summary(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "domain": self.domain,
+            "description": self.description,
+            "tags": list(self.tags) + list(self.features),
+            "level": self.level,
+        }
+
+
+CATALOG: tuple[TemplateMeta, ...] = (
+    # ── Hackathon flagships ──────────────────────────────────────────────────
+    # Enterprise-grade ML challenges: each composes a deep causal DAG, a latent
+    # confounder, a stacked data-quality failure profile and (where applicable)
+    # a calibrated difficulty band — a realistic dataset to build a model on,
+    # carrying a `meta.challenge` brief (target / metric / split / gotchas).
+    TemplateMeta(
+        id="credit-default-challenge",
+        name="Credit default (challenge)",
+        domain="Finance",
+        description=(
+            "Consumer credit default. Demographics and employment drive income, which "
+            "feeds a latent risk score behind the default label — calibrated to the "
+            "'advanced' AUROC band, then corrupted with MNAR income, drifting debt-to-"
+            "income, a leaked collections proxy and label noise. Train/test split included."
+        ),
+        tags=("credit-risk", "classification"),
+        features=("causal", "latent", "difficulty", "failure-injection", "leakage"),
+        filename="credit_default_challenge.datadoom.yaml",
+        level="hackathon",
+    ),
+    TemplateMeta(
+        id="clinical-deterioration",
+        name="Clinical deterioration (challenge)",
+        domain="Healthcare",
+        description=(
+            "ICU early-warning with a hidden confounder: a latent illness severity drives "
+            "both the observed vitals (heart rate, lactate, BP) and the outcome, so the "
+            "vitals are confounded proxies. Calibrated to 'advanced', with realistic "
+            "MNAR/MAR/MCAR clinical missingness."
+        ),
+        tags=("clinical", "classification"),
+        features=("causal", "latent", "confounder", "difficulty", "missingness"),
+        filename="clinical_deterioration.datadoom.yaml",
+        level="hackathon",
+    ),
+    TemplateMeta(
+        id="predictive-maintenance",
+        name="Predictive maintenance (challenge)",
+        domain="Industrial IoT",
+        description=(
+            "Turbine maintenance on multi-sensor time-series (vibration, bearing temp, oil "
+            "pressure) plus load and component grade, driving a latent wear index behind a "
+            "maintenance label. The load regime drifts, gains sensor noise and drops "
+            "readings; a leaked alarm proxy is planted. Sequential — preserve row order."
+        ),
+        tags=("predictive-maintenance", "classification"),
+        features=("time-series", "causal", "latent", "drift", "leakage"),
+        filename="predictive_maintenance.datadoom.yaml",
+        level="hackathon",
+    ),
+    TemplateMeta(
+        id="telecom-churn-challenge",
+        name="Telecom churn (challenge)",
+        domain="Telecom",
+        description=(
+            "Customer churn with realistic records: believable identity fields (name, "
+            "email, city) sit beside the real signal — tenure, charges, support load, "
+            "contract and usage feed a latent dissatisfaction score. Calibrated to the hard "
+            "'kaggle' AUROC band, with MNAR usage and noisy labels. Drop the identifiers."
+        ),
+        tags=("churn", "classification"),
+        features=("causal", "latent", "difficulty", "realistic-text", "missingness"),
+        filename="telecom_churn_challenge.datadoom.yaml",
+        level="hackathon",
+    ),
+    # ── Starter templates (learn one capability at a time) ───────────────────
+    TemplateMeta(
+        id="fraud-detection",
+        name="Transaction fraud",
+        domain="Finance",
+        description=(
+            "Customer age and card type drive monthly spend, which drives a fraud-risk "
+            "label — then realistic data-quality failures (under-reported spend, random "
+            "gaps, mislabels) corrupt a copy so you can study robustness."
+        ),
+        tags=("classification",),
+        features=("causal", "failure-injection"),
+        filename="fraud_detection.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="customer-churn",
+        name="Customer churn",
+        domain="SaaS",
+        description=(
+            "Tenure, monthly charges and support load feed a latent satisfaction score "
+            "behind a churn label, calibrated down to an 'intermediate' baseline-AUROC "
+            "band so the dataset is hard in a measured, honest way."
+        ),
+        tags=("classification",),
+        features=("difficulty", "latent", "causal"),
+        filename="customer_churn.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="hospital-readmission",
+        name="Hospital readmission",
+        domain="Healthcare",
+        description=(
+            "Patient age, diagnosis count, length of stay and prior admissions drive a "
+            "latent severity score behind a 30-day readmission label — a clean causal "
+            "starter with a hidden confounder in the true graph."
+        ),
+        tags=("classification",),
+        features=("causal", "latent"),
+        filename="hospital_readmission.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="ecommerce-orders",
+        name="E-commerce orders",
+        domain="E-commerce",
+        description=(
+            "A fast orders table — lognormal order value, basket quantity, product "
+            "category, channel, order date and a return flag. Distribution-only, so it "
+            "generates instantly."
+        ),
+        tags=("tabular",),
+        features=("distributions", "datetime"),
+        filename="ecommerce_orders.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="iot-sensors",
+        name="IoT sensor readings",
+        domain="IoT",
+        description=(
+            "Hourly multi-sensor telemetry — temperature, humidity, pressure and battery "
+            "by device, with bounded distributions that stay physically plausible."
+        ),
+        tags=("tabular",),
+        features=("numeric", "datetime"),
+        filename="iot_sensors.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="people-directory",
+        name="People directory",
+        domain="People",
+        description=(
+            "Believable identities — names, emails, phones, companies, job titles, "
+            "cities and countries — via deterministic mimesis providers. Great for demos "
+            "and UIs that need realistic-looking records."
+        ),
+        tags=("tabular",),
+        features=("realistic-text", "datetime"),
+        filename="people_directory.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="marketing-ab-test",
+        name="Marketing A/B test",
+        domain="Marketing",
+        description=(
+            "A web experiment — 50/50 control vs. treatment, session engagement "
+            "(exponential dwell, Poisson pageviews), conversion and revenue. "
+            "Distribution-only and instant."
+        ),
+        tags=("experiment",),
+        features=("distributions",),
+        filename="ab_test.datadoom.yaml",
+    ),
+    TemplateMeta(
+        id="insurance-claims",
+        name="Insurance claims",
+        domain="Insurance",
+        description=(
+            "Claims with a heavy-tailed (Pareto) claim amount — most small, a few very "
+            "large — plus policyholder age, region, prior-claim count and a fraud flag."
+        ),
+        tags=("tabular",),
+        features=("heavy-tail",),
+        filename="insurance_claims.datadoom.yaml",
+    ),
+)
+
+_BY_ID = {t.id: t for t in CATALOG}
+
+
+def list_templates() -> list[TemplateMeta]:
+    """Every built-in template, in catalog order."""
+    return list(CATALOG)
+
+
+def get_template(template_id: str) -> TemplateMeta | None:
+    return _BY_ID.get(template_id)
+
+
+def load_template_text(template_id: str) -> str:
+    """The template's raw spec YAML (comments preserved — good for `template show`)."""
+    meta = _BY_ID.get(template_id)
+    if meta is None:
+        raise KeyError(f"unknown template {template_id!r}")
+    return (resources.files(__package__) / meta.filename).read_text(encoding="utf-8")
+
+
+def load_template_body(template_id: str) -> dict[str, Any]:
+    """Parse a template's spec YAML into a raw dict (not yet validated)."""
+    body = yaml.safe_load(load_template_text(template_id))
+    if not isinstance(body, dict):
+        raise ValueError(f"template {template_id!r} did not parse to a mapping")
+    return body

datadoom/templates/ab_test.datadoom.yaml

@@ -0,0 +1,46 @@
+datadoom_version: "1"
+name: "marketing-ab-test"
+description: >
+  Marketing A/B-test starter — a fast experiment table: a 50/50 control vs.
+  treatment assignment, session engagement (exponential dwell time, Poisson
+  pageviews), a conversion flag and order revenue. Distribution-only, so it
+  generates instantly.
+seed: 27
+rows: 9000
+
+features:
+  variant:
+    type: categorical
+    categories: [control, treatment]
+    weights: [0.5, 0.5]
+  device:
+    type: categorical
+    categories: [desktop, mobile, tablet]
+    weights: [0.5, 0.42, 0.08]
+  session_minutes:
+    type: numeric
+    dist: exponential
+    params: { scale: 6.0 }
+    min: 0
+  pageviews:
+    type: numeric
+    dist: poisson
+    params: { lam: 5 }
+    min: 0
+    dtype: int
+  revenue:
+    type: numeric
+    dist: lognormal
+    params: { mu: 2.6, sigma: 1.1 }
+    min: 0
+  converted:
+    type: boolean
+    rate: 0.12
+
+export:
+  formats: [csv]
+  versions: [clean]
+
+meta:
+  problem_statement: "Web A/B experiment data (assignment, engagement, conversion)."
+  tags: [marketing, experiment, tabular]

datadoom/templates/clinical_deterioration.datadoom.yaml

@@ -0,0 +1,124 @@
+datadoom_version: "1"
+name: "clinical-deterioration"
+description: >
+  HACKATHON — ICU clinical deterioration with a hidden confounder. A latent
+  illness `severity` (emit: false) is driven by age, comorbidity burden and
+  admission type, and severity in turn drives BOTH the observed vitals
+  (heart rate ↑, lactate ↑, systolic BP ↓) AND the `deterioration` label. Because
+  the true cause is unobserved, the vitals are only *proxies* — a textbook
+  latent-confounder problem. Calibrated to the 'advanced' baseline-AUROC band.
+  Realistic clinical missingness corrupts a copy: lactate is MNAR (extreme assay
+  values dropped), systolic BP is MAR (missing for older patients), heart-rate
+  telemetry is MCAR, and 2% of outcomes are mislabelled. `sex` is included but
+  carries no causal signal — a fairness/feature-selection check.
+seed: 202
+rows: 7000
+
+features:
+  patient_age:
+    type: numeric
+    dist: normal
+    params: { mean: 63, std: 17 }
+    min: 18
+    max: 100
+    dtype: int
+  sex:
+    type: categorical
+    categories: [female, male]
+    weights: [0.49, 0.51]
+  admission_type:
+    type: categorical
+    categories: [elective, urgent, emergency]
+    weights: [0.4, 0.35, 0.25]
+  num_comorbidities:
+    type: numeric
+    dist: poisson
+    params: { lam: 2.6 }
+    min: 0
+    dtype: int
+  severity:
+    type: numeric          # LATENT confounder — the true generative driver
+    dtype: float
+    emit: false            # not shipped; drives both vitals and outcome
+  heart_rate:
+    type: numeric          # derived: observed proxy of severity (bpm)
+    dtype: float
+    min: 0
+  lactate:
+    type: numeric          # derived: observed proxy of severity (mmol/L)
+    dtype: float
+    min: 0
+  systolic_bp:
+    type: numeric          # derived: observed proxy of severity (mmHg)
+    dtype: float
+    min: 0
+  deterioration:
+    type: boolean          # label (derived): logistic of severity
+
+causal:
+  edges:
+    # roots → latent severity
+    - { from: patient_age,       to: severity, fn: linear, weight: 0.025 }
+    - { from: num_comorbidities, to: severity, fn: linear, weight: 0.55 }
+    - { from: admission_type,    to: severity, fn: map,    mapping: { elective: -1.0, urgent: 0.5, emergency: 2.0 } }
+    # latent severity → observed vitals (reverse causation → confounding)
+    - { from: severity, to: heart_rate,  fn: linear, weight: 9.0,  bias: 78 }
+    - { from: severity, to: lactate,     fn: linear, weight: 0.6,  bias: 1.4 }
+    - { from: severity, to: systolic_bp, fn: linear, weight: -7.0, bias: 124 }
+    # latent severity → outcome
+    - { from: severity, to: deterioration, fn: logistic, weight: 1.2, bias: -5.5 }
+  noise:
+    severity: { dist: normal, params: { mean: 0, std: 0.5 } }
+    heart_rate:  { dist: normal, params: { mean: 0, std: 8 } }
+    lactate:     { dist: normal, params: { mean: 0, std: 0.4 } }
+    systolic_bp: { dist: normal, params: { mean: 0, std: 10 } }
+    deterioration: { dist: none }
+
+difficulty:
+  target: advanced          # baseline ROC-AUC calibrated into [0.72, 0.80]
+  label: deterioration
+  probe: logreg
+  max_iters: 10
+  knobs: [noise, label_noise]
+
+failures:
+  - type: mnar               # extreme lactate values not recorded
+    column: lactate
+    rate: 0.12
+    strength: 2.0
+  - type: mar                # BP missing more often for older patients
+    column: systolic_bp
+    driver: patient_age
+    rate: 0.10
+    strength: 2.0
+  - type: mcar               # random telemetry gaps in heart rate
+    columns: [heart_rate]
+    rate: 0.05
+  - type: label_noise        # 2% chart-coding errors
+    column: deterioration
+    rate: 0.02
+
+export:
+  formats: [csv]
+  versions: [clean, injected]
+  splits: { train: 0.8, test: 0.2 }
+
+meta:
+  level: hackathon
+  challenge:
+    title: "Early warning for clinical deterioration"
+    task: classification
+    target: deterioration
+    metric: ROC-AUC
+    difficulty: advanced
+    baseline_auroc_band: [0.72, 0.80]
+    train_test_split: "80 / 20"
+    hidden_structure: >
+      The true cause (severity) is latent. It drives the observed vitals AND the
+      outcome, so heart_rate / lactate / systolic_bp are correlated proxies, not
+      independent causes.
+    gotchas:
+      - "lactate is MNAR (extreme values missing) and systolic_bp is MAR (by age) — imputation choice matters."
+      - "sex carries no causal signal; including it should not help — watch for spurious importance."
+      - "Vitals are confounded proxies of a hidden severity, not independent predictors."
+  tags: [healthcare, clinical, causal, latent, confounder, difficulty, missingness, classification]