Data model

DearDiary organises tracking data as a four-level hierarchy. Understanding the hierarchy makes it easier to choose where to attach a given piece of information.

Entity hierarchy

Project
└── Experiment
    ├── Resource
    └── Iteration
        ├── Parameter
        └── Metric

A Project is the top-level container. Each project owns one or more Experiments, and each experiment owns one or more Iterations. Parameters and metrics are scoped to a single iteration; artifact resources attach to the parent experiment.

Tags attach at three levels: a Tag can be associated with a project, an experiment, or an iteration via the add_tag function.

Iterations

An Iteration represents one training run or evaluation job. It carries a lifecycle status (IterationStatus): RUNNING when the run is in progress, then one of SUCCEEDED, FAILED, or KILLED when it ends. On failure, the iteration row stores the captured exception text in error_message.

Iterations form parent/child trees through parent_iteration_id. A child iteration whose parent_iteration_id is set points at the parent run that spawned it. This models common multi-run patterns:

• hyperparameter optimisation trials under a driver sweep
• nested cross-validation folds
• distributed-worker fan-outs

get_child_iterations returns the direct children of a given iteration.

Metrics

A Metric is a named floating-point measurement. Repeated logs of the same key form a series indexed by step, so a training script can record a loss curve across epochs in a single iteration.

Resources

A Resource stores artifact bytes (model checkpoints, plots, data files) attached to an experiment. The backend that holds the bytes is recorded on the row itself (see Storage for details).

Deleting records

Deletes cascade downwards: removing a project removes its registry, experiments, iterations, artifacts, permissions, and tags; removing an experiment removes its iterations and artifacts; removing an iteration removes its parameters and metrics and detaches its children; removing a model removes its versions and keeps their artifacts. A record that a ModelVersion still points at (the iteration it was registered from, or the artifact it stores) cannot be deleted until that version is deleted, so the registry never references a missing run. The REST API answers such a delete with 409 CONFLICT; the service functions return false.

Tags outlive the records they were attached to. Deleting a tagged project, experiment, or iteration removes the association and leaves the tag in place, and a tag that is still attached to a record cannot be deleted.

Model registry

The model registry adds two more entity types, both project-scoped:

• Model: a named entry in the registry. The name is unique within the project: create_model and update_model return Duplicate for a name another model in the same project already uses. A model can be renamed at any time, including after versions have been registered.
• ModelVersion: one concrete checkpoint of a model. Each version has a monotonically increasing version number, points at the Iteration that produced it, and optionally links to a Resource holding the serialised bytes.

A freshly registered version starts at stage NO_STAGE. It can be promoted to STAGING, then PRODUCTION. Promoting a version to production automatically archives the previous incumbent. Superseded versions move to ARCHIVED.