Types and internals

User <: ResultType

A struct that represents a user.

Fields

• id::Int64: 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::Int64: 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::Int64: The unique identifier for the user permission record.
• user_id::Int64: The ID of the user.
• project_id::Int64: 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::Int64: 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::Int64: The unique identifier of the experiment.
• project_id::Int64: 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::Int64: The unique identifier of the iteration.
• experiment_id::Int64: 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{Int64}: 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 bit-exact dependency tree that restore reconstructs.

Parameter <: ResultType

A struct representing a parameter with its details.

Fields

• id::Int64: The ID of the parameter.
• iteration_id::Int64: 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::Int64: The ID of the metric.
• iteration_id::Int64: 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::Int64: The ID of the resource.
• experiment_id::Int64: 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 (legacy inline storage); nothing for rows whose canonical bytes live in an external backend (filesystem, S3) and are fetched on demand via the trait.
• 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. Empty string for legacy rows not yet re-hashed by the backfill pass.

Tag <: ResultType

A struct that represents a tag.

Fields

• id::Int64: 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::Int64: The unique identifier of the model.
• project_id::Int64: The identifier of the Project that owns the model.
• name::String: The registry-unique name of the model (unique per project).
• 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::Int64: The unique identifier of the model version.
• model_id::Int64: 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::Int64: The identifier of the Iteration that produced this checkpoint, recording lineage from training run to registered artifact.
• resource_id::Optional{Int64}: 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. 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 connection if one is open.

@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

A unique-constraint violation: the resource already exists. 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.