talkie

type Agent interface {
	Respond(ctx context.Context, turn Turn, reply *Reply) error
}

type AgentFunc func(ctx context.Context, turn Turn, reply *Reply) error

type BargeIn int

type CancellerProfile struct {
	// Snapshot is the canceller's state (go-speexdsp's echo.Canceller
	// Snapshot); it restores only into talkie's canceller configuration.
	Snapshot []byte
	// ERLEDB is the echo it removed at the end of training, in dB.
	ERLEDB float64
}

type Config struct {
	// ORTLibrary is the ONNX Runtime library, a path or OS-loader name,
	// shared by every model. A CUDA build is needed for CUDA.
	ORTLibrary string
	// CUDA runs speech-to-text and text-to-speech on GPU DeviceID. The wake
	// word and VAD always run on the CPU.
	CUDA     bool
	DeviceID int

	Parakeet ParakeetConfig
	Kokoro   KokoroConfig

	// WakeWord is the phrase that starts a session, such as "hey computer".
	// Empty disables it: sessions start with Listen or when the agent speaks.
	WakeWord string
	// WakeFAR selects PhonMatchNet's operating point by its target
	// false-accept rate; zero selects 0.01.
	WakeFAR float64

	// OutputRate is the speaker's sample rate; zero selects 48 kHz.
	OutputRate int

	// InputDevice and OutputDevice select the microphone and speaker by
	// name, ignoring case: a device named exactly that, or else the first
	// whose name contains it. PulseAudio's and PipeWire's monitor sources
	// ("Monitor of ...") are skipped unless InputDevice says "monitor", so a
	// USB headset's name selects its microphone. Empty selects the system
	// defaults. OutputRate is the rate both run at.
	InputDevice, OutputDevice string

	// AudioLatency is the audio devices' round trip, from writing a sample
	// to the speaker to hearing it at the microphone. Barge-in waits it out
	// before judging a voice against the agent's echo, and the follow-up
	// window ignores the agent's last words for that long. Zero assumes
	// 100 ms; PipeWire and Bluetooth devices are often slower.
	AudioLatency time.Duration

	// RoomProfileDir is where Run looks for the room profile of its
	// devices; empty selects DefaultProfileDir. IgnoreRoomProfile makes Run
	// use only this Config.
	RoomProfileDir    string
	IgnoreRoomProfile bool

	// Logger, if set, receives the conversation's events at Info level and
	// their details at Debug.
	Logger *slog.Logger

	// OnEvent, if set, receives the conversation's events as they happen:
	// state changes, the wake word, transcripts, replies, interruptions,
	// latency measurements and errors. It is called on Run's goroutine,
	// which also runs the audio: return quickly, and hand anything slow to
	// another goroutine.
	OnEvent func(Event)

	// DisableEchoCancellation turns off the built-in echo canceller
	// (go-speexdsp), for a headset or a microphone that is already
	// echo-cancelled, such as PipeWire's echo-cancel source. Barge-in still
	// verifies interruptions against the predicted echo.
	DisableEchoCancellation bool

	// BargeIn sets how the user can interrupt the agent by voice; the zero
	// value, BargeInWakeWord, allows only the wake word, so the agent's own
	// echo can't interrupt it. Talkie.Interrupt works whatever it is set to.
	BargeIn BargeIn

	// Cues are sounds that say when talkie starts listening, while it
	// thinks, and when the session ends, for a device without a screen; the
	// zero value plays none. DefaultCues has built-in ones.
	Cues Cues

	// DisableReadyChime turns off the short chime Run plays when it starts.
	// Run measures each session's audio latency from the chime's echo,
	// since it can differ between device opens; without it, the latency
	// comes from the room profile until the first reply measures it.
	DisableReadyChime bool
}

type Cues struct {
	// Listening plays when talkie starts listening at the user's request:
	// the wake word, Talkie.Listen opening a session, or Talkie.Interrupt.
	// Follow-up windows after a reply are silent.
	Listening *Sound
	// Thinking loops while the user waits: from ThinkingDelay after they
	// stop talking, through transcription and the agent's work, until the
	// reply starts playing, the user interrupts, or the session ends. It
	// should loop seamlessly. ThinkingDelay is zero for 500 ms, so a quick
	// reply doesn't blip.
	Thinking      *Sound
	ThinkingDelay time.Duration
	// Idle plays when the session ends and talkie waits for the wake word.
	Idle *Sound
}

type EchoProfile struct {
	// Heard is false when the microphone didn't hear the speaker, as with a
	// headset; echo cancellation can then be turned off.
	Heard bool
	// GainDB is the echo's level relative to what the speaker was given,
	// direct path and reverb. At or below -3 dB barge-in works; above 0 dB
	// the echo is louder than the voice that made it, and the user can't be
	// heard over it.
	GainDB float64
	// Clipped reports that the microphone reached full scale during a quiet
	// chirp: its gain is far too high.
	Clipped bool
	// Advice says what to change in the room, or is empty.
	Advice string
}

type Event struct {
	Type EventType
	// Time is when it happened; At is the same moment in the audio stream,
	// since Run started.
	Time time.Time
	At   time.Duration
	// Session is the session it belongs to, empty outside one.
	Session string

	// State and From are the new and previous state, for EventState.
	State, From State
	// Trigger is what opened the session, listening window, utterance or
	// transcript, for EventSessionStarted, EventListening,
	// EventSpeechStarted and EventTranscript.
	Trigger Trigger
	// Reason says why, for EventSessionEnded, EventSpeechDiscarded and
	// EventReplyStopped.
	Reason string
	// Timeout is how long the listening window stays open, for
	// EventListening.
	Timeout time.Duration

	// Text is what the user said, without the wake phrase, for
	// EventTranscript; STT is how long transcribing it took, and Speech how
	// long the user spoke.
	Text        string
	STT, Speech time.Duration

	// Reply identifies the agent's reply, for the EventReply* events and
	// EventInterrupted; Heard, Cut, Unspoken and Played are how far it
	// played, as in Interruption.
	Reply                string
	Heard, Cut, Unspoken string
	Played               time.Duration
	// InterruptedBy and While are what interrupted the agent and what it
	// was doing, StateSpeaking or StateThinking, for EventInterrupted.
	InterruptedBy InterruptedBy
	While         State

	// Latency is the speaker-to-microphone round trip, for EventLatency
	// and EventRoomChanged; LatencySource says how it was measured, and
	// EchoGainDB is the echo's level.
	Latency       time.Duration
	LatencySource LatencySource
	EchoGainDB    float64

	// Err is what failed, for EventError.
	Err error
}

type EventType string

type InterruptedBy string

type Interruption struct {
	Heard    string // sentences that played completely
	Cut      string // the sentence playing when the user interrupted
	Unspoken string // what the agent wrote that never played
	// Played is how long the reply played; zero when the user spoke while
	// the agent was still thinking.
	Played time.Duration
}

type KokoroConfig struct {
	ModelPath  string // kokoro-v1.0.onnx
	VoicesPath string // voices-v1.0.bin
	// Voice is a US (a*) or UK (b*) English voice; empty selects af_heart.
	Voice string
	// Speed is 0.5 to 2; zero selects 1.
	Speed float32
	// FirstChunkPhonemes and MaxChunkPhonemes limit each model run. A run in
	// progress can't be interrupted, so shorter runs make barge-in quicker
	// and start the first sentence sooner. Zero selects 80 and 160.
	FirstChunkPhonemes, MaxChunkPhonemes int
}

type LatencyProfile struct {
	Runs             []time.Duration
	Min, Median, Max time.Duration
}

type LatencySource string

type ParakeetConfig struct {
	// Dir holds nemo128.onnx, encoder-model.onnx (with its .onnx.data) and
	// decoder_joint-model.onnx.
	Dir string
	// INT8 uses encoder-model.int8.onnx and decoder_joint-model.int8.onnx,
	// smaller and faster on CPU.
	INT8 bool
}

type Profile struct {
	Trained time.Time
	// Input and Output are the full names of the microphone and speaker, as
	// the system reports them; Rate is the rate they were trained at.
	Input, Output string
	Rate          int

	// Latency is the speaker-to-microphone round trip.
	Latency LatencyProfile
	// Echo is how loud the speaker is at the microphone.
	Echo EchoProfile
	// NoiseDBFS is the room's background level at the microphone, in dB
	// relative to full scale.
	NoiseDBFS float64
	// Canceller is the echo canceller as it learned the room, or nil when
	// training didn't play speech.
	Canceller *CancellerProfile
	// Wake is the wake word tuned to the user, or nil when training had no
	// wake word.
	Wake *WakeProfile
}

type Prompt func(ctx context.Context, step Step) error

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

type Sound struct {
	Samples []float32
	Rate    int
}

type State string

type Step struct {
	Name        string // "noise", "echo", "canceller", "wake", "speech"
	Instruction string // what to tell the user
}

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

type Then string

type Trigger string

type Turn struct {
	Session string  // the conversation it belongs to
	Reply   string  // the reply's ID, as in Event.Reply
	Text    string  // what the user said, with any leading wake phrase removed
	Trigger Trigger // what opened the utterance
	// Interrupted is set when the user cut off the previous reply to say
	// this. Agents that keep a history should replace the reply they wrote
	// with what was heard.
	Interrupted *Interruption
}

type WakeProfile struct {
	// Keyword is the wake word it was trained for; Run uses Threshold only
	// for the same wake word.
	Keyword string
	// Threshold is the PhonMatchNet score at or above which the wake word
	// is heard, between the user saying it and the user's ordinary speech;
	// zero when training couldn't separate them, and PhonMatchNet's default
	// operating point is kept.
	Threshold float64
	// Positives are the scores of the times the user said the wake word;
	// NegativeMax is the highest score anywhere in their ordinary speech.
	// The threshold sits below all but one in five of the positives.
	Positives   []float64
	NegativeMax float64
	// Advice says what to change, or is empty.
	Advice string
}