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 is an adapter over the reference app's internal config loader so that Load applies exactly the defaults, legacy-field backfills, and normalisations the desktop app applies — one loader, no drifting reimplementation. Every exported signature uses public types only; the internal imports never leak into the API surface.
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)
}
Output:
Index ¶
- Constants
- func Load(path string) (speechkit.ModeSettings, speechkit.RuntimePolicy, error)
- func ModeSettingsFrom(cfg *Config) speechkit.ModeSettings
- func PolicyFrom(cfg *Config) speechkit.RuntimePolicy
- type Config
- type General
- type ModeSelection
- type ModelSelection
- type ServerConnection
- type TTS
- type Vocabulary
- type VoiceAgent
Examples ¶
Constants ¶
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.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
func Load(path string) (speechkit.ModeSettings, speechkit.RuntimePolicy, error)
Load reads and decodes the SpeechKit TOML config at path — applying the same defaults the reference app applies — and returns the host-facing ModeSettings together with a RuntimePolicy derived from it.
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 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 Parse ¶ added in v0.61.28
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 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