Scientific contracts and identities

Role: Model author. Prerequisites: Know your model’s input/output meanings, units, constraints and numerical tolerances. Work in the project created by enumeray model init; preparing and testing the contract needs no API account.

Edit one publication file

publication.json is the complete author-maintained declaration. It contains model metadata, scientific identities, schemas and examples, together with the selected context and installed release. Edit this file directly throughout development. The complete process example is:

{
  "publication_version": 1,
  "model": {
    "description": "Editable protocol demonstration; replace with your scientific model.",
    "id": "example",
    "name": "example"
  },
  "identities": {
    "model": "example@v1",
    "wrapper": "example-wrapper@v1",
    "runtime": "author-example:python3-standard-library:1"
  },
  "execution": {
    "context_id": "lab-cpu",
    "release_path": "/opt/enumeray/models/example/r1",
    "entrypoint": [
      "wrapper.py",
      "execute"
    ]
  },
  "input_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "value": {
        "type": "number"
      }
    },
    "required": [
      "value"
    ],
    "type": "object"
  },
  "output_schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "doubled": {
        "type": "number"
      }
    },
    "required": [
      "doubled"
    ],
    "type": "object"
  },
  "examples": [
    {
      "inputs": {
        "value": 2
      },
      "name": "starter-example",
      "outputs": {
        "doubled": 4
      }
    }
  ]
}

Scaffolding initially omits execution.context_id and execution.release_path, so you can test the science before selecting compute. Fill them after agreeing on installation with the connector owner. The Slurm example additionally declares execution.slurm_script. Connection hosts, SSH keys, launchers and shared compute stays in the connector owner’s context configuration.

Field	Need and default
publication_version	Required 1; identifies the editable file format
model.id	Required stable catalogue ID; must match CLI model arguments and wrapper requests
model.name, model.description	Catalogue metadata; omitted values become the ID and an empty description
identities.model	Required identity of the scientific implementation/version
identities.wrapper	Required identity of the mapping/wrapper code
identities.runtime	Required identity of the intended runtime and dependencies
identities.datasets	Identities of installed datasets; defaults to []
execution.entrypoint	Required fixed argv; the executable is relative to the immutable release
execution.context_id, execution.release_path	Selected compute context and absolute installed release; required before freezing a release
execution.environment	Optional bounded string settings; defaults to {}; never credentials
execution.slurm_script	Release-relative batch script for Slurm; omitted for process
input_schema, output_schema	Required scientific input/output schemas
examples	Named valid inputs and optional expected outputs; defaults to []
log_files	Optional named diagnostic files; defaults to {}
contract_version, wrapper_protocol_version	Scientific-contract profile and wrapper envelope protocol; both default to 1

Keep meaningful names, units and interpretation in schemas and examples. Defaults for file-format fields reduce boilerplate; schema default annotations still do not fill scientific input values. Implement scientific defaulting in the wrapper when intended.

Create catalogue metadata from the same file with enumeray model create example --file publication.json. This imports only ID/name/description; it does not install, register or activate a publication. It does not update an existing model’s catalogue metadata. The broader catalogue-update workflow remains separate.

Identity strings are author claims. Registration does not prove which interpreter, package or dataset is installed. Keep an environment lockfile/container digest and dataset checksums with the release when needed for reproducibility. Connector-observed entrypoint and batch-file digests remain separate evidence.

Describe values that users can understand

Give properties descriptions with units and meaning, and scientifically justified ranges. For example, a temperature property can be:

{
  "type": "number",
  "description": "Initial material temperature in kelvin.",
  "minimum": 0,
  "maximum": 2000
}

Schemas use the supported JSON Schema Draft 2020-12 profile. References must be document-local JSON Pointers to declared schema positions; remote schemas, nested schema IDs, anchors, dynamic references and custom vocabularies are unsupported. Each schema allows at most 128 schema nodes. Output schemas must describe a closed object with at most 64 named properties; unconditional required names must come from those properties. See limits for document, depth and numeric bounds.

Example names must be unique. Every example input must satisfy the input schema; supplied example outputs must satisfy the output schema. The doubling fixture is {"value":2} → {"doubled":4}. Contract validation checks examples against schemas; your executable tests establish numerical behavior, known answers, edge cases and tolerances.

Declare files and collections

The complete file publication corresponds to model init csv-example --directory csv-example --io files. Its dataset input and processed_dataset output use this complete schema for one named file slot:

{
  "type": "object",
  "properties": {"artifact_id": {"type": "string"}},
  "required": ["artifact_id"],
  "additionalProperties": false,
  "x-enumeray-file": {"media_types": ["text/csv"], "max_bytes": 1048576}
}

Place it directly at input_schema.properties.dataset or output_schema.properties.processed_dataset. Add required slots to the containing schema’s required array. x-enumeray-file requires explicit allowed media types and a positive byte bound; wildcards are rejected. File-containing schemas cannot contain schema references. Public values contain completed artifact UUIDs; fixture UUIDs only label local staging. See wrapper file staging.

The complete collection publication and collection wrapper show variable membership. A named collection slot contains a closed {collection_id} reference and an x-enumeray-collection annotation with media_types, max_members, max_file_bytes and max_total_bytes. Empty collections are valid; every listed member is required. Standalone files and collection members share the 10,000-member limit per run direction. See collection inputs and outputs.

Scientific byte bounds can exceed the service’s supported transfer profile; check service limits. Files and collections require wrapper protocol 1.

Validate and freeze deliberately

python3 -m unittest discover -s . -p 'test_starter.py'
enumeray model validate --file publication.json

Local tests work with the scaffold before compute is selected. model validate also runs offline, but requires both execution.context_id and execution.release_path; an incomplete draft receives an actionable error. Fill both fields before validation and follow installation and publication. Validation never assigns a candidate ID or changes the editable file.

model release init example --file publication.json --directory release-r1 freezes a complete source snapshot and assigns a durable candidate ID. Resume that saved operation after interruption. Editing the source later requires an explicit initialization into a new release directory; it never changes an existing candidate.

Keep scientific changes traceable

A changed contract or identity needs a new publication. Schema/example-only edits may reuse installed content if the wrapper supports the revised contract. Changes to model, wrapper, runtime or datasets need a new immutable release and matching identities. Do not edit installed files already referenced by publications or accepted work.

Registration derives installation claims from scientific identities and resolves compute authority from the account. Grant UUIDs, provider binding keys, duplicate installation claims, old split declarations and machine request envelopes are rejected as author input. Updates and rollback preserve previous releases and guarded activation.

Use top-level log_files for up to eight optional workspace-relative diagnostic files, independently of scientific outputs. See model-declared log files for confinement and retention.