modelregistry

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package modelregistry Model registry runtime and cache for backend model inventory.

Package modelregistry provides core-owned lookup over backend-exposed models.

Index

Constants

View Source 
const (
	CapabilitySourceStaticConfig    = "static_config"
	CapabilitySourceRemoteDiscovery = "remote_discovery"
	CapabilitySourceBuiltin         = "builtin"
)
View Source 
const MaxInventoryModelSample = 3

MaxInventoryModelSample is the maximum number of model rows exposed in operator diagnostics.

Variables

View Source 
var (
	ErrNilContext             = errors.New("modelregistry: nil context")
	ErrMissingProvider        = errors.New("modelregistry: missing inventory provider")
	ErrMissingBackendPrefix   = errors.New("modelregistry: missing backend prefix")
	ErrDuplicateBackendPrefix = errors.New("modelregistry: duplicate backend prefix")
	ErrInvalidModel           = errors.New("modelregistry: invalid model")
	ErrInvalidCanonicalID     = errors.New("modelregistry: invalid canonical model id")
	ErrNoUsableInventory      = errors.New("modelregistry: no usable inventory")
	// ErrConflictingMapping is returned when two rows claim the same
	// (backendID, canonicalID) with different NativeID values.
	ErrConflictingMapping = errors.New("modelregistry: conflicting exact model mapping")
)
View Source 
var ErrSnapshotUnavailable = errors.New("modelregistry: snapshot unavailable")

Functions

func MarshalOpenAIModelsListJSON 

func MarshalOpenAIModelsListJSON(models []BackendModel) ([]byte, error)

MarshalOpenAIModelsListJSON returns the JSON body for GET /v1/models.

func WithBoundView 

func WithBoundView(ctx context.Context, v BoundView) context.Context

WithBoundView attaches v to ctx for request-scoped consumers.

Types

type BackendDiscovery 

type BackendDiscovery struct {
	BackendID  string
	Kind       string
	Status     modelinventory.DiscoveryStatus
	Source     modelinventory.Source
	ModelCount int
	ErrorCode  string
}

BackendDiscovery is per-backend inventory discovery state for diagnostics.

type BackendInventory 

type BackendInventory struct {
	BackendID       string
	Kind            string
	BackendPrefixes []string
	Provider        modelinventory.Provider
	FetchTimeout    time.Duration
}

type BackendModel 

type BackendModel struct {
	CanonicalID      string
	NativeID         string
	DisplayName      string
	BackendID        string
	Kind             string
	Source           modelinventory.Source
	LoadedAt         time.Time
	Prefix           string
	CapabilitySource string
}

type BoundView 

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

BoundView is an immutable, request-scoped publication of the model registry. It freezes registry lookups, models JSON, generation, and publication-tied discovery metadata so a later Runtime refresh cannot alter an in-flight request.

BoundView never exposes the mutable Runtime, its mutexes, or atomics. Live operational last-refresh/cache failure categories are captured at bind time for diagnostics but are not part of the immutable publication object.

func BoundViewFromContext 

func BoundViewFromContext(ctx context.Context) (BoundView, bool)

BoundViewFromContext returns the request-bound registry view when present.

func EmptyBoundView 

func EmptyBoundView() BoundView

EmptyBoundView returns a safe empty view (nil/unavailable runtime).

func (BoundView) Active 

func (v BoundView) Active() bool

Active reports whether a publication was bound.

func (BoundView) All 

func (v BoundView) All() []BackendModel

All returns a defensive clone of all frozen registry rows.

func (BoundView) Diagnostics 

func (v BoundView) Diagnostics() Diagnostics

Diagnostics returns coherent publication diagnostics frozen at bind time. LastRefreshErrorCategory / LastCacheErrorCategory reflect live operational state captured at bind and are not publication identity fields.

func (BoundView) Generation 

func (v BoundView) Generation() string

Generation returns the frozen model-registry generation identity.

func (BoundView) Lookup 

func (v BoundView) Lookup(canonicalID string) ([]BackendModel, bool)

Lookup returns defensive clones of models for canonicalID from the frozen registry.

func (BoundView) ModelsJSON 

func (v BoundView) ModelsJSON() (body []byte, generation string, ok bool)

ModelsJSON returns a defensive copy of the frozen OpenAI /v1/models body.

func (BoundView) PublicationGeneration 

func (v BoundView) PublicationGeneration() string

PublicationGeneration returns the frozen publication generation (alias of Generation).

func (BoundView) RefreshedAt 

func (v BoundView) RefreshedAt() time.Time

RefreshedAt returns the frozen publication refresh time.

func (BoundView) ResolveModelBinding 

func (v BoundView) ResolveModelBinding(backendID, model string) routing.ModelBinding

ResolveModelBinding implements routing.NativeModelResolver with multi-state outcomes.

func (BoundView) ResolveNative 

func (v BoundView) ResolveNative(backendID, model string) (native string, ok bool)

ResolveNative is a compatibility helper: ok is true only for exact-canonical or known-native bindings. Wrong-backend and unknown both return ok=false; callers that need fail-closed planning must use ResolveModelBinding.

type BuildResult 

type BuildResult struct {
	Registry    *Registry
	Discoveries []BackendDiscovery
}

BuildResult is the fail-soft aggregation outcome for configured backend inventories.

func Build 

func Build(ctx context.Context, inventories []BackendInventory, log *slog.Logger) (BuildResult, error)

type Cache 

type Cache interface {
	Load(ctx context.Context) (Snapshot, error)
	Save(ctx context.Context, snap Snapshot) error
}

type Diagnostics 

type Diagnostics struct {
	Active                   bool
	Generation               string
	RefreshedAt              time.Time
	ModelCount               int
	BackendModelCounts       map[string]int
	BackendDiscoveries       []BackendDiscovery
	LastRefreshErrorCategory RefreshFailureCategory
	LastCacheErrorCategory   RefreshFailureCategory
}

type OpenAIModel 

type OpenAIModel struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	OwnedBy string `json:"owned_by"`
}

OpenAIModel is one advertised model row. IDs are instance-pinned canonical selectors (`<backend-instance>:<canonicalID>`). Native IDs are never exposed.

type OpenAIModelList 

type OpenAIModelList struct {
	Object string        `json:"object"`
	Data   []OpenAIModel `json:"data"`
}

OpenAIModelList is the minimal OpenAI-compatible GET /v1/models response body.

func BuildOpenAIModelsList 

func BuildOpenAIModelsList(models []BackendModel) OpenAIModelList

BuildOpenAIModelsList converts registry rows into a stable, deduplicated OpenAI list. Ordering is by id then owned_by. owned_by is the backend kind.

type RefreshFailureCategory 

type RefreshFailureCategory string
const (
	RefreshFailureNone  RefreshFailureCategory = ""
	RefreshFailureFetch RefreshFailureCategory = "fetch"
	RefreshFailureCache RefreshFailureCategory = "cache"
	RefreshFailureParse RefreshFailureCategory = "parse"
)

type Registry 

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

func (*Registry) All 

func (r *Registry) All() []BackendModel

func (*Registry) Len 

func (r *Registry) Len() int

Len returns the number of published backend model rows without cloning.

func (*Registry) Lookup 

func (r *Registry) Lookup(canonicalID string) ([]BackendModel, bool)

type Runtime 

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

func NewRuntime 

func NewRuntime(cfg RuntimeConfig) *Runtime

func (*Runtime) ActiveRegistry 

func (r *Runtime) ActiveRegistry() *Registry

func (*Runtime) All 

func (r *Runtime) All() []BackendModel

func (*Runtime) BoundView 

func (r *Runtime) BoundView() BoundView

BoundView captures the current atomic publication (registry+discoveries) once. A nil receiver returns an empty view.

func (*Runtime) Diagnostics 

func (r *Runtime) Diagnostics() Diagnostics

func (*Runtime) Discoveries 

func (r *Runtime) Discoveries() []BackendDiscovery

func (*Runtime) LastCacheFailure 

func (r *Runtime) LastCacheFailure() RefreshFailureCategory

func (*Runtime) LastRefreshFailure 

func (r *Runtime) LastRefreshFailure() RefreshFailureCategory

func (*Runtime) Lookup 

func (r *Runtime) Lookup(canonicalID string) ([]BackendModel, bool)

func (*Runtime) ModelsJSON 

func (r *Runtime) ModelsJSON() (body []byte, generation string, ok bool)

ModelsJSON returns the precomputed OpenAI /v1/models JSON body and generation ETag for the published snapshot. ok is false when nothing is published.

func (*Runtime) RunRefresh 

func (r *Runtime) RunRefresh(ctx context.Context)

RunRefresh runs a background inventory refresh. Concurrent calls while a refresh is already in flight are skipped (no stampede of LoadModels/CLI spawns).

func (*Runtime) Start 

func (r *Runtime) Start(ctx context.Context) error

type RuntimeConfig 

type RuntimeConfig struct {
	Inventories []BackendInventory
	Cache       Cache
	Now         func() time.Time
	// Log receives fail-soft inventory warnings from Build. Nil disables logging.
	Log *slog.Logger
}

type Snapshot 

type Snapshot struct {
	Generation  string
	RefreshedAt time.Time
	Models      []BackendModel
}

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.