ReqLLM.Metadata (ReqLLM v1.0.0-rc.5)

View Source

Unified metadata and configuration schema definitions.

This module consolidates all provider configuration and model metadata schemas into a single source of truth, providing validation for:

  • Provider connection configuration (API endpoints, authentication, timeouts)
  • Model capabilities (reasoning, tool calling, temperature support, etc.)
  • Model limits (context window, output tokens, rate limits)
  • Model costs (pricing per million tokens)

Usage

# Validate provider connection config
{:ok, config} = ReqLLM.Metadata.validate(:connection, %{
  id: :openai,
  base_url: "https://api.openai.com/v1",
  api_key: "sk-..."
})

# Validate model capabilities
{:ok, caps} = ReqLLM.Metadata.validate(:capabilities, %{
  id: "gpt-4",
  reasoning: false,
  tool_call: true
})

# Get schema information
schema = ReqLLM.Metadata.schema(:capabilities)
keys = ReqLLM.Metadata.keys(:capabilities)

Summary

Functions

Builds capabilities map from metadata.

Converts modality string values to atoms.

Gets the default model for a provider spec.

Extracts authentication options from provider configuration.

Extracts HTTP client options from provider configuration.

Returns all option keys for a schema type.

Converts string keys in metadata maps to atoms for safe keys only.

Merges model metadata with defaults for missing fields.

Parses a provider string to a valid provider atom.

Returns the schema for a metadata type.

Validates metadata using the appropriate schema.

Functions

build_capabilities_from_metadata(metadata)

@spec build_capabilities_from_metadata(map()) :: map()

Builds capabilities map from metadata.

Examples

metadata = %{"reasoning" => true, "tool_call" => false}
ReqLLM.Metadata.build_capabilities_from_metadata(metadata)
#=> %{reasoning: true, tool_call: false, temperature: false, attachment: false}

convert_modality_values(modalities)

@spec convert_modality_values(map() | nil) :: map() | nil

Converts modality string values to atoms.

Examples

modalities = %{input: ["text", "image"], output: ["text"]}
ReqLLM.Metadata.convert_modality_values(modalities)
#=> %{input: [:text, :image], output: [:text]}

default_model(spec)

@spec default_model(map()) :: binary() | nil

Gets the default model for a provider spec.

Falls back to the first available model if no default is specified.

Parameters

  • spec - Provider spec struct with :default_model and :models fields

Returns

The default model string, or nil if no models are available.

Examples

spec = %{default_model: "gpt-4", models: %{"gpt-3.5" => %{}, "gpt-4" => %{}}}
ReqLLM.Metadata.default_model(spec)
#=> "gpt-4"

spec = %{default_model: nil, models: %{"model-a" => %{}, "model-b" => %{}}}
ReqLLM.Metadata.default_model(spec)
#=> "model-a"

spec = %{default_model: nil, models: %{}}
ReqLLM.Metadata.default_model(spec)
#=> nil

extract_auth_options(config)

@spec extract_auth_options(map()) :: map()

Extracts authentication options from provider configuration.

Takes provider config and extracts options related to authentication.

Examples

config = %{api_key: "secret", organization_id: "org-123", project_id: "proj-456"}
ReqLLM.Metadata.extract_auth_options(config)
#=> %{api_key: "secret", organization_id: "org-123", project_id: "proj-456"}

extract_http_options(config)

@spec extract_http_options(map()) :: map()

Extracts HTTP client options from provider configuration.

Takes provider config and extracts options that should be passed to the HTTP client (Req).

Examples

config = %{timeout: 60_000, retry_attempts: 5, api_key: "secret"}
ReqLLM.Metadata.extract_http_options(config)
#=> %{timeout: 60_000, retry_attempts: 5}

keys(type)

@spec keys(:connection | :capabilities | :limits | :costs) :: [atom()]

Returns all option keys for a schema type.

Examples

keys = ReqLLM.Metadata.keys(:capabilities)
#=> [:id, :provider_model_id, :name, :modalities, ...]

map_string_keys_to_atoms(map)

@spec map_string_keys_to_atoms(map() | nil) :: map() | nil

Converts string keys in metadata maps to atoms for safe keys only.

This prevents atom leakage by only converting known safe keys to atoms.

Examples

data = %{"input" => [:text], "unknown_key" => "value"}
ReqLLM.Metadata.map_string_keys_to_atoms(data)
#=> %{input: [:text], "unknown_key" => "value"}

merge_with_defaults(existing, defaults)

@spec merge_with_defaults(map() | nil, map()) :: map()

Merges model metadata with defaults for missing fields.

Examples

ReqLLM.Metadata.merge_with_defaults(nil, %{context: 4096})
#=> %{context: 4096}

ReqLLM.Metadata.merge_with_defaults(%{output: 1024}, %{context: 4096, output: 2048})
#=> %{context: 4096, output: 1024}

parse_provider(str)

@spec parse_provider(String.t()) :: {:ok, atom()} | {:error, String.t()}

Parses a provider string to a valid provider atom.

Converts hyphenated provider names to underscored atoms and validates against the list of supported providers.

Parameters

  • str - Provider name string (e.g., "anthropic", "google-vertex")

Returns

{:ok, atom} if provider is valid, {:error, reason} otherwise.

Examples

ReqLLM.Metadata.parse_provider("anthropic")
#=> {:ok, :anthropic}

ReqLLM.Metadata.parse_provider("google-vertex")
#=> {:ok, :google_vertex}

ReqLLM.Metadata.parse_provider("unknown")
#=> {:error, "Unknown provider: unknown"}

schema(atom)

@spec schema(:connection | :capabilities | :limits | :costs) :: NimbleOptions.t()

Returns the schema for a metadata type.

Examples

schema = ReqLLM.Metadata.schema(:capabilities)
schema.schema[:id][:required]  #=> true

validate(atom, data)

@spec validate(:connection | :capabilities | :limits | :costs, map()) ::
  {:ok, map()} | {:error, NimbleOptions.ValidationError.t()}

Validates metadata using the appropriate schema.

Parameters

  • type - Schema type (:connection, :capabilities, :limits, :costs)
  • data - Data to validate

Returns

  • {:ok, validated_data} - Successfully validated data with defaults applied
  • {:error, NimbleOptions.ValidationError} - Validation error

Examples

{:ok, config} = ReqLLM.Metadata.validate(:connection, %{
  id: :openai,
  base_url: "https://api.openai.com/v1"
})

{:ok, caps} = ReqLLM.Metadata.validate(:capabilities, %{
  id: "gpt-4",
  reasoning: true
})