catalog

package
v0.68.2 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: 7 Imported by: 0

Documentation

Overview

Package catalog ships the built-in SpeechKit provider and model catalog.

DefaultCatalog returns the immutable set of speechkit.ProviderProfile values SpeechKit knows about, grouped by speechkit.Mode; Catalog.With extends it with host-owned providers without mutating the built-in set. DefaultProviderDefaults and DefaultProviderMatrix describe per-provider auth, transport and feature support for setup UIs, and DefaultModelRegistry is the source of truth for model IDs, lifecycles and freshness metadata.

The root speechkit package owns the contracts this catalog is expressed in (profiles, modes, capabilities, speechkit.RuntimePolicy); this package owns the data. Hosts that never show a provider picker do not need to import it.

Index

Examples

Constants

View Source 
const (
	ModelAssemblyAIUniversal35ProRealtime = "universal-3-5-pro"
	ModelAssemblyAIU3RTPro                = "u3-rt-pro"
	ModelAssemblyAIVoiceAgent             = "assemblyai-voice-agent"
	ModelDeepgramFluxGeneralEN            = "flux-general-en"
	ModelDeepgramFluxGeneralMulti         = "flux-general-multi"
	// ModelDeepgramFluxTTSDefaultEN is Deepgram's default Flux TTS voice. Flux
	// TTS is English-only; Aura-2 remains the multilingual speak leg.
	ModelDeepgramFluxTTSDefaultEN        = "flux-kit-en"
	ModelDeepgramNova3                   = "nova-3"
	ModelGroqWhisperLargeV3              = "whisper-large-v3"
	ModelGroqWhisperLargeV3Turbo         = "whisper-large-v3-turbo"
	ModelGemini35LiveTranslatePreview    = "gemini-3.5-live-translate-preview"
	ModelGemini31FlashLivePreview        = "gemini-3.1-flash-live-preview"
	ModelGemini25FlashNativeAudioPreview = "gemini-2.5-flash-native-audio-preview-12-2025"
	ModelOpenAIGPT4OTranscribe           = "gpt-4o-transcribe"
	ModelOpenAIGPT4OMiniTranscribe       = "gpt-4o-mini-transcribe"
	ModelOpenAIGPT4OTranscribeDiarize    = "gpt-4o-transcribe-diarize"
	ModelOpenAIRealtime2                 = "gpt-realtime-2"
	ModelOpenAIRealtime21                = "gpt-realtime-2.1"
	ModelOpenAIRealtime21Mini            = "gpt-realtime-2.1-mini"
)
View Source 
const (
	ProviderAuthNone             = "none"
	ProviderAuthAPIKey           = "api_key"
	ProviderAuthToken            = "token"
	ProviderAuthHostDependencies = "host_dependencies"
	ProviderAuthOptionalAPIKey   = "optional_api_key"

	ProviderTransportLocal     = "local"
	ProviderTransportHTTP      = "http"
	ProviderTransportHTTPS     = "https"
	ProviderTransportWebSocket = "websocket"
	ProviderTransportPipeline  = "pipeline"
)
View Source 
const DefaultLocalBuiltInLLMModel = "ggml-org/gemma-4-E2B-it-GGUF:Q8_0"
View Source 
const ModelFreshnessSLA = 7 * 24 * time.Hour

ModelFreshnessSLA is the maximum age of LastVerifiedAt before a default or recommended model row is considered stale.

Variables

View Source 
var (
	// ErrDuplicateProfileID is returned by NewCatalog and Catalog.With when two
	// profiles share an id.
	ErrDuplicateProfileID = errors.New("speechkit: duplicate provider profile id")
	// ErrInvalidProfile wraps the mode-contract violation that keeps a profile
	// out of a Catalog.
	ErrInvalidProfile = errors.New("speechkit: invalid provider profile")
)

Functions

func DefaultProviderAuthRequirement 

func DefaultProviderAuthRequirement(profile speechkit.ProviderProfile) string

DefaultProviderAuthRequirement describes the credential class a host must satisfy before a provider profile can run. It is intentionally semantic: hosts map the value to their own env vars or secret stores.

func DefaultProviderProfiles 

func DefaultProviderProfiles() []speechkit.ProviderProfile

DefaultProviderProfiles returns the built-in framework provider catalog for the three strict SpeechKit modes. The Windows desktop host adapts this public catalog into its internal runtime model; the catalog itself belongs to the reusable framework layer.

func DefaultProviderTransport 

func DefaultProviderTransport(profile speechkit.ProviderProfile) string

DefaultProviderTransport exposes the dominant runtime transport class for a profile. Native realtime providers use websocket; cascaded voice providers use pipeline; batch/provider APIs use HTTPS/HTTP/local.

func MissingFreshnessReports 

func MissingFreshnessReports(rows []ProviderModelDescriptor) []string

MissingFreshnessReports lists default/recommended registry rows that still lack LastVerifiedAt.

func NormalizeProviderID 

func NormalizeProviderID(provider string) string

NormalizeProviderID maps a provider alias or a "<mode>.<provider>.<model>" profile id to its canonical provider id. Profile ids are reduced to their provider segment first, so every mode (stt, assist, utility, realtime, tts, speaker) shares one alias table; third-party providers pass through as-is.

func ProfilesForMode 

func ProfilesForMode(mode speechkit.Mode) []speechkit.ProviderProfile

func ProviderCredentialTarget 

func ProviderCredentialTarget(profile speechkit.ProviderProfile) string

func ProviderIDForExecutionMode 

func ProviderIDForExecutionMode(mode speechkit.ExecutionMode) string

func ProviderIDForProfile 

func ProviderIDForProfile(profile speechkit.ProviderProfile) string

func ProviderKindsForMode 

func ProviderKindsForMode(mode speechkit.Mode) []speechkit.ProviderKind

func ProviderProfileRequiresCredential 

func ProviderProfileRequiresCredential(profile speechkit.ProviderProfile) bool

func ProviderProfileWithDefaults 

func ProviderProfileWithDefaults(profile speechkit.ProviderProfile) speechkit.ProviderProfile

ProviderProfileWithDefaults returns a copy with framework-standard provider metadata filled in. Explicit profile metadata wins; missing provider, credential, and transport fields are derived from the canonical provider id, execution mode, and mode capabilities.

func StaleFreshnessReports 

func StaleFreshnessReports(rows []ProviderModelDescriptor, now time.Time) []string

StaleFreshnessReports lists default/recommended rows whose LastVerifiedAt is missing, unparsable, or older than ModelFreshnessSLA relative to now.

func ValidateDefaultCatalog 

func ValidateDefaultCatalog() error

ValidateDefaultCatalog verifies the framework invariant that every strict mode exposes all four provider groups and every visible profile satisfies its mode contract. v0.37 added ModeTTS as a model-selection axis with the same four-provider-group invariant (Local Built-in via Piper, Local Provider via Kokoro/openedai-speech, Cloud Provider via Hugging Face Parler, Direct Provider via OpenAI + Google).

Types

type Catalog 

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

Catalog is an immutable, host-composable set of provider profiles.

The built-in catalog (DefaultCatalog) is what the reference apps ship. A host that adds its own STT, TTS or realtime provider describes it as a ProviderProfile and extends the catalog with With; the result feeds the same matrix, defaults, policy filtering and mode validation the built-ins go through, so the provider shows up in setup UIs, readiness and routing like any shipped one. Every profile is normalised with ProviderProfileWithDefaults and checked against its mode contract on the way in — a Catalog never holds an invalid profile.

func DefaultCatalog 

func DefaultCatalog() *Catalog

DefaultCatalog returns the built-in framework catalog. It is the same data as DefaultProviderProfiles, exposed as a Catalog so hosts extend it with With instead of concatenating slices by hand.

func NewCatalog 

func NewCatalog(profiles ...speechkit.ProviderProfile) (*Catalog, error)

NewCatalog builds a catalog from the given profiles. Profiles are normalised, validated against their mode contract, and must have unique ids.

func (*Catalog) Filter 

func (c *Catalog) Filter(policy speechkit.RuntimePolicy) []speechkit.ProviderProfile

Filter applies a RuntimePolicy and returns the profiles a host may present.

func (*Catalog) Profile 

func (c *Catalog) Profile(id string) (speechkit.ProviderProfile, bool)

Profile looks a profile up by id. Legacy ids are resolved through NormalizeProviderProfileID first.

func (*Catalog) Profiles 

func (c *Catalog) Profiles() []speechkit.ProviderProfile

Profiles returns a copy of every profile in catalog order.

func (*Catalog) ProfilesForMode 

func (c *Catalog) ProfilesForMode(mode speechkit.Mode) []speechkit.ProviderProfile

ProfilesForMode returns the profiles that belong to mode, in catalog order.

func (*Catalog) ProviderDefaults 

func (c *Catalog) ProviderDefaults() []ProviderDefault

ProviderDefaults returns the preferred profile per provider and mode, the same shape DefaultProviderDefaults returns for the built-ins.

func (*Catalog) ProviderMatrix 

func (c *Catalog) ProviderMatrix() []ProviderMatrixRow

ProviderMatrix groups the catalog by provider with per-feature support, the same shape DefaultProviderMatrix returns for the built-ins.

func (*Catalog) With 

func (c *Catalog) With(profiles ...speechkit.ProviderProfile) (*Catalog, error)

With returns a new Catalog containing the receiver's profiles plus the given ones. The receiver is unchanged. Ids must not collide with existing profiles; a host that wants to replace a built-in filters Profiles() first and builds a fresh catalog with NewCatalog.

Example

ExampleCatalog_With extends the built-in catalog with a host-owned STT provider. The profile id follows the "<mode>.<provider>.<model>" shape, so the provider id, auth requirement and transport are derived; the result participates in mode listing, the provider matrix and policy filtering like any shipped provider. 

package main

import (
	"fmt"
	"log"

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

func main() {
	extended, err := catalog.DefaultCatalog().With(speechkit.ProviderProfile{
		ID:            "stt.acme.whisper-turbo",
		Name:          "Acme Whisper Turbo",
		Mode:          speechkit.ModeDictation,
		ProviderKind:  speechkit.ProviderKindCloudProvider,
		ExecutionMode: speechkit.ExecutionModeSelfHostedHTTP,
		Capabilities:  []speechkit.Capability{speechkit.CapabilityTranscription, speechkit.CapabilitySTT},
	})
	if err != nil {
		log.Fatal(err)
	}

	profile, _ := extended.Profile("stt.acme.whisper-turbo")
	fmt.Println(profile.Provider, profile.AuthRequirement, profile.Transport)

	for _, row := range extended.ProviderMatrix() {
		if row.Provider == "acme" {
			fmt.Println(row.DisplayName, len(row.Profiles))
		}
	}
}

Output:
acme optional_api_key http
acme 1

type ProviderDefault 

type ProviderDefault struct {
	Provider           string                   `json:"provider"`
	DisplayName        string                   `json:"displayName"`
	Mode               speechkit.Mode           `json:"mode"`
	ProfileID          string                   `json:"profileId"`
	ModelID            string                   `json:"modelId,omitempty"`
	ProviderKind       speechkit.ProviderKind   `json:"providerKind"`
	ExecutionMode      speechkit.ExecutionMode  `json:"executionMode,omitempty"`
	Support            ProviderSupportKind      `json:"support"`
	Capabilities       []speechkit.Capability   `json:"capabilities,omitempty"`
	NativeOptions      []string                 `json:"nativeOptions,omitempty"`
	AuthRequirement    string                   `json:"authRequirement,omitempty"`
	CredentialRequired bool                     `json:"credentialRequired"`
	CredentialTarget   string                   `json:"credentialTarget,omitempty"`
	Transport          string                   `json:"transport,omitempty"`
	EvidenceURL        string                   `json:"evidenceUrl,omitempty"`
	Default            bool                     `json:"default,omitempty"`
	Recommended        bool                     `json:"recommended,omitempty"`
	Experimental       bool                     `json:"experimental,omitempty"`
	Variants           []speechkit.ModelVariant `json:"variants,omitempty"`
}

func DefaultProviderDefaults 

func DefaultProviderDefaults() []ProviderDefault

func FindProviderDefault 

func FindProviderDefault(provider string, mode speechkit.Mode) (ProviderDefault, bool)

func ProviderDefaultsFor 

func ProviderDefaultsFor(provider string) []ProviderDefault

type ProviderFeature 

type ProviderFeature string
const (
	ProviderFeatureDictation             ProviderFeature = "dictation"
	ProviderFeatureDictationStreaming    ProviderFeature = "dictation_streaming"
	ProviderFeatureLongTranscription     ProviderFeature = "long_transcription"
	ProviderFeatureSpeakerDiarization    ProviderFeature = "speaker_diarization"
	ProviderFeatureSpeakerIdentification ProviderFeature = "speaker_identification"
	ProviderFeatureAssist                ProviderFeature = "assist"
	ProviderFeatureRealtimeVoice         ProviderFeature = "realtime_voice"
	ProviderFeatureTTS                   ProviderFeature = "tts"
)

type ProviderFeatureSupport 

type ProviderFeatureSupport struct {
	Feature       ProviderFeature     `json:"feature"`
	Support       ProviderSupportKind `json:"support"`
	Mode          speechkit.Mode      `json:"mode,omitempty"`
	ProfileID     string              `json:"profileId,omitempty"`
	ModelID       string              `json:"modelId,omitempty"`
	NativeOptions []string            `json:"nativeOptions,omitempty"`
	EvidenceURL   string              `json:"evidenceUrl,omitempty"`
}

type ProviderMatrixRow 

type ProviderMatrixRow struct {
	Provider    string                   `json:"provider"`
	DisplayName string                   `json:"displayName"`
	Profiles    []ProviderDefault        `json:"profiles"`
	Features    []ProviderFeatureSupport `json:"features"`
}

func DefaultProviderMatrix 

func DefaultProviderMatrix() []ProviderMatrixRow

func FindProviderMatrixRow 

func FindProviderMatrixRow(provider string) (ProviderMatrixRow, bool)

func (ProviderMatrixRow) Feature 

func (r ProviderMatrixRow) Feature(feature ProviderFeature) (ProviderFeatureSupport, bool)

type ProviderModelDescriptor 

type ProviderModelDescriptor struct {
	Provider    string                   `json:"provider"`
	ModelID     string                   `json:"modelId"`
	ProfileID   string                   `json:"profileId,omitempty"`
	Mode        speechkit.Mode           `json:"mode"`
	Name        string                   `json:"name"`
	Lifecycle   speechkit.ModelLifecycle `json:"lifecycle"`
	Default     bool                     `json:"default,omitempty"`
	Recommended bool                     `json:"recommended,omitempty"`
	SourceURL   string                   `json:"sourceUrl"`

	// Freshness metadata (kombify-SpeechKit-glnc). Dates are calendar days
	// (YYYY-MM-DD) from vendor documentation. LastVerifiedAt is the day the
	// row was last checked against those docs. TestDefaultModelRegistryFreshnessSLA
	// always fails when a default/recommended row lacks it; the age check
	// against ModelFreshnessSLA only fails under SPEECHKIT_MODEL_FRESHNESS_GATE,
	// which the scheduled model-freshness-gate workflow sets.
	ReleasedAt           string `json:"releasedAt,omitempty"`
	DeprecatedAt         string `json:"deprecatedAt,omitempty"`
	SunsetAt             string `json:"sunsetAt,omitempty"`
	LastVerifiedAt       string `json:"lastVerifiedAt,omitempty"`
	MultilanguageCapable bool   `json:"multilanguageCapable,omitempty"`
}

ProviderModelDescriptor is the public source-of-truth row for model IDs that SpeechKit treats as framework defaults or first-class live-provider choices.

func DefaultModelRegistry 

func DefaultModelRegistry() []ProviderModelDescriptor

func FindModelDescriptor 

func FindModelDescriptor(provider, modelID string) (ProviderModelDescriptor, bool)

type ProviderSupportKind 

type ProviderSupportKind string
const (
	ProviderSupportUnsupported ProviderSupportKind = "unsupported"
	ProviderSupportPlanned     ProviderSupportKind = "planned"
	ProviderSupportCascaded    ProviderSupportKind = "cascaded"
	ProviderSupportRouted      ProviderSupportKind = "routed"
	ProviderSupportNative      ProviderSupportKind = "native"
)

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.