catalog

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jun 9, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package catalog builds and validates Lightcode's provider/model catalog.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnknownProvider = errors.New("catalog: unknown provider")
	ErrUnknownModel    = errors.New("catalog: unknown model")
	ErrIncomplete      = errors.New("catalog: incomplete model")
)

Catalog lookup errors.

View Source 
var ErrInvalidModelRef = coremodel.ErrInvalidModelRef

ErrInvalidModelRef is returned when a provider-prefixed model reference is malformed.

View Source 
var ReservedKeys = []string{
	"model",
	"messages",
	"tools",
	"tool_choice",
	"stream",
	"stream_options",
	"max_tokens",
	"max_completion_tokens",
	"n",
}

ReservedKeys lists request-body fields owned by the loop.

Functions

func BundledModelIDs added in v0.0.2 

func BundledModelIDs() map[string]map[string]struct{}

BundledModelIDs returns, for each bundled built-in provider, the set of model IDs declared in its embedded catalog file. It lets callers classify a model's provenance (bundled vs discovered vs user-added) without re-reading the merged catalog, which has already collapsed the layers together.

func BundledProviderHeaders added in v0.0.2 

func BundledProviderHeaders(providerID string) map[string]string

BundledProviderHeaders returns the transport headers a bundled provider ships with (e.g. OpenRouter's attribution HTTP-Referer / X-Title). These are part of the built-in's identity and must not be user-editable.

func CheckReservedKeys 

func CheckReservedKeys(body map[string]any) []string

CheckReservedKeys returns reserved keys present in body, in ReservedKeys order.

func DeepMergeCatalog 

func DeepMergeCatalog(bundled, user map[string]any) map[string]any

DeepMergeCatalog merges catalog layers. Objects recurse; arrays, primitives, and null replace whole.

func DiscoveryAttemptRecent 

func DiscoveryAttemptRecent(home, providerID string, now time.Time) (bool, error)

DiscoveryAttemptRecent reports whether provider discovery had a real network attempt inside the cache TTL.

func DiscoveryRefreshCandidates 

func DiscoveryRefreshCandidates(cat *Catalog, attempts map[string]time.Time, now time.Time) []string

DiscoveryRefreshCandidates returns enabled discovery providers that have not had a real discovery attempt in the last 24 hours.

func ShallowMergeBody 

func ShallowMergeBody(layers ...map[string]any) map[string]any

ShallowMergeBody merges request body sidecars top-level only. Later layers win.

func WriteDiscoveryAttempt 

func WriteDiscoveryAttempt(home, providerID string, attemptedAt time.Time) error

WriteDiscoveryAttempt records a real discovery network attempt without changing any cached model metadata.

func WriteDiscoveryCache 

func WriteDiscoveryCache(home, providerID string, discovered DiscoveredProvider, fetchedAt time.Time) error

WriteDiscoveryCache writes one provider's discovery cache file.

Types

type BuildInputs 

type BuildInputs struct {
	Bundled map[string]json.RawMessage
	UserRaw map[string]any
	Cache   map[string]DiscoveredProvider
}

BuildInputs contains the raw catalog layers consumed by Build.

type BuildResult 

type BuildResult struct {
	Catalog  *Catalog
	Warnings []Warning
}

BuildResult contains the effective catalog and non-fatal warnings.

func Build 

func Build(inputs BuildInputs) BuildResult

Build constructs an effective catalog from bundled, discovery, and user layers.

type Catalog 

type Catalog struct {
	Providers map[string]*Provider
}

Catalog is the in-memory effective catalog.

func (*Catalog) AllModels 

func (c *Catalog) AllModels() []ModelRef

AllModels returns every provider/model ref sorted by prefix string.

func (*Catalog) IncompleteModels 

func (c *Catalog) IncompleteModels() []Incomplete

IncompleteModels returns all incomplete models in the catalog.

func (*Catalog) Lookup 

func (c *Catalog) Lookup(ref ModelRef) (*Provider, *Model, error)

Lookup returns the provider and model for ref, rejecting incomplete models.

func (*Catalog) LookupOrIncomplete 

func (c *Catalog) LookupOrIncomplete(ref ModelRef) (*Provider, *Model, error)

LookupOrIncomplete returns the provider and model for ref, allowing incomplete models.

func (*Catalog) MergeDiscoveredProvider 

func (c *Catalog) MergeDiscoveredProvider(providerID string, discovered DiscoveredProvider) error

MergeDiscoveredProvider gap-fills provider models from discovery data.

func (*Catalog) MergeDiscoveredProviderWithCostProtection 

func (c *Catalog) MergeDiscoveredProviderWithCostProtection(providerID string, discovered DiscoveredProvider, protected map[string]map[string]bool) error

MergeDiscoveredProviderWithCostProtection gap-fills provider models from discovery data while preserving user-declared cost subfields.

func (*Catalog) VisibleModels 

func (c *Catalog) VisibleModels() []ModelRef

VisibleModels returns non-hidden provider/model refs sorted by prefix string.

type Cost 

type Cost struct {
	Input      *float64 `json:"input,omitempty"`
	Output     *float64 `json:"output,omitempty"`
	CacheRead  *float64 `json:"cache_read,omitempty"`
	CacheWrite *float64 `json:"cache_write,omitempty"`
}

Cost is per-million-token USD pricing.

type DiscoveredModel 

type DiscoveredModel struct {
	Name            string
	ContextWindow   int
	MaxOutputTokens int
	Cost            *Cost
	// contains filtered or unexported fields
}

DiscoveredModel is model metadata loaded from discovery cache.

type DiscoveredProvider 

type DiscoveredProvider struct {
	Models map[string]DiscoveredModel
}

DiscoveredProvider is provider metadata loaded from discovery cache.

func FetchDiscovery 

func FetchDiscovery(ctx context.Context, client *http.Client, provider *Provider) (DiscoveredProvider, error)

FetchDiscovery fetches and parses a provider's OpenAI-compatible /models list.

type Incomplete 

type Incomplete struct {
	Ref     ModelRef
	Reasons []IncompleteReason
}

Incomplete describes a model entry missing required capacity metadata.

type IncompleteReason 

type IncompleteReason int

IncompleteReason explains why a model cannot be used yet. 

const (
	// ReasonMissingContextWindow means context_window is unset.
	ReasonMissingContextWindow IncompleteReason = iota
)

type Loader 

type Loader struct {
	AllowRefresh func(providerID string, provider *Provider) bool
	// contains filtered or unexported fields
}

Loader reads catalog inputs from disk and delegates assembly to Build.

func NewLoader 

func NewLoader(home string, bundled fs.FS) *Loader

NewLoader constructs a catalog loader rooted at the user's home directory.

func NewLoaderWithConfigPath added in v0.0.2 

func NewLoaderWithConfigPath(home string, bundled fs.FS, configPath string) *Loader

NewLoaderWithConfigPath constructs a catalog loader that reads user provider overlays from the same config file the agent loaded at startup.

func (*Loader) Load 

func (l *Loader) Load() (*Catalog, []Warning, error)

Load reads the bundled catalog, user config, and discovery cache, then calls Build.

type Modality 

type Modality string

Modality is an input modality supported by a model. 

const (
	// ModalityText is plain text input.
	ModalityText Modality = "text"
	// ModalityImage is image input.
	ModalityImage Modality = "image"
	// ModalityAudio is audio input.
	ModalityAudio Modality = "audio"
	// ModalityDocument is document input.
	ModalityDocument Modality = "document"
)

type Model 

type Model struct {
	ID               string            `json:"id"`
	Name             string            `json:"name"`
	ContextWindow    int               `json:"context_window"`
	MaxOutputTokens  int               `json:"max_output_tokens"`
	InputModalities  []Modality        `json:"input_modalities"`
	SystemRole       SystemRole        `json:"system_role"`
	UsageInStream    bool              `json:"usage_in_stream"`
	Hidden           bool              `json:"hidden,omitempty"`
	ExtraBody        map[string]any    `json:"extra_body,omitempty"`
	Cost             *Cost             `json:"cost,omitempty"`
	ProtocolMetadata *ProtocolMetadata `json:"protocol_metadata,omitempty"`
}

Model is a resolved model entry in the effective catalog.

func (*Model) Incomplete 

func (m *Model) Incomplete() (Incomplete, bool)

Incomplete returns capacity fields missing from the model. Only context_window is required; max_output_tokens is optional and only acts as a request cap when set, so missing it does not block use.

type ModelRef 

type ModelRef = coremodel.ModelRef

ModelRef is the canonical internal identity of a model.

func ParseModelRef 

func ParseModelRef(s string) (ModelRef, error)

ParseModelRef parses a provider-prefixed model reference.

type ProtocolMetadata 

type ProtocolMetadata struct {
	Family       string   `json:"family,omitempty"`
	MustPreserve []string `json:"must_preserve,omitempty"`
	Drop         []string `json:"drop,omitempty"`
}

ProtocolMetadata describes provider-specific protocol-state policy.

type Provider 

type Provider struct {
	ID               string            `json:"id"`
	Name             string            `json:"name"`
	Transport        Transport         `json:"transport"`
	SystemRole       SystemRole        `json:"system_role"`
	UsageInStream    bool              `json:"usage_in_stream"`
	MaxTokensField   string            `json:"max_tokens_field"`
	ExtraBody        map[string]any    `json:"extra_body,omitempty"`
	Discovery        bool              `json:"discovery"`
	Hidden           bool              `json:"hidden,omitempty"`
	ProtocolMetadata *ProtocolMetadata `json:"protocol_metadata,omitempty"`
	Models           map[string]*Model `json:"models"`
	Builtin          bool              `json:"-"`
}

Provider is a resolved provider entry in the effective catalog.

type RawDiscoveredModel 

type RawDiscoveredModel map[string]any

RawDiscoveredModel is one provider-supplied model object from /v1/models.

type SystemRole 

type SystemRole string

SystemRole is the request role used for the system prompt. 

const (
	// RoleSystem uses the OpenAI system role.
	RoleSystem SystemRole = "system"
	// RoleUser uses the user role for system-prompt content.
	RoleUser SystemRole = "user"
	// RoleDeveloper uses the OpenAI developer role.
	RoleDeveloper SystemRole = "developer"
)

type Transport 

type Transport struct {
	BaseURL   string            `json:"base_url"`
	APIKeyEnv string            `json:"api_key_env"`
	Headers   map[string]string `json:"headers,omitempty"`
	Options   map[string]any    `json:"options,omitempty"`
}

Transport holds provider HTTP-construction config.

type ValidationError 

type ValidationError struct {
	Provider string
	Model    string
	Field    string
	Reason   string
}

ValidationError describes a catalog validation failure.

func ValidateEffective 

func ValidateEffective(p *Provider) []ValidationError

ValidateEffective checks a resolved provider and its models.

func ValidateRaw 

func ValidateRaw(provID string, raw map[string]any, strict bool) []ValidationError

ValidateRaw checks a raw provider envelope.

func (ValidationError) Error 

func (e ValidationError) Error() string

Error returns a human-readable validation error.

type Warning 

type Warning struct {
	Kind     string
	Message  string
	Provider string
	Model    string
}

Warning describes a recoverable catalog build problem.

func ReadDiscoveryCache 

func ReadDiscoveryCache(home string) (map[string]DiscoveredProvider, map[string]time.Time, []Warning)

ReadDiscoveryCache reads all on-disk discovery cache files and last-attempt timestamps. Old cache files without attempted_at use fetched_at as the attempt time for backwards compatibility.

func RefreshProviderDiscovery 

func RefreshProviderDiscovery(ctx context.Context, home string, cat *Catalog, providerID string) (bool, []Warning)

RefreshProviderDiscovery fetches one provider's live discovery data, merges it into the in-memory catalog, and writes the discovery cache. Discovery failures are returned as warnings so callers can continue startup.

func RefreshProviderDiscoveryWithConfigPath added in v0.0.2 

func RefreshProviderDiscoveryWithConfigPath(ctx context.Context, home, configPath string, cat *Catalog, providerID string) (bool, []Warning)

RefreshProviderDiscoveryWithConfigPath is RefreshProviderDiscovery with an explicit config path for preserving user-owned cost fields during merges.

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.