realtime

type Agent interface {
	// Start opens the underlying transport (WebSocket for current vendors)
	// and configures the session. Returns once the session is ready to
	// receive audio (or with an error before EventSessionOpen fires).
	Start(ctx context.Context) error
	// PushAudio appends one PCM16LE chunk at Options.InputSampleRate.
	// Implementations base64-encode internally as required by the wire
	// protocol. Safe to call from a single goroutine.
	PushAudio(pcm []byte) error
	// CommitInputAudio signals end-of-utterance manually. No-op when
	// server VAD is enabled (the default).
	CommitInputAudio() error
	// Cancel asks the model to stop the current reply (barge-in). The
	// EventAssistantTurnEnd will still fire so callers can drain state
	// machines uniformly.
	Cancel() error
	// Close tears the session down. Idempotent.
	Close() error
	// UpdateInstructions patches session instructions mid-call (e.g. transfer
	// confirm counter). No-op or error if the session is not open.
	UpdateInstructions(instructions string) error
}

type ErrUnknownProvider struct {
	Provider string
}

type Event struct {
	Type    EventType
	Text    string
	Final   bool
	AudioPC []byte // PCM16LE mono @ Options.OutputSampleRate
	Err     error
	Fatal   bool
	// Vendor is the provider slug ("aliyun_omni", …) for logging.
	Vendor string
	// Raw carries the unparsed event JSON for diagnostic logs (optional;
	// implementations may leave nil to avoid the allocation).
	Raw []byte
}

type EventType string

type Options struct {
	// SystemPrompt is sent as the model's `instructions` (Qwen-Omni) or
	// `instructions` field on session.update (GPT-4o realtime).
	SystemPrompt string
	// Voice selects the AI voice. Provider-specific values (Ethan / Cherry
	// for Qwen, alloy / nova for GPT-4o).
	Voice string
	// InputSampleRate is the sample rate of PCM frames passed to PushAudio.
	// Defaults to 16000 if 0.
	InputSampleRate int
	// OutputSampleRate is the rate the provider will emit audio at.
	// Defaults to 24000 if 0.
	OutputSampleRate int
	// OnEvent receives all session events. Required.
	OnEvent func(Event)
	// EnableServerVAD opts in to server-side voice activity detection.
	// When false, caller is responsible for sending response.create /
	// equivalent boundary signals (advanced; not used by SIP attach
	// today). Defaults to true.
	DisableServerVAD bool
	// Modalities selects which output streams the model emits. Empty =
	// vendor default (audio + text). The realtime SIP path always wants
	// audio, but text-only is useful for dry-run tests.
	Modalities []string
	// Temperature controls sampling randomness on the model side. 0
	// means "use vendor default" (caller didn't set it). Provider
	// implementations clamp to their supported range. Lower values
	// produce more deterministic / consistent replies which is what
	// telephony deployments usually want (script adherence > variety).
	Temperature float64
	// Tools are sent in session.update (Qwen3.5-Omni-Realtime Function Calling).
	Tools []Tool
	// ToolHandler runs when the model requests a tool (response.done batch).
	// Return value is sent back as function_call_output. Nil skips tool execution.
	ToolHandler ToolHandler
}

type Provider func(cfg map[string]any, opts Options) (Agent, error)

type Tool struct {
	Name        string
	Description string
	Parameters  json.RawMessage
}

type ToolHandler func(name string, args map[string]any) string