ZeroModel

ZeroModel turns scored data into deterministic, inspectable Visual Policy Map artifacts and small consumers that can operate without a model at decision time.

A VPM is a deterministic spatial view over a table of scored items. It carries values, stable row and metric identifiers, a layout recipe, view ordering, source mapping, provenance, and deterministic identity.

The package is now the clean new ZeroModel surface. There is no public zeromodel.v2 namespace: import directly from zeromodel.

Public claims are tracked in docs/claims-audit.md. Treat that file as the source of truth for what is validated, what is implemented with thin evidence, and what remains a roadmap claim.

Install

Current GitHub install:

python -m pip install "git+https://github.com/ernanhughes/zeromodel.git@main"

After the TestPyPI release candidate workflow publishes 0.1.0a1:

python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  zeromodel==0.1.0a1

After the production PyPI release is cut:

python -m pip install zeromodel

For development:

python -m pip install -e .[dev]
pytest
python -m build
python -m twine check dist/*

Release steps are documented in docs/release.md.

Core artifact

from zeromodel import LayoutRecipe, ScoreTable, build_vpm

score_table = ScoreTable(
    values=[[0.9, 0.2], [0.4, 0.8]],
    row_ids=["candidate-a", "candidate-b"],
    metric_ids=["quality", "uncertainty"],
)

recipe = LayoutRecipe.from_dict({
    "version": "vpm-layout/0",
    "name": "quality-first",
    "row_order": {
        "kind": "lexicographic",
        "keys": [{"metric_id": "quality", "direction": "desc"}],
        "tie_break": "row_id",
    },
    "column_order": {"kind": "source"},
    "normalization": {"kind": "per_metric_minmax", "clip": True},
})

artifact = build_vpm(score_table, recipe)
cell = artifact.cell(view_row=0, view_column=0)
region = artifact.region(rows=slice(0, 1), columns=slice(0, 2))

Capability surface

Dense view profiles

A source table can contain many signals at once. A view profile is a policy lens over that dense table: turn up one set of metrics and the matching rows/columns become salient without changing the source evidence.

from zeromodel import ScoreTable, ViewProfile, build_view

source = ScoreTable(
    values=[
        [0.10, 0.96, 0.05, 0.72, 0.20],
        [0.94, 0.12, 0.08, 0.18, 0.35],
        [0.24, 0.07, 0.97, 0.08, 0.78],
        [0.07, 0.18, 0.04, 0.98, 0.10],
    ],
    row_ids=["forest", "crowd", "traffic", "meadow"],
    metric_ids=["people", "trees", "cars", "grass", "risk"],
)

people_view = build_view(source, ViewProfile.from_metric("people", name="people"))
tree_view = build_view(source, ViewProfile.from_metric("trees", name="trees"))
risk_view = build_view(source, ViewProfile.from_metric("risk", name="risk"))

assert people_view.source.digest == tree_view.source.digest == risk_view.source.digest
print(people_view.cell(0, 0).row_id)  # crowd
print(tree_view.cell(0, 0).row_id)    # forest
print(risk_view.cell(0, 0).row_id)    # traffic

Positive weights make high values salient. Negative weights make low values salient.

See docs/examples/view-profiles.md and docs/research/dense-multiview-representation.md.

Spatial optimizer

The spatial optimizer derives a ViewProfile for one explicit geometric objective: concentrate high-signal mass in the top-left inspection region.

from zeromodel import ScoreTable, SpatialOptimizer, build_optimized_view, optimize_view_profile

source = ScoreTable(
    values=[
        [0.10, 0.50, 0.20],
        [0.95, 0.50, 0.25],
        [0.90, 0.50, 0.15],
        [0.05, 0.50, 0.20],
    ],
    row_ids=["background", "target_a", "target_b", "flat"],
    metric_ids=["target", "constant", "weak"],
)

optimizer = SpatialOptimizer(Kc=2, Kr=2, alpha=0.95, max_iters=40)
result = optimize_view_profile(source, name="optimized-target", optimizer=optimizer)
view = build_optimized_view(source, name="optimized-target", optimizer=optimizer)

print(result.baseline_mass, result.optimized_mass)
print(view.cell(0, 0).row_id, view.cell(0, 0).metric_id)

This does not claim the optimizer learns the correct semantic view for every task. It proves a deterministic top-left mass objective can emit a normal ViewProfile while preserving source mapping.

See docs/examples/spatial-optimizer.md and docs/research/spatial-calculus.md.

Decision manifold

A decision manifold turns a sequence of dense scored panels into optimized VPM frames, then surfaces where the spatial view changes most.

from zeromodel import ScoreTable, SpatialOptimizer, build_decision_manifold

panels = [
    ScoreTable(
        values=[[0.20, 0.60, 0.10], [1.00, 0.10, 0.10], [0.10, 0.20, 0.30]],
        row_ids=["forest", "crowd", "traffic"],
        metric_ids=["people", "trees", "risk"],
    ),
    ScoreTable(
        values=[[0.15, 0.55, 0.14], [0.25, 0.10, 0.30], [0.10, 0.18, 1.00]],
        row_ids=["forest", "crowd", "traffic"],
        metric_ids=["people", "trees", "risk"],
    ),
]

summary = build_decision_manifold(
    panels,
    optimizer=SpatialOptimizer(Kc=1, Kr=1),
    name="scene-shift",
    inflection_top_k=1,
)

print(summary.inflection_indices)
print(summary.mass_series)
print(summary.curvature_series)

This does not claim semantic cause or universal change-point discovery. It provides deterministic temporal geometry over scored panels.

See docs/examples/decision-manifold.md and docs/research/temporal-spatial-calculus.md.

PHOS and edge usage

from zeromodel import TopLeftGate, guarded_pack_artifact, write_png

packed = guarded_pack_artifact(artifact)
write_png(packed.packed, "artifact_phos.png")

result = TopLeftGate(threshold=0.75).evaluate(packed.packed)
print(result.accepted, result.score)

Learning trace usage

Tracking means a score moved. Learning means a feedback-driven change improves corrected work, transfers to held-out work, and avoids unacceptable regression.

from zeromodel import LearningObservation, build_learning_vpm

assessment = build_learning_vpm([
    LearningObservation("claim-support", before=0.42, after=0.72, split="train"),
    LearningObservation("related-claim", before=0.50, after=0.63, split="heldout"),
    LearningObservation("summary-quality", before=0.82, after=0.81, split="regression"),
])

print(assessment.learned)
learning_artifact = assessment.artifact

See docs/examples/learning-trace-vpm.md.

Training progress usage

Training telemetry can become a checkpoint-level VPM that shows train improvement, held-out transfer, regression safety, stability, efficiency, and best-checkpoint evidence.

from zeromodel import TrainingCheckpoint, build_training_progress_vpm

progress = build_training_progress_vpm(
    [
        TrainingCheckpoint(step=1000, metrics={
            "train_loss": 1.00,
            "heldout_score": 0.50,
            "regression_safety": 0.99,
        }),
        TrainingCheckpoint(step=2000, metrics={
            "train_loss": 0.82,
            "heldout_score": 0.57,
            "regression_safety": 0.98,
        }),
    ]
)

print(progress.best_checkpoint_id, progress.learned, progress.warnings)
training_artifact = progress.artifact

See docs/examples/training-progress-vpm.md.

Tracker adapter usage

Adapters parse exported tracker files into TrainingCheckpoint objects without requiring TensorBoard, W&B, or Trackio SDKs at runtime.

from zeromodel import build_training_progress_vpm
from zeromodel.adapters import checkpoints_from_tensorboard_scalars

checkpoints = checkpoints_from_tensorboard_scalars("runs/scalars.csv")
progress = build_training_progress_vpm(checkpoints)
print(progress.best_checkpoint_id, progress.learned, progress.warnings)

Supported inputs are JSON, JSONL/NDJSON, and CSV exports. TensorBoard scalar CSV rows shaped like wall_time,step,tag,value are grouped into one checkpoint per step.

See docs/examples/training-tracker-adapters.md.

Critic evidence usage

Critic, verifier, RAG, or policy outputs can become risk-first VPMs for inspection. The module is shaped around Writer-style critic results: score, label, verdict, explanation, and numeric feature scores.

from zeromodel import CriticObservation, build_critic_vpm

assessment = build_critic_vpm([
    CriticObservation(
        item_id="claim_supported",
        critic_score=0.91,
        policy_fit=0.95,
        evidence_support=0.92,
        citation_match=0.94,
        semantic_drift=0.04,
    ),
    CriticObservation(
        item_id="claim_hallucinated",
        critic_score=0.25,
        policy_fit=0.38,
        evidence_support=0.18,
        citation_match=0.20,
        semantic_drift=0.82,
        hallucination_energy=0.86,
        verifiability=0.25,
    ),
])

print(assessment.highest_risk_item_id, assessment.warnings)
critic_artifact = assessment.artifact

See docs/examples/critic-evidence-vpm.md and docs/research/hallucination-energy-to-zeromodel.md.

Research readiness examples

The repository includes committed training fixtures and end-to-end scripts so the full path can be reproduced before making broader research claims.

python examples/end_to_end_training_progress.py
python examples/end_to_end_learning_trace.py
python examples/research_hallucination_energy_vpm.py
python examples/research_multiview_dense_artifact.py
python examples/research_spatial_optimizer.py
python examples/research_decision_manifold.py

The training example reads tests/fixtures/training/tensorboard_scalars.csv, builds a training progress VPM, renders PNG/SVG, writes a .vpm bundle, and emits a JSON summary under .zeromodel-demo/.

See docs/examples/research-readiness.md.

Bundle usage

from zeromodel import from_bundle, to_bundle

to_bundle(artifact, "artifact.vpm")
loaded = from_bundle("artifact.vpm")
assert loaded.artifact_id == artifact.artifact_id

Design rule

The artifact remains a representation. Routing, gates, visual logic, hierarchy, rendering, PHOS packing, view profiles, spatial optimization, decision manifolds, learning traces, training progress, tracker adapters, critic evidence maps, and controllers are consumers around the artifact. This keeps the core auditable while allowing the full ZeroModel system to grow.