LLMDB.Model (LLM DB v2026.2.5)

Model struct with Zoi schema validation.

Represents an LLM model with complete metadata including identity, provider, dates, limits, costs, pricing, modalities, capabilities, tags, lifecycle status, and aliases.

Lifecycle

Models have a lifecycle with three possible states: "active", "deprecated", and "retired".

The lifecycle is represented in two ways for flexibility and backward compatibility:

:deprecated and :retired - Boolean flags for quick checks
:lifecycle - Structured map with status, dates, and replacement info

These are automatically synchronized:

If lifecycle.status is set, the boolean flags are derived from it
If only boolean flags are set, lifecycle.status is derived from them

Lifecycle Fields

lifecycle.status - One of "active", "deprecated", "retired"
lifecycle.deprecated_at - ISO8601 date when deprecation occurred/will occur
lifecycle.retires_at - ISO8601 date when retirement is planned
lifecycle.replacement - Suggested replacement model ID

Temporal Lifecycle

Use effective_status/2, deprecated?/2, and retired?/2 to get status that respects deprecated_at and retires_at dates:

model = LLMDB.Model.new!(%{
  id: "old-model",
  provider: :openai,
  lifecycle: %{status: "active", deprecated_at: "2025-01-01", retires_at: "2025-06-01"}
})

LLMDB.Model.effective_status(model, ~U[2025-03-01 00:00:00Z])
# => "deprecated"

LLMDB.Model.retired?(model, ~U[2025-07-01 00:00:00Z])
# => true

Pricing Fields

Models have two pricing-related fields:

:cost - Legacy simple pricing (per-million-token rates for input/output/cache/reasoning)
:pricing - Flexible component-based pricing with support for tokens, tools, images, storage

The :cost field is automatically converted to :pricing.components at load time for backward compatibility. See LLMDB.Pricing and the Pricing and Billing guide.

Summary

Types

t()

Functions

deprecated?(model, now \\ DateTime.utc_now())

Returns true if the model is deprecated or retired (effective status).

effective_status(model, now \\ DateTime.utc_now())

Returns the effective lifecycle status, considering dates, declared status, and boolean flags.

lifecycle_status(arg1)

Returns the declared lifecycle status from the model's lifecycle field.

new(attrs)

Creates a new Model struct from a map, validating with Zoi schema.

new!(attrs)

Creates a new Model struct from a map, raising on validation errors.

retired?(model, now \\ DateTime.utc_now())

Returns true if the model is retired (effective status).

schema()

Returns the Zoi schema for Model

spec(model, format \\ nil)

Formats a model as a spec string in the given format.

Types

t()

@type t() :: %LLMDB.Model{
  aliases: [binary()],
  base_url: nil | binary(),
  capabilities:
    nil
    | %{
        :tools => %{
          optional(:enabled) => nil | boolean(),
          optional(:strict) => nil | boolean(),
          optional(:parallel) => nil | boolean(),
          optional(:streaming) => nil | boolean(),
          optional(:forced_choice) => nil | boolean()
        },
        :reasoning => %{
          optional(:enabled) => nil | boolean(),
          optional(:token_budget) => nil | integer()
        },
        :streaming => %{
          optional(:text) => nil | boolean(),
          optional(:tool_calls) => nil | boolean()
        },
        :chat => boolean(),
        :embeddings =>
          boolean()
          | %{
              optional(:min_dimensions) => nil | integer(),
              optional(:max_dimensions) => nil | integer(),
              optional(:default_dimensions) => nil | integer()
            },
        :json => %{
          optional(:native) => nil | boolean(),
          optional(:strict) => nil | boolean(),
          optional(:schema) => nil | boolean()
        },
        optional(:caching) => nil | %{optional(:type) => nil | binary()}
      },
  cost:
    nil
    | %{
        optional(:input) => nil | number(),
        optional(:output) => nil | number(),
        optional(:request) => nil | number(),
        optional(:image) => nil | number(),
        optional(:audio) => nil | number(),
        optional(:cache_read) => nil | number(),
        optional(:cache_write) => nil | number(),
        optional(:training) => nil | number(),
        optional(:reasoning) => nil | number(),
        optional(:input_audio) => nil | number(),
        optional(:output_audio) => nil | number(),
        optional(:input_video) => nil | number(),
        optional(:output_video) => nil | number()
      },
  deprecated: boolean(),
  extra: nil | map(),
  family: nil | binary(),
  id: binary(),
  knowledge: nil | binary(),
  last_updated: nil | binary(),
  lifecycle:
    nil
    | %{
        optional(:status) => nil | binary(),
        optional(:deprecated_at) => nil | binary(),
        optional(:retires_at) => nil | binary(),
        optional(:replacement) => nil | binary()
      },
  limits:
    nil
    | %{
        optional(:output) => nil | integer(),
        optional(:context) => nil | integer()
      },
  modalities:
    nil
    | %{optional(:input) => nil | [atom()], optional(:output) => nil | [atom()]},
  model: nil | binary(),
  name: nil | binary(),
  pricing:
    nil
    | %{
        :merge => binary(),
        optional(:currency) => nil | binary(),
        components: [
          %{
            :id => binary(),
            optional(:unit) => nil | binary(),
            optional(:kind) => nil | binary(),
            optional(:per) => nil | integer(),
            optional(:rate) => nil | number(),
            optional(:meter) => nil | binary(),
            optional(:tool) => nil | atom() | binary(),
            optional(:size_class) => nil | binary(),
            optional(:notes) => nil | binary()
          }
        ]
      },
  provider: atom(),
  provider_model_id: nil | binary(),
  release_date: nil | binary(),
  retired: boolean(),
  tags: nil | [binary()]
}

Functions

deprecated?(model, now \\ DateTime.utc_now())

@spec deprecated?(t(), DateTime.t()) :: boolean()

Returns true if the model is deprecated or retired (effective status).

Considers declared status, date-based lifecycle transitions, and boolean flags.

Examples

iex> model = %LLMDB.Model{id: "gpt-4", provider: :openai, deprecated: true}
iex> LLMDB.Model.deprecated?(model)
true

effective_status(model, now \\ DateTime.utc_now())

@spec effective_status(t(), DateTime.t()) :: String.t()

Returns the effective lifecycle status, considering dates, declared status, and boolean flags.

This function determines status using this precedence:

Declared lifecycle.status (if it indicates an advanced stage)
Date-based auto-advancement (deprecated_at, retires_at)
Boolean flags (retired, deprecated) as fallback
Default: "active"

Examples

iex> model = %LLMDB.Model{
...>   id: "gpt-4",
...>   provider: :openai,
...>   lifecycle: %{status: "active", deprecated_at: "2025-01-01T00:00:00Z"}
...> }
iex> LLMDB.Model.effective_status(model, ~U[2025-06-01 00:00:00Z])
"deprecated"

lifecycle_status(arg1)

@spec lifecycle_status(t()) :: String.t() | nil

Returns the declared lifecycle status from the model's lifecycle field.

Examples

iex> model = %LLMDB.Model{id: "gpt-4", provider: :openai, lifecycle: %{status: "deprecated"}}
iex> LLMDB.Model.lifecycle_status(model)
"deprecated"

iex> model = %LLMDB.Model{id: "gpt-4", provider: :openai}
iex> LLMDB.Model.lifecycle_status(model)
nil

new(attrs)

@spec new(map()) :: {:ok, t()} | {:error, term()}

Creates a new Model struct from a map, validating with Zoi schema.

Examples

iex> LLMDB.Model.new(%{id: "gpt-4", provider: :openai})
{:ok, %LLMDB.Model{id: "gpt-4", model: "gpt-4", provider: :openai}}

iex> LLMDB.Model.new(%{})
{:error, _validation_errors}

new!(attrs)

@spec new!(map()) :: t()

Creates a new Model struct from a map, raising on validation errors.

Examples

iex> LLMDB.Model.new!(%{id: "gpt-4", provider: :openai})
%LLMDB.Model{id: "gpt-4", model: "gpt-4", provider: :openai}

retired?(model, now \\ DateTime.utc_now())

@spec retired?(t(), DateTime.t()) :: boolean()

Returns true if the model is retired (effective status).

Considers declared status, date-based lifecycle transitions, and boolean flags.

Examples

iex> model = %LLMDB.Model{id: "gpt-4", provider: :openai, retired: true}
iex> LLMDB.Model.retired?(model)
true

schema()

Returns the Zoi schema for Model

spec(model, format \\ nil)

@spec spec(t(), atom() | nil) :: String.t()

Formats a model as a spec string in the given format.

Delegates to LLMDB.Spec.format_spec/2 with the model's provider and ID. If no format is specified, uses the application config :llm_db, :model_spec_format (default: :provider_colon_model).

Parameters

model - The model struct
format - Optional format override (:provider_colon_model, :model_at_provider, :filename_safe)

Examples

iex> model = %LLMDB.Model{provider: :openai, id: "gpt-4"}
iex> LLMDB.Model.spec(model)
"openai:gpt-4"

iex> LLMDB.Model.spec(model, :model_at_provider)
"gpt-4@openai"

iex> LLMDB.Model.spec(model, :filename_safe)
"gpt-4@openai"