voicemate.pipeline.turn_taking

Turn-taking rules: what each thing the user does means for the conversation.

TurnTaking is a small state machine with no event loop and no I/O. The voice session tells it what happened (an utterance, typed text, a button, a cancelled turn, …) as plain values and executes the Decision it returns. That keeps the rules (merging a cut-off question, answering a confirmation, holding until the user is finished, barge-in) testable without a graph, a microphone or a voice.

Attributes

Classes

Begin

Start a turn.

Collect

Keep the words; the user is holding.

Interrupt

Stop what the assistant is doing (barge-in, or the user took the floor).

Ignore

Nothing to do.

TurnTaking

Decides what user input means. Times are monotonic seconds supplied by the caller.

Module Contents

voicemate.pipeline.turn_taking.MERGE_WINDOW_S: float = 20.0
class voicemate.pipeline.turn_taking.Begin[source]

Start a turn.

Variables:
  • text – The user’s words (a merged question already joined).

  • merged – text continues a question that was cut off.

  • resume – The user’s words answer a pending confirmation (the turn resumes the run).

  • discard – Id of the cut-off message to remove from the history (when merged).

  • shown – The UI already shows text (it was collected during a hold).

text: str
merged: bool = False
resume: str | None = None
discard: str | None = None
shown: bool = False
class voicemate.pipeline.turn_taking.Collect[source]

Keep the words; the user is holding.

Variables:
  • text – Everything collected so far, joined.

  • parts – How many separate inputs it holds.

text: str
parts: int
class voicemate.pipeline.turn_taking.Interrupt[source]

Stop what the assistant is doing (barge-in, or the user took the floor).

Returned for input while a turn is running too: nothing was consumed, so the caller cancels the turn and presents the same input again.

class voicemate.pipeline.turn_taking.Ignore[source]

Nothing to do.

voicemate.pipeline.turn_taking.Decision
class voicemate.pipeline.turn_taking.TurnTaking(merge_window_s: float = MERGE_WINDOW_S)[source]

Decides what user input means. Times are monotonic seconds supplied by the caller.

Parameters:

merge_window_s – See MERGE_WINDOW_S.

Variables:
  • holding – While True, input is collected instead of answered.

  • question – The confirmation the agent is waiting on, if any.

merge_window_s = 20.0
holding = False
question: str | None = None
on_utterance(text: str, ended_at: float, turn_running: bool) → Decision[source]

The user said text; it may continue a question that was just cut off.

on_typed(text: str, now: float, turn_running: bool) → Decision[source]

The user typed text (typed input never merges).

on_answer(text: str, now: float, turn_running: bool) → Decision[source]

The user answered the pending question with a button (works while holding).

on_speech_start(busy: bool) → Decision[source]

The user started speaking: barge in if the assistant is busy.

hold(busy: bool) → Decision[source]

The user wants time to think: collect input; a busy assistant must stop.

release(turn_running: bool = False) → Decision[source]

The user is finished: everything collected becomes one turn.

question_asked(question: str) → None[source]

The agent paused and waits for the user’s answer.

turn_cancelled(message_id: str, text: str, at: float, spoke: bool, resumed: bool) → None[source]

A turn was cancelled; remember its question if nothing was said and it was new.