Machine Learning / Evidence and operational responsibility / Lesson 17

Deployment contracts and reproducibility

Package the complete learned procedure with a validated inference schema, provenance, and a reviewable rollback boundary.

About 4 min readContent reviewed 2026-10-26

On this page

Lesson goals

A deployable model is more than coefficients
Apply a frozen linear pipeline with explicit checks
Reproduce procedures and verify release behavior

A deployable model is more than coefficients

An inference artifact includes the learned preprocessing, estimator, class or target convention, calibration and decision policy where used, feature schema, and compatible runtime information. A coefficient vector without its feature order or units is ambiguous. Keep training data identity, split manifest, code version, dependencies, and selection record with the artifact. These records support audit and reproduction but do not prove the data was lawful, representative, or correctly labeled. A model version should identify an immutable reviewed package rather than a filename repeatedly overwritten with different contents. Plan how the application selects a version and how it can return to a known-good one.

Validate the boundary before calculating predictions

Check required fields, order or explicit name mapping, types, units, finite values, categories, missingness, and batch limits before matrix operations. NumPy broadcasting can produce a plausible but wrong-shaped result when dimensions accidentally align. Reject incompatible input or route it to a documented fallback; silently coercing every failure to zero can create convincing incorrect predictions. Keep validation and prediction deterministic under the stated artifact. A shared mathematical function is not a complete service: authentication, resource limits, transport errors, request identity, and authorization belong to the surrounding application and remain outside these offline examples.

Apply a frozen linear pipeline with explicit checks

The first example records feature names, a mean, a scale, coefficients, and an intercept. It validates the supplied feature order and array structure, then applies the same fixed transformation to each row. A deliberately reversed name list is rejected before prediction. The numbers are synthetic and no training quality is claimed. Test one record alone and in a batch, boundary values, unknown categories if present, and the exact output convention. If the product needs an abstain or review response, expose it deliberately instead of returning a numeric value that downstream code mistakes for a confident decision.

python Fixed synthetic offline example

import numpy as np
feature_names = ["bookings", "days"]
mean = np.array([1.0, 2.0])
scale = np.array([2.0, 1.0])
coef = np.array([1.0, 2.0])
def predict(values, names):
    if list(names) != feature_names:
        raise ValueError("Feature order mismatch")
    X = np.asarray(values, dtype=float)
    if X.ndim != 2 or X.shape[1] != 2 or not np.isfinite(X).all():
        raise ValueError("Invalid feature matrix")
    return 0.5 + ((X - mean) / scale) @ coef
print(predict([[3.0, 5.0], [4.0, 6.0]], feature_names).tolist())
try:
    predict([[3.0, 5.0]], ["days", "bookings"])
except ValueError as error:
    print(error)

Expected output

[7.5, 10.0]
Feature order mismatch

The frozen arithmetic yields two deterministic fixture predictions. Wrong semantic column order is rejected even though its shape would fit.

Persist artifacts under a trust policy

The second example serializes a small JSON manifest deterministically and computes a content digest. This can identify a changed artifact, but an unauthenticated digest does not prove who created it or whether it is trustworthy. Loading pickle-like formats can execute code, so never load an untrusted model file merely because it has a familiar extension. JSON avoids that object-execution mechanism but still needs schema, size, and semantic validation. Library model persistence also has version-compatibility constraints; record and test the supported environment instead of assuming arbitrary future runtimes can load an old artifact safely and identically.

python Fixed synthetic offline example

import hashlib
import json
manifest = {"model_version": "synthetic-linear-v1", "feature_names": ["bookings", "days"], "training_data_id": "lab-v1", "numpy_version": "1.26.4"}
text = json.dumps(manifest, sort_keys=True, separators=(",", ":"))
digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
loaded = json.loads(text)
print(loaded["feature_names"])
print(len(digest), hashlib.sha256(text.encode("utf-8")).hexdigest() == digest)

Expected output

['bookings', 'days']
64 True

The manifest round-trips locally and the same serialized bytes yield the same digest. No file is loaded from an untrusted source.

Reproduce procedures and verify release behavior

A random seed controls one source of variation under a particular implementation; it does not fully specify data ordering, parallel reductions, numerical libraries, hardware, or all training behavior. Pin the environment and record the complete procedure, using tolerances where appropriate rather than promising bitwise identity everywhere. Before release, compare an approved offline fixture through both training-side and inference-side code, then test fallback, latency, rollback, and monitoring contracts in an isolated environment. This course deploys no service or external model. The proof is limited to small local calculations and explicit contracts, not production reliability or future predictive accuracy.

Common errors and fixes

The service runs but predictions differ from offline results

Why it happens: Schema, units, preprocessing, or runtime differ.
How to fix it: Compare the full frozen procedure on the same fixture.
Prevent it next time: Version all transforms and semantic inputs together.

A downloaded model file is loaded as harmless data

Why it happens: An execution-capable persistence format was trusted blindly.
How to fix it: Use a reviewed artifact trust and format policy.
Prevent it next time: Validate provenance and compatibility before loading.

A seed is presented as complete reproducibility

Why it happens: Other data and execution sources of variation were omitted.
How to fix it: Record the environment and entire procedure.
Prevent it next time: Define appropriate numerical comparison tolerances.

Check your understanding

1. Why can a two-column matrix still be invalid for a two-feature model?

Show worked solution

Columns can be reversed, use different units, or represent another category mapping while preserving dimensions. Validate semantic names and preprocessing as well as shape and finite values. A successful matrix multiplication establishes arithmetic compatibility, not that the model received the intended information.

2. What does a content hash fail to establish about an artifact?