core

package
v0.40.7 Latest Latest
Warning

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

Go to latest
Published: May 28, 2026 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Overview

Package core is the SpeechKit server bootstrap layer. It owns process-level state (config, routers, registries, lifecycle) and wires the HTTP mux that each mode package hangs its handlers off.

M1 scope: HTTP listener, /healthz, /readyz, signal handling, middleware chain. STT/TTS/Voice-Agent wiring comes in M2–M4 as those modes come online.

Index

Constants

View Source
const (
	ProviderGemini   = "gemini"
	ProviderOpenAI   = "openai"
	ProviderCascaded = "cascaded"
	ProviderMoshi    = "moshi"
)

Supported provider strings for cfg.VoiceAgent.Provider.

Variables

This section is empty.

Functions

func NotifySignals

func NotifySignals(parent context.Context) (context.Context, context.CancelFunc)

NotifySignals wraps signal.NotifyContext for SIGINT + SIGTERM. Calling the returned stop func is idempotent and safe from defer.

func ResolveModelDir

func ResolveModelDir(configured string) (string, error)

ResolveModelDir returns the configured model directory, creating it if it does not exist. Used by whisper.cpp for downloaded model artifacts.

func ResolveWhisperBinary

func ResolveWhisperBinary(configured string) (string, error)

ResolveWhisperBinary returns the path to the whisper.cpp server binary, preferring the configured value and falling back to well-known Linux paths. Returns an error if no candidate exists on disk.

Kept in a Linux-only file so the Windows desktop build does not pick up these conventions.

func Run

func Run(ctx context.Context, cfg *config.Config, opts RunOptions) error

Run boots the server, blocks until ctx is cancelled or the listener fails, and performs graceful shutdown. The caller is responsible for cancelling ctx on SIGTERM/SIGINT (see NotifySignals).

Types

type App

type App struct {
	Cfg            *config.Config
	Mux            *http.ServeMux
	Health         *HealthRegistry
	Modes          map[Mode]bool
	Lifecycle      *lifecycle.Registry
	SharedDeps     *lifecycle.SharedDepRegistry
	Version        string
	AuthState      *middleware.AuthState
	STTRouter      *router.Router
	AssistPipeline *assistpkg.Pipeline

	// Shared AI deps — populated by ensureSharedAIDeps on demand.
	GenkitRuntime *ai.Runtime
	AssistFlow    *genkitcore.Flow[flows.AssistInput, flows.AssistOutput, struct{}]
	AgentFlow     *genkitcore.Flow[flows.AgentInput, flows.AgentOutput, struct{}]
	TTSRouter     *tts.Router
	TTSEnabled    bool

	// PersonaRegistry holds the in-memory persona / role / sequence catalog.
	// Populated by ensurePersonaRegistry — loaded from TOML seeds at boot;
	// admin CRUD writes land here too (M5a). Durable persistence is
	// attached via a Persister when the store supports it (M5b).
	PersonaRegistry *persona.Registry

	// Store is the durable backend for transcriptions, quick notes, voice
	// agent session summaries, and — since M5b — the persona catalog.
	// Nil when the server is configured without a store.
	Store store.Store
	// contains filtered or unexported fields
}

App is the process-wide dependency bundle. Mode packages receive it and register their handlers against app.Mux.

Shared AI dependencies (Genkit runtime, TTS router, Agent flow) are built lazily via ensureSharedAIDeps so Assist and Cascaded-VoiceAgent share one Genkit instance instead of paying init cost twice.

func (*App) ModeEnabled

func (a *App) ModeEnabled(m Mode) bool

ModeEnabled reports whether the given mode is active for this process.

type ComponentOptions added in v0.31.0

type ComponentOptions struct {
	Blocking bool
	Kind     string
	Modes    []string
	Provider string
}

type ComponentStatus

type ComponentStatus string

ComponentStatus describes a single component's health.

const (
	// StatusOK means the component is fully available.
	StatusOK ComponentStatus = "ok"
	// StatusDegraded means the component is reachable but reporting errors.
	StatusDegraded ComponentStatus = "degraded"
	// StatusUnavailable means the component cannot be used.
	StatusUnavailable ComponentStatus = "unavailable"
	// StatusDisabled means the component is intentionally turned off by
	// configuration. Unlike StatusUnavailable this is a deliberate
	// operator choice, not a failure, so it does not degrade strict
	// readiness.
	StatusDisabled ComponentStatus = "disabled"
	// StatusStarting means the component is initializing and not yet ready.
	StatusStarting ComponentStatus = "starting"
)

type HealthRegistry

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

HealthRegistry tracks the readiness of named components. The server binary starts in "starting" state and mode packages flip their components to "ok" (or "unavailable") once their bootstrap completes.

func NewHealthRegistry

func NewHealthRegistry() *HealthRegistry

NewHealthRegistry returns an empty registry.

func (*HealthRegistry) ReadinessSnapshot added in v0.31.0

func (r *HealthRegistry) ReadinessSnapshot() (overall ComponentStatus, components map[string]componentEntry, uptimeSeconds int64)

func (*HealthRegistry) SetReady

func (r *HealthRegistry) SetReady(name string, status ComponentStatus, detail string)

SetReady records or updates a component's status.

func (*HealthRegistry) SetReadyWithOptions added in v0.31.0

func (r *HealthRegistry) SetReadyWithOptions(name string, status ComponentStatus, detail string, opts ComponentOptions)

func (*HealthRegistry) Snapshot

func (r *HealthRegistry) Snapshot() (overall ComponentStatus, components map[string]componentEntry, uptimeSeconds int64)

Snapshot returns a copy of the current component map plus strict readiness. Strict readiness is "ok" iff every component is "ok"; otherwise the worst individual status wins (starting < degraded < unavailable).

type Mode

type Mode string

Mode identifies a server mode toggle.

const (
	ModeDictation  Mode = "dictation"
	ModeAssist     Mode = "assist"
	ModeVoiceAgent Mode = "voiceagent"
)

type RunOptions

type RunOptions struct {
	Version string
	// HandlerHooks lets tests inject extra routes onto the mux before the
	// server starts listening. Production leaves this nil.
	HandlerHooks func(mux *http.ServeMux, app *App)
}

RunOptions exposes bootstrap-time knobs that don't belong in config.toml.

Jump to

Keyboard shortcuts

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