Documentation
¶
Overview ¶
Package settings holds the part of a service's configuration that can change while the pipeline is running: the model, the voice, the language, the sampling knobs an LLM exposes. It is not the whole of a service's configuration. What a service is built with stays in its own Config; what may change mid-call lives here.
A settings value is read in one of two ways.
As a store, held by a running service, every field carries the current state. A field with no value means the service has no such setting.
As a delta, carried by an update frame, only the fields the caller wants to change are given. The rest are left alone, which is what lets a caller change the voice without restating the model.
Both are the same Go type, because a field carries the three states that needs: not given, given with a value, and given with no value. The last is how a caller clears a setting, which is a different request from not mentioning it, and the two would be indistinguishable if a field were a plain pointer.
Index ¶
- Variables
- func FromMap(delta any, values map[string]any) error
- func Get(v any, name string) (any, bool)
- func Given(delta any) (map[string]any, error)
- func NewDelta(store any) (any, error)
- func Resolve(f *frames.ServiceUpdateSettingsFrame, store any) (delta any, ok bool, err error)
- func SetNamed(v any, name string, value any) error
- type Aliaser
- type Base
- type Changed
- type LLM
- type Opt
- type STT
- type TTS
Constants ¶
This section is empty.
Variables ¶
var ( // ErrType is returned when a value cannot be stored in a field without // losing something. ErrType = errors.New("settings: value does not fit the field") // ErrMismatch is returned when a delta and a store are different types. ErrMismatch = errors.New("settings: delta and store are different types") // ErrNotSettings is returned for anything that is not a settings struct. ErrNotSettings = errors.New("settings: not a pointer to a settings struct") )
Errors reported when a settings value does not fit where it is being put.
Functions ¶
func FromMap ¶
FromMap fills delta from plain setting names and values, for an update that arrived as data rather than as a typed value. A name the settings type declares, or one of its aliases, gives that field; anything else lands in Extra, so a provider-specific setting survives the trip rather than being dropped on the way.
A value whose type does not fit its field is reported rather than skipped: applying half an update silently is worse than refusing it.
func Get ¶
Get is what a settings value holds for the named field: the value, and whether the field carries one at all. A field a provider's own settings declare is reached the same way as one of the shared fields.
func Given ¶
Given lists the fields a delta gives, mapped to their values, with the extra settings alongside. It is what a service reads when it wants the update as plain data rather than reacting field by field. A field given no value is present with a nil value.
func NewDelta ¶
NewDelta builds an empty delta of the same type as store, for an update that arrived as plain data and has to be given a shape before it can be applied.
Types ¶
type Aliaser ¶
Aliaser is implemented by a settings type that accepts more than one spelling for a field, mapping each alternative to the canonical name. It is consulted when a delta is built from plain data, where the names come from outside.
type Base ¶
type Base struct {
// Model is the service's model identifier.
Model Opt[string] `settings:"model"`
// Extra carries settings a provider understands that have no field of their
// own. They are merged and compared like declared fields, so a change to one
// is reported the same way.
Extra map[string]any `settings:"-"`
}
Base is the part every service's settings share. Embed it.
type Changed ¶
Changed maps each field a delta altered to the value it held before, so a service can see both what moved and what it is moving away from.
func Apply ¶
Apply merges delta into store and reports what changed. Only the fields the delta gives are considered, and a field changes only when what it carries differs from what is already there, so re-sending a service what it already has reports nothing and a service that reconnects on a change is not made to reconnect for a non-change.
store and delta must be pointers to the same settings type.
func (Changed) Except ¶
Except lists the changed fields a service does not act on, given the ones it does. A service warns about these rather than staying silent: a caller who asked for a change that cannot take effect should hear so.
type LLM ¶
type LLM struct {
Base
// SystemInstruction is the system prompt the model is given.
SystemInstruction Opt[string] `settings:"system_instruction"`
// Temperature is the sampling temperature.
Temperature Opt[float64] `settings:"temperature"`
// MaxTokens bounds how much the model generates.
MaxTokens Opt[int] `settings:"max_tokens"`
// TopP is the nucleus sampling probability.
TopP Opt[float64] `settings:"top_p"`
// TopK is the top-k sampling cutoff.
TopK Opt[int] `settings:"top_k"`
// FrequencyPenalty discourages repeating the same tokens.
FrequencyPenalty Opt[float64] `settings:"frequency_penalty"`
// PresencePenalty discourages repeating the same subjects.
PresencePenalty Opt[float64] `settings:"presence_penalty"`
// Seed makes generation reproducible where the provider supports it.
Seed Opt[int] `settings:"seed"`
// FilterIncompleteUserTurns gates each reply on the model's own verdict of
// whether the user had finished speaking. It is set by the turn strategy that
// drives the protocol rather than by an application directly.
FilterIncompleteUserTurns Opt[bool] `settings:"filter_incomplete_user_turns"`
// UserTurnCompletionConfig configures that gating: the protocol taught to the
// model, the waits before re-prompting, and the re-prompts themselves. It is
// set by the same turn strategy.
//
// It is typed loosely because the type belongs to the LLM service, which is
// built on this package and so cannot be named here. Set it to an
// llm.UserTurnCompletionConfig; anything else is reported and ignored.
UserTurnCompletionConfig Opt[any] `settings:"user_turn_completion_config"`
}
LLM is the runtime-updatable settings of a language model service.
type Opt ¶
type Opt[T any] struct { // contains filtered or unexported fields }
Opt is one runtime-updatable setting. Its zero value is not given, which is what every field of a delta starts as.
func Cleared ¶
Cleared is a setting given no value, for a caller asking a service to drop one: to stop naming a language and go back to detecting it, say. It differs from leaving the field alone, which asks for no change at all.
type STT ¶
type STT struct {
Base
// Language is the language transcribed, as the service names it. A caller
// may give a neutral tag; the service converts it before it is stored.
Language Opt[string] `settings:"language"`
}
STT is the runtime-updatable settings of a transcription service.
type TTS ¶
type TTS struct {
Base
// Voice is the voice identifier or name.
Voice Opt[string] `settings:"voice"`
// Language is the language spoken, as the service names it. A caller may
// give a neutral tag; the service converts it before it is stored.
Language Opt[string] `settings:"language"`
}
TTS is the runtime-updatable settings of a speech synthesis service.
Source Files