SpeechKit

SpeechKit

SpeechKit is a local-first voice framework, server, device runtime, and the home of the shared voice contracts. The kernel is platform-neutral Go and can be embedded directly, run as a self-hosted server, or used through a device client.

Beta. Public APIs, config keys, and defaults can still change between minor releases. Use it in production only with version pins. Pre-1.0 releases use the v0.MAJOR.MINOR scheme; breaking changes are called out in each CHANGELOG.md entry.

Local testing standard: run the public verification gate before any deploy. See CONTRIBUTING.md.

Scope

This repository owns:

• The platform-neutral Go voice kernel in pkg/speechkit: mode contracts, provider profiles, routing policy, readiness metadata, and the reusable Dictation, Assist, and Voice Agent services.
• The self-host server target in cmd/speechkit-server, which wraps the same kernel behind HTTP and WebSocket APIs plus its OpenAPI/AsyncAPI contracts.
• The agent-facing surfaces: the speechkit-mcp MCP server and the speechkit-cli command-line tool.
• The Windows Wails device client in cmd/speechkit, a reference implementation of a device target — not a separate product.
• The shared voice surface contract consumed by Kombify Companion, Workbench, and embeds.

This repository does not own:

• Product identity, tenancy, entitlement decisions, or edge policy. Those belong to kombify-Gateway and the platform standards.
• Cloud AI provider-key custody for the platform. kombify-AI-Platform is the only cloud provider-key custodian; SpeechKit deliberately keeps its own self-contained provider layer so the open-core framework stays usable standalone.
• The consuming client UX of Companion, Workbench, or any embedding host.

When a SpeechKit server is operated as a Kombify-hosted surface, its public traffic goes through https://api.kombify.io.

Runtime And Stack

SpeechKit imports no Kombify Go modules — it has no dependency on kombify-go-common and does not call /v1/ai/*. That self-containment is a deliberate open-core exception. The relationships that do exist are contract and edge relationships: shared client and voice contracts, and kombify-Gateway as the edge for the Kombify-hosted server target consumed by Companion and Workbench.

Public dependency and export rules are documented in the SDK surface boundary.

Repository Context

flowchart LR
  CORE["Shared client + voice contracts"] --> SK["kombify-SpeechKit"]
  HOST["Go host apps<br/>self-hosted servers"] --> SK
  SK --> GW["kombify-Gateway<br/>api.kombify.io"]
  GW --> COMP["kombify-AI-Mobile<br/>Companion"]
  GW --> WB["kombify-Workbench"]

The public kernel and adapter boundary is documented in the SDK surface boundary.

Modes

The runtime targets share the same three strict modes:

Hands-Free is not a fourth mode. It is an activation and voice-output layer over the three modes: wake activation, microphone capture, auto-end policy, and optional speaker output.

Words and Replacements are the first-class customization axis over the same three modes. Words teach SpeechKit terms to recognize; Replacements define deterministic text, command, snippet, synonym, and template transformations. See the Words And Replacements standard.

Speaker diarization, identification, and attribution are add-on capabilities. Provider support and auth status are tracked in the voice capability matrix.

Targets

Desktop device support is Windows 10/11 x64 only today. Linux is supported as a server runtime, not as a desktop capture client; macOS and Linux desktop packages are not currently supported. Default device hotkeys are Ctrl+Win (Dictation), Win+Alt (Assist), and Ctrl+Shift (Voice Agent).

Public Windows builds are published on GitHub Releases. A fresh clone also carries current installer metadata in release/latest/windows/, including canonical download URLs and SHA-256 hashes; the GitHub Release assets remain canonical.

Quick Start

Embed the Go kernel:

go get github.com/kombifyio/SpeechKit

Import only the components your host needs: pkg/speechkit/dictation for dictation, pkg/speechkit/wakeword for activation, pkg/speechkit/tts for spoken output, pkg/speechkit/companion plus Assist/TTS adapters for one-shot Voice Companion hosts, pkg/speechkit/speaker for speaker-aware apps, and pkg/speechkit/client for server-connected apps.

To drive the framework from a config.toml instead of building settings by hand, pkg/speechkit/hostconfig turns a config file into the public ModeSettings and a starting RuntimePolicy in one call:

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

Real providers run in-process — no SpeechKit server required. Two runnable references:

# in-process Voice Agent (Gemini Live), no server:
GOOGLE_AI_API_KEY=... go run ./examples/voice-agent/in-process
# in-process Assist (host-owned LLM + optional public TTS), no server:
GOOGLE_AI_API_KEY=... go run ./examples/assist/in-process

Scaffold a single-prompt Go starter, run the server image, or drive the agent tools:

speechkit-cli init --template go-assist-voice-companion ./my-companion
docker pull ghcr.io/kombifyio/speechkit-server:latest
go run ./cmd/speechkit-mcp --mode=docs,test
go run ./cmd/speechkit-cli status --server "$SPEECHKIT_SERVER_URL" --token "$SPEECHKIT_SERVER_TOKEN"

More starting points: Framework API, Voice Companion, and examples/.

Common Commands

Public source verification:

go test ./pkg/... ./cmd/speechkit-cli/... ./cmd/speechkit-mcp/... ./examples/...
GOOS=linux CGO_ENABLED=0 go build ./cmd/speechkit-server ./cmd/speechkit-mcp ./cmd/speechkit-cli

The complete public-clone gate is documented in CONTRIBUTING.md.

Repository Layout

pkg/speechkit/          Public Go kernel and SDK surface
cmd/speechkit/          Windows device client (reference implementation)
cmd/speechkit-server/   Self-host server entry point
cmd/speechkit-mcp/      MCP server for agent docs, validation, and management
cmd/speechkit-cli/      CLI diagnostics, scaffolding, and quick actions
internal/               Implementation packages behind the public binaries
docs/                   Detailed documentation
deploy/                 Container and server configuration
scripts/                Install and release-note helpers

Standards

• CONTRIBUTING.md
• SDK surface boundary
• SECURITY.md
• CODE_OF_CONDUCT.md
• SUPPORT.md

Documentation

Generated agent documentation never overrides this README or the detailed public documentation.

Issue Tracking

Public issues and contributions use the GitHub repository. Internal planning metadata is not part of the public source export.

Dual-Repo

The consumer-facing source repository is kombifyio/SpeechKit: the go get path, Go Reference badge, container image, and release assets all use that identity. The public source tree is produced by an allowlist-based export from governed working source. Exported code and documentation must remain usable without access to that working repository; see CONTRIBUTING.md and the SDK surface boundary.

Trust

Public releases include checksums and an unsigned Windows notice while the no-cost unsigned release path is active. Download only from the official kombifyio/SpeechKit releases.

License

Apache-2.0. See LICENSE.