@spec run(ALLM.Engine.t(), ALLM.Thread.t() | [ALLM.Message.t()], chat_opts()) ::
  {:ok, ALLM.ChatResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()}

Run a multi-turn chat loop and return a %ALLM.ChatResult{}.

Composes step/3 calls: each step's thread becomes the next step's input thread. Halts on the first matching terminal condition (see terminal_condition/4 source for the seven-entry total order).

Halt reasons

Adapter pre-flight errors surface as {:error, struct} from the FIRST step's step/3 call. Mid-loop adapter errors fold into the step's response and surface as halted_reason: :error on the ChatResult.

structured_finalize semantics (Phase 10.4 — see spec §5.4)

When called with opts[:structured_finalize] == true AND opts[:response_format] != nil, run/3 runs a two-pass orchestration per design Decision #7:

• Pass 1 runs the tool loop with response_format cleared (tools preserved). Halts naturally per the table above.
• Pass 2 fires only when pass 1 halted on :completed | :max_turns | :halt_when. Other halts skip pass 2; the pass-1 result is returned with metadata.structured_finalize.pass_1_halted == <reason>.
• Pass 2 issues a single tools-disabled adapter call carrying the original response_format, after appending a user-nudge message to the thread (override via opts[:structured_finalize_nudge] > Application.get_env(:allm, :structured_finalize_nudge) > library default "Now provide your final structured response."; empty-string nudge skips the append).
• The merged %ChatResult{} carries :steps from BOTH passes, :final_response from pass 2, :halted_reason from pass 2, :thread from pass 2, and metadata.structured_finalize.pass_1_halted.

Per Invariant #4: pass 1 consumes the max_turns budget; pass 2's single call does NOT decrement it.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     scripts: [
...>       [{:tool_call, id: "c0", name: "echo", arguments: %{"x" => 1}},
...>        {:finish, :tool_calls}],
...>       [{:text, "done"}, {:finish, :stop}]
...>     ]
...>   ],
...>   tools: [ALLM.tool(
...>     name: "echo",
...>     description: "",
...>     schema: %{},
...>     handler: fn args -> {:ok, args} end
...>   )]
...> )
iex> thread = ALLM.Thread.from_messages([ALLM.user("echo please")])
iex> {:ok, %ALLM.ChatResult{} = r} = ALLM.Chat.run(engine, thread)
iex> r.halted_reason
:completed
iex> length(r.steps)
2

@spec step(ALLM.Engine.t(), ALLM.Thread.t() | [ALLM.Message.t()], step_opts()) ::
  {:ok, ALLM.StepResult.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()}

Execute a single step (one adapter call plus any auto-executed tool calls) and return a %ALLM.StepResult{}.

Normalises thread_or_messages — a list of %Message{} is wrapped via ALLM.Thread.from_messages/1. Validates the thread via ALLM.Validate.thread/1 before the adapter call. Dispatches to ALLM.Runner.run/3 for the adapter round-trip, then branches on :mode and response.finish_reason:

• mode: :manual with finish_reason: :tool_calls — returns the tool calls surfaced on response.tool_calls; tool_results: [], done?: false, metadata.mode: :manual. Handler is NOT invoked.
• mode: :auto with finish_reason: :tool_calls — dispatches to ALLM.ToolRunner.run_tool_calls/3, appends tool-role messages to the thread, and returns the composed step result.
• Anything else (:stop, :length, :content_filter, :error) — done?: true, tool_results: [].

Error reason table

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     script: [
...>       {:tool_call, id: "c0", name: "echo", arguments: %{"x" => 1}},
...>       {:finish, :tool_calls}
...>     ]
...>   ],
...>   tools: [ALLM.tool(
...>     name: "echo",
...>     description: "",
...>     schema: %{},
...>     handler: fn args -> {:ok, args} end
...>   )]
...> )
iex> thread = ALLM.Thread.from_messages([ALLM.user("echo please")])
iex> {:ok, %ALLM.StepResult{} = sr} = ALLM.Chat.step(engine, thread)
iex> sr.done?
false
iex> length(sr.tool_results)
1

@spec stream(ALLM.Engine.t(), ALLM.Thread.t() | [ALLM.Message.t()], chat_opts()) ::
  {:ok, Enumerable.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()}

Stream a multi-turn chat loop and return a lazy stream of ALLM.Event values terminating in exactly one :chat_completed event.

Composes stream_step/3 sub-streams sequentially: the outer Stream.resource/3 drives the current step's reducer one event at a time (mirroring Phase 6's stream_step/3 continuation idiom one layer up). When a step completes, terminal_condition/5 decides whether to start a new step (with the augmented thread) or transition to the terminal :chat_completed emission.

Multi-turn stream composition

Two-phase state machine (see Phase 7 design Non-obvious Decision #1):

• Phase S (:step) — drives the current stream_step/3 enumerable via its reducer continuation. Each next_fun pulls one event, folds it into the outer StreamCollector, and emits it. On :step_completed, computes a %StepResult{} from the PRE-fold collector state, folds the event, then invokes terminal_condition/5. On :continue, starts the next step. On {:halt, reason, _}, builds the final %ChatResult{} and transitions to Phase F.
• Phase F (:final) — emits exactly one {:chat_completed, %{result: chat_result}} event and halts.

Cleanup chain

Chat.stream/3 after_fun
  → halt step_cont
    → Chat.stream_step/3 after_fun
      → halt adapter_cont OR tool_cont (whichever is active)

Consumer halt produces NO :chat_completed event (per spec §30 cancellation contract). Callers needing a final %ChatResult{} for a cancelled stream collect events and call ALLM.StreamCollector.to_chat_result/1 on the partial state.

Ask-user thread asymmetry

When a step's handler returns {:ask_user, _}, the streamed :step_completed.thread does NOT include the assistant question message — only the :chat_completed.result.thread does (Phase 7 Invariant 8). Consumers persisting thread state across turns should read ChatResult.thread, not :step_completed.thread.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     scripts: [
...>       [{:tool_call, id: "c0", name: "echo", arguments: %{"x" => 1}},
...>        {:finish, :tool_calls}],
...>       [{:text, "done"}, {:finish, :stop}]
...>     ]
...>   ],
...>   tools: [ALLM.tool(
...>     name: "echo",
...>     description: "",
...>     schema: %{},
...>     handler: fn args -> {:ok, args} end
...>   )]
...> )
iex> thread = ALLM.Thread.from_messages([ALLM.user("echo please")])
iex> {:ok, stream} = ALLM.Chat.stream(engine, thread)
iex> events = Enum.to_list(stream)
iex> Enum.count(events, &match?({:chat_completed, _}, &1))
1

@spec stream_step(ALLM.Engine.t(), ALLM.Thread.t() | [ALLM.Message.t()], step_opts()) ::
  {:ok, Enumerable.t()}
  | {:error,
     ALLM.Error.EngineError.t()
     | ALLM.Error.AdapterError.t()
     | ALLM.Error.ValidationError.t()}

Execute a single step and return a lazy stream of ALLM.Event values.

The stream is open — no events fire until the caller reduces. Events are emitted in this order: all adapter events (pass-through from stream_generate/3), then zero-to-N tool-execution event groups (one per tool: :tool_execution_started → :tool_execution_completed → :tool_result_encoded / :ask_user_requested / :tool_halt), then exactly one terminal :step_completed event.

Consumer halt (via Enum.take/2, Stream.take_while/2, etc.) propagates to whichever phase is currently active — the adapter stream in Phase A or the tool-execution stream in Phase B — triggering that sub-resource's own cleanup exactly once.

Event sequence

See the module doc's "Event sequence" section. No new :message_completed is synthesised after tool execution (Non-obvious Decision #12).

Unknown tools (Phase B pre-flight)

When the adapter requests a tool that is not registered on the engine, stream_step/3 still returns {:ok, stream} — the error does NOT surface on the outer tuple. Instead, after the adapter phase completes, the stream emits a single {:error, %ALLM.EngineError{reason: :unknown_tool}} event followed by the terminal :step_completed event. Consumers that need to short-circuit on unknown tools should pattern-match on {:error, _} elements during reduction. This differs from the non-streaming step/3 which returns {:error, %EngineError{}} on the outer tuple; the asymmetry exists because once a stream has been constructed the consumer has already committed to reducing it, and late-surfacing the error as a stream element keeps the open-stream contract intact. See Non-obvious Decision #1 for the underlying three-phase state machine.

Examples

iex> engine = ALLM.Engine.new(
...>   adapter: ALLM.Providers.Fake,
...>   adapter_opts: [
...>     script: [
...>       {:tool_call, id: "c0", name: "echo", arguments: %{"x" => 1}},
...>       {:finish, :tool_calls}
...>     ]
...>   ],
...>   tools: [ALLM.tool(
...>     name: "echo",
...>     description: "",
...>     schema: %{},
...>     handler: fn args -> {:ok, args} end
...>   )]
...> )
iex> thread = ALLM.Thread.from_messages([ALLM.user("echo please")])
iex> {:ok, stream} = ALLM.Chat.stream_step(engine, thread)
iex> events = Enum.to_list(stream)
iex> Enum.any?(events, &match?({:step_completed, _}, &1))
true