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)DearDiary.Model
 ├ id = "52188659-23fc-482d-8b29-f506e517b638"
 ├ project_id = "8e784627-0e6c-48e3-bf05-abf18ab8a37e"
 ├ name = "fraud-classifier"
 ├ description = ""
 ├ created_date = 2026-08-25T20:37:38.526
 └ 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)DearDiary.ModelVersion
 ├ id = "8a95fa5f-4bf7-46b7-9c3c-7afce133db2e"
 ├ model_id = "52188659-23fc-482d-8b29-f506e517b638"
 ├ version = 1
 ├ iteration_id = "baa1d93c-5a9d-42f5-a5c6-e593198b3c6c"
 ├ resource_id = "b8b30a1c-0f08-442f-9466-505da83b5ea8"
 ├ stage_id = 1
 ├ description = "Decision tree, max_depth=7"
 ├ created_date = 2026-08-25T20:37:38.747
 └ 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_iterationDearDiary.Iteration
 ├ id = "0f15c235-1450-4027-a7f6-c41650155c46"
 ├ experiment_id = "f4e125a7-e921-4baa-b88f-8f8296ba7698"
 ├ notes = ""
 ├ created_date = 2026-08-25T20:37:39.142
 ├ end_date = nothing
 ├ parent_iteration_id = nothing
 ├ status_id = 1
 ├ 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}:
DearDiary.Parameter
 ├ id = "0689eea8-3027-4610-9b1c-27e70af763ff"
 ├ iteration_id = "0f15c235-1450-4027-a7f6-c41650155c46"
 ├ key = "max_depth"
 └ value = "9"