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 bucket 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 cares only about 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: the human-readable handle that survives across hundreds of training runs.

julia> model_id, _ = create_model(project_id, "fraud-classifier");

julia> get_model(model_id)DearDiary.Model
 ├ id = "639a08a8-b269-4e35-97b7-119089ebd505"
 ├ project_id = "b3228828-e9c5-4ecf-a597-990da82708bc"
 ├ name = "fraud-classifier"
 ├ description = ""
 ├ created_date = 2026-07-19T05:20:31.622
 └ updated_date = nothing

Register a version

A ModelVersion ties a Resource to the Iteration that produced it. The per-model version number is assigned by the server (gap-free, monotonic, unique 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 = "54c61621-a095-4fac-9ac6-9dfbdbec971e"
 ├ model_id = "639a08a8-b269-4e35-97b7-119089ebd505"
 ├ version = 1
 ├ iteration_id = "2cfce950-b539-4126-86ab-692f849a305d"
 ├ resource_id = "854c49b5-ca22-4509-9eb2-295097a79cc3"
 ├ stage_id = 1
 ├ description = "Decision tree, max_depth=7"
 ├ created_date = 2026-07-19T05:20:31.844
 └ updated_date = nothing

A freshly registered version starts in DearDiary.NO_STAGE. Promote it through the lifecycle as the model proves itself in evaluation:

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 incumbent is auto-archived in the same transaction:

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 = "52c9af3b-6a0d-43dc-bc91-18b5d0699846"
 ├ experiment_id = "2f9f8551-4615-43ae-b1ee-beeeeafa0dce"
 ├ notes = ""
 ├ created_date = 2026-07-19T05:20:32.258
 ├ 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 = "12a46bf9-6102-4f5a-b032-89e0f8bbdf9a"
 ├ iteration_id = "52c9af3b-6a0d-43dc-bc91-18b5d0699846"
 ├ key = "max_depth"
 └ value = "9"