zeromodel-analysis 1.1.0__py3-none-any.whl

zeromodel/analysis/__init__.py

@@ -0,0 +1,219 @@
+"""ZeroModel analysis public API."""
+
+from __future__ import annotations
+
+from .adapters.common import (
+    checkpoints_from_export,
+    load_tracker_records,
+    records_to_checkpoints,
+)
+from .adapters.jsonl import (
+    checkpoints_from_csv,
+    checkpoints_from_json,
+    checkpoints_from_jsonl,
+)
+from .adapters.tensorboard import (
+    TENSORBOARD_DEFAULT_ALIASES,
+    checkpoints_from_tensorboard_scalars,
+)
+from .adapters.trackio import (
+    TRACKIO_DEFAULT_ALIASES,
+    checkpoints_from_trackio_export,
+)
+from .adapters.wandb import (
+    WANDB_DEFAULT_ALIASES,
+    checkpoints_from_wandb_export,
+)
+from .compare import (
+    VPMComparison,
+    compare_fields,
+)
+from .compose import (
+    as_field,
+    vpm_add,
+    vpm_and,
+    vpm_not,
+    vpm_or,
+    vpm_subtract,
+    vpm_xor,
+)
+from .controller import (
+    Decision,
+    Policy,
+    Signal,
+    Thresholds,
+    VPMController,
+    VPMRow,
+    default_controller,
+)
+from .critic import (
+    CriticAssessment,
+    CriticObservation,
+    build_critic_vpm,
+    critic_recipe,
+    observations_from_critic_lines,
+)
+from .edge import (
+    TopLeftGate,
+    TopLeftGateResult,
+)
+from .hierarchy import (
+    HierarchyLevel,
+    build_pyramid,
+    reduce_blocks,
+)
+from .learning import (
+    LearningAssessment,
+    LearningObservation,
+    VALID_SPLITS,
+    build_learning_vpm,
+    learning_recipe,
+)
+from .manifold import (
+    DecisionManifold,
+    ManifoldFrame,
+    ManifoldSummary,
+    ManifoldTransition,
+    build_decision_manifold,
+    find_inflection_points,
+)
+from .patterns import (
+    MatrixPatternDetector,
+    OBJECTIVE_IDS,
+    ObjectiveResult,
+    PATTERN_CHECKER_VERSION,
+    PATTERN_METHOD,
+    PatternAnalysisSpec,
+    PatternDiscoveryArtifacts,
+    PatternReport,
+    REPORT_METRICS,
+    build_discovered_view,
+    detect_patterns,
+)
+from .phos import (
+    PHOSResult,
+    guarded_pack_artifact,
+    image_entropy,
+    pack_artifact,
+    phos_sort_pack,
+    robust01,
+    to_square,
+    top_left_concentration,
+)
+from .policy_diagnostics import (
+    CRITICALITY_METRIC_ID,
+    DECISION_MARGIN_METRIC_ID,
+    with_q_diagnostics,
+)
+from .policy_properties import (
+    CHECKER_VERSION,
+    PolicyPropertyChecker,
+    PolicyPropertyResult,
+    PolicyPropertySpec,
+    PolicyPropertyViolation,
+    PolicyVerificationReport,
+    VERIFICATION_METRICS,
+    decode_key_value_row_id,
+)
+from .spatial import (
+    SpatialOptimizationResult,
+    SpatialOptimizer,
+    build_optimized_view,
+    optimize_view_profile,
+)
+from .training import (
+    TrainingCheckpoint,
+    TrainingProgressAssessment,
+    build_training_progress_vpm,
+    training_progress_recipe,
+)
+
+__all__ = [
+    "CHECKER_VERSION",
+    "CRITICALITY_METRIC_ID",
+    "CriticAssessment",
+    "CriticObservation",
+    "DECISION_MARGIN_METRIC_ID",
+    "Decision",
+    "DecisionManifold",
+    "HierarchyLevel",
+    "LearningAssessment",
+    "LearningObservation",
+    "ManifoldFrame",
+    "ManifoldSummary",
+    "ManifoldTransition",
+    "MatrixPatternDetector",
+    "OBJECTIVE_IDS",
+    "ObjectiveResult",
+    "PATTERN_CHECKER_VERSION",
+    "PATTERN_METHOD",
+    "PHOSResult",
+    "PatternAnalysisSpec",
+    "PatternDiscoveryArtifacts",
+    "PatternReport",
+    "Policy",
+    "PolicyPropertyChecker",
+    "PolicyPropertyResult",
+    "PolicyPropertySpec",
+    "PolicyPropertyViolation",
+    "PolicyVerificationReport",
+    "REPORT_METRICS",
+    "Signal",
+    "SpatialOptimizationResult",
+    "SpatialOptimizer",
+    "TENSORBOARD_DEFAULT_ALIASES",
+    "TRACKIO_DEFAULT_ALIASES",
+    "Thresholds",
+    "TopLeftGate",
+    "TopLeftGateResult",
+    "TrainingCheckpoint",
+    "TrainingProgressAssessment",
+    "VALID_SPLITS",
+    "VERIFICATION_METRICS",
+    "VPMComparison",
+    "VPMController",
+    "VPMRow",
+    "WANDB_DEFAULT_ALIASES",
+    "as_field",
+    "build_critic_vpm",
+    "build_decision_manifold",
+    "build_discovered_view",
+    "build_learning_vpm",
+    "build_optimized_view",
+    "build_pyramid",
+    "build_training_progress_vpm",
+    "checkpoints_from_csv",
+    "checkpoints_from_export",
+    "checkpoints_from_json",
+    "checkpoints_from_jsonl",
+    "checkpoints_from_tensorboard_scalars",
+    "checkpoints_from_trackio_export",
+    "checkpoints_from_wandb_export",
+    "compare_fields",
+    "critic_recipe",
+    "decode_key_value_row_id",
+    "default_controller",
+    "detect_patterns",
+    "find_inflection_points",
+    "guarded_pack_artifact",
+    "image_entropy",
+    "learning_recipe",
+    "load_tracker_records",
+    "observations_from_critic_lines",
+    "optimize_view_profile",
+    "pack_artifact",
+    "phos_sort_pack",
+    "records_to_checkpoints",
+    "reduce_blocks",
+    "robust01",
+    "to_square",
+    "top_left_concentration",
+    "training_progress_recipe",
+    "vpm_add",
+    "vpm_and",
+    "vpm_not",
+    "vpm_or",
+    "vpm_subtract",
+    "vpm_xor",
+    "with_q_diagnostics",
+]

zeromodel/analysis/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""Dependency-light adapters from tracker exports to ZeroModel checkpoints."""
+
+from __future__ import annotations
+
+from zeromodel.analysis.adapters.common import (
+    checkpoints_from_export,
+    load_tracker_records,
+    records_to_checkpoints,
+)
+from zeromodel.analysis.adapters.jsonl import (
+    checkpoints_from_csv,
+    checkpoints_from_json,
+    checkpoints_from_jsonl,
+)
+from zeromodel.analysis.adapters.tensorboard import checkpoints_from_tensorboard_scalars
+from zeromodel.analysis.adapters.trackio import checkpoints_from_trackio_export
+from zeromodel.analysis.adapters.wandb import checkpoints_from_wandb_export
+
+__all__ = [
+    "checkpoints_from_csv",
+    "checkpoints_from_export",
+    "checkpoints_from_json",
+    "checkpoints_from_jsonl",
+    "checkpoints_from_tensorboard_scalars",
+    "checkpoints_from_trackio_export",
+    "checkpoints_from_wandb_export",
+    "load_tracker_records",
+    "records_to_checkpoints",
+]

zeromodel/analysis/adapters/common.py

@@ -0,0 +1,207 @@
+"""Common helpers for converting tracker exports into training checkpoints.
+
+The adapters in this package intentionally parse exported files rather than live
+tracker APIs. That keeps ZeroModel dependency-light and makes the resulting
+training progress artifacts reproducible from checked-in fixtures.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+from zeromodel.core.artifact import VPMValidationError
+from zeromodel.analysis.training import TrainingCheckpoint
+
+_DEFAULT_IGNORE_KEYS = {
+    "step",
+    "global_step",
+    "_step",
+    "checkpoint_id",
+    "metadata",
+    "wall_time",
+    "timestamp",
+    "time",
+    "epoch",
+    "tag",
+    "name",
+    "value",
+}
+
+
+def _as_number(value: Any) -> float | None:
+    if isinstance(value, bool) or value is None:
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    if number != number or number in (float("inf"), float("-inf")):
+        return None
+    return number
+
+
+def _load_json(path: Path) -> list[Mapping[str, Any]]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        records = payload
+    elif isinstance(payload, dict):
+        for key in ("records", "history", "checkpoints", "rows", "data"):
+            if isinstance(payload.get(key), list):
+                records = payload[key]
+                break
+        else:
+            records = [payload]
+    else:
+        raise VPMValidationError(
+            "JSON tracker export must be an object or list of objects"
+        )
+    if not all(isinstance(item, Mapping) for item in records):
+        raise VPMValidationError("Tracker export records must be objects")
+    return [dict(item) for item in records]
+
+
+def _load_jsonl(path: Path) -> list[Mapping[str, Any]]:
+    records: list[Mapping[str, Any]] = []
+    for line_number, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        text = line.strip()
+        if not text:
+            continue
+        item = json.loads(text)
+        if not isinstance(item, Mapping):
+            raise VPMValidationError(
+                "JSONL tracker record on line %s must be an object" % line_number
+            )
+        records.append(dict(item))
+    return records
+
+
+def _load_csv(path: Path) -> list[Mapping[str, Any]]:
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        return [dict(row) for row in csv.DictReader(handle)]
+
+
+def load_tracker_records(path: str | Path) -> list[Mapping[str, Any]]:
+    """Load JSON, JSONL, or CSV tracker records from ``path``."""
+    source = Path(path)
+    suffix = source.suffix.lower()
+    if suffix == ".json":
+        return _load_json(source)
+    if suffix in {".jsonl", ".ndjson"}:
+        return _load_jsonl(source)
+    if suffix == ".csv":
+        return _load_csv(source)
+    raise VPMValidationError("Unsupported tracker export format: %s" % suffix)
+
+
+def _first_present(record: Mapping[str, Any], keys: Sequence[str]) -> str | None:
+    for key in keys:
+        if key in record:
+            return key
+    return None
+
+
+def _metric_name(name: str, aliases: Mapping[str, str]) -> str:
+    return str(aliases.get(name, name)).replace("/", "_").replace(" ", "_")
+
+
+def _metadata_for_record(
+    record: Mapping[str, Any], metadata_keys: Iterable[str]
+) -> dict[str, Any]:
+    return {key: record[key] for key in metadata_keys if key in record}
+
+
+def records_to_checkpoints(
+    records: Sequence[Mapping[str, Any]],
+    *,
+    step_keys: Sequence[str] = ("step", "global_step", "_step"),
+    metrics_key: str = "metrics",
+    tag_key: str | None = None,
+    value_key: str | None = None,
+    checkpoint_id_key: str = "checkpoint_id",
+    metric_aliases: Mapping[str, str] | None = None,
+    metadata_keys: Sequence[str] = ("wall_time", "timestamp", "time", "epoch"),
+    ignore_keys: Iterable[str] = _DEFAULT_IGNORE_KEYS,
+) -> list[TrainingCheckpoint]:
+    """Convert tracker records into ordered ``TrainingCheckpoint`` objects.
+
+    Two export shapes are supported:
+
+    1. one row per checkpoint, with either a nested ``metrics`` object or flat
+       numeric columns;
+    2. one row per scalar, with ``tag`` and ``value`` columns that are grouped by
+       step, as in TensorBoard scalar CSV exports.
+    """
+    if not records:
+        raise VPMValidationError("Tracker export contained no records")
+
+    aliases = {
+        str(key): str(value) for key, value in dict(metric_aliases or {}).items()
+    }
+    ignored = {str(key) for key in ignore_keys}
+    by_step: "OrderedDict[int, dict[str, Any]]" = OrderedDict()
+
+    for record in records:
+        step_key = _first_present(record, step_keys)
+        if step_key is None:
+            raise VPMValidationError(
+                "Tracker record is missing a step key; tried %r" % (tuple(step_keys),)
+            )
+        step_number = _as_number(record[step_key])
+        if step_number is None:
+            raise VPMValidationError("Tracker step value must be numeric")
+        step = int(step_number)
+        if step not in by_step:
+            by_step[step] = {"metrics": {}, "metadata": {}}
+        bucket = by_step[step]
+
+        if tag_key and value_key and tag_key in record and value_key in record:
+            value = _as_number(record[value_key])
+            if value is not None:
+                bucket["metrics"][_metric_name(str(record[tag_key]), aliases)] = value
+        elif isinstance(record.get(metrics_key), Mapping):
+            for key, value in record[metrics_key].items():
+                number = _as_number(value)
+                if number is not None:
+                    bucket["metrics"][_metric_name(str(key), aliases)] = number
+        else:
+            for key, value in record.items():
+                if key in ignored:
+                    continue
+                number = _as_number(value)
+                if number is not None:
+                    bucket["metrics"][_metric_name(str(key), aliases)] = number
+
+        bucket["metadata"].update(_metadata_for_record(record, metadata_keys))
+        if checkpoint_id_key in record:
+            bucket["checkpoint_id"] = str(record[checkpoint_id_key])
+
+    checkpoints: list[TrainingCheckpoint] = []
+    for step, payload in by_step.items():
+        metrics = payload["metrics"]
+        if not metrics:
+            continue
+        checkpoints.append(
+            TrainingCheckpoint(
+                step=step,
+                checkpoint_id=payload.get("checkpoint_id") or "step_%s" % step,
+                metrics=metrics,
+                metadata=payload.get("metadata", {}),
+            )
+        )
+    if not checkpoints:
+        raise VPMValidationError("Tracker export contained no numeric metrics")
+    return sorted(checkpoints, key=lambda checkpoint: checkpoint.step)
+
+
+def checkpoints_from_export(
+    path: str | Path,
+    **kwargs: Any,
+) -> list[TrainingCheckpoint]:
+    """Load records from a tracker export and convert them to checkpoints."""
+    return records_to_checkpoints(load_tracker_records(path), **kwargs)

zeromodel/analysis/adapters/jsonl.py

@@ -0,0 +1,52 @@
+"""Generic JSON/JSONL/CSV training telemetry adapters."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from zeromodel.analysis.training import TrainingCheckpoint
+
+from zeromodel.analysis.adapters.common import checkpoints_from_export
+
+
+def checkpoints_from_jsonl(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("step", "global_step", "_step"),
+    metric_aliases: Mapping[str, str] | None = None,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoint telemetry from a JSONL export.
+
+    Each line may contain a nested ``metrics`` object or flat numeric metric
+    columns. The return value can be passed directly to
+    ``build_training_progress_vpm``.
+    """
+    return checkpoints_from_export(
+        path, step_keys=step_keys, metric_aliases=metric_aliases
+    )
+
+
+def checkpoints_from_json(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("step", "global_step", "_step"),
+    metric_aliases: Mapping[str, str] | None = None,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoint telemetry from a JSON export."""
+    return checkpoints_from_export(
+        path, step_keys=step_keys, metric_aliases=metric_aliases
+    )
+
+
+def checkpoints_from_csv(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("step", "global_step", "_step"),
+    metric_aliases: Mapping[str, str] | None = None,
+    **kwargs: Any,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoint telemetry from a CSV export."""
+    return checkpoints_from_export(
+        path, step_keys=step_keys, metric_aliases=metric_aliases, **kwargs
+    )

zeromodel/analysis/adapters/tensorboard.py

@@ -0,0 +1,52 @@
+"""TensorBoard scalar export adapter.
+
+This adapter parses exported scalar CSV/JSON/JSONL files. It deliberately does not
+parse TensorBoard event protobufs directly, keeping ZeroModel free of TensorBoard
+runtime dependencies.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from zeromodel.analysis.training import TrainingCheckpoint
+
+from zeromodel.analysis.adapters.common import checkpoints_from_export
+
+TENSORBOARD_DEFAULT_ALIASES = {
+    "train/loss": "train_loss",
+    "loss/train": "train_loss",
+    "eval/loss": "eval_loss",
+    "validation/loss": "eval_loss",
+    "eval/accuracy": "heldout_score",
+    "validation/accuracy": "heldout_score",
+    "eval/reward": "heldout_score",
+    "tokens/sec": "tokens_per_second",
+    "tokens_per_second": "tokens_per_second",
+}
+
+
+def checkpoints_from_tensorboard_scalars(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("step", "global_step"),
+    tag_key: str = "tag",
+    value_key: str = "value",
+    metric_aliases: Mapping[str, str] | None = None,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoints from TensorBoard scalar exports.
+
+    TensorBoard's scalar dashboard can export rows shaped like
+    ``wall_time,step,tag,value``. Those rows are grouped into one checkpoint per
+    step.
+    """
+    aliases = dict(TENSORBOARD_DEFAULT_ALIASES)
+    aliases.update(dict(metric_aliases or {}))
+    return checkpoints_from_export(
+        path,
+        step_keys=step_keys,
+        tag_key=tag_key,
+        value_key=value_key,
+        metric_aliases=aliases,
+    )

zeromodel/analysis/adapters/trackio.py

@@ -0,0 +1,40 @@
+"""Trackio training telemetry export adapter.
+
+Supports JSON/JSONL/CSV metric exports shaped as flat rows or rows with nested
+``metrics`` dictionaries. No Trackio runtime dependency is required.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from zeromodel.analysis.training import TrainingCheckpoint
+
+from zeromodel.analysis.adapters.common import checkpoints_from_export
+
+TRACKIO_DEFAULT_ALIASES = {
+    "train/loss": "train_loss",
+    "train_loss": "train_loss",
+    "eval/loss": "eval_loss",
+    "validation/loss": "eval_loss",
+    "eval/accuracy": "heldout_score",
+    "validation/accuracy": "heldout_score",
+    "eval/reward": "heldout_score",
+    "regression_safety": "regression_safety",
+    "safety/regression": "regression_safety",
+    "tokens/sec": "tokens_per_second",
+    "tokens_per_second": "tokens_per_second",
+}
+
+
+def checkpoints_from_trackio_export(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("step", "global_step", "_step"),
+    metric_aliases: Mapping[str, str] | None = None,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoints from a Trackio metrics export."""
+    aliases = dict(TRACKIO_DEFAULT_ALIASES)
+    aliases.update(dict(metric_aliases or {}))
+    return checkpoints_from_export(path, step_keys=step_keys, metric_aliases=aliases)

zeromodel/analysis/adapters/wandb.py

@@ -0,0 +1,45 @@
+"""Weights & Biases history export adapter.
+
+Supports exported history JSONL/JSON/CSV files. No W&B SDK is required.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from zeromodel.analysis.training import TrainingCheckpoint
+
+from zeromodel.analysis.adapters.common import checkpoints_from_export
+
+WANDB_DEFAULT_ALIASES = {
+    "train/loss": "train_loss",
+    "train_loss": "train_loss",
+    "eval/loss": "eval_loss",
+    "val/loss": "eval_loss",
+    "validation/loss": "eval_loss",
+    "eval/accuracy": "heldout_score",
+    "val/accuracy": "heldout_score",
+    "validation/accuracy": "heldout_score",
+    "eval/reward": "heldout_score",
+    "safety/regression": "regression_safety",
+    "regression/safety": "regression_safety",
+    "system/tokens_per_second": "tokens_per_second",
+    "tokens/sec": "tokens_per_second",
+}
+
+
+def checkpoints_from_wandb_export(
+    path: str | Path,
+    *,
+    step_keys: Sequence[str] = ("_step", "step", "global_step"),
+    metric_aliases: Mapping[str, str] | None = None,
+) -> list[TrainingCheckpoint]:
+    """Load checkpoints from a W&B history export.
+
+    The adapter accepts flat history rows and nested ``metrics`` rows. Metric names
+    with slashes are normalized to underscores after aliasing.
+    """
+    aliases = dict(WANDB_DEFAULT_ALIASES)
+    aliases.update(dict(metric_aliases or {}))
+    return checkpoints_from_export(path, step_keys=step_keys, metric_aliases=aliases)

zeromodel/analysis/compare.py

@@ -0,0 +1,55 @@
+"""Differential analysis helpers for VPM artifacts and fields."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+from zeromodel.analysis.compose import as_field, vpm_add, vpm_and, vpm_subtract, vpm_xor
+
+
+@dataclass(frozen=True)
+class VPMComparison:
+    diff: np.ndarray
+    overlap: np.ndarray
+    contrast: np.ndarray
+    enriched: np.ndarray
+    gain: float
+    loss: float
+    improvement_ratio: float
+
+
+def compare_fields(
+    baseline: Any, target: Any, *, overlap_weight: float = 0.25
+) -> VPMComparison:
+    """Compare a baseline field with a target field.
+
+    ``gain`` is positive target-minus-baseline mass; ``loss`` is negative mass;
+    ``improvement_ratio`` is gain / (gain + loss).
+    """
+    base = as_field(baseline)
+    tgt = as_field(target)
+    if base.shape != tgt.shape:
+        raise ValueError(
+            "VPM fields must have identical shapes; got %s and %s"
+            % (base.shape, tgt.shape)
+        )
+
+    signed = tgt - base
+    gain = float(np.sum(np.clip(signed, 0.0, None)))
+    loss = float(np.sum(np.clip(-signed, 0.0, None)))
+    total = gain + loss + 1e-12
+    overlap = vpm_and(base, tgt)
+    contrast = vpm_xor(base, tgt)
+    enriched = vpm_add(vpm_subtract(tgt, base), overlap * float(overlap_weight))
+    return VPMComparison(
+        diff=signed,
+        overlap=overlap,
+        contrast=contrast,
+        enriched=enriched,
+        gain=gain,
+        loss=loss,
+        improvement_ratio=float(gain / total),
+    )