ClaudeAgentSDK.Model (claude_agent_sdk v0.14.0)

Copy Markdown View Source

Config-driven model validation and normalization.

All known models are read at runtime from application config, so new models can be added without recompilation.

Configuration

Models are configured in config/config.exs (or any environment overlay):

config :claude_agent_sdk, :models, %{
  short_forms: %{
    "opus"       => "opus",
    "sonnet"     => "sonnet",
    "haiku"      => "haiku",
    "sonnet[1m]" => "sonnet[1m]"
  },
  full_ids: %{
    "claude-opus-4-6"                => "claude-opus-4-6",
    "claude-sonnet-4-5-20250929"     => "claude-sonnet-4-5-20250929",
    "claude-haiku-4-5-20251001"      => "claude-haiku-4-5-20251001",
    "claude-sonnet-4-5-20250929[1m]" => "claude-sonnet-4-5-20250929[1m]"
  },
  default: "haiku"
}

SDK consumers can add custom models at runtime:

config = Application.get_env(:claude_agent_sdk, :models)
updated = Map.update!(config, :full_ids, &Map.put(&1, "my-custom-model", "my-custom-model"))
Application.put_env(:claude_agent_sdk, :models, updated)

See the Model Configuration guide for details.

Examples

iex> ClaudeAgentSDK.Model.validate("opus")
{:ok, "opus"}

iex> ClaudeAgentSDK.Model.validate("invalid")
{:error, :invalid_model}

iex> "opus" in ClaudeAgentSDK.Model.list_models()
true

iex> ClaudeAgentSDK.Model.suggest("opuss")
["opus"]

Summary

Functions

default_model()

Returns the configured default model name.

full_ids()

Returns the list of configured full model identifiers.

known_models()

Returns the merged map of all known models (short forms + full IDs).

list_models()

Returns a sorted list of all known model names.

short_forms()

Returns the list of configured short-form aliases.

suggest(invalid_model)

Suggests similar model names for an invalid input.

validate(model)

Validates and normalizes a model name.

Functions

default_model()

@spec default_model() :: String.t()

Returns the configured default model name.

full_ids()

@spec full_ids() :: [String.t()]

Returns the list of configured full model identifiers.

known_models()

@spec known_models() :: %{required(String.t()) => String.t()}

Returns the merged map of all known models (short forms + full IDs).

list_models()

@spec list_models() :: [String.t()]

Returns a sorted list of all known model names.

The list includes both short forms and full model identifiers.

Examples

iex> models = ClaudeAgentSDK.Model.list_models()
iex> "opus" in models
true

iex> models = ClaudeAgentSDK.Model.list_models()
iex> models == Enum.sort(models)
true

short_forms()

@spec short_forms() :: [String.t()]

Returns the list of configured short-form aliases.

suggest(invalid_model)

@spec suggest(String.t()) :: [String.t()]

Suggests similar model names for an invalid input.

Uses Jaro distance algorithm to find models with similarity > 0.7. Returns up to 3 suggestions, sorted by similarity (highest first).

Examples

iex> ClaudeAgentSDK.Model.suggest("opuss")
["opus"]

iex> ClaudeAgentSDK.Model.suggest("completely-unrelated-xyz123")
[]

iex> suggestions = ClaudeAgentSDK.Model.suggest("claude")
iex> length(suggestions) <= 3
true

validate(model)

@spec validate(String.t() | nil) :: {:ok, String.t()} | {:error, :invalid_model}

Validates and normalizes a model name.

Accepts both short forms (e.g., "opus") and full model identifiers. Returns the normalized value on success.

Examples

iex> ClaudeAgentSDK.Model.validate("opus")
{:ok, "opus"}

iex> ClaudeAgentSDK.Model.validate("sonnet")
{:ok, "sonnet"}

iex> ClaudeAgentSDK.Model.validate("invalid-model")
{:error, :invalid_model}

iex> ClaudeAgentSDK.Model.validate(nil)
{:error, :invalid_model}

iex> ClaudeAgentSDK.Model.validate("")
{:error, :invalid_model}