driver

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package driver is the compiled engine an agent runs on: the LLM HTTP client (Host, a host.Host implementation), TTS synthesis + playback, the serial speech queue, and health/Twilio HTTP servers. An agent supplies its particulars — tiers, TTS transport, and a system-prompt provider — through Config and stands the driver up with New. It bakes in no agent identity: prompts and policy come from the caller.

The the engine driver is becoming an HTTP server (design design/aa-server-status.md §7.1, §10): aa-server-status needs a mandatory GET /healthz on :9730 to manage it as a "source" server (§6.1 — health probe is the authoritative "serving" signal). This file is intentionally minimal: just the listener + health route. The full twilio-cli/HTTP command surface is separate, deferred work (design §11) and does not belong here.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvBool

func EnvBool(k string) bool

EnvBool reads a boolean-ish env var: "1"/"true"/"yes"/"on" (any case) is true.

func EnvFloatOr

func EnvFloatOr(k string, def float64) float64

EnvFloatOr reads a float env var, falling back to def when unset or unparseable.

func EnvOr

func EnvOr(k, def string) string

func FilePrompt

func FilePrompt(path, defaultText string) func() string

FilePrompt returns a system-prompt provider (Config.Prompt) that reads path and hot-reloads it when the file's mtime changes, falling back to defaultText (or the last good load) if the file can't be read. Agents that don't want a file can pass any func() string to Config.Prompt instead.

func ParseStreamScheme

func ParseStreamScheme(args []string) (string, error)

ParseStreamScheme parses the -stream-scheme flag, defaulting to "wss" and rejecting any value other than "ws" or "wss" (PRD D15 — the flag itself is validated so an invalid scheme never reaches twilio.Server.StreamScheme). It uses a fresh FlagSet (rather than the package-global flag.CommandLine) so it can be called repeatedly and in isolation from tests.

func StartHealthServer

func StartHealthServer(addr string) *http.Server

StartHealthServer launches the health listener in the background and returns the *http.Server handle so the caller can Shutdown it on exit. A bind failure is reported loudly to stderr but does not crash the driver — aa-server-status will simply see the health probe fail, which is itself the correct signal (design §6.5: runtime errors abort loudly, they don't take the whole program down).

func StartTwilioServer

func StartTwilioServer(addr string, s *twilio.Server) *http.Server

StartTwilioServer launches the Twilio-facing HTTP listener in the background, serving the routes built by newTwilioMux — which is where they are listed, so adding one is not a two-comment edit. Bind failures are reported to stderr but do not crash the process.

Types

type Config

type Config struct {
	Tiers       map[string]Tier
	TTS         TTSConfig
	Prompt      func() string
	UserContext func(queryText string) string // optional user context block injected after system prompt; queryText is what the policy passed to Context

	// RealtimeURL selects the voice transport. Empty — the default — runs the
	// existing VAD/STT/TTS sidecar path and constructs no realtime client. Set
	// to a backend websocket URL, calls run over that backend instead, which
	// also hands it the turn-taking; see twilio.NewStreamHandler for what that
	// bypasses. The engine supplies no default URL: like every other field
	// here, it is the consumer's to inject.
	RealtimeURL string
}

Config is what an agent supplies to stand up a driver: its LLM tiers, TTS transport, and a system-prompt provider. The engine holds none of this by default — a different agent (with its own prompt, tiers, policy) constructs its own Config. Prompt is called every turn; use FilePrompt for a hot-reloading file or supply any func() string (embed, remote, constant).

func (Config) StreamHandler added in v0.3.0

func (c Config) StreamHandler() twilio.StreamHandler

StreamHandler returns the Media Streams handler for the configured transport, for a consumer to install on twilio.Server.HandleStream. It is the one place the transport switch is read.

type Host

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

Host is the driver's concrete host.Host: it turns a (messages, tier) pair into an HTTP call against the tier's llama-server.

func New

func New(cfg Config) *Host

New builds a driver Host from cfg, wiring the serial speech queue internally.

func (*Host) CancelQueued

func (h *Host) CancelQueued()

CancelQueued implements host.Host: drops all pending clips from the speech queue without rendering them. Call alongside Forget() on stream errors so orphaned segments don't play from a rolled-back turn.

func (*Host) Clear

func (h *Host) Clear()

func (*Host) Context

func (h *Host) Context(queryText string) []byte

Context assembles [current system prompt] + optional user context + history into a JSON messages array ready for Send. queryText is handed to the user context provider so its block can depend on the current turn.

func (*Host) Forget

func (h *Host) Forget()

func (*Host) LastAnswer

func (h *Host) LastAnswer() []byte

func (*Host) Remember

func (h *Host) Remember(role string, content []byte)

func (*Host) Send

func (h *Host) Send(contextWindow []byte, tier string) ([]byte, []byte, error)

Send implements host.Host. contextWindow is the already serialized `messages` array; tier is "fast" | "deep". Returns content, reasoning (empty if the model/flags don't emit it), error. It's SendStream without the per-segment callback — the full assembled text is all the caller wants.

func (*Host) SendStream

func (h *Host) SendStream(contextWindow []byte, tier string, onSegment func(string)) ([]byte, []byte, error)

SendStream is like Send but streams the response, calling onSegment each time a punctuation boundary is reached with enough accumulated text. The returned slices are the fully assembled (content, reasoning). Segments are flushed when the buffer crosses ~30 chars and a delimiter (. ? ! , \n) is seen; the delimiter is kept at the end of the segment so the TTS has the punctuation it needs for natural cadence.

func (*Host) Speak

func (h *Host) Speak(text []byte, voice string, speed float64) error

Speak implements host.Host. It queues synthesis+playback on the serial speech worker and returns immediately, so the turn's text prints without waiting for audio; a failure is logged to stderr and never breaks the turn. No cgo — the ONNX runtime lives in the separate `supertonic serve` process; the driver only does an HTTP POST and shells out to afplay.

func (*Host) SpeakSync

func (h *Host) SpeakSync(text []byte, voice string, speed float64) error

SpeakSync is Speak that blocks until playback finishes, so callers can play clips in sequence (used by /voicetest).

func (*Host) SynthesizeWAV added in v0.3.0

func (h *Host) SynthesizeWAV(ctx context.Context, text []byte, voice string, speed float64) ([]byte, error)

SynthesizeWAV fetches synthesized WAV bytes from the TTS server without playing them.

func (*Host) SystemPrompt

func (h *Host) SystemPrompt() string

SystemPrompt implements host.Host: the current system prompt, reloaded from its file only when the file changes.

type TTSConfig

type TTSConfig struct {
	URL    string // .../v1/tts
	Lang   string // ISO code, e.g. "en"
	Format string // wav / flac / ogg — wav plays via afplay
}

TTSConfig is the driver's fixed TTS transport config for Supertonic's native /v1/tts endpoint (the OpenAI-compatible /v1/audio/speech has no speed knob). The tunable per-call settings — voice and speed — are owned by the interpreted policy and passed into Speak, so /voice and /speed change them live.

type Tier

type Tier struct {
	URL, Model string
	Reasoning  bool
	MaxTokens  int
	// APIKey, when non-empty, is sent as "Authorization: Bearer <APIKey>" on
	// this tier's chat request (AATK-112) -- what a hosted OpenAI-compatible
	// API needs and a local llama-server ignores. Empty sends no header.
	APIKey string
	// NoTools, when true, declares an empty tools list on this tier's chat
	// request (AATK-113). This driver is text-only -- it reads content and
	// reasoning and drops tool_calls -- and a tool-trained hosted model that
	// is merely TOLD about capabilities in the prompt will invent a function
	// call and answer nothing. An explicit "tools": [] is what stops it;
	// tool_choice "none" was measured not to. Off by default: the local
	// servers have not been exercised against an empty tools array.
	NoTools bool
}

Tier describes one tier's llama-server. reasoning=false asks the model to skip its thinking trace; maxTokens caps a single turn so a runaway generation can't burn the whole 300s timeout.

type Turn

type Turn struct {
	Text    string
	Speaker string
}

Turn is one unit of user input. Text is the typed line or the transcript; Speaker is who said it (empty until speaker-ID lands — SOP-2 keeps it "").

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL