@spec merge_opts(
  t(),
  keyword()
) :: t()

Compose per-call overrides into the engine struct, returning a new engine.

Convenience helper — merge_opts/2 is not a primitive of the resolver chain; execution functions typically use resolve_model/2, resolve_tools/2, and resolve_params/2 directly rather than rebuilding an engine. merge_opts/2 is useful when you want a single engine value reflecting per-call overrides (e.g. for telemetry or for passing into a pre-built helper).

Recognized opt keys:

• :model — replaces engine.model via with_model/2.
• :tools — dedup-by-name merge via resolve_tools/2 (Non-obvious decision #6 — this does not call put_tools/2, which is naive append).
• :params — shallow-merge into engine.params. The value must be a map; a non-map value (e.g., a keyword list) is silently dropped, because engine.params is itself a map and the merge target is not defined for other shapes.
• :context — shallow-merge into engine.context. Same map-only rule as :params.

Any other opts key is silently dropped — unknown keys are for execution functions, not the engine itself.

Total on valid input: given any %ALLM.Engine{} and any keyword list, merge_opts/2 returns an %ALLM.Engine{} and does not raise.

Examples

iex> a = ALLM.Tool.new(name: "a", description: "a", schema: %{})
iex> b = ALLM.Tool.new(name: "b", description: "b", schema: %{})
iex> engine = ALLM.Engine.new(model: "old") |> ALLM.Engine.put_tool(a)
iex> merged = ALLM.Engine.merge_opts(engine, model: "new", tools: [b], params: %{temperature: 0.9})
iex> merged.model
"new"
iex> Enum.map(merged.tools, & &1.name)
["a", "b"]
iex> merged.params
%{temperature: 0.9}

@spec new(keyword()) :: t()

Build an %ALLM.Engine{} from keyword opts.

Accepts any subset of the documented struct fields; unknown keys raise KeyError via struct!/2. :adapter may be nil at construction — the missing-adapter check fires at adapter-call time (:missing_adapter per spec §20), not here.

Examples

iex> engine = ALLM.Engine.new(adapter: ALLM.Providers.Fake, model: "fake:m")
iex> engine.adapter
ALLM.Providers.Fake
iex> engine.model
"fake:m"
iex> engine.tools
[]

@spec put_context(t(), atom() | String.t(), term()) :: t()

Set a single entry in the engine's :context map.

:context is opaque to the library; tool handlers receive it as the second argument when declared with arity 2.

Examples

iex> engine = ALLM.Engine.new() |> ALLM.Engine.put_context(:user_id, 42)
iex> engine.context
%{user_id: 42}

@spec put_param(t(), atom() | String.t(), term()) :: t()

Set a single entry in the engine's :params map.

Keys may be atoms or strings — adapters decide which form they accept at wire time.

Examples

iex> engine = ALLM.Engine.new() |> ALLM.Engine.put_param(:temperature, 0.7)
iex> engine.params
%{temperature: 0.7}

@spec put_tool(t(), ALLM.Tool.t()) :: t()

Append a single tool to the engine's :tools list.

Naive append — does not dedup by :name. Use merge_opts/2 or resolve_tools/2 when you need opts-win dedup semantics for per-call overrides.

Examples

iex> tool = ALLM.Tool.new(name: "echo", description: "echo", schema: %{})
iex> engine = ALLM.Engine.new() |> ALLM.Engine.put_tool(tool)
iex> Enum.map(engine.tools, & &1.name)
["echo"]

@spec put_tools(t(), [ALLM.Tool.t()]) :: t()

Append multiple tools to the engine's :tools list.

Naive append (engine.tools ++ more) — does not dedup by :name. Use merge_opts/2 for per-call override semantics that replace an engine tool in place when names collide (Non-obvious decision #6).

Examples

iex> a = ALLM.Tool.new(name: "a", description: "a", schema: %{})
iex> b = ALLM.Tool.new(name: "b", description: "b", schema: %{})
iex> engine = ALLM.Engine.new() |> ALLM.Engine.put_tools([a, b])
iex> Enum.map(engine.tools, & &1.name)
["a", "b"]

@spec resolve_model(
  t(),
  keyword()
) :: resolved_model()

Resolve the effective model for an adapter call.

Reads opts[:model] if present, otherwise falls back to engine.model. When llm_db is loaded in the BEAM, delegates to LLMDB.model/1 on the chosen value so the caller can receive a catalog-backed model ref; when absent (the default v0.2 configuration), returns the value verbatim (Non-obvious decision #3, spec §6.3). Core must function without llm_db.

Examples

iex> engine = ALLM.Engine.new(model: "fake:m")
iex> ALLM.Engine.resolve_model(engine, [])
"fake:m"
iex> ALLM.Engine.resolve_model(engine, model: "override")
"override"
iex> ALLM.Engine.resolve_model(ALLM.Engine.new(model: {:openai, "gpt-x"}), [])
{:openai, "gpt-x"}

@spec resolve_params(
  t(),
  keyword()
) :: map()

Resolve the effective params map for an adapter call via a shallow merge of engine.params with opts filtered by the engine-field deny-list (Non-obvious decision #5).

Returned as a map (not a keyword list). Engine-field keys (:adapter, :adapter_opts, :model, :tools, :tool_executor, :tool_result_encoder, :image_adapter, :params, :context, :retry, :middleware, :metadata, :api_key) are never forwarded — they are consumed by the engine layer or by other resolvers. Every other opts key flows through unchanged, so provider-specific knobs (:reasoning_effort) and orchestration knobs (:max_turns, :halt_when) naturally reach the adapter per spec §10's "unknown options in opts are forwarded to the adapter unchanged" rule.

Examples

iex> engine = ALLM.Engine.new(params: %{temperature: 0.2, top_p: 1.0})
iex> ALLM.Engine.resolve_params(engine, temperature: 0.7)
%{temperature: 0.7, top_p: 1.0}
iex> ALLM.Engine.resolve_params(engine, model: "x", reasoning_effort: "high")
%{temperature: 0.2, top_p: 1.0, reasoning_effort: "high"}

@spec resolve_tools(
  t(),
  keyword()
) :: [ALLM.Tool.t()]

Resolve the effective tool list for an adapter call using dedup-by-name semantics (Non-obvious decision #4, Invariant 4).

The result preserves engine.tools order; each engine tool whose :name matches a tool in opts[:tools] is replaced in place by the matching opts tool. Opts tools whose :name doesn't match any engine tool are appended in opts[:tools] order. Example: engine.tools = [a, b, c], opts[:tools] = [b', d] → [a, b', c, d].

When opts has no :tools key, returns engine.tools unchanged.

Examples

iex> a = ALLM.Tool.new(name: "a", description: "a", schema: %{})
iex> b = ALLM.Tool.new(name: "b", description: "b", schema: %{})
iex> c = ALLM.Tool.new(name: "c", description: "c", schema: %{})
iex> b_prime = ALLM.Tool.new(name: "b", description: "override", schema: %{})
iex> d = ALLM.Tool.new(name: "d", description: "d", schema: %{})
iex> engine = ALLM.Engine.new() |> ALLM.Engine.put_tools([a, b, c])
iex> ALLM.Engine.resolve_tools(engine, tools: [b_prime, d]) |> Enum.map(& &1.name)
["a", "b", "c", "d"]

@spec with_model(t(), String.t()) :: t()

Replace the engine's :model string.

Examples

iex> engine = ALLM.Engine.new(model: "old") |> ALLM.Engine.with_model("new")
iex> engine.model
"new"