Struct Conversation 

pub struct Conversation { /* private fields */ }

Fluent builder that produces a ConversationSpec; sugar over the spec.

(Not Debug: resolve_slot bindings hold async closures. The serializable ConversationSpec is Debug via spec.)

Implementations

impl Conversation

pub fn new(name: impl Into<String>) -> Self

Start a new conversation.

pub fn stage(self, id: impl Into<String>) -> Self

Begin authoring a new stage; subsequent setters apply to it. Routes to the active overlay when between .overlay(..) and .end_overlay().

pub fn overlay(self, name: impl Into<String>) -> Self

Begin authoring a digression/overlay; subsequent .stage(..) calls (until .end_overlay()) populate it. Set its activation guard with .trigger(..) (an overlay with no trigger never fires — fail-closed).

pub fn trigger(self, guard: Guard) -> Self

Set the activation guard of the overlay currently being authored.

pub fn resume(self, resume: Resume) -> Self

Set the resume policy of the overlay currently being authored.

pub fn end_overlay(self) -> Self

End overlay authoring; subsequent .stage(..) calls target the main flow again. (Not a sub-builder exit — the Conversation is the same value throughout — so it is named for what it does.)

pub fn add_stage(self, stage: StageSpec) -> Self

Append a pre-built StageSpec (e.g. from a Motif). Routes to the active overlay when authoring one, else the main flow. Subsequent stage setters (next, say, …) apply to it.

pub fn add_overlay(self, overlay: OverlaySpec) -> Self

Append a pre-built OverlaySpec (e.g. a Motif::faq_digression). Leaves overlay-authoring mode (the overlay is already complete).

pub fn policy(self, policy: impl Into<Policy>) -> Self

Attach a cross-cutting Policy aspect.

pub fn instruction(self, text: impl Into<String>) -> Self

Set the stage’s instruction: guidance projected to the model while the stage is active. It steers what the model says; it is not verbatim speech and carries no guarantee of exact wording.

pub fn say(self, text: impl Into<String>) -> Self

Alias of instruction. The name suggests exact speech, which this never was; prefer instruction in new code.

pub fn ground(self, template: impl Into<String>) -> Self

Set the stage’s grounding template.

pub fn collect<I, S>(self, fields: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Collect the given slots in this stage (drives default completion).

pub fn collect_frame<F: Frame>(self) -> Self

Collect the slots of a typed gemini_adk_rs::frame::Frame in this stage. The frame’s slot state-keys drive the captured completion; its metadata (prompts/confirm/pii) is available via F::frame() for confirmation and repair.

pub fn allow<I, S>(self, tools: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Allow the given tools while this stage is active.

Calls to other governed tools are refused. Under SteeringMode::ContextUpdate the model is also offered only the admitted tools while the stage is active.

pub fn complete_when(self, guard: Guard) -> Self

Set an explicit completion guard for this stage: the stage counts as complete when guard holds (default: all collected slots captured).

pub fn commit(self, tool: impl Into<String>, when: Guard) -> Self

Commit a confirm-before-act tool in this stage, gated by when.

pub fn next(self, to: impl Into<String>, when: Guard) -> Self

Add a forward transition to to when when holds.

pub fn resolve_slot<I, S, F, Fut>( self, name: impl Into<String>, args: I, ttl: Option<Duration>, fetch: F, ) -> Self

where I: IntoIterator<Item = S>, S: Into<String>, F: Fn(Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Value, String>> + Send + 'static,

Fill a slot in the current stage from an async resolver — a tool call, HTTP fetch, MCP request, or agent. args names the State keys bound into the JSON object passed to fetch; the returned value fills name. With a ttl, results are memoized by (field, canonical args).

The slot is added to the stage’s collect, so its captured completion waits for the resolution. The closure lives only in the builder; the serializable spec is unaffected.

pub fn after(self, dep: impl Into<String>) -> Self

Add an explicit dependency on another stage.

pub fn terminal(self) -> Self

Mark the current stage terminal.

pub fn repair(self, policy: RepairPolicy) -> Self

Attach a RepairPolicy to the current stage.

pub fn verbatim(self, text: impl Into<String>) -> Self

Require the current stage to say text word for word (strict canned mode): it completes only once the model’s output transcript matches. The model holds the floor while it reads, unless the stage sets timing. Needs output transcription on the session.

pub fn timing(self, timing: VoiceTiming) -> Self

Set the current stage’s voice pacing; see VoiceTiming.

use std::time::Duration;
Conversation::new("disclosure")
    .stage("read_terms")
    .say("Read the terms word for word.")
    .timing(VoiceTiming::new().uninterruptible())
    .stage("confirm")
    .collect(["agreed"])
    .timing(VoiceTiming::new().reprompt_after(Duration::from_secs(6)));

pub fn require<I, S>(self, steps: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Require these stages for completion (lowers to a Flow require). Targets the active overlay when authoring one, else the main flow.

pub fn spec(&self) -> &ConversationSpec

The spec built so far.

pub fn into_spec(self) -> ConversationSpec

Consume into the underlying spec.

pub fn from_spec( spec: ConversationSpec, ) -> Result<CompiledConversation, ConversationError>

Compile from a ConversationSpec (e.g. parsed from JSON/YAML).

If the spec declares any named-resolver slots (stage.resolve), this errors — those slots would be collected but never filled. Use Conversation::from_spec_with_resolvers to bind them.

pub fn from_spec_stubbing_resolvers( spec: ConversationSpec, ) -> Result<CompiledConversation, ConversationError>

Compile a ConversationSpec with its declared resolvers stubbed (each returns JSON null) — for structural validation, model-free simulation, and CI, where resolver outputs are supplied by scenario set steps rather than live fetches.

Use this (not from_spec) when compiling a spec from untrusted JSON for testing/authoring; use from_spec_with_resolvers at deploy time to bind real implementations.

pub fn from_spec_with_resolvers( spec: ConversationSpec, registry: &ResolverRegistry, ) -> Result<CompiledConversation, ConversationError>

Compile a ConversationSpec and bind its declared named-resolver slots from registry. This makes a JSON spec + a resolver registry a complete deployable unit.

Errors if the spec references a resolver name absent from registry.

pub fn compile(self) -> Result<CompiledConversation, ConversationError>

Lower and validate into a CompiledConversation.

Trait Implementations

impl Clone for Conversation

fn clone(&self) -> Conversation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Conversation

fn default() -> Conversation

Returns the “default value” for a type.