gateway

type AudioConverter interface {
	// Convert converts audio from the source format to the target format.
	Convert(audio []byte, from, to format.AudioFormat) ([]byte, error)
}

type AudioFormat = format.AudioFormat

type BridgeConfig struct {
	// Provider is the realtime provider to use.
	Provider realtime.Provider

	// ProcessConfig is passed to the provider's ProcessAudioStream.
	ProcessConfig realtime.ProcessConfig

	// FromFormat is the telephony audio format (e.g., format.Twilio).
	FromFormat format.AudioFormat

	// ToFormat is the realtime provider's format (e.g., format.OpenAI).
	ToFormat format.AudioFormat

	// BufferSize is the size of audio channel buffers (default: 100).
	BufferSize int
}

type CallHandler func(call *CallInfo) error

type CallInfo struct {
	CallID    string
	From      string
	To        string
	Direction string
	StartTime time.Time
}

type Config struct {
	// Server configuration
	ListenAddr string // e.g., ":8080"
	PublicURL  string // e.g., "https://your-server.com"

	// Pipeline mode selection
	// Default: PipelineModeText if RealtimeProvider is nil
	Mode PipelineMode

	// Text pipeline configuration (used when Mode == PipelineModeText)
	STTProvider string
	STTAPIKey   string
	STTModel    string
	STTLanguage string

	TTSProvider string
	TTSAPIKey   string
	TTSVoiceID  string
	TTSModel    string

	LLMProvider     string
	LLMAPIKey       string
	LLMModel        string
	LLMSystemPrompt string

	// Realtime pipeline configuration (used when Mode == PipelineModeRealtime)
	// Provide either RealtimeProvider directly, or RealtimeConfig to create one.
	RealtimeProvider realtime.Provider
	RealtimeConfig   *RealtimeConfig

	// Session configuration
	MaxSessionDuration time.Duration
	InterruptionMode   string // "immediate", "after_sentence", "disabled"

	// Logging
	Logger *slog.Logger
}

type Event struct {
	Type      EventType `json:"type"`
	Timestamp time.Time `json:"timestamp"`
	Data      any       `json:"data,omitempty"`
	Error     error     `json:"error,omitempty"`
}

type EventType string

type Gateway interface {
	// Name returns the provider name.
	Name() ProviderName

	// Start starts the gateway server.
	Start(ctx context.Context) error

	// Stop gracefully shuts down the gateway.
	Stop() error

	// OnCall sets the handler for incoming calls.
	OnCall(handler CallHandler)

	// MakeCall initiates an outbound call.
	MakeCall(ctx context.Context, to string) (Session, error)

	// GetSession retrieves an active session by call ID.
	GetSession(callID string) (Session, bool)

	// ListSessions returns all active sessions.
	ListSessions() []Session
}

type LLMProvider interface {
	// Generate produces a response given user input and conversation history.
	Generate(ctx context.Context, input string, history []Turn) (response string, toolCalls []ToolCall, err error)
}

type Metrics struct {
	SessionDurationMs     int   `json:"session_duration_ms"`
	TurnCount             int   `json:"turn_count"`
	UserSpeechDurationMs  int   `json:"user_speech_duration_ms"`
	AgentSpeechDurationMs int   `json:"agent_speech_duration_ms"`
	AvgSTTLatencyMs       int   `json:"avg_stt_latency_ms"`
	AvgLLMLatencyMs       int   `json:"avg_llm_latency_ms"`
	AvgTTSLatencyMs       int   `json:"avg_tts_latency_ms"`
	AvgTotalLatencyMs     int   `json:"avg_total_latency_ms"`
	InterruptionCount     int   `json:"interruption_count"`
	ToolCallCount         int   `json:"tool_call_count"`
	ErrorCount            int   `json:"error_count"`
	AudioBytesReceived    int64 `json:"audio_bytes_received"`
	AudioBytesSent        int64 `json:"audio_bytes_sent"`
}

type ParticipantHandler func(participant *ParticipantInfo) error

type ParticipantInfo struct {
	// Identity is the unique identifier for the participant.
	Identity string

	// DisplayName is the human-readable name.
	DisplayName string

	// RoomName is the room the participant joined.
	RoomName string

	// Metadata is optional JSON metadata attached to the participant.
	Metadata string

	// JoinedAt is when the participant joined.
	JoinedAt time.Time
}

type PipelineMode string

type ProviderName string

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

type RealtimeConfig struct {
	// Provider is the realtime provider name ("openai" or "gemini").
	Provider string `json:"provider"`

	// APIKey is the API key for the realtime provider.
	APIKey string `json:"api_key"`

	// Model is the model to use (e.g., "gpt-4o-realtime-preview-2024-12-17").
	Model string `json:"model,omitempty"`

	// Voice is the voice for audio output (e.g., "alloy", "Puck").
	Voice string `json:"voice,omitempty"`

	// Instructions is the system prompt for the conversation.
	Instructions string `json:"instructions,omitempty"`

	// Functions are tools the model can call during conversation.
	Functions []realtime.FunctionDeclaration `json:"functions,omitempty"`

	// OnFunctionCall handles function calls from the model.
	// If nil, function calls are ignored.
	OnFunctionCall func(id, name, args string) (result any, err error) `json:"-"`

	// Temperature controls response randomness (0-2).
	Temperature float64 `json:"temperature,omitempty"`
}

type RealtimeProviderFactory interface {
	// Create creates a realtime provider from the given configuration.
	Create(config *RealtimeConfig) (realtime.Provider, error)

	// Name returns the provider name (e.g., "openai", "gemini").
	Name() string
}

type RoomInfo struct {
	// Name is the room identifier.
	Name string

	// ParticipantCount is the number of participants in the room.
	ParticipantCount int

	// CreatedAt is when the room was created.
	CreatedAt time.Time

	// Metadata is optional JSON metadata attached to the room.
	Metadata string
}

type Session interface {
	// ID returns the session identifier.
	ID() string

	// From returns the caller phone number.
	From() string

	// To returns the called phone number.
	To() string

	// Direction returns "inbound" or "outbound".
	Direction() string

	// StartTime returns when the session started.
	StartTime() time.Time

	// Duration returns the session duration.
	Duration() time.Duration

	// Events returns a channel for session events.
	Events() <-chan Event

	// Transcript returns the conversation transcript.
	Transcript() []Turn

	// Metrics returns session performance metrics.
	Metrics() Metrics

	// SendText sends text input to the agent (bypasses STT).
	SendText(text string) error

	// Interrupt stops the current agent speech.
	Interrupt()

	// Close ends the session.
	Close() error
}

type ToolCall struct {
	Name       string         `json:"name"`
	Arguments  map[string]any `json:"arguments"`
	Result     string         `json:"result"`
	Error      string         `json:"error,omitempty"`
	DurationMs int            `json:"duration_ms"`
}

type Turn struct {
	Role       string     `json:"role"` // "user" or "agent"
	Text       string     `json:"text"`
	Timestamp  time.Time  `json:"timestamp"`
	DurationMs int        `json:"duration_ms"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
}

type WebRTCConfig struct {
	// Server URL (e.g., "wss://your-app.livekit.cloud")
	ServerURL string

	// API credentials
	APIKey    string
	APISecret string

	// Room configuration
	RoomName      string
	AgentIdentity string
	AgentName     string

	// Audio configuration
	SampleRate int // 16000 or 24000 (default: 24000)
	Channels   int // 1 for mono (default: 1)

	// Voice pipeline configuration
	STTProvider string
	STTAPIKey   string
	STTModel    string
	STTLanguage string

	TTSProvider string
	TTSAPIKey   string
	TTSVoiceID  string
	TTSModel    string

	LLMProvider     string
	LLMAPIKey       string
	LLMModel        string
	LLMSystemPrompt string

	// Session configuration
	MaxSessionDuration time.Duration
	InterruptionMode   string // "immediate", "after_sentence", "disabled"
}

type WebRTCGateway interface {
	// Name returns the provider name.
	Name() ProviderName

	// Start connects to the room and starts handling participants.
	Start(ctx context.Context) error

	// Stop disconnects from the room and cleans up.
	Stop() error

	// OnParticipantJoined sets the handler for when participants join.
	// Return nil to accept the participant, or an error to ignore them.
	OnParticipantJoined(handler ParticipantHandler)

	// JoinRoom joins a specific room. Some implementations may join
	// automatically on Start() based on configuration.
	JoinRoom(ctx context.Context, roomName string) error

	// LeaveRoom leaves the current room.
	LeaveRoom() error

	// CurrentRoom returns the name of the currently joined room, or empty string.
	CurrentRoom() string

	// GetSession retrieves an active session by participant identity.
	GetSession(participantID string) (WebRTCSession, bool)

	// ListSessions returns all active sessions.
	ListSessions() []WebRTCSession

	// GenerateClientToken creates a JWT token for a client to join a room.
	GenerateClientToken(roomName, identity, displayName string) (string, error)
}

type WebRTCSession interface {
	// ID returns the session identifier (typically participant identity).
	ID() string

	// Participant returns information about the remote participant.
	Participant() *ParticipantInfo

	// RoomName returns the room this session is in.
	RoomName() string

	// AgentIdentity returns the identity of the AI agent.
	AgentIdentity() string

	// StartTime returns when the session started.
	StartTime() time.Time

	// Duration returns the session duration.
	Duration() time.Duration

	// Events returns a channel for session events.
	// Uses the same Event type as PSTN sessions.
	Events() <-chan Event

	// Transcript returns the conversation transcript.
	Transcript() []Turn

	// Metrics returns session performance metrics.
	Metrics() Metrics

	// SendText sends text input to the agent (bypasses STT).
	SendText(text string) error

	// SendAudio sends PCM16 audio samples to the participant.
	// This is the raw audio output method for WebRTC.
	SendAudio(samples []int16) error

	// Interrupt stops the current agent speech.
	Interrupt()

	// Close ends the session.
	Close() error
}