Records and canonicalization¶

The SDK exposes immutable Pydantic models for the six OCLP core record kinds:

Kind	SDK model	Role
`computation`	`Computation`	A reusable computation interface, implementation basis, and optional exact Evidence evaluators required for success.
`execution`	`Execution`	One actual run of a Computation; each retry or rerun is a distinct Execution.
`artifact`	`Artifact`	Immutable content bytes, such as an input, output, log, or package.
`artifact_set`	`ArtifactSet`	A named, exact collection of Artifacts.
`evidence`	`Evidence`	An evaluator result about a record.
`event`	`Event`	An ordered observation about an Execution.

The API names are Python conveniences. Field semantics, required fields, and conformance requirements belong to the normative specification.

Every Core record may carry a concise name, an optional plain-text description, and structured application annotations. These are distinct: the description is universal human-facing explanation, while annotations carry application-defined JSON semantics. A supplied description participates in canonical record bytes, so changing it requires a fresh UUID record.

Core API¶

from oclp import (
    canonical_json_bytes,
    parse_record,
    record_digest,
    validate_derivation_graph,
    validate_execution_acceptance,
    validate_execution_hierarchy,
)

parse_record(value) validates a JSON-compatible value and returns the appropriate typed record.
canonical_json_bytes(record) emits the RFC 8785 canonical JSON bytes used for an OCLP record digest.
record_digest(record) returns the SHA-256 digest of those canonical bytes.
validate_derivation_graph(records) validates resolved input/output derivation bindings, declared Execution parameters (including their JSON Schema), and rejects cycles.
validate_execution_hierarchy(records) validates the separate parent-child Execution hierarchy and rejects orchestration cycles.
validate_execution_acceptance(records) rejects a claimed successful Execution when it lacks passing Evidence for every evaluator required by its Computation.

An Execution input or output may resolve to either an Artifact or an ArtifactSet. Use an ArtifactSet when a computation consumes or produces one named, immutable package (for example a model-serving release). The SDK treats that package as one derivation node; its named members remain an inventory overlay rather than fan-out input edges.

Opaque identity and integrity digests¶

Every Core record has one opaque UUID id, which identifies that exact immutable record. A RecordReference contains only that UUID. Stores may keep record_digest as an integrity check over canonical record JSON, but it is not part of the portable reference. An Artifact also has a separate digest for the payload bytes it describes.

An Artifact or ArtifactSet may include created_at when its producer can assert the time it created that exact immutable record/materialization. It is not a source-file mtime, object-store upload, or viewer observation time. Omit it when unknown; use Event.occurred_at for execution and publication chronology.

from oclp.models import RecordReference

reference = RecordReference(id=artifact.id)

Changing Artifact metadata creates a new Artifact record UUID. Its payload digest may remain unchanged when the described bytes are unchanged.

Profiles¶

Profiles add opt-in semantic layers without expanding the portable core. This SDK includes optional validation adapters for the OCLP-maintained dataset-snapshot, execution-context, and run profiles under oclp.profiles. Their definitions, schemas, and conformance vectors are owned by the separate OCLP Profiles package.

Profile bindings are carried by the core profiles field. A producer emits profiles: null when no profile applies. A consumer that needs profile-specific meaning explicitly validates the named profile in addition to the core record; parse_record intentionally validates only the portable Core envelope.