LLMDB.Runtime (LLM DB v2026.3.0)

Runtime configuration compilation for consumer applications.

Phase 2 of LLMDB: Compile runtime configuration by merging application environment config with per-call options, enabling consumers to:

Filter models by provider/model patterns (allow/deny)
Define provider preferences
Add custom providers/models

This module handles the consumer-facing runtime configuration that gets applied when loading the packaged snapshot into the Store.

Example

# Compile runtime config from app env + per-call opts
runtime = LLMDB.Runtime.compile(
  allow: [:openai, :anthropic],
  custom: %{
    providers: [%{id: :myprov, name: "My Provider"}],
    models: [%{provider: :myprov, id: "my-model", capabilities: %{chat: true}}]
  }
)

# Runtime config can then be used to filter and customize the catalog

Summary

Functions

apply(snapshot, overrides)

Applies runtime overrides to an existing snapshot.

compile(opts \\ [])

Compiles runtime configuration by merging app env and per-call options.

Functions

apply(snapshot, overrides)

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

Applies runtime overrides to an existing snapshot.

Parameters

snapshot - The current snapshot map
overrides - Map with optional :filter and :prefer keys

Override Options

:filter - %{allow: patterns, deny: patterns} to recompile and reapply
:prefer - List of provider atoms to update preference order

Returns

{:ok, updated_snapshot} - Success with updated snapshot
{:error, reason} - Validation or processing error

compile(opts \\ [])

@spec compile(keyword()) :: map()

Compiles runtime configuration by merging app env and per-call options.

Merges application environment configuration (from config :llm_db, ...) with options passed at load time, normalizes the configuration, and compiles filters.

Parameters

opts - Keyword list of per-call options that override app env:
- :allow - :all, list of providers [:openai], or map %{openai: :all | [patterns]}
- :deny - List of providers [:provider] or map %{provider: [patterns]}
- :prefer - List of provider atoms in preference order
- :custom - Map with provider IDs as keys, provider configs (with models) as values
- :provider_ids - Optional list of known provider IDs for validation

Returns

Map with compiled runtime configuration:

:filters - Compiled allow/deny patterns
:prefer - Provider preference list
:custom - Normalized custom providers/models (%{providers: [...], models: [...]})
:unknown - List of unknown providers in filters (for warnings)

Examples

# Simple provider allow list
runtime = Runtime.compile(allow: [:openai, :anthropic])
runtime.filters.allow
#=> %{openai: :all, anthropic: :all}

# Provider allow list with model patterns
runtime = Runtime.compile(
  allow: %{openai: ["gpt-4*"], anthropic: :all},
  deny: %{openai: ["gpt-4-0613"]}
)

# With custom providers
runtime = Runtime.compile(
  custom: %{
    vllm: [
      name: "Local vLLM Provider",
      models: %{
        "llama-3" => %{capabilities: %{chat: true}}
      }
    ]
  }
)