Register and stage models

DearDiary.Model and DearDiary.ModelVersion form a project-scoped registry on top of the run-tracking entities. A Model is the named entry that downstream serving code refers to (e.g. "fraud-classifier"); a ModelVersion is a concrete checkpoint with lineage back to the Iteration that produced it, an optional pointer at the artifact bytes in any configured storage backend, and a lifecycle DearDiary.Stage.

Versions transition through NO_STAGE → STAGING → PRODUCTION → ARCHIVED. Promoting a version to PRODUCTION automatically demotes whichever sibling was previously in PRODUCTION, preserving the "at most one production version per model" invariant.

Scaffold a project and an iteration

julia> project_id, _ = create_project("Fraud detection");
julia> experiment_id, _ = create_experiment(project_id, DearDiary.IN_PROGRESS, "DT sweep");
julia> iteration_id, _ = create_iteration(experiment_id);
julia> create_parameter(iteration_id, "max_depth", 7);
julia> create_metric(iteration_id, "accuracy", 0.96);

Save the trained model bytes as a Resource. Any serialisation format works; the registry stores only the byte payload and its lineage.

julia> checkpoint_bytes = rand(UInt8, 1024);
julia> resource_id, _ = create_resource(experiment_id, "fraud-clf.jlso", checkpoint_bytes);

Register the model

A Model is a named entry: a stable identifier that persists across successive training runs and model versions.

julia> model_id, _ = create_model(project_id, "fraud-classifier");
julia> get_model(model_id)Model("fraud-classifier")
  id            "111a03f7-673e-473f-b21e-bed0ac331b4b"
  project_id    "659c6137-a327-41b0-ad54-b16ecd4da068"
  name          "fraud-classifier"
  description   ""
  created_date  2026-10-30T16:40:55.225
  updated_date  nothing

Register a version

A ModelVersion ties a Resource to the Iteration that produced it. The per-model version number is assigned on insert as one greater than the model's current highest version, and a uniqueness constraint keeps it distinct within the model:

julia> version_a_id, _ = create_modelversion(
           model_id, iteration_id, resource_id,
           "Decision tree, max_depth=7",
       );
julia> version_a = get_modelversion(version_a_id)ModelVersion(1, NO_STAGE)
  id            "24f21f14-b49a-4d0b-9adb-3a4fad009dd8"
  model_id      "111a03f7-673e-473f-b21e-bed0ac331b4b"
  version       1
  iteration_id  "9da64825-a982-4273-ae35-b27f1f5e4c60"
  resource_id   "e73d3ee7-4d1d-4e8c-9446-0588c0120d2f"
  stage_id      1 (NO_STAGE)
  description   "Decision tree, max_depth=7"
  created_date  2026-10-30T16:40:55.382
  updated_date  nothing

A freshly registered version starts in DearDiary.NO_STAGE. Promote it through the lifecycle as evaluation results become available:

julia> update_modelversion(version_a_id, DearDiary.STAGING, nothing, nothing);
julia> update_modelversion(version_a_id, DearDiary.PRODUCTION, nothing, nothing);

Roll forward to a new checkpoint

Train another iteration, register a second version, and promote it to PRODUCTION. The previous production version is archived by the same update_modelversion call:

julia> iteration_b_id, _ = create_iteration(experiment_id);
julia> create_parameter(iteration_b_id, "max_depth", 9);
julia> create_metric(iteration_b_id, "accuracy", 0.974);
julia> resource_b_id, _ = create_resource(experiment_id, "fraud-clf-v2.jlso", rand(UInt8, 1024));
julia> version_b_id, _ = create_modelversion( model_id, iteration_b_id, resource_b_id, "Decision tree, max_depth=9", );
julia> update_modelversion(version_b_id, DearDiary.PRODUCTION, nothing, nothing);

The previous production version is now archived:

julia> get_modelversion(version_a_id).stage_id == (DearDiary.ARCHIVED |> Integer)true
julia> get_modelversion(version_b_id).stage_id == (DearDiary.PRODUCTION |> Integer)true

Browsing the registry

get_modelversions returns the per-model history ordered by version ascending, so finding the current production checkpoint is a single filter:

julia> versions = get_modelversions(model_id);
julia> production = filter(v -> v.stage_id == (DearDiary.PRODUCTION |> Integer), versions);
julia> production[1].version2

The full lineage is reachable from version.iteration_id and version.resource_id:

julia> producing_iteration = (version_b_id |> get_modelversion).iteration_id |> get_iterationIteration(f77c0f18…, RUNNING)
  id                   "f77c0f18-2adc-491a-acdd-9c751463bb64"
  experiment_id        "bab1ff5b-50ad-4e10-9596-4642cb16b0e6"
  notes                ""
  created_date         2026-10-30T16:40:55.712
  end_date             nothing
  parent_iteration_id  nothing
  status_id            1 (RUNNING)
  error_message        ""
  julia_version        ""
  git_sha              ""
  git_dirty            false
  entrypoint           ""
  project_toml         ""
  manifest_toml        ""
julia> get_parameters(producing_iteration.id)1-element Vector{DearDiary.Parameter}:
 Parameter(max_depth = "9")

The model page in the dashboard shows a model's version history, with each version's stage, source iteration, and artifact:

A model page with v2 in production and v1 archived, each linked to its source iteration and checkpoint file

Rename a model

The registry name can change after versions exist. update_model leaves a field alone when it is nothing and returns DearDiary.Duplicate when another model in the project already uses the new name:

julia> update_model(model_id, "fraud-classifier-dt", nothing)DearDiary.Updated
julia> get_model(model_id).name"fraud-classifier-dt"

Delete rules

An iteration or artifact that a version points at cannot be deleted while that version exists, so the registry never references a missing run:

julia> delete_iteration(iteration_b_id)false

Delete the version first, then the run. Deleting a model removes its versions and keeps their artifacts. See Deleting records.

julia> delete_modelversion(version_b_id);
julia> delete_iteration(iteration_b_id)true