cvprofiles 2.0.0__py3-none-any.whl

cvprofiles/__init__.py

@@ -0,0 +1,6 @@
+"""cvprofiles — construct-validity profiles (score-agnostic, model-free engine)."""
+
+from __future__ import annotations
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

cvprofiles/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m cvprofiles`` / ``python -m cvprofiles.cli``."""
+
+from cvprofiles.cli import app
+
+app()

cvprofiles/anchors/__init__.py

@@ -0,0 +1,27 @@
+"""θ-anchor documentation discipline (v2.0 thread c).
+
+Pre-data anchors as a first-class schema'd artifact: one anchor per
+restriction id, hashed for provenance (anchors_hash), excluded from the
+freeze preimage. "Pre-data" is a process commitment — the engine enforces
+completeness + hash, never timing.
+"""
+
+from cvprofiles.anchors.pipeline import (
+    AnchorError,
+    AnchorsConfig,
+    ThetaAnchor,
+    anchors_hash,
+    anchors_payload,
+    parse_anchors,
+    validate_completeness,
+)
+
+__all__ = [
+    "AnchorError",
+    "AnchorsConfig",
+    "ThetaAnchor",
+    "anchors_hash",
+    "anchors_payload",
+    "parse_anchors",
+    "validate_completeness",
+]

cvprofiles/anchors/pipeline.py

@@ -0,0 +1,136 @@
+"""θ-anchor parsing, completeness validation, and provenance hashing.
+
+v2.0 thread c (docs/12 2026-08-05 D4/D6): anchors.yaml is a schema'd
+pre-data artifact. One anchor per restriction id; completeness is enforced
+against the pinned network. anchors_hash is SHA-256 of canonical JSON and is
+**excluded from the freeze preimage** — it is documentation provenance, not
+an engine input. "Pre-data" is a process commitment; the engine cannot
+verify when a file was written.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from cvprofiles.freeze import hash_canonical_json
+from cvprofiles.schemas.network import NetworkConfig
+
+AnchorKind = Literal["literature", "derived", "author"]
+
+
+class AnchorError(ValueError):
+    """Loud anchor failure (parse / schema / completeness)."""
+
+
+class ThetaAnchor(BaseModel):
+    """One pre-data anchor for one restriction r."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    restriction_id: str = Field(..., min_length=1)
+    citation_key: str = Field(..., min_length=1)
+    source_phrase: str = Field(..., min_length=1)
+    anchor_kind: AnchorKind
+    pre_data: bool = Field(
+        default=True,
+        description=(
+            "Process commitment flag: anchor declared before data analysis. "
+            "The engine cannot verify timing; this is the researcher's record."
+        ),
+    )
+
+    @field_validator("restriction_id")
+    @classmethod
+    def _id_strip(cls, v: str) -> str:
+        s = v.strip()
+        if not s:
+            raise ValueError("restriction_id must be non-empty")
+        return s
+
+
+class AnchorsConfig(BaseModel):
+    """The full anchor set for one network."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: str = "1"
+    anchors: list[ThetaAnchor] = Field(..., min_length=1)
+
+    @model_validator(mode="after")
+    def _unique_ids(self) -> AnchorsConfig:
+        ids = [a.restriction_id for a in self.anchors]
+        if len(ids) != len(set(ids)):
+            raise ValueError("anchor restriction_ids must be unique")
+        return self
+
+
+def parse_anchors(source: Path | str | dict[str, Any]) -> AnchorsConfig:
+    """Load and validate anchors from YAML path or mapping.
+
+    All invalid inputs raise ``AnchorError`` (never raw pydantic at the IO
+    boundary), mirroring the RESTRICT pattern.
+    """
+    if isinstance(source, dict):
+        try:
+            return AnchorsConfig.model_validate(source)
+        except Exception as exc:  # pydantic ValidationError
+            raise AnchorError(f"invalid anchors schema: {exc}") from exc
+    p = Path(source)
+    if not p.is_file():
+        raise AnchorError(f"anchors file not found: {p}")
+    try:
+        raw = yaml.safe_load(p.read_text())
+    except yaml.YAMLError as exc:
+        raise AnchorError(f"invalid anchors YAML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise AnchorError("anchors YAML must be a mapping at top level")
+    try:
+        return AnchorsConfig.model_validate(raw)
+    except Exception as exc:  # pydantic ValidationError
+        raise AnchorError(f"invalid anchors schema: {exc}") from exc
+
+
+def validate_completeness(
+    config: AnchorsConfig, network: NetworkConfig
+) -> AnchorsConfig:
+    """Fail loud unless every restriction id has exactly one anchor.
+
+    Unknown anchor ids (not in the network) also fail: an anchor must bind
+    to a real restriction.
+    """
+    net_ids = {r.id for r in network.restrictions}
+    anchor_ids = {a.restriction_id for a in config.anchors}
+    missing = net_ids - anchor_ids
+    if missing:
+        raise AnchorError(
+            f"missing anchors for restriction(s): {sorted(missing)}"
+        )
+    unknown = anchor_ids - net_ids
+    if unknown:
+        raise AnchorError(
+            f"anchor restriction_id(s) not in the network: {sorted(unknown)}"
+        )
+    return config
+
+
+def anchors_hash(config: AnchorsConfig) -> str:
+    """SHA-256 hex of canonical JSON for the validated anchor set.
+
+    Excluded from the freeze preimage by design (docs/12 D4): anchors are
+    documentation provenance, not engine inputs.
+    """
+    return hash_canonical_json(config.model_dump(mode="json"))
+
+
+def anchors_payload(config: AnchorsConfig) -> dict[str, Any]:
+    """JSON-serializable audit payload (anchors.json + report panel)."""
+    return {
+        "schema_version": "1",
+        "anchors_hash": anchors_hash(config),
+        "n_anchors": len(config.anchors),
+        "anchors": [a.model_dump(mode="json") for a in config.anchors],
+    }

cvprofiles/cli.py

@@ -0,0 +1,213 @@
+"""Thin Typer CLI — state helpers + full SCORE→REPORT run."""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cvprofiles import __version__
+
+app = typer.Typer(
+    name="cvprofiles",
+    help="Construct-validity profiles: admissible sets and construct-identified ranges.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _parse_theta_grid(raw: str | None) -> list[float] | None:
+    """Parse a comma-separated positive finite λ grid, fail-loudly."""
+    if raw is None:
+        return None
+    tokens = raw.split(",")
+    if not raw.strip() or any(not token.strip() for token in tokens):
+        raise ValueError("must be a non-empty comma-separated list of positive numbers")
+    values: list[float] = []
+    for token in tokens:
+        try:
+            value = float(token.strip())
+        except ValueError as exc:
+            raise ValueError(f"invalid lambda {token.strip()!r}") from exc
+        if not math.isfinite(value) or value <= 0.0:
+            raise ValueError(f"lambda {token.strip()!r} must be finite and > 0")
+        if value in values:
+            raise ValueError(f"duplicate lambda {token.strip()!r}")
+        values.append(value)
+    return values
+
+
+def _parse_delta_grid(raw: str | None) -> list[float] | None:
+    """Parse a comma-separated non-negative finite δ grid, fail-loudly."""
+    if raw is None:
+        return None
+    tokens = raw.split(",")
+    if not raw.strip() or any(not token.strip() for token in tokens):
+        raise ValueError("must be a non-empty comma-separated list of non-negative numbers")
+    values: list[float] = []
+    for token in tokens:
+        try:
+            value = float(token.strip())
+        except ValueError as exc:
+            raise ValueError(f"invalid delta {token.strip()!r}") from exc
+        if not math.isfinite(value) or value < 0.0:
+            raise ValueError(f"delta {token.strip()!r} must be finite and >= 0")
+        if value in values:
+            raise ValueError(f"duplicate delta {token.strip()!r}")
+        values.append(value)
+    return values
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cvprofiles {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show package version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """cvprofiles CLI (thin v1.0 spine)."""
+
+
+@app.command("run")
+def run_cmd(
+    scores: Annotated[
+        Path,
+        typer.Option("--scores", exists=True, dir_okay=False, help="Scores CSV/parquet"),
+    ],
+    roles: Annotated[
+        Path,
+        typer.Option("--roles", exists=True, dir_okay=False, help="roles.json"),
+    ],
+    network: Annotated[
+        Path,
+        typer.Option("--network", exists=True, dir_okay=False, help="network.yaml"),
+    ],
+    beta: Annotated[
+        Path,
+        typer.Option("--beta", exists=True, dir_okay=False, help="beta.yaml"),
+    ],
+    out: Annotated[
+        Path | None,
+        typer.Option("--out", help="Output dir (default: reports/runs/<run_id>/)"),
+    ] = None,
+    policy: Annotated[
+        str,
+        typer.Option("--policy", help="SCORE normalization: none | zscore_measures"),
+    ] = "none",
+    seed: Annotated[int, typer.Option("--seed", min=0)] = 0,
+    n_boot: Annotated[
+        int,
+        typer.Option(
+            "--n-boot",
+            min=0,
+            help="Bootstrap replicates over units; 0 disables bootstrap.",
+        ),
+    ] = 0,
+    theta_grid: Annotated[
+        str | None,
+        typer.Option(
+            "--theta-grid",
+            help="Comma-separated positive threshold scale multipliers.",
+        ),
+    ] = None,
+    delta_grid: Annotated[
+        str | None,
+        typer.Option(
+            "--delta-grid",
+            help="Comma-separated non-negative tolerance values (absolute δ).",
+        ),
+    ] = None,
+    anchors: Annotated[
+        Path | None,
+        typer.Option(
+            "--anchors",
+            exists=True,
+            dir_okay=False,
+            help="Pre-data θ-anchor YAML (documentation; excluded from run_id).",
+        ),
+    ] = None,
+    title: Annotated[
+        str,
+        typer.Option("--title"),
+    ] = "Construct-validity profile",
+) -> None:
+    """SCORE → RESTRICT → IDENTIFY → REPORT. Empty M* exits 0.
+
+    stdout is always a single JSON summary (machine-clean).
+    Human status crumbs go to stderr only.
+    """
+    from cvprofiles.identify.pipeline import IdentifyError
+    from cvprofiles.pipeline import run_profile, summary_dict
+    from cvprofiles.report.pipeline import ReportError
+    from cvprofiles.restrict.pipeline import RestrictError
+    from cvprofiles.score.pipeline import ScoreError
+
+    if policy not in ("none", "zscore_measures"):
+        typer.secho(f"error: unknown policy: {policy}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        theta_grid_lambdas = _parse_theta_grid(theta_grid)
+    except ValueError as exc:
+        typer.secho(f"error: theta-grid: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from exc
+
+    try:
+        delta_grid_deltas = _parse_delta_grid(delta_grid)
+    except ValueError as exc:
+        typer.secho(f"error: delta-grid: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from exc
+
+    try:
+        result = run_profile(
+            scores=scores,
+            roles=roles,
+            network=network,
+            beta=beta,
+            out_dir=out,
+            policy=policy,  # type: ignore[arg-type]
+            seed=seed,
+            title=title,
+            n_boot=n_boot,
+            theta_grid_lambdas=theta_grid_lambdas,
+            delta_grid_deltas=delta_grid_deltas,
+            anchors=anchors,
+        )
+    except (ScoreError, RestrictError, IdentifyError, ReportError, ValueError) as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc
+
+    summary = summary_dict(result)
+    # stdout = JSON only (tests + scripts parse this)
+    typer.echo(json.dumps(summary, indent=2))
+    # human crumbs → stderr only
+    if result.identify.empty:
+        typer.secho(
+            "empty M* — clean success; see report.html for binding restrictions",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+    else:
+        typer.secho(
+            f"M*={result.identify.admissible}  "
+            f"[L,U]=[{result.identify.range_L}, {result.identify.range_U}]",
+            fg=typer.colors.GREEN,
+            err=True,
+        )
+
+
+if __name__ == "__main__":
+    app()

cvprofiles/freeze.py

@@ -0,0 +1,279 @@
+"""Freeze hashing and run_id construction (M1 lock).
+
+Algorithm (LOCKED 2026-08-01 — see docs/12):
+
+1. Piece hashes are bare lowercase SHA-256 hex (64 chars), no ``sha256:`` prefix.
+2. Canonical JSON: UTF-8, ``sort_keys=True``, separators ``(",", ":")``,
+   ``allow_nan=False``. Non-JSON types raise.
+3. ``network_hash`` / ``beta_hash``: hash canonical JSON of
+   ``model_dump(mode="json")`` for validated NetworkConfig / BetaSpec.
+4. ``scores_hash``: hash canonical CSV text of the score table:
+   - columns in declared order (caller supplies column list);
+   - rows sorted by ``unit_id`` ascending (string sort);
+   - header line = comma-joined column names;
+   - floats formatted with 17 significant digits (``format(x, ".17g")``);
+   - integers without decimal; bool as ``0``/``1``; null as empty field;
+   - UTF-8 bytes of the full CSV (including trailing newline after last row).
+5. ``run_id``: SHA-256 of canonical JSON of the freeze preimage dict with keys
+   (JSON is sort_keys; documentation order is not the hash order):
+   ``beta_hash``, ``config``, ``delta``, ``n_boot``, ``network_hash``,
+   ``package_version``, ``schema_version``, ``scores_hash``, ``seed``.
+   ``n_boot`` is JSON ``null`` in v1.0.
+6. **Excluded from run_id preimage:** ``created_at``, wall clock, absolute paths,
+   hostnames, artifact path maps, report HTML.
+
+Bit-stability: same validated scores + network + beta + package_version +
+seed + delta + config ⇒ identical scores/network/beta hashes and run_id.
+
+Engine freeze column list should be unit_id + measures + aux + outcome only;
+diagnostic columns (e.g. ``V_star``) stay out of ``scores_hash`` unless the
+caller intentionally versions them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from cvprofiles.schemas.beta import BetaSpec
+from cvprofiles.schemas.network import NetworkConfig
+from cvprofiles.schemas.run import FreezeBundle
+
+CANONICAL_JSON_SEPARATORS = (",", ":")
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def canonical_json_bytes(obj: Any) -> bytes:
+    """Serialize ``obj`` to canonical UTF-8 JSON bytes (sorted keys, compact)."""
+    try:
+        text = json.dumps(
+            obj,
+            sort_keys=True,
+            separators=CANONICAL_JSON_SEPARATORS,
+            ensure_ascii=False,
+            allow_nan=False,
+        )
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"object is not JSON-canonicalizable: {exc}") from exc
+    return text.encode("utf-8")
+
+
+def sha256_hex(data: bytes) -> str:
+    """Bare lowercase SHA-256 hex digest (64 chars)."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def hash_canonical_json(obj: Any) -> str:
+    """SHA-256 hex of canonical JSON bytes."""
+    return sha256_hex(canonical_json_bytes(obj))
+
+
+def _format_cell(value: Any) -> str:
+    if value is None:
+        return ""
+
+    # Numpy scalars → Python before NA / bool / int branching
+    if isinstance(value, np.generic):
+        value = value.item()
+
+    # Non-finite floats must fail loud (never coerce NaN/Inf to empty).
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise ValueError("scores table must not contain NaN or Inf for freeze hash")
+        return format(value, ".17g")
+
+    # Remaining missing values (e.g. pd.NA on non-float columns) → empty field
+    try:
+        if pd.isna(value):
+            return ""
+    except (TypeError, ValueError):
+        pass
+
+    if isinstance(value, bool):
+        return "1" if value else "0"
+    if isinstance(value, int) and not isinstance(value, bool):
+        return str(value)
+    if isinstance(value, str):
+        if any(c in value for c in (",", '"', "\n", "\r")):
+            escaped = value.replace('"', '""')
+            return f'"{escaped}"'
+        return value
+    raise ValueError(f"unsupported cell type for scores hash: {type(value)!r}")
+
+
+def scores_canonical_csv_bytes(
+    df: pd.DataFrame,
+    columns: Sequence[str],
+    *,
+    unit_id_col: str = "unit_id",
+) -> bytes:
+    """Build canonical CSV bytes for score-table hashing.
+
+    Rows are sorted by ``unit_id_col`` (as string). Column order is exactly
+    ``columns`` (typically unit_id + measures + aux + outcome; diagnostics out).
+    """
+    missing = [c for c in columns if c not in df.columns]
+    if missing:
+        raise ValueError(f"scores frame missing columns for hash: {missing}")
+    if unit_id_col not in columns:
+        raise ValueError(f"unit_id column {unit_id_col!r} must be included in columns")
+
+    work = df.loc[:, list(columns)].copy()
+    work["_sort_key"] = work[unit_id_col].astype(str)
+    work = work.sort_values("_sort_key", kind="mergesort").drop(columns=["_sort_key"])
+
+    lines: list[str] = [",".join(columns)]
+    for row in work.itertuples(index=False, name=None):
+        lines.append(",".join(_format_cell(v) for v in row))
+    text = "\n".join(lines) + "\n"
+    return text.encode("utf-8")
+
+
+def hash_scores_frame(
+    df: pd.DataFrame,
+    columns: Sequence[str],
+    *,
+    unit_id_col: str = "unit_id",
+) -> str:
+    """SHA-256 hex of canonical score CSV bytes."""
+    return sha256_hex(scores_canonical_csv_bytes(df, columns, unit_id_col=unit_id_col))
+
+
+def hash_network(network: NetworkConfig | Mapping[str, Any]) -> str:
+    """SHA-256 of canonical JSON for a validated network (or raw mapping)."""
+    if isinstance(network, NetworkConfig):
+        payload = network.model_dump(mode="json")
+    else:
+        payload = NetworkConfig.model_validate(dict(network)).model_dump(mode="json")
+    return hash_canonical_json(payload)
+
+
+def hash_beta(beta: BetaSpec | Mapping[str, Any]) -> str:
+    """SHA-256 of canonical JSON for a validated beta spec (or raw mapping)."""
+    if isinstance(beta, BetaSpec):
+        payload = beta.model_dump(mode="json")
+    else:
+        payload = BetaSpec.model_validate(dict(beta)).model_dump(mode="json")
+    return hash_canonical_json(payload)
+
+
+def _validate_hex64(name: str, value: str) -> None:
+    if not isinstance(value, str) or not _HEX64.match(value):
+        raise ValueError(f"{name} must be 64-char lowercase hex string")
+
+
+def normalize_n_boot(n_boot: int | None) -> int | None:
+    """Normalize ``n_boot`` for the freeze preimage (docs/12 v1.1 lock).
+
+    ``< 1`` (or None) ⇒ JSON ``null`` so v1.0-era run_ids stay bit-stable
+    when bootstrap is off; ``>= 1`` ⇒ int. Every preimage producer must call
+    this before ``compute_run_id`` / ``build_freeze_bundle``.
+    """
+    if n_boot is None or n_boot < 1:
+        return None
+    return int(n_boot)
+
+
+def freeze_preimage(
+    *,
+    scores_hash: str,
+    network_hash: str,
+    beta_hash: str,
+    package_version: str,
+    seed: int = 0,
+    delta: float = 0.0,
+    schema_version: str = "1",
+    n_boot: int | None = None,
+    config: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the run_id preimage dict (hashed by ``compute_run_id``)."""
+    return {
+        "beta_hash": beta_hash,
+        "config": dict(config or {}),
+        "delta": float(delta),
+        "n_boot": n_boot,
+        "network_hash": network_hash,
+        "package_version": package_version,
+        "schema_version": schema_version,
+        "scores_hash": scores_hash,
+        "seed": int(seed),
+    }
+
+
+def compute_run_id(
+    *,
+    scores_hash: str,
+    network_hash: str,
+    beta_hash: str,
+    package_version: str,
+    seed: int = 0,
+    delta: float = 0.0,
+    schema_version: str = "1",
+    n_boot: int | None = None,
+    config: Mapping[str, Any] | None = None,
+) -> str:
+    """Compute ``run_id`` = SHA-256 hex of canonical freeze preimage JSON."""
+    _validate_hex64("scores_hash", scores_hash)
+    _validate_hex64("network_hash", network_hash)
+    _validate_hex64("beta_hash", beta_hash)
+
+    preimage = freeze_preimage(
+        scores_hash=scores_hash,
+        network_hash=network_hash,
+        beta_hash=beta_hash,
+        package_version=package_version,
+        seed=seed,
+        delta=delta,
+        schema_version=schema_version,
+        n_boot=n_boot,
+        config=config,
+    )
+    return hash_canonical_json(preimage)
+
+
+def build_freeze_bundle(
+    *,
+    scores_hash: str,
+    network_hash: str,
+    beta_hash: str,
+    package_version: str,
+    seed: int = 0,
+    delta: float = 0.0,
+    schema_version: str = "1",
+    n_boot: int | None = None,
+    config: Mapping[str, Any] | None = None,
+) -> FreezeBundle:
+    """Construct a validated FreezeBundle (does not compute run_id)."""
+    return FreezeBundle(
+        scores_hash=scores_hash,
+        network_hash=network_hash,
+        beta_hash=beta_hash,
+        package_version=package_version,
+        schema_version=schema_version,
+        seed=seed,
+        delta=delta,
+        n_boot=n_boot,
+        config=dict(config or {}),
+    )
+
+
+def run_id_from_bundle(bundle: FreezeBundle) -> str:
+    """Compute run_id from a FreezeBundle (created_at is not on the bundle)."""
+    return compute_run_id(
+        scores_hash=bundle.scores_hash,
+        network_hash=bundle.network_hash,
+        beta_hash=bundle.beta_hash,
+        package_version=bundle.package_version,
+        seed=bundle.seed,
+        delta=bundle.delta,
+        schema_version=bundle.schema_version,
+        n_boot=bundle.n_boot,
+        config=bundle.config,
+    )

cvprofiles/identify/__init__.py

@@ -0,0 +1,17 @@
+"""IDENTIFY state — slacks, M*, β image, and headline range."""
+
+from __future__ import annotations
+
+from cvprofiles.identify.pipeline import (
+    IdentifyError,
+    IdentifyResult,
+    run_identify,
+    write_identify_artifacts,
+)
+
+__all__ = [
+    "IdentifyError",
+    "IdentifyResult",
+    "run_identify",
+    "write_identify_artifacts",
+]