ReqLLM.Catalog (ReqLLM v1.0.0)

View Source

Runtime catalog system that applies configuration to the compile-time base catalog.

The Catalog layer sits between raw model metadata sources (priv/models_dev/*.json) and the Provider Registry. It is responsible for:

  • Loading metadata from base sources (models.dev snapshots)
  • Merging custom provider/model definitions from config
  • Applying model-level allowlist filtering
  • Applying metadata overrides
  • Producing the "effective catalog" used by the rest of the system

Summary

Functions

allowed_patterns()

Returns the allowed patterns map from catalog config.

allowed_spec?(provider, model_id)

Checks if a specific model is allowed based on catalog patterns.

load()

Load the effective catalog from Application config.

load(config)

Load the effective catalog by applying allowlist, custom providers, and overrides to the compile-time base catalog.

resolve_allowed_specs()

Resolves all allowed model specs from the catalog and registry.

Functions

allowed_patterns()

@spec allowed_patterns() :: %{required(atom()) => :all | [String.t()]}

Returns the allowed patterns map from catalog config.

Reads directly from Application config :catalog :allow key. Patterns can be:

  • :all - All models for the provider
  • List of model IDs or glob patterns with *

Examples

allowed_patterns()
# => %{anthropic: :all, openai: ["gpt-4o-mini", "gpt-*"]}

allowed_spec?(provider, model_id)

@spec allowed_spec?(atom(), String.t()) :: boolean()

Checks if a specific model is allowed based on catalog patterns.

Examples

allowed_spec?(:anthropic, "claude-3-5-sonnet")
# => true (if anthropic: :all in catalog)

allowed_spec?(:openai, "gpt-4o-mini")
# => true (if matches pattern)

load()

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

Load the effective catalog from Application config.

Reads configuration from Application.get_env(:req_llm, :catalog, []) and calls load/1.

When :catalog_enabled? is false, bypasses filtering and returns all models.

Returns {:ok, catalog} or {:error, reason}.

load(config)

@spec load(keyword()) :: {:ok, map()} | {:error, term()}

Load the effective catalog by applying allowlist, custom providers, and overrides to the compile-time base catalog.

Returns a map: %{provider_id => %{"id" => ..., "models" => %{model_id => ...}}}

Returns {:error, reason} if:

  • Config validation fails
  • Allow is empty in non-test environment
  • Base catalog loading fails

Processing Order

  1. Validate config with NimbleOptions schema
  2. Load base catalog from ReqLLM.Catalog.Base.base() (compile-time, zero I/O)
  3. Merge config.custom (custom providers/models replace by ID)
  4. Filter by config.allow (drop all non-allowed models)
  5. Apply config.overrides.providers (deep merge, excluding "models" key)
  6. Apply config.overrides.models (deep merge per model)
  7. Return effective catalog

resolve_allowed_specs()

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

Resolves all allowed model specs from the catalog and registry.

Expands provider patterns to concrete "provider:model_id" specs.

Examples

resolve_allowed_specs()
# => ["anthropic:claude-3-5-sonnet", "openai:gpt-4o-mini", ...]