xtalk.events

BaseEvent

Defined in xtalk.serving.events.

@dataclass
class BaseEvent

Base dataclass for all Xtalk events.

Parameters

• session_id (str) Session identifier associated with the event.

Attributes

• timestamp (float) Unix timestamp recorded when the event instance is created.
• session_id (str) Session identifier associated with the event.
• TYPE (str) Stable event type string used by the event bus.

Class Fields

• timestamp: float = field(init=False)
• session_id: str
• TYPE: ClassVar[str] = 'base'

Methods

event_type

Defined in xtalk.serving.events.

def event_type(self) -> str

create_event_class

Defined in xtalk.serving.events.

def create_event_class(*, name: str, fields: dict[str, Any] | None = None, type_name: str | None = None) -> Type[BaseEvent]

Create a BaseEvent subclass dynamically.

Parameters

• name (str) Dataclass name for the generated event type.
• fields (dict[str, Any] | None, optional) Mapping of field names to default values. Value types are inferred from the defaults.
• type_name (str | None, optional) Event bus type string. Defaults to name.lower() when omitted.

Returns

• Type[BaseEvent] Generated dataclass type inheriting from BaseEvent.

Examples

>>> CustomEvent = create_event_class(
...     name="CustomEvent",
...     fields={"text": ""},
... )

WebSocketMessageReceived

Defined in xtalk.serving.events.

@dataclass
class WebSocketMessageReceived(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'websocket.message_received'
• message: str = ''

AudioFrameReceived

Defined in xtalk.serving.events.

@dataclass
class AudioFrameReceived(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'audio.frame_received'
• audio_data: bytes
• sample_rate: int = 16000

EnhancedAudioFrameReceived

Defined in xtalk.serving.events.

@dataclass
class EnhancedAudioFrameReceived(BaseEvent)

Enhanced audio frame for downstream ASR/VAD.

Class Fields

• TYPE: ClassVar[str] = 'audio.enhanced_frame_received'
• audio_data: bytes
• sample_rate: int = 16000

VADSpeechStart

Defined in xtalk.serving.events.

@dataclass
class VADSpeechStart(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'vad.speech_start'
• origin: str = 'client'

VADSpeechEnd

Defined in xtalk.serving.events.

@dataclass
class VADSpeechEnd(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'vad.speech_end'
• origin: str = 'client'

ASRResultPartial

Defined in xtalk.serving.events.

@dataclass
class ASRResultPartial(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'asr.result_partial'
• text: str = ''
• display_text: str = ''
• speech_pause: bool = False

ASRResultFinal

Defined in xtalk.serving.events.

@dataclass
class ASRResultFinal(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'asr.result_final'
• text: str = ''
• display_text: str = ''

LLMFirstChunk

Defined in xtalk.serving.events.

@dataclass
class LLMFirstChunk(BaseEvent)

Event for first LLM chunk/tool call (measure first token latency).

Class Fields

• TYPE: ClassVar[str] = 'llm.first_chunk'

LLMFirstSentence

Defined in xtalk.serving.events.

@dataclass
class LLMFirstSentence(BaseEvent)

Event for first synthesizable sentence (measure sentence latency).

Class Fields

• TYPE: ClassVar[str] = 'llm.sentence_ready'

TTSStarted

Defined in xtalk.serving.events.

@dataclass
class TTSStarted(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.started'

TTSStopped

Defined in xtalk.serving.events.

@dataclass
class TTSStopped(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.stopped'

TTSPaused

Defined in xtalk.serving.events.

@dataclass
class TTSPaused(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.paused'

TTSResumed

Defined in xtalk.serving.events.

@dataclass
class TTSResumed(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.resumed'

TTSFinished

Defined in xtalk.serving.events.

@dataclass
class TTSFinished(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.finished'

LLMAgentResponseUpdate

Defined in xtalk.serving.events.

@dataclass
class LLMAgentResponseUpdate(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'llm_agent.response_update'
• text: str = ''

LLMAgentResponseFinish

Defined in xtalk.serving.events.

@dataclass
class LLMAgentResponseFinish(BaseEvent)

Final text emitted by the agent for one response.

Attributes

• text (str) Final response text.

Class Fields

• TYPE: ClassVar[str] = 'llm_agent.response_finish'
• text: str = ''

ResponseUpdate

Defined in xtalk.serving.events.

@dataclass
class ResponseUpdate(BaseEvent)

Text prefix whose corresponding TTS playback progress has been confirmed.

Attributes

• text (str) Text prefix that has been played to the user.

Class Fields

• TYPE: ClassVar[str] = 'response.update'
• text: str = ''

ResponseFinish

Defined in xtalk.serving.events.

@dataclass
class ResponseFinish(BaseEvent)

Final text whose corresponding TTS playback has finished.

Attributes

• text (str) Final response text whose playback completed.

Class Fields

• TYPE: ClassVar[str] = 'response.finish'
• text: str = ''

TTSTextSynthesized

Defined in xtalk.serving.events.

@dataclass
class TTSTextSynthesized(BaseEvent)

Text marker emitted after one synthesized text segment is fully produced.

Attributes

• text (str) Text segment that was synthesized.
• audio_duration (float) Estimated playback duration of the synthesized audio in milliseconds.

Class Fields

• TYPE: ClassVar[str] = 'tts.text_synthesized'
• text: str = ''
• audio_duration: float = 0.0

TTSVoiceChange

Defined in xtalk.serving.events.

@dataclass
class TTSVoiceChange(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.reference_audio_changed'
• voice_name: str = ''

TTSEmotionChange

Defined in xtalk.serving.events.

@dataclass
class TTSEmotionChange(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.emotion_changed'
• emotion_name: str = ''
• emotion_vector: list = None

TTSSpeedChange

Defined in xtalk.serving.events.

@dataclass
class TTSSpeedChange(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.speed_changed'
• speed: float = 1.0

TTSChunkReady

Defined in xtalk.serving.events.

@dataclass
class TTSChunkReady(BaseEvent)

Indicates one TTS audio chunk is ready for sending. Not emitted when the chunk is generated.

Class Fields

• TYPE: ClassVar[str] = 'tts.chunk_ready'
• audio_chunk: bytes = b''
• sample_rate: int = 48000

TTSChunkPlayed

Defined in xtalk.serving.events.

@dataclass
class TTSChunkPlayed(BaseEvent)

Frontend confirmed playback completion for a TTS audio chunk.

InputGateway publishes this after receiving tts_chunk_played so downstream listeners can observe frontend playback completion in FIFO order.

Class Fields

• TYPE: ClassVar[str] = 'tts.chunk_played_confirm'

TTSPlaybackFinished

Defined in xtalk.serving.events.

@dataclass
class TTSPlaybackFinished(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'tts.playback_finished'

FullAudioFrameReady

Defined in xtalk.serving.events.

@dataclass
class FullAudioFrameReady(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'audio.full_frame_ready'
• audio_chunk: bytes = b''
• sample_rate: int = 48000
• channels: int = 2
• format: str = 'pcm_s16le'

ErrorOccurred

Defined in xtalk.serving.events.

@dataclass
class ErrorOccurred(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'error.occurred'
• error_type: str = ''
• error_message: str = ''

CaptionUpdated

Defined in xtalk.serving.events.

@dataclass
class CaptionUpdated(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'caption.updated'
• text: str = ''
• is_final: bool = False
• reason: str = ''

ToolCallOccurred

Defined in xtalk.serving.events.

@dataclass
class ToolCallOccurred(BaseEvent)

LLM/Agent tool invocation notification.

Class Fields

• TYPE: ClassVar[str] = 'agent.tool_called'
• name: str = ''
• args: Dict[str, Any] = field(default_factory=dict)

RetrievalUpdated

Defined in xtalk.serving.events.

@dataclass
class RetrievalUpdated(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'retrieval.updated'
• text: str = ''
• is_final: bool = False

EmbeddingStatusUpdated

Defined in xtalk.serving.events.

@dataclass
class EmbeddingStatusUpdated(BaseEvent)

Embedding lifecycle update consumed by the LLM agent context manager.

Class Fields

• TYPE: ClassVar[str] = 'embedding.status_updated'
• status: str = ''
• text: str | None = None
• vector_store_instance: Any = None

LLMAgentLoop

Defined in xtalk.serving.events.

@dataclass
class LLMAgentLoop(BaseEvent)

Request one agent-context accept loop iteration for the session.

Class Fields

• TYPE: ClassVar[str] = 'llm.agent_loop'

TextForEmbeddingReady

Defined in xtalk.serving.events.

@dataclass
class TextForEmbeddingReady(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'embeddings.text_ready'
• text: str = ''

LatencyMetricsUpdated

Defined in xtalk.serving.events.

@dataclass
class LatencyMetricsUpdated(BaseEvent)

Fine-grained backend latency metrics (milliseconds).

Class Fields

• TYPE: ClassVar[str] = 'metrics.latency_updated'
• network_latency_ms: int = 0
• asr_latency_ms: int = 0
• llm_first_token_ms: int = 0
• llm_sentence_ms: int = 0
• tts_first_chunk_ms: int = 0

TurnTTSStartRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSStartRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_start_requested'

TurnTTSPauseRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSPauseRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_pause_requested'

TurnTTSResumeRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSResumeRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_resume_requested'

TurnTTSStopRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSStopRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_stop_requested'
• reason: str = ''

TurnTTSFlushRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSFlushRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_flush_requested'

ConsumeLLMAgentGenerationRequested

Defined in xtalk.serving.events.

@dataclass
class ConsumeLLMAgentGenerationRequested(BaseEvent)

Request consumption of one LLM-agent output stream.

Class Fields

• TYPE: ClassVar[str] = 'llm_agent.consume_generation_requested'
• stream: AsyncIterator[AgentOutput]

TurnLLMAgentResumeRequested

Defined in xtalk.serving.events.

@dataclass
class TurnLLMAgentResumeRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.llm_agent_resume_requested'

TurnLLMAgentPauseRequested

Defined in xtalk.serving.events.

@dataclass
class TurnLLMAgentPauseRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.llm_agent_pause_requested'

TurnLLMAgentStopRequested

Defined in xtalk.serving.events.

@dataclass
class TurnLLMAgentStopRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.llm_agent_stop_requested'
• reason: str = ''

TurnASRStartRequested

Defined in xtalk.serving.events.

@dataclass
class TurnASRStartRequested(BaseEvent)

Class Fields

• TYPE: ClassVar[str] = 'turn.asr_start_requested'

TurnASREndRequested

Defined in xtalk.serving.events.

@dataclass
class TurnASREndRequested(BaseEvent)

Indicates hard turn end. ASR model state is reset. Turn moves to next.

Class Fields

• TYPE: ClassVar[str] = 'turn.asr_end_requested'

TurnASRPauseRequested

Defined in xtalk.serving.events.

@dataclass
class TurnASRPauseRequested(BaseEvent)

Used when user indicates a wait, or pauses in the speech. Triggers recognition once. ASR model state is preserved; turn unchanged.

Class Fields

• TYPE: ClassVar[str] = 'turn.asr_pause_requested'

TurnTTSTextAppendRequested

Defined in xtalk.serving.events.

@dataclass
class TurnTTSTextAppendRequested(BaseEvent)

Request to append text into ongoing TTS stream (sim-trans).

Class Fields

• TYPE: ClassVar[str] = 'turn.tts_text_append_requested'
• text: str = ''

SpeakerRecognized

Defined in xtalk.serving.events.

@dataclass
class SpeakerRecognized(BaseEvent)

Speaker-recognition result for frontend display.

Class Fields

• TYPE: ClassVar[str] = 'speaker.recognized'
• speaker_id: str | None = None
• reason: str = ''

TTSModelSwitchRequested

Defined in xtalk.serving.events.

@dataclass
class TTSModelSwitchRequested(BaseEvent)

Request to switch TTS model (IndexTTS / IndexTTS2).

Class Fields

• TYPE: ClassVar[str] = 'tts.model_switch_requested'
• model_type: str = ''
• config: Dict[str, Any] = field(default_factory=dict)

LLMModelSwitchRequested

Defined in xtalk.serving.events.

@dataclass
class LLMModelSwitchRequested(BaseEvent)

Request to switch LLM configuration (ChatOpenAI model/base_url).

Class Fields

• TYPE: ClassVar[str] = 'llm.model_switch_requested'
• model_name: str = ''
• base_url: str = ''
• api_key: str = ''
• extra_body: dict | None = None

ClockSyncReceived

Defined in xtalk.serving.events.

@dataclass
class ClockSyncReceived(BaseEvent)

Clock-sync event for offset calculation.

Class Fields

• TYPE: ClassVar[str] = 'clock.sync_received'
• client_send_ts: float = 0.0
• server_recv_ts: float = 0.0
• client_recv_ts: float = 0.0

SessionConfigReceived

Defined in xtalk.serving.events.

@dataclass
class SessionConfigReceived(BaseEvent)

Client sent per-session configuration (e.g., recording path).

Class Fields

• TYPE: ClassVar[str] = 'session.config_received'
• recording_path: str | None = None

TurnDetectorStopSpeaking

Defined in xtalk.serving.events.

@dataclass
class TurnDetectorStopSpeaking(BaseEvent)

Turn detector determined ai should stop speaking.

Class Fields

• TYPE: ClassVar[str] = 'turn_detector.stop_speaking'

TurnDetectorStartGeneration

Defined in xtalk.serving.events.

@dataclass
class TurnDetectorStartGeneration(BaseEvent)

Turn detector determined ai should start generation.

Class Fields

• TYPE: ClassVar[str] = 'turn_detector.start_generation'