GenAI.Dialogue (GenAI Core v0.3.3)

Copy Markdown

Pure multi-turn slot-filling dialogue stepper.

Product code supplies a GenAI.Dialogue.Schema and optional extract/merge functions. No I/O: after status: :complete, the host runs side effects (e.g. genai_approval scripts) outside this module.

Summary

Types

extract_fun()

Extract callback. Both arities are supported

extract_result()

Result of an extract callback.

status()
t()

Functions

cancelled?(arg1)
complete?(arg1)
draft(dialogue)

Current draft map (atom keys preferred).

start(schema, utterance, opts \\ [])

Start a dialogue from the first user utterance.

turn(d, text)

Process one user turn. Returns {dialogue, agent_message}.

Types

extract_fun()

@type extract_fun() ::
  (String.t(), atom() | nil -> extract_result())
  | (String.t(), atom() | nil, map() -> extract_result())

Extract callback. Both arities are supported:

  • (text, pending_field) — legacy 2-arity form.
  • (text, pending_field, draft) — receives the accumulated draft so an LLM-backed extractor can avoid re-asking filled slots.

extract_result()

@type extract_result() :: {:cancel} | {:ok, map()} | {:ok, map(), String.t()}

Result of an extract callback.

  • {:cancel} — user abandoned the dialogue.
  • {:ok, attrs} — slots harvested; the agent message stays schema-driven.
  • {:ok, attrs, reply} — slots harvested AND the extractor supplied its own natural-language reply, which replaces the canned schema question / ready message for this turn.

status()

@type status() :: :collecting | :complete | :cancelled

t()

@type t() :: %GenAI.Dialogue{
  cancel_message: String.t(),
  draft: map(),
  extract: extract_fun(),
  last_agent_message: String.t() | nil,
  pending_field: atom() | nil,
  ready_message: (map() -> String.t()),
  schema: GenAI.Dialogue.Schema.t(),
  status: status(),
  turns: non_neg_integer()
}

Functions

cancelled?(arg1)

complete?(arg1)

draft(dialogue)

Current draft map (atom keys preferred).

start(schema, utterance, opts \\ [])

@spec start(GenAI.Dialogue.Schema.t(), String.t(), keyword()) :: {t(), String.t()}

Start a dialogue from the first user utterance.

Options:

  • :extract — (text, pending_field) or (text, pending_field, draft) returning {:cancel} | {:ok, attrs} | {:ok, attrs, reply}
  • :initial_draft — map pre-filled slots
  • :ready_message — (draft) -> String.t() when complete
  • :cancel_message — string on cancel

turn(d, text)

@spec turn(t(), String.t()) :: {t(), String.t()}

Process one user turn. Returns {dialogue, agent_message}.