ReqLLM.Metadata (ReqLLM v1.0.0-rc.5)
View SourceUnified 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
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}
Converts modality string values to atoms.
Examples
modalities = %{input: ["text", "image"], output: ["text"]}
ReqLLM.Metadata.convert_modality_values(modalities)
#=> %{input: [:text, :image], output: [:text]}
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
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"}
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}
@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, ...]
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"}
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}
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"}
@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
@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
})