Struct PhaseBuilder 

pub struct PhaseBuilder { /* private fields */ }

Builder for a conversation phase.

Created by Live::phase and returned to the Live chain via done.

Implementations

impl PhaseBuilder

pub fn needs(self, keys: &[&str]) -> Self

Declare what state keys this phase is responsible for gathering.

Purely informational — does not enforce transitions or block progress. The ContextBuilder reads these to append a “[Gathering] key1, key2” line to the instruction, so the model knows what to focus on in the current phase.

Example

.phase("identify_caller")
    .instruction("Get the caller's name and organization.")
    .needs(&["caller_name", "caller_organization"])
    .transition("determine_purpose", S::is_set("caller_name"))
    .done()

pub fn requires(self, keys: &[&str]) -> Self

Declare state keys that must exist before this phase can be entered.

This is a hard phase-machine gate, unlike needs, which is only conversational guidance. Use requires for authoritative facts that must be produced by tools, callbacks, retrieval, or other runtime mechanisms before the model can operate in the phase.

.phase("quote_price")
    .requires(&["catalog_item_loaded", "price"])
    .instruction("Quote only the loaded catalog price.")
    .done()

pub fn prepare<F, Fut>( self, name: impl Into<String>, produces: &[&str], f: F, ) -> Self

where F: Fn(State, Arc<dyn SessionWriter>) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Add a preparation effect that runs before this phase is entered when its required state is missing.

Preparations are run by the phase lifecycle after an outbound transition guard selects this phase, but before the phase is committed. If the preparation does not satisfy this phase’s requires, the transition remains blocked.

pub fn presents(self, concepts: &[&str]) -> Self

Declare semantic concepts presented to the user by this phase.

On phase entry the runtime writes presented:<concept> = true. Use this with transition_after_presented to avoid accepting stale acknowledgements from earlier phases.

pub fn clear_on_enter(self, keys: &[&str]) -> Self

Clear state keys on phase entry.

This is useful for removing stale acknowledgements or intents that were extracted before the current phase’s concept was presented.

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

Set a static instruction for this phase.

pub fn dynamic_instruction<F>(self, f: F) -> Self

where F: Fn(&State) -> String + Send + Sync + 'static,

Set a dynamic instruction that is resolved from state at transition time.

pub fn tools(self, tools: Vec<String>) -> Self

Set the tool filter for this phase. Only these tools will be enabled.

pub fn guard<F>(self, f: F) -> Self

where F: Fn(&State) -> bool + Send + Sync + 'static,

Set a guard that must return true for this phase to be entered.

pub fn on_enter<F, Fut>(self, f: F) -> Self

where F: Fn(State, Arc<dyn SessionWriter>) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Set an async callback to run when entering this phase.

pub fn on_exit<F, Fut>(self, f: F) -> Self

where F: Fn(State, Arc<dyn SessionWriter>) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Set an async callback to run when exiting this phase.

pub fn transition( self, target: &str, guard: impl Fn(&State) -> bool + Send + Sync + 'static, ) -> Self

Add a guard-based transition to a target phase.

pub fn transition_with( self, target: &str, guard: impl Fn(&State) -> bool + Send + Sync + 'static, description: impl Into<String>, ) -> Self

Add a guard-based transition with a human-readable description.

The description is used by PhaseMachine::describe_navigation() to help the model understand what paths are available from the current phase.

pub fn transition_after_presented( self, target: &str, concept: &str, ack_key: &str, description: impl Into<String>, ) -> Self

Add a transition that only fires after a semantic concept was presented and an acknowledgement key is true.

pub fn terminal(self) -> Self

Mark this phase as terminal (no outbound transitions will be evaluated).

pub fn with_state(self, keys: &[&str]) -> Self

Append state keys to the instruction at runtime. Renders as [Context: key1=val1, key2=val2, ...].

pub fn when( self, predicate: impl Fn(&State) -> bool + Send + Sync + 'static, text: impl Into<String>, ) -> Self

Conditionally append text when a predicate is true.

pub fn with_context( self, f: impl Fn(&State) -> String + Send + Sync + 'static, ) -> Self

Append the result of a custom formatter to the instruction.

pub fn context(self, ctx: ContextBuilder) -> Self

Append a declarative gemini_adk_rs::live::context_builder::ContextBuilder to this phase’s instruction.

pub fn prompt_on_enter(self, enabled: bool) -> Self

Send turnComplete: true after instruction + context on phase entry, causing the model to generate a response immediately.

pub fn on_enter_context<F>(self, f: F) -> Self

where F: Fn(&State, &TranscriptWindow) -> Option<Vec<Content>> + Send + Sync + 'static,

Set a context injection callback for phase entry. Returns Content to send as client_content before prompting.

pub fn enter_prompt(self, message: impl Into<String>) -> Self

Inject a model-role bridge message on phase entry and prompt immediately.

Combines on_enter_context + prompt_on_enter(true) into a single call, eliminating the need to import Content in application code.

.phase("verify_identity")
    .instruction(VERIFY_IDENTITY_INSTRUCTION)
    .enter_prompt("The caller confirmed the disclosure. I'll now verify their identity.")
    .done()

pub fn enter_prompt_fn<F>(self, f: F) -> Self

where F: Fn(&State, &TranscriptWindow) -> String + Send + Sync + 'static,

Like enter_prompt but with a state-aware closure.

.enter_prompt_fn(|state, _tw| {
    if state.get::<bool>("cease_desist_requested").unwrap_or(false) {
        "Cease-and-desist requested. Closing call respectfully.".into()
    } else {
        "Wrapping up the call.".into()
    }
})

pub fn navigation(self) -> Self

Include phase navigation context in this phase’s instruction.

pub fn modifiers(self, mods: &[InstructionModifier]) -> Self

Apply a slice of pre-built instruction modifiers to this phase.

Use with P::with_state(), P::when(), P::context_fn() factories.

.phase("disclosure")
    .modifiers(&[P::with_state(KEYS), P::when(pred, "warning")])
    .done()

pub fn done(self) -> Live

Finish building this phase and return the Live builder.

Merges phase defaults (from Live::phase_defaults) with phase-specific settings. Defaults are prepended so phase-specific modifiers take priority.