hostconfig

package
v0.68.13 Latest Latest
Warning

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

 Go to latest Published: Sep 3, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package hostconfig turns a SpeechKit TOML configuration file into the public SDK types an embedding host drives the framework with: a speechkit.ModeSettings (which modes are on, their hotkeys and selected provider profiles) and a permissive speechkit.RuntimePolicy (which modes the host exposes and whether fallbacks are allowed).

Without this package a library host has to build ModeSettings by hand from a parsed config, the way the reference Windows app does internally. Load does that wiring once so a host can go from a config.toml on disk to a ready-to-validate ModeSettings/RuntimePolicy pair in a single call: 

settings, policy, err := hostconfig.Load("config.toml")

Hosts that load or synthesise configuration themselves construct a public Config (directly, or from raw TOML via Parse) and hand it to ModeSettingsFrom and PolicyFrom.

The conversion is intentionally kernel-clean. It maps the embedder-relevant fields only; the reference desktop app additionally introspects the host secret store to report whether a server bearer token env var is set, which is a device-UI concern and is deliberately left out here.

Boundary note: this package owns the loader semantics for the tables it reads — Defaults, the legacy-field backfills and value normalisation in Normalize. The reference desktop app's internal config loader delegates to the same functions for those fields, so Load and the desktop app agree by construction rather than by a parallel reimplementation. The package imports no internal/* code.

Example

Example shows the one-call path from a config.toml on disk to the public ModeSettings and RuntimePolicy an embedding host drives the framework with. 

package main

import (
	"fmt"
	"log"

	"github.com/kombifyio/SpeechKit/pkg/speechkit/hostconfig"
)

func main() {
	settings, policy, err := hostconfig.Load("config.toml")
	if err != nil {
		log.Fatal(err)
	}

	// settings tells the host which modes are on and which provider profiles
	// they use; policy is a starting point the host can tighten before
	// validating selections with speechkit.ValidateModeSettingsForPolicy.
	fmt.Println("dictation enabled:", settings.Dictation.Enabled)
	fmt.Println("enabled modes:", policy.EnabledModes)
}

Index

Examples

Constants

View Source 
const (
	ModeSourceLocal  = "local"
	ModeSourceServer = "server"
)

Mode source values for ModeSelection.ModeSource. "local" runs the mode against the in-process framework kernel (the default); "server" routes the mode through Config.ServerConnection to a remote speechkit-server.

View Source 
const (
	// HotkeyBehaviorHoldToTalk is "hold the shortcut while you speak, release
	// to end". The historical push_to_talk spelling is accepted as an alias.
	HotkeyBehaviorHoldToTalk = "hold_to_talk"
	HotkeyBehaviorToggle     = "toggle"

	VoiceAgentCloseBehaviorContinue = "continue"
	VoiceAgentCloseBehaviorNewChat  = "new_chat"

	ServerConnectionAuthModeBearer = "bearer"
	ServerConnectionAuthModeAPIKey = "api_key"
	// ServerConnectionAuthModeEdgeBeta sends no shared server credential; the
	// client identifies the installation to a managed edge broker with
	// per-install headers instead.
	ServerConnectionAuthModeEdgeBeta = "edge_beta"

	DefaultBearerTokenEnv       = "SPEECHKIT_SERVER_TOKEN" //nolint:gosec // env var name, not a credential
	DefaultBetaInstallIDEnv     = "SPEECHKIT_BETA_INSTALL_ID"
	DefaultBetaInstallSecretEnv = "SPEECHKIT_BETA_INSTALL_SECRET"

	// Default*PrimaryProfileID are the fresh-install selections per mode. All
	// three resolve to the local-only path, so a config without
	// [model_selection] runs with zero cloud keys.
	DefaultDictatePrimaryProfileID    = "stt.local.whispercpp"
	DefaultAssistPrimaryProfileID     = "assist.builtin.gemma4-e4b"
	DefaultVoiceAgentPrimaryProfileID = "realtime.builtin.pipeline"

	DefaultDictateHotkey    = "ctrl+win"
	DefaultAssistHotkey     = "win+alt"
	DefaultVoiceAgentHotkey = "ctrl+shift"

	// DefaultVoiceAgentProfileID is the built-in voice-agent behaviour profile
	// an empty agent_profile_id resolves to. Non-empty ids pass through
	// unchanged; which ids exist is the host's behaviour catalog.
	DefaultVoiceAgentProfileID = "default"
)

Canonical values for the embedder-relevant enumerations. The reference desktop app and the server read the same constants through this package, so a TOML value is normalised identically wherever it is loaded.

Variables

View Source 
var ErrMalformedConfig = errors.New("hostconfig: malformed config")

ErrMalformedConfig wraps TOML decode failures from Load.

Functions

func Load 

func Load(path string) (speechkit.ModeSettings, speechkit.RuntimePolicy, error)

Load reads and decodes the SpeechKit TOML config at path over Defaults, applies Normalize, and returns the host-facing ModeSettings together with a RuntimePolicy derived from it. A missing file yields the defaults; a malformed file returns an error wrapping ErrMalformedConfig. Use LoadConfig to keep the intermediate Config. Unlike the desktop app, an empty path is not resolved to the app's per-user config location; the host decides where its configuration lives.

The returned policy enables exactly the modes turned on in config and allows fallback profiles only when the config actually pins one. It leaves AllowedProfiles and FixedProfiles empty (meaning "all") so the host can tighten the policy further before calling speechkit.ValidateModeSettingsForPolicy.

func ModeSettingsFrom 

func ModeSettingsFrom(cfg *Config) speechkit.ModeSettings

ModeSettingsFrom converts a Config into the public ModeSettings shape, applying the embedder-relevant normalisation: profile IDs are canonicalised, an empty primary selection falls back to the built-in default profile for that mode, a fallback identical to its primary is dropped, and mode source and auth mode normalise their documented defaults. A nil cfg yields the zero ModeSettings.

Example

ExampleModeSettingsFrom converts a host-constructed Config — useful for hosts that load or synthesise configuration themselves. An empty primary selection is filled with the built-in default profile. 

package main

import (
	"fmt"

	"github.com/kombifyio/SpeechKit/pkg/speechkit/hostconfig"
)

func main() {
	cfg := &hostconfig.Config{}
	cfg.General.AssistEnabled = true
	cfg.General.AssistHotkey = "ctrl+alt+a"

	settings := hostconfig.ModeSettingsFrom(cfg)
	fmt.Println(settings.Assist.Enabled, settings.Assist.Hotkey, settings.Assist.PrimaryProfileID)
}

Output:
true ctrl+alt+a assist.builtin.gemma4-e4b

func Normalize added in v0.67.14 

func Normalize(cfg *Config, defined KeyDefined, legacy LegacyGeneral)

Normalize applies the shared legacy backfills and value normalisation to cfg in place. It is the single definition of "what a decoded config means" for the embedder-relevant tables; Load calls it, and the reference app's internal loader delegates to it for the same fields.

defined answers whether a key was explicitly present; nil is treated as "everything was defined", which disables the presence-dependent backfills. legacy supplies the removed [general] keys (zero value when none).

func NormalizeHotkeyBehavior added in v0.67.14 

func NormalizeHotkeyBehavior(value, fallback string) string

NormalizeHotkeyBehavior canonicalises a hotkey behavior value, accepting the legacy push_to_talk alias. Unknown values resolve to fallback, and an unknown fallback (or one equal to the unknown value) to hold-to-talk.

func NormalizeServerConnectionAuthMode added in v0.67.14 

func NormalizeServerConnectionAuthMode(mode string) string

NormalizeServerConnectionAuthMode canonicalises the [server_connection] auth mode; anything unrecognised is bearer.

func NormalizeVoiceAgentCloseBehavior added in v0.67.14 

func NormalizeVoiceAgentCloseBehavior(value, fallback string) string

NormalizeVoiceAgentCloseBehavior canonicalises what happens to the conversation when the voice agent window closes.

func PolicyFrom 

func PolicyFrom(cfg *Config) speechkit.RuntimePolicy

PolicyFrom derives a permissive RuntimePolicy from a Config: it enables the modes turned on in [general] and allows fallbacks only if any mode pins a fallback profile. AllowedProfiles and FixedProfiles are left empty (meaning "all"), so a host can lock the policy down further. A nil cfg yields the zero RuntimePolicy.

Note: if config enables no modes at all, EnabledModes is empty, which SpeechKit treats as "all modes enabled". Set an explicit policy if you need a hard mode lockout.

Types

type Config added in v0.61.28 

type Config struct {
	General          General          `toml:"general"`
	ModelSelection   ModelSelection   `toml:"model_selection"`
	Vocabulary       Vocabulary       `toml:"vocabulary"`
	TTS              TTS              `toml:"tts"`
	VoiceAgent       VoiceAgent       `toml:"voice_agent"`
	ServerConnection ServerConnection `toml:"server_connection"`
}

Config is the embedder-relevant subset of the SpeechKit TOML configuration. It carries exactly the tables Load and ModeSettingsFrom read; the reference desktop app's full configuration file decodes into it losslessly for these tables, and unknown tables or keys are simply ignored.

Hosts can obtain a Config three ways: Load reads a config.toml with the reference app's defaults and compatibility backfills applied, Parse decodes raw TOML bytes verbatim, and literal construction works for hosts that synthesise their configuration programmatically.

func Defaults added in v0.67.14 

func Defaults() *Config

Defaults returns the shipped defaults for the embedder-relevant tables: dictation on with the local Whisper profile, assist and voice agent off, hold-to-talk hotkeys, TTS on, session summary on, server connection off with bearer auth. It is the starting point Load decodes a file over.

func LoadConfig added in v0.67.14 

func LoadConfig(path string) (*Config, error)

LoadConfig reads the TOML file at path over Defaults and applies Normalize. A missing file yields the normalised defaults; a file that fails to decode returns an error wrapping ErrMalformedConfig rather than silently falling back — a library host should see a broken config, not run on defaults.

func Parse added in v0.61.28 

func Parse(data []byte) (*Config, error)

Parse decodes raw TOML bytes into a Config. Unknown tables and keys are ignored, so the reference app's full config.toml parses cleanly.

Parse decodes the file verbatim: it does not apply the reference app's defaults, legacy-field backfills, or registry policy overlay — use Load for full compatibility with configs written by the desktop app. The embedder-relevant normalisation (profile-ID canonicalisation, default primary profiles, mode-source and auth-mode fallbacks) is applied later by ModeSettingsFrom and PolicyFrom either way.

Example

ExampleParse decodes raw TOML bytes into the public Config. Unknown tables (the reference app's full config carries many more) are ignored. 

package main

import (
	"fmt"
	"log"

	"github.com/kombifyio/SpeechKit/pkg/speechkit/hostconfig"
)

func main() {
	cfg, err := hostconfig.Parse([]byte(`
[general]
dictate_enabled = true
dictate_hotkey = "ctrl+alt+d"
`))
	if err != nil {
		log.Fatal(err)
	}

	settings := hostconfig.ModeSettingsFrom(cfg)
	fmt.Println(settings.Dictation.Enabled, settings.Dictation.Hotkey)
}

Output:
true ctrl+alt+d

type General added in v0.61.28 

type General struct {
	DictateEnabled           bool   `toml:"dictate_enabled"`
	AssistEnabled            bool   `toml:"assist_enabled"`
	VoiceAgentEnabled        bool   `toml:"voice_agent_enabled"`
	DictateHotkey            string `toml:"dictate_hotkey"`
	AssistHotkey             string `toml:"assist_hotkey"`
	VoiceAgentHotkey         string `toml:"voice_agent_hotkey"`
	DictateHotkeyBehavior    string `toml:"dictate_hotkey_behavior"`
	AssistHotkeyBehavior     string `toml:"assist_hotkey_behavior"`
	VoiceAgentHotkeyBehavior string `toml:"voice_agent_hotkey_behavior"`
}

General mirrors the embedder-relevant [general] switches: which modes are enabled and how they are activated.

type KeyDefined added in v0.67.14 

type KeyDefined func(keys ...string) bool

KeyDefined reports whether the given TOML key path was present in the decoded document (as opposed to filled by defaults). Load passes toml.MetaData.IsDefined; hosts that decode elsewhere pass their own.

type LegacyGeneral added in v0.67.14 

type LegacyGeneral struct {
	Hotkey      string `toml:"hotkey"`
	AgentHotkey string `toml:"agent_hotkey"`
	AgentMode   string `toml:"agent_mode"`
	HotkeyMode  string `toml:"hotkey_mode"`
}

LegacyGeneral carries the removed [general] keys older config files may still set. Normalize folds them into the current fields; they are never part of Config itself.

type ModeSelection added in v0.61.28 

type ModeSelection struct {
	PrimaryProfileID  string `toml:"primary_profile_id"`
	FallbackProfileID string `toml:"fallback_profile_id"`

	// ModeSource selects whether this mode runs locally (framework kernel
	// in-process, default) or against a remote SpeechKit Server-Target
	// configured under [server_connection]. Empty is treated as
	// [ModeSourceLocal] so a missing TOML field never silently means
	// "server"; read it through [ModeSelection.ResolvedModeSource].
	ModeSource string `toml:"mode_source"`
}

ModeSelection pins the provider profile (and optional fallback) one mode runs with, and whether the mode executes locally or against a remote server.

func (ModeSelection) ResolvedModeSource added in v0.61.28 

func (sel ModeSelection) ResolvedModeSource() string

ResolvedModeSource returns the effective mode source, normalising the empty default to ModeSourceLocal.

type ModelSelection added in v0.61.28 

type ModelSelection struct {
	Dictate    ModeSelection `toml:"dictate"`
	Assist     ModeSelection `toml:"assist"`
	VoiceAgent ModeSelection `toml:"voice_agent"`
}

ModelSelection carries the per-mode provider profile selection.

type ServerConnection added in v0.61.28 

type ServerConnection struct {
	Enabled              bool   `toml:"enabled"`
	URL                  string `toml:"url"`
	BearerTokenEnv       string `toml:"bearer_token_env"`
	AuthMode             string `toml:"auth_mode"`
	BetaInstallIDEnv     string `toml:"beta_install_id_env"`
	BetaInstallSecretEnv string `toml:"beta_install_secret_env"`
	FallbackToLocal      bool   `toml:"fallback_to_local"`
	RequestTimeoutSec    int    `toml:"request_timeout_sec"`
}

ServerConnection mirrors the [server_connection] table. The bearer token value is never part of configuration — only the env var name is carried.

type TTS added in v0.61.28 

type TTS struct {
	Enabled bool `toml:"enabled"`
}

TTS mirrors the embedder-relevant [tts] switch. Provider-level TTS detail stays host-owned; the mode mapping only needs to know whether spoken output is on.

type Vocabulary added in v0.61.28 

type Vocabulary struct {
	Dictionary string `toml:"dictionary"`
}

Vocabulary mirrors the embedder-relevant [vocabulary] fields.

type VoiceAgent added in v0.61.28 

type VoiceAgent struct {
	EnableSessionSummary bool   `toml:"enable_session_summary"`
	PipelineFallback     bool   `toml:"pipeline_fallback"`
	CloseBehavior        string `toml:"close_behavior"`
	AgentProfileID       string `toml:"agent_profile_id"`
	AgentSequenceID      string `toml:"agent_sequence_id"`
}

VoiceAgent mirrors the embedder-relevant [voice_agent] fields.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.