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)
	// OnHostPrompt may reject a Started event by returning false. Sent and
	// SendFailed are correlated terminal phases for an accepted prompt; their
	// return values are ignored.
	OnHostPrompt  func(event HostPromptEvent) bool
	OnInterrupted func() // User interrupted model (barge-in)
	OnSessionEnd  func() // Session ended (error, GoAway failure, or deactivation)
}

type CapabilityRequirement struct {
	Capability LiveCapabilityFlag `json:"capability"`
	Required   bool               `json:"required,omitempty"`
}

type ContextCompressionPolicy struct {
	Enabled       bool
	TriggerTokens int64
	TargetTokens  int64
}

type EndSensitivity string

type HostPromptEvent struct {
	ID   uint64
	Kind HostPromptKind
	Type HostPromptEventType
}

type HostPromptEventType string

type HostPromptKind string

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

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

type LatencyProfile string

type LiveCapabilityFlag string

type LiveConfig struct {
	Provider  string // e.g. "google", "deepgram", "assemblyai", "openai"
	ProfileID string // e.g. "realtime.google.gemini-native-audio"
	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
	// BearerToken mints a short-lived bearer token for the connection when
	// the host authenticates with an identity provider (Microsoft Entra on
	// Foundry) instead of a static key. Providers that support it call it at
	// dial time and send "Authorization: Bearer <token>"; when set it wins
	// over APIKey, and providers that require a credential accept either.
	// The framework never acquires tokens itself.
	BearerToken func(ctx context.Context) (string, error)
	// Endpoint overrides the provider's default WebSocket base URL. Providers
	// that speak a shared wire protocol from different hosts use it — e.g.
	// Microsoft Foundry serves the OpenAI Realtime protocol from
	// wss://<account-host>/openai/v1/realtime. Empty keeps the provider's
	// built-in default endpoint. The model/deployment query parameter is
	// appended by the provider; do not include it here.
	Endpoint         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 LiveEndpointReporter interface {
	EndpointURL() string
}

type LiveEventType string

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

type LiveMessage struct {
	EventType        LiveEventType   // Provider-neutral event type for hosts that need precise routing.
	EventTypes       []LiveEventType // All provider-neutral event meanings when a provider combines multiple events in one frame.
	ProviderMetadata map[string]any  // Optional provider-native metadata for debugging and advanced hosts.

	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
	SessionResumable        bool // True when the provider indicates reconnect/resume is possible.
}

type LiveModelDescriptor struct {
	Provider    string                   `json:"provider"`
	ModelID     string                   `json:"modelId"`
	Name        string                   `json:"name"`
	Lifecycle   framework.ModelLifecycle `json:"lifecycle"`
	Default     bool                     `json:"default,omitempty"`
	Recommended bool                     `json:"recommended,omitempty"`
	SourceURL   string                   `json:"sourceUrl"`
}

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 LiveSessionCapabilities interface {
	SessionCapabilities() SessionCapabilities
}

type ModelLifecyclePolicy string

type ProviderDescriptor struct {
	Provider         string                  `json:"provider"`
	DisplayName      string                  `json:"displayName"`
	ProfileID        string                  `json:"profileId"`
	Capabilities     []LiveCapabilityFlag    `json:"capabilities"`
	Models           []LiveModelDescriptor   `json:"models,omitempty"`
	SupportedLocales []string                `json:"supportedLocales,omitempty"`
	NativeOptions    []provideropts.OptionID `json:"nativeOptions,omitempty"`
	AuthRequirement  string                  `json:"authRequirement,omitempty"`
	Transport        string                  `json:"transport,omitempty"`
	EvidenceURL      string                  `json:"evidenceUrl,omitempty"`
}

type ProviderFallback struct {
	Kind                        ProviderFallbackKind     `json:"kind"`
	Provider                    string                   `json:"provider"`
	ProfileID                   string                   `json:"profileId,omitempty"`
	Model                       string                   `json:"model,omitempty"`
	ModelLifecycle              framework.ModelLifecycle `json:"modelLifecycle,omitempty"`
	Reason                      string                   `json:"reason,omitempty"`
	MissingRequiredCapabilities []LiveCapabilityFlag     `json:"missingRequiredCapabilities,omitempty"`
	MissingRequiredOptions      []provideropts.OptionID  `json:"missingRequiredOptions,omitempty"`
	AuthRequirement             string                   `json:"authRequirement,omitempty"`
	Transport                   string                   `json:"transport,omitempty"`
	EvidenceURL                 string                   `json:"evidenceUrl,omitempty"`
}

type ProviderFallbackKind string

type ProviderIntent struct {
	Mode                  string                  `json:"mode,omitempty"`
	Provider              string                  `json:"provider,omitempty"`
	ProfileID             string                  `json:"profileId,omitempty"`
	Model                 string                  `json:"model,omitempty"`
	RequiredCapabilities  []LiveCapabilityFlag    `json:"requiredCapabilities,omitempty"`
	PreferredCapabilities []LiveCapabilityFlag    `json:"preferredCapabilities,omitempty"`
	Requirements          []CapabilityRequirement `json:"requirements,omitempty"`
	RequiredOptions       []provideropts.OptionID `json:"requiredOptions,omitempty"`
	PreferredOptions      []provideropts.OptionID `json:"preferredOptions,omitempty"`
	Locale                string                  `json:"locale,omitempty"`
	LanguageHints         []string                `json:"languageHints,omitempty"`
	PrivacyRedaction      bool                    `json:"privacyRedaction,omitempty"`
	ResumePreferred       bool                    `json:"resumePreferred,omitempty"`
	LatencyProfile        LatencyProfile          `json:"latencyProfile,omitempty"`
	SelectionPolicy       ProviderSelectionPolicy `json:"selectionPolicy,omitempty"`
}

type ProviderIntentError struct {
	Intent                      ProviderIntent          `json:"intent"`
	MissingRequiredCapabilities []LiveCapabilityFlag    `json:"missingRequiredCapabilities,omitempty"`
	MissingRequiredOptions      []provideropts.OptionID `json:"missingRequiredOptions,omitempty"`
	Fallbacks                   []ProviderFallback      `json:"fallbacks,omitempty"`
	RejectedProviders           []ProviderRejection     `json:"rejectedProviders,omitempty"`
}

type ProviderRejection struct {
	Provider                    string                   `json:"provider"`
	ProfileID                   string                   `json:"profileId,omitempty"`
	Model                       string                   `json:"model,omitempty"`
	ModelLifecycle              framework.ModelLifecycle `json:"modelLifecycle,omitempty"`
	FallbackKind                ProviderFallbackKind     `json:"fallbackKind,omitempty"`
	Reason                      string                   `json:"reason"`
	MissingRequiredCapabilities []LiveCapabilityFlag     `json:"missingRequiredCapabilities,omitempty"`
	MissingRequiredOptions      []provideropts.OptionID  `json:"missingRequiredOptions,omitempty"`
	AuthRequirement             string                   `json:"authRequirement,omitempty"`
	Transport                   string                   `json:"transport,omitempty"`
	EvidenceURL                 string                   `json:"evidenceUrl,omitempty"`
	UnsupportedLocale           string                   `json:"unsupportedLocale,omitempty"`
}

type ProviderSelectionPolicy struct {
	PreferredProviders []string             `json:"preferredProviders,omitempty"`
	AllowPreview       bool                 `json:"allowPreview,omitempty"`
	AllowLegacy        bool                 `json:"allowLegacy,omitempty"`
	ModelLifecycle     ModelLifecyclePolicy `json:"modelLifecycle,omitempty"`
}

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

type ResolvedProviderPlan struct {
	Provider                         string                  `json:"provider"`
	ProfileID                        string                  `json:"profileId"`
	Model                            string                  `json:"model"`
	Descriptor                       ProviderDescriptor      `json:"descriptor"`
	ModelDescriptor                  LiveModelDescriptor     `json:"modelDescriptor"`
	SelectionReason                  string                  `json:"selectionReason,omitempty"`
	SelectedFallbackKind             ProviderFallbackKind    `json:"selectedFallbackKind,omitempty"`
	Fallbacks                        []ProviderFallback      `json:"fallbacks,omitempty"`
	RejectedProviders                []ProviderRejection     `json:"rejectedProviders,omitempty"`
	MatchedRequiredCapabilities      []LiveCapabilityFlag    `json:"matchedRequiredCapabilities,omitempty"`
	MatchedPreferredCapabilities     []LiveCapabilityFlag    `json:"matchedPreferredCapabilities,omitempty"`
	UnsupportedPreferredCapabilities []LiveCapabilityFlag    `json:"unsupportedPreferredCapabilities,omitempty"`
	MatchedRequiredOptions           []provideropts.OptionID `json:"matchedRequiredOptions,omitempty"`
	MatchedPreferredOptions          []provideropts.OptionID `json:"matchedPreferredOptions,omitempty"`
	UnsupportedPreferredOptions      []provideropts.OptionID `json:"unsupportedPreferredOptions,omitempty"`
	AuthRequirement                  string                  `json:"authRequirement,omitempty"`
	Transport                        string                  `json:"transport,omitempty"`
	LatencyProfile                   LatencyProfile          `json:"latencyProfile,omitempty"`
}

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

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

type SessionCapabilities struct {
	Provider         string               `json:"provider,omitempty"`
	ProfileID        string               `json:"profileId,omitempty"`
	Model            string               `json:"model,omitempty"`
	Capabilities     []LiveCapabilityFlag `json:"capabilities,omitempty"`
	ProviderMetadata map[string]any       `json:"providerMetadata,omitempty"`
}

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
}