Types and internals

User <: ResultType

A struct that represents a user.

Fields

• id::String: The ID of the user.
• first_name::String: The first name of the user.
• last_name::String: The last name of the user.
• username::String: The username of the user.
• password::String: Bcrypt hash of the user's password.
• created_date::DateTime: The date and time the user was created.
• is_admin::Bool: Whether the user is an administrator.

UserResponse <: ResultType

A safe-for-API projection of User that omits the password hash.

Fields

• id::String: The ID of the user.
• first_name::String: The first name of the user.
• last_name::String: The last name of the user.
• username::String: The username of the user.
• created_date::DateTime: The date and time the user was created.
• is_admin::Bool: Whether the user is an administrator.

UserPermission <: ResultType

A struct representing a user's permissions for a specific project.

Fields

• id::String: The unique identifier for the user permission record.
• user_id::String: The ID of the user.
• project_id::String: The ID of the project.
• create_permission::Bool: Permission to create resources.
• read_permission::Bool: Permission to read resources.
• update_permission::Bool: Permission to update resources.
• delete_permission::Bool: Permission to delete resources.

Project <: ResultType

A struct representing a project with its details.

Fields

• id::String: The ID of the project.
• name::String: The name of the project.
• description::String: A brief description of the project.
• created_date::DateTime: The date and time the project was created.

Experiment <: ResultType

A struct representing an experiment within a project.

Fields

• id::String: The unique identifier of the experiment.
• project_id::String: The identifier of the project to which the experiment belongs.
• status_id::Int64: The status of the experiment.
• name::String: The name of the experiment.
• description::String: A description of the experiment.
• created_date::DateTime: The date and time when the experiment was created.
• end_date::Optional{DateTime}: The date and time when the experiment ended, or nothing if it is still ongoing.

Iteration <: ResultType

A struct representing an iteration within an experiment.

Fields

• id::String: The unique identifier of the iteration.
• experiment_id::String: The identifier of the experiment to which the iteration belongs.
• notes::String: Notes associated with the iteration.
• created_date::DateTime: The date and time when the iteration was created.
• end_date::Optional{DateTime}: The date and time when the iteration ended, or nothing if it is still ongoing.
• parent_iteration_id::Optional{String}: The identifier of the parent Iteration when this iteration is a child run (e.g. one trial in an HPO sweep, one fold in a nested CV, one worker in a distributed run). nothing for top-level iterations.
• status_id::Int64: The current lifecycle IterationStatus. RUNNING while the iteration is in flight, then SUCCEEDED, FAILED, or KILLED once it terminates.
• error_message::String: Captured exception text when status_id is FAILED. Empty otherwise.
• julia_version::String: string(VERSION) captured by snapshot_environment!. Empty when no snapshot has been taken.
• git_sha::String: HEAD commit SHA captured by snapshot_environment!. Empty when the iteration ran outside a git working tree or no snapshot was taken.
• git_dirty::Bool: true when the working tree had uncommitted changes at snapshot time.
• entrypoint::String: PROGRAM_FILE captured by snapshot_environment!. Empty for REPL-driven runs.
• project_toml::String: Verbatim contents of the active Project.toml at snapshot time.
• manifest_toml::String: Verbatim contents of the active Manifest.toml at snapshot time, the pinned dependency tree that restore reconstructs.

Parameter <: ResultType

A struct representing a parameter with its details.

Fields

• id::String: The ID of the parameter.
• iteration_id::String: The ID of the iteration this parameter belongs to.
• key::String: The key/name of the parameter.
• value::String: The value of the parameter.

Metric <: ResultType

A struct representing a metric value logged against an Iteration. Repeated logs of the same key form a series indexed by step and timestamped by recorded_at, so a training script can record a loss curve over many epochs.

Fields

• id::String: The ID of the metric.
• iteration_id::String: The ID of the iteration this metric belongs to.
• key::String: The key/name of the metric (e.g. "loss", "accuracy").
• value::Float64: The recorded value.
• step::Int64: Position in the time series for this (iteration_id, key). Defaults to max(step) + 1 server-side when not supplied by the caller.
• recorded_at::DateTime: When the value was captured. Defaults to the server clock when not supplied by the caller.

Resource <: ResultType

A struct representing a resource associated with an experiment.

Fields

• id::String: The ID of the resource.
• experiment_id::String: The ID of the experiment this resource belongs to.
• name::String: The name of the resource.
• description::String: A description of the resource.
• data::Optional{Array{UInt8,1}}: The binary data of the resource. Populated for the inline backend when the row is fetched by id. Empty for rows whose canonical bytes live in an external backend (filesystem, S3) and are fetched on demand through uri. nothing in list results, which never load the column.
• created_date::DateTime: The date and time when the resource was created.
• updated_date::Optional{DateTime}: The date and time when the resource was last updated.
• backend::String: Short backend identifier ("inline", "filesystem", "s3"). Drives dispatch on the AbstractArtifactStore trait.
• uri::String: Stable pointer at the canonical bytes ("file:///...", "s3://..."). Empty string when backend == "inline" (the bytes are inline in data).
• size_bytes::Int64: Exact byte count of the artifact. Surfaced in list endpoints without materialising the BLOB.
• content_hash::String: Lower-case sha256 hex digest of the bytes.

Tag <: ResultType

A struct that represents a tag.

Fields

• id::String: The ID of the tag.
• value::String: The value of the tag.

Model <: ResultType

A struct representing a registered model in the project-scoped model registry. A Model is the named container under which one or more ModelVersion checkpoints are recorded.

Fields

• id::String: The unique identifier of the model.
• project_id::String: The identifier of the Project that owns the model.
• name::String: The registry name of the model. Unique within its project, a rule enforced by create_model and update_model.
• description::String: A free-form description of the model.
• created_date::DateTime: The date and time when the model was registered.
• updated_date::Optional{DateTime}: The date and time of the most recent update, or nothing if the record has never been updated.

ModelVersion <: ResultType

A struct representing a concrete checkpoint of a registered Model. Each version is produced by a specific Iteration and may point at an artifact Resource that stores the serialised bytes.

Fields

• id::String: The unique identifier of the model version.
• model_id::String: The identifier of the parent Model.
• version::Int64: The per-model monotonically-increasing version number, assigned by the service layer at registration time.
• iteration_id::String: The identifier of the Iteration that produced this checkpoint, recording lineage from training run to registered artifact.
• resource_id::Optional{String}: The identifier of the Resource that holds the serialised artifact, or nothing when the registration predates the upload.
• stage_id::Int64: The lifecycle Stage the version currently occupies.
• description::String: A free-form description of the version (e.g. training notes).
• created_date::DateTime: The date and time when the version was registered.
• updated_date::Optional{DateTime}: The date and time of the most recent update, or nothing if the record has never been updated.

Client

Handle for talking to a running DearDiary REST API. Constructed via connect. The token, expiry, and cached user are mutable so refresh_token! and reauthentication do not require rebuilding the client.

Fields

• base_url::String: Base URL of the server (e.g. "http://127.0.0.1:9000"), without trailing slash.
• token::Optional{String}: Bearer token, or nothing when the server runs with auth disabled.
• expires_at::Optional{Int}: Unix epoch seconds at which the token expires.
• user::Optional{UserResponse}: The signed-in user, if known.

ClientError <: Exception

Raised by Client methods when the server returns a non-2xx status.

Fields

• status::Int: The HTTP status code.
• code::String: The stable error code from the response body ("NOT_FOUND", "CONFLICT", …), or "UNKNOWN" when the body is unparseable.
• message::String: Human-readable description from the response body.

initialize_database(; file_name::String="deardiary.db")

Open file_name (creating it if needed), run every pending Migration via apply_migrations, and re-seed the default user. A database that is already open is closed first, so two instances never hold the same file. Calling this repeatedly is safe: each migration runs at most once per database, and the default-user insert uses ON CONFLICT DO NOTHING.

get_database()::Union{DuckDB.DB,Nothing}

Return the active DuckDB connection, or nothing if the database has not been initialized.

close_database()

Close the database if one is open. Garbage is collected before and after the close so DuckDB finalizers release the instance and its write-ahead log is checkpointed before this function returns.

@enum ExperimentStatus IN_PROGRESS = 1 STOPPED = 2 FINISHED = 3

An enumeration representing the lifecycle status of an Experiment.

IN_PROGRESS::ExperimentStatus

An enumeration value representing an experiment that is currently in progress.

STOPPED::ExperimentStatus

An enumeration value representing an experiment that has been stopped.

FINISHED::ExperimentStatus

An enumeration value representing an experiment that has finished.

@enum IterationStatus RUNNING = 1 SUCCEEDED = 2 FAILED = 3 KILLED = 4

An enumeration representing the lifecycle status of an Iteration. A freshly created iteration is RUNNING; the value transitions to a terminal status (SUCCEEDED, FAILED, or KILLED) when the iteration ends.

RUNNING::IterationStatus

An enumeration value representing an Iteration that is still in progress. This is the value assigned when the iteration is created.

SUCCEEDED::IterationStatus

An enumeration value representing an Iteration that ran to completion without raising an exception.

FAILED::IterationStatus

An enumeration value representing an Iteration that ended because of an exception. The captured exception text is stored in error_message.

KILLED::IterationStatus

An enumeration value representing an Iteration that was terminated externally (operator action, timeout, scheduler kill) rather than by a clean return or an exception.

UpsertResult

A marker abstract type for the result of an upsert operation.

Created

A marker type indicating that a record was successfully created.

Updated <: UpsertResult

A marker type indicating that a record was successfully updated.

Duplicate <: UpsertResult

A marker type indicating that a record already exists.

Unprocessable <: UpsertResult

A marker type indicating that a record violates a constraint and cannot be processed.

Error <: UpsertResult

A marker type indicating that an error occurred while creating or updating a record.

PermissionAction

Abstract supertype representing a CRUD action that a UserPermission can grant on a Project. Concrete subtypes are dispatched on by has_permission to read the matching boolean field.

CreatePermission <: PermissionAction

Action that requires create_permission on the target Project.

ReadPermission <: PermissionAction

Action that requires read_permission on the target Project.

UpdatePermission <: PermissionAction

Action that requires update_permission on the target Project.

DeletePermission <: PermissionAction

Action that requires delete_permission on the target Project.

ErrorCode

Marker abstract type for error codes returned in non-2xx response bodies.

Concrete subtypes pair with error_code to produce a stable, frontend-facing identifier (e.g., "NOT_FOUND", "PROJECT_PERMISSION_REQUIRED") that callers can switch on without parsing English messages.

NotFound <: ErrorCode

The requested entity does not exist. Pairs with HTTP 404 Not Found.

InvalidCredentials <: ErrorCode

The supplied username/password did not authenticate. Pairs with HTTP 401 Unauthorized.

TokenMissing <: ErrorCode

The request did not include an Authorization header. Pairs with HTTP 401 Unauthorized.

TokenInvalid <: ErrorCode

The bearer token failed signature validation. Pairs with HTTP 401 Unauthorized.

TokenExpired <: ErrorCode

The bearer token's exp claim is in the past. Pairs with HTTP 401 Unauthorized.

TokenPayloadInvalid <: ErrorCode

The bearer token decoded but its claims are missing or malformed. Pairs with HTTP 401.

UserNotFound <: ErrorCode

The user identified by the credentials or token does not exist. Pairs with HTTP 401/404 depending on context.

AdminRequired <: ErrorCode

The route requires administrative privileges. Pairs with HTTP 403 Forbidden.

SameUserRequired <: ErrorCode

The route can only be accessed by the targeted user (or an admin). Pairs with HTTP 403.

ProjectPermissionRequired <: ErrorCode

The user lacks the required CRUD permission on the project that scopes the route. Pairs with HTTP 403 Forbidden.

Conflict <: ErrorCode

The request clashes with existing state: a unique constraint is violated, or a delete is refused because registered model versions still reference the target. Pairs with HTTP 409 Conflict.

InvalidPayload <: ErrorCode

The request payload violates a constraint (foreign key, check, missing field). Pairs with HTTP 422 Unprocessable Entity.

ServerError <: ErrorCode

Generic catch-all for unexpected failures. Pairs with HTTP 500 Internal Server Error.

error_code(::Type{<:ErrorCode})::String

Return the stable SCREAMING_SNAKE identifier for an ErrorCode type, as used in error response bodies ({"code": ..., "message": ...}). The mapping is fixed so frontend code can switch on the value without parsing English messages.

Pagination

Cursor for windowing a collection of records.

Fields

• limit::Int64: Maximum number of records to return (capped at the route boundary).
• offset::Int64: Number of records to skip before the page starts.

PaginatedResponse{T} <: ResultType

Envelope returned by paginated list endpoints.

Fields

• data::Array{T,1}: The records in this page.
• total::Int64: Total number of matching records (across all pages).
• limit::Int64: The page size used.
• offset::Int64: The offset used.