@spec catalog_loaded?() :: boolean()

Return true when the optional LLMDB catalog module is loaded into the BEAM AND the test override (Application.put_env(:allm, :force_capability_absent, true)) is NOT set.

The override seam exists for the dep-free smoke test — see Phase 9.4 Non-obvious Decision #5. :code.delete/1 + :code.purge/1 does NOT work because test/support/llm_db.ex re-loads from _build on the next Code.ensure_loaded?/1; the application-env override is the reliable simulator.

Use the Module.concat(["LLMDB"]) idiom to keep the dep optional — the literal-string-list argument produces a single atom at runtime with no compile-time reference (the same pattern as ALLM.Engine.resolve_model/2 at lib/allm/engine.ex:301-304).

Examples

iex> is_boolean(ALLM.Capability.catalog_loaded?())
true

@spec populate_costs(ALLM.Usage.t(), model_ref_or_string()) :: ALLM.Usage.t()

Populate Usage.{input_cost, output_cost, total_cost} from model_ref.pricing (per-million-token rates).

Returns the input usage unchanged when the catalog is absent, when the model is a bare string/tuple/nil, or when model_ref.pricing == nil. Partial population is allowed: when :input_tokens is nil, :input_cost stays nil; :output_cost can still populate from :output_tokens. :total_cost is populated only when both partial costs are present. NEVER overwrites a non-nil cost field — only fills nil (Phase 9 design Invariant 8).

Examples

iex> ref = ALLM.ModelRef.new(provider: :openai, id: "x", pricing: %{input: 0.15, output: 0.6})
iex> usage = %ALLM.Usage{input_tokens: 1000, output_tokens: 500}
iex> populated = ALLM.Capability.populate_costs(usage, ref)
iex> populated.input_cost
1.5e-4
iex> populated.output_cost
3.0e-4
iex> populated.total_cost
4.5e-4

@spec preflight(model_ref_or_string(), ALLM.Request.t(), module() | nil) ::
  preflight_result()

Pre-flight a request against the catalog's view of a model.

Three return shapes (Phase 10.4)

• :ok — no rewrite needed, no rejection. Caller dispatches the original request unchanged. Returned when the catalog is absent, when the model is a bare string/tuple/nil (no capability info), or when no rejection rule fires AND no rewrite predicate matches.
• {:ok, %Request{}} — pre-flight rewrote the request. v0.2's only rewrite is structured_finalize: true (auto-set when the adapter's requires_structured_finalize?/1 returns true for a request that combines tools and a json_schema response_format). Caller MUST dispatch the returned request.
• {:error, %ValidationError{reason: :unsupported_capability, errors: [...]}} — pre-flight rejected the request. Both rejection rules accumulate in :errors when both fire.

Adapter argument (Phase 10.4 — optional)

The third argument carries the adapter module so pre-flight can call function_exported?(adapter, :requires_structured_finalize?, 1) to decide the rewrite. Defaults to nil (no rewrite) so existing 2-arg callers continue to work — the rewrite branch only fires when the caller threads the adapter through. Per design Decision #14, requires_structured_finalize?/1 is a regular module function, NOT a @callback, so most adapters do not export it.

Examples

iex> ALLM.Capability.preflight("openai:gpt-4.1-mini", ALLM.request([ALLM.user("hi")]))
:ok

iex> ref = ALLM.ModelRef.new(
...>   provider: :local, id: "no-tools",
...>   capabilities: %{tools: %{enabled: false}, json_native: true}
...> )
iex> tool = ALLM.Tool.new(name: "echo", description: "x", schema: %{})
iex> req = ALLM.Request.new([%ALLM.Message{role: :user, content: "hi"}], tools: [tool])
iex> {:error, err} = ALLM.Capability.preflight(ref, req)
iex> err.reason
:unsupported_capability
iex> err.errors
[{[:tools], :tools_disabled}]

@spec preflight_image(model_ref_or_string(), ALLM.ImageRequest.t()) ::
  image_preflight_result()

Pre-flight an ALLM.ImageRequest against the catalog's view of a model — sister of preflight/3, narrower contract.

Returns :ok | {:error, %ValidationError{reason: :unsupported_capability}} only — there is no {:ok, %ImageRequest{}} rewrite branch (image requests have no analogous rewrite need in v0.3, per Phase 14.3 design Decision #10). 2-arity by design — symmetric with populate_costs/2, NOT with preflight/3.

Rejection rules (both accumulate when both fire)

• {[:images_enabled], :images_disabled} — fires when model_ref.capabilities.images_enabled == false.
• {[:operation], :unsupported_image_operation} — fires when request.operation not in model_ref.capabilities.supported_image_operations.

Tolerates JSON-rehydrated %ModelRef{} with string-keyed capabilities (%{"images_enabled" => false, "supported_image_operations" => ["generate"]}) per the existing pattern in check_tools/3 / check_json_native/3.

Returns :ok early when the catalog is absent (catalog_loaded?/0 == false) or when model_ref_or_string is a bare string / tuple / nil (no capability info).

Examples

iex> req = ALLM.ImageRequest.new(prompt: "a kestrel")
iex> ALLM.Capability.preflight_image("openai:gpt-image-1", req)
:ok

iex> ref = ALLM.ModelRef.new(
...>   provider: :local, id: "no-images",
...>   capabilities: %{images_enabled: false, supported_image_operations: []}
...> )
iex> req = ALLM.ImageRequest.new(prompt: "a kestrel")
iex> {:error, err} = ALLM.Capability.preflight_image(ref, req)
iex> err.reason
:unsupported_capability
iex> err.errors
[{[:images_enabled], :images_disabled}, {[:operation], :unsupported_image_operation}]

@spec select(keyword()) ::
  {:ok, ALLM.ModelRef.t()} | {:error, :catalog_not_loaded | :no_match | term()}

Delegate to LLMDB.select/1 for capability-based model selection.

Returns LLMDB.select(criteria) when the catalog is loaded; returns {:error, :catalog_not_loaded} (atom shape, not a struct — the only :error shape this module produces with an atom reason) otherwise.

Examples

iex> match?({:error, :catalog_not_loaded}, ALLM.Capability.select(require: [:tools])) or
...>   match?({:ok, _}, ALLM.Capability.select(require: [:tools])) or
...>   match?({:error, _}, ALLM.Capability.select(require: [:tools]))
true