Documentation
¶
Overview ¶
Package sampling owns the sampling-profile data type and the resolution chain that decides which sampler fields land on the wire for a given (model, profile, provider-override) tuple. See ADR-007.
Slice 4 of the ADR-007 implementation will add Resolve(); this file currently carries only the data type so the model catalog and config packages can share it without a circular import.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SourceSummary ¶
func SourceSummary(sources []FieldSource) string
SourceSummary collapses a FieldSource list into the comma-separated layer list that LLMRequestData.SamplingSource records. Layers appear in the chain order (catalog before provider_config before cli); a layer is included once if it supplied any non-nil field. Empty input → "".
Types ¶
type CatalogLookup ¶
type CatalogLookup interface {
// SamplingProfile returns the named profile bundle, or false if the
// catalog does not declare it.
SamplingProfile(name string) (Profile, bool)
// ModelSamplingControl returns the SamplingControl declared on the
// ModelEntry for the given concrete model ID, or "" if the model is
// not declared in the catalog or carries no explicit value.
ModelSamplingControl(modelID string) string
}
CatalogLookup is the narrow interface the resolver needs from the model catalog. It exists so test code can supply a stub without depending on the full Catalog type.
type FieldSource ¶
FieldSource records the layer that supplied a single non-nil sampler field on the resolved profile.
type Profile ¶
type Profile struct {
Temperature *float64 `yaml:"temperature,omitempty"`
TopP *float64 `yaml:"top_p,omitempty"`
TopK *int `yaml:"top_k,omitempty"`
MinP *float64 `yaml:"min_p,omitempty"`
RepetitionPenalty *float64 `yaml:"repetition_penalty,omitempty"`
Seed *int64 `yaml:"seed,omitempty"`
}
Profile is a named bundle of sampling-parameter overrides. Each field is a pointer so nil means "leave-unset — fall through to lower layers, then to the server default" — distinct from any concrete value (notably 0). Stored on the model catalog (per-profile bundles), in user provider config (the providers.<name>.sampling override block), and as the resolved bundle the resolver returns to the CLI.
type ResolveResult ¶
type ResolveResult struct {
// Profile is the per-field-merged sampling bundle to send on the wire.
Profile Profile
// Sources records which layer supplied each non-nil field.
Sources []FieldSource
// MissingProfile is true when the caller asked for a named catalog
// profile (profileName != "") but the catalog did not declare it. The
// CLI uses this to emit a single first-use nudge pointing at
// "fiz catalog update". MissingProfile is false when
// profileName is empty (no L1 lookup was attempted) or when the
// resolver short-circuited via harness_pinned (deliberate skip, not
// a missing-data condition).
MissingProfile bool
}
ResolveResult is the full output of Resolve: the merged Profile, the per-field origin record, and a flag the caller uses to drive the catalog-stale nudge per ADR-007 §7 rule 4.
func Resolve ¶
func Resolve(catalog CatalogLookup, modelID string, profileName string, providerOverride *Profile) ResolveResult
Resolve walks the precedence chain (catalog profile → provider override) and produces a per-field-merged Profile plus a record of which layer supplied each non-nil field. nil at every layer means the wire field is omitted and the server's own default applies — a first-class outcome per ADR-007 §2.
modelID may be empty if no model has been resolved yet; in that case the catalog's sampling_control is unknown and treated as the default (client_settable). When sampling_control is "harness_pinned" the resolver short-circuits to a zero-value profile regardless of layer inputs: wrapped subprocess harnesses pin samplers internally and ignore wire fields, so emitting them would only mislead telemetry.
profileName is the name of the catalog profile to seed L1 from (e.g., "code"). Empty names skip L1 silently. Unknown names (caller asked for a profile the catalog does not declare) set ResolveResult.MissingProfile so the CLI can emit an ADR-007 §7 catalog-stale nudge.
providerOverride is the user-config L2 override; nil means none.
type Source ¶
type Source string
Source identifies which layer of the resolution chain supplied a non-nil field on the resolved profile. See ADR-007 §2.
const ( // SourceCatalog is the L1 layer: a manifest sampling_profiles entry. SourceCatalog Source = "catalog" // SourceProviderConfig is the L2 layer: a providers.<name>.sampling // override block in user config. SourceProviderConfig Source = "provider_config" // SourceCLI is the L3 layer: an explicit per-request override (CLI // flags). Reserved; not emitted by the v1 resolver. SourceCLI Source = "cli" )
Source Files