LLMDB.Query (LLM DB v2026.8.3)

Query functions for selecting models by capability, architecture, and size.

Provides capability and architecture filters with provider preferences and optional hardware-related sorting. All queries operate on the filtered catalog loaded into the Store.

Summary

Types

model_id()

model_spec()

provider()

Functions

candidates(opts \\ [])

Gets all allowed models matching capability requirements.

capabilities(spec)

Gets capabilities for a model spec.

select(opts \\ [])

Selects the first model matching capability requirements.

Types

model_id()

@type model_id() :: String.t()

model_spec()

@type model_spec() :: {provider(), model_id()} | String.t() | LLMDB.Model.t()

provider()

@type provider() :: atom()

Functions

candidates(opts \\ [])

@spec candidates(keyword()) :: [{provider(), model_id()}]

Gets all allowed models matching capability requirements.

Returns all models that match the capability filters. Provider preference controls the order unless :sort_by is set. Similar to select/1 but returns all matches instead of only the first.

Options

:require - Keyword list of required capabilities (e.g., [tools: true, json_native: true])
:forbid - Keyword list of forbidden capabilities
:prefer - List of provider atoms in preference order (e.g., [:openai, :anthropic])
:scope - Either :all (default) or a specific provider atom
:sort_by - :total_parameters, :active_parameters, :minimum_ram_gb, or :minimum_vram_gb from optional extra.llmfit metadata
:sort_order - :asc (default) or :desc; models without a numeric value are last
:architecture - One of :dense, :moe, or :unknown (default: :all). Models without usable llmfit architecture metadata are :unknown.

Returns

List of {provider, model_id} tuples matching the criteria.

Examples

candidates = Query.candidates(
  require: [chat: true, tools: true],
  prefer: [:openai, :anthropic]
)
#=> [{:openai, "gpt-4o"}, {:openai, "gpt-4o-mini"}, {:anthropic, "claude-3-5-sonnet-20241022"}, ...]

candidates = Query.candidates(
  require: [json_native: true],
  scope: :openai
)
#=> [{:openai, "gpt-4o"}, {:openai, "gpt-4o-mini"}, ...]

local_candidates = Query.candidates(
  sort_by: :minimum_ram_gb
)

moe_candidates = Query.candidates(architecture: :moe)

capabilities(spec)

@spec capabilities(model_spec()) :: map() | nil

Gets capabilities for a model spec.

Returns capabilities map or nil if model not found.

Parameters

spec - Either {provider, model_id} tuple, "provider:model" string, or %Model{} struct

Examples

caps = Query.capabilities({:openai, "gpt-4o-mini"})
#=> %{chat: true, tools: %{enabled: true, ...}, ...}

caps = Query.capabilities("openai:gpt-4o-mini")
#=> %{chat: true, tools: %{enabled: true, ...}, ...}

{:ok, model} = LLMDB.model("openai:gpt-4o-mini")
caps = Query.capabilities(model)
#=> %{chat: true, tools: %{enabled: true, ...}, ...}

select(opts \\ [])

@spec select(keyword()) :: {:ok, {provider(), model_id()}} | {:error, :no_match}

Selects the first model matching capability requirements.

Returns the first allowed model that matches the required capabilities. Provider preference controls the order unless :sort_by is set.

Options

:require - Keyword list of required capabilities (e.g., [tools: true, json_native: true])
:forbid - Keyword list of forbidden capabilities
:prefer - List of provider atoms in preference order (e.g., [:openai, :anthropic])
:scope - Either :all (default) or a specific provider atom
:sort_by - :total_parameters, :active_parameters, :minimum_ram_gb, or :minimum_vram_gb from optional extra.llmfit metadata
:sort_order - :asc (default) or :desc; models without a numeric value are last
:architecture - One of :dense, :moe, or :unknown (default: :all). Models without usable llmfit architecture metadata are :unknown.

Returns

{:ok, {provider, model_id}} - First matching model
{:error, :no_match} - No models match the criteria

Examples

{:ok, {provider, model_id}} = Query.select(
  require: [chat: true, tools: true],
  prefer: [:openai, :anthropic]
)

{:ok, {:openai, model_id}} = Query.select(
  require: [json_native: true],
  scope: :openai
)

{:ok, {provider, model_id}} = Query.select(
  sort_by: :total_parameters
)

{:ok, {provider, model_id}} = Query.select(architecture: :moe)