live

type ActivityDetectionPolicy struct {
	Automatic         bool
	StartSensitivity  StartSensitivity
	EndSensitivity    EndSensitivity
	PrefixPaddingMs   int32
	SilenceDurationMs int32
	ActivityHandling  ActivityHandling
	TurnCoverage      TurnCoverage
}

type ActivityHandling string

type Callbacks struct {
	OnStateChange          func(state State)
	OnAudio                func(audio []byte) // Audio chunk to play
	OnText                 func(text string)  // Text for display (speech bubble)
	OnError                func(err error)
	OnInputTranscript      func(text string, done bool) // User speech transcribed
	OnOutputTranscript     func(text string, done bool) // Model speech transcribed
	OnToolCall             func(call ToolCall)
	OnToolCallCancellation func(ids []string)
	OnInterrupted          func() // User interrupted model (barge-in)
	OnSessionEnd           func() // Session ended (error, GoAway failure, or deactivation)
}

type ContextCompressionPolicy struct {
	Enabled       bool
	TriggerTokens int64
	TargetTokens  int64
}

type DeepgramLive struct {
	// Optional overrides; zero values fall back to the package defaults.
	ListenModel   string
	SpeakModel    string
	ThinkProvider string
	ThinkModel    string

	// ThinkEndpointURL + ThinkAPIKey switch the think leg to a bring-your-own
	// LLM deployment. When ThinkEndpointURL is set, the Settings message carries
	// an agent.think.endpoint block so Deepgram calls the operator's own LLM
	// instead of a Deepgram-managed model; ThinkAPIKey (when set) is sent as an
	// "Authorization: Bearer <key>" header on that endpoint. Leave both empty to
	// use Deepgram's managed LLM for ThinkProvider/ThinkModel (no key needed).
	ThinkEndpointURL string
	ThinkAPIKey      string
	// contains filtered or unexported fields
}

type EndSensitivity string

type GeminiLive struct {
	// contains filtered or unexported fields
}

type IdleConfig struct {
	ReminderAfter   time.Duration // Default: 5 minutes
	DeactivateAfter time.Duration // Default: 15 minutes
}

type IdleTimer struct {
	// contains filtered or unexported fields
}

type LiveConfig struct {
	Model string // e.g. "gemini-3.1-flash-live-preview"
	// FallbackModel is tried when the primary Model's Connect fails. Empty
	// disables the fallback. Typical pairing in 2026: a preview model as
	// Model + the last GA model as FallbackModel, so transient preview
	// outages don't take down a Voice Agent deployment.
	FallbackModel    string
	APIKey           string
	Voice            string // Voice name
	FrameworkPrompt  string
	RefinementPrompt string
	VocabularyHint   string
	Locale           string
	// Region is the Google Cloud region the caller's API key / project is
	// pinned to (e.g. "europe-west3", "us-central1"). Used by providers that
	// support regional endpoints. For Gemini Live (as of May 2026) the API
	// exposes a single global WebSocket endpoint, so this field does NOT
	// redirect traffic — it is logged at connect time for compliance evidence
	// (byok.key_updated audit event) and reserved for future regional routing
	// once Google publishes per-region hostnames. Data residency is controlled
	// at the Google Cloud project level; both the project region AND this field
	// must agree for audit records to be accurate.
	// See docs/compliance/byok-gemini-region-pinning.md.
	Region          string
	Policies        LivePolicies
	Tools           []ToolDefinition
	Workflow        *WorkflowConfig
	Speaker         speaker.Options
	Options         provideropts.Values
	ProviderOptions provideropts.Values
}

type LiveInstructionUpdater interface {
	UpdateInstructions(ctx context.Context, cfg LiveConfig) error
}

type LiveMessage struct {
	Audio []byte // PCM audio chunk (24kHz 16-bit mono)
	Text  string // Text transcript (may be partial or empty)
	Done  bool   // True when the model's turn is complete

	// Transcription fields (populated when transcription is enabled).
	InputTranscript        string  // User speech transcribed by server
	InputTranscriptDone    bool    // True when input transcription segment is final
	InputSpeakerLabel      string  // Optional diarized speaker label for input transcript segments
	InputPersonID          string  // Optional known person id for input transcript segments
	InputDisplayName       string  // Optional known display name for input transcript segments
	InputSpeakerConfidence float64 // Optional speaker-label confidence
	OutputTranscript       string  // Model speech transcribed by server
	OutputTranscriptDone   bool    // True when output transcription segment is final

	ToolCalls               []ToolCall
	ToolCallCancellationIDs []string
	Interrupted             bool // True when user interrupted model (barge-in)
	GoAway                  bool // True when server signals imminent session end
}

type LivePolicies struct {
	EnableInputAudioTranscription  bool
	EnableOutputAudioTranscription bool
	EnableAffectiveDialog          bool
	Thinking                       ThinkingPolicy
	ContextCompression             ContextCompressionPolicy
	ActivityDetection              ActivityDetectionPolicy
}

type LiveProvider interface {
	// Connect establishes a WebSocket session to the real-time model.
	Connect(ctx context.Context, cfg LiveConfig) error

	// SendAudio streams PCM audio chunks to the model.
	// Format: 16-bit signed int, little-endian, mono, 16kHz.
	SendAudio(chunk []byte) error

	// SendAudioStreamEnd signals that microphone input for the current turn ended.
	SendAudioStreamEnd() error

	// Receive blocks until the next server message arrives.
	// Returns audio chunks and/or text from the model.
	Receive(ctx context.Context) (*LiveMessage, error)

	// SendText injects a text prompt into the session (for idle reminders).
	SendText(text string) error

	// SendToolResponse sends the result of a host-side tool invocation back to the model.
	SendToolResponse(response ToolResponse) error

	// Close terminates the WebSocket session.
	Close() error

	// Name returns the provider identifier.
	Name() string
}

type LiveReconnector interface {
	Reconnect(ctx context.Context) error
}

type OpenAILive struct {
	// contains filtered or unexported fields
}

type ResolvedLiveOptions struct {
	Locale              string
	Voice               string
	Keyterms            []string
	TurnDetection       bool
	TurnDetectionSource provideropts.ValueSource
	EndpointingMs       int
	EndpointingSource   provideropts.ValueSource
	Effective           provideropts.EffectiveOptions
}

type Session struct {
	// contains filtered or unexported fields
}

type StartSensitivity string

type State string

type ThinkingLevel string

type ThinkingPolicy struct {
	Enabled         bool
	IncludeThoughts bool
	ThinkingBudget  int32
	ThinkingLevel   ThinkingLevel
}

type ToolBehavior string

type ToolCall struct {
	ID   string
	Name string
	Args map[string]any
}

type ToolDefinition struct {
	Name                 string
	Description          string
	ParametersJSONSchema map[string]any
	ResponseJSONSchema   map[string]any
	Behavior             ToolBehavior
}

type ToolResponse struct {
	ID       string
	Name     string
	Response map[string]any

	Scheduling   ToolResponseScheduling
	WillContinue *bool
}

type ToolResponseScheduling string

type TurnCoverage string

type WorkflowConfig struct {
	SequenceID string
	Completion string
	MaxTurns   int
	BasePrompt string
	Steps      []WorkflowStep
	// InitialStep selects the first active step. Out-of-range values fall
	// back to zero.
	InitialStep int
}

type WorkflowStep struct {
	ID           string
	Instruction  string
	ExitCriteria string
	RequireTools []string
	MaxTurns     int
}