modelcatalog

package
v0.3.0-beta.18 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ReasoningEffortNone disables model reasoning explicitly.
	ReasoningEffortNone = reasoning.EffortNone
	// ReasoningEffortMinimal is the smallest non-zero reasoning level.
	ReasoningEffortMinimal = reasoning.EffortMinimal
	// ReasoningEffortLow is the low reasoning level.
	ReasoningEffortLow = reasoning.EffortLow
	// ReasoningEffortMedium is the medium reasoning level.
	ReasoningEffortMedium = reasoning.EffortMedium
	// ReasoningEffortHigh is the high reasoning level.
	ReasoningEffortHigh = reasoning.EffortHigh
	// ReasoningEffortXHigh is the extra-high reasoning level.
	ReasoningEffortXHigh = reasoning.EffortXHigh
	// ReasoningEffortMax requests the provider's maximum supported reasoning level.
	ReasoningEffortMax = reasoning.EffortMax
)
View Source
const (
	// SourceIDBuiltin is Compozy's offline bootstrap catalog source.
	SourceIDBuiltin = "builtin"
	// SourceIDConfig is the operator-authored provider config source.
	SourceIDConfig = "config"
	// SourceIDModelsDev is the models.dev catalog source.
	SourceIDModelsDev = "models_dev"
)
View Source
const (
	// PriorityConfig lets explicit operator config win source conflicts.
	PriorityConfig = 120
	// PriorityProviderLive ranks live provider data above extension rows.
	PriorityProviderLive = 110
	// PriorityExtension ranks extension-provided rows above catalog enrichment.
	PriorityExtension = 100
	// PriorityModelsDev ranks models.dev as catalog enrichment.
	PriorityModelsDev = 50
	// PriorityBuiltin ranks offline bootstrap rows last.
	PriorityBuiltin = 10
)

Variables

View Source
var (
	// ErrAllSourcesFailed reports that refresh could not produce usable rows.
	ErrAllSourcesFailed = errors.New("model catalog: all usable sources failed")
	// ErrSourceDisabled reports that a source is intentionally disabled.
	ErrSourceDisabled = errors.New("model catalog: source disabled")
	// ErrSourceNotRegistered reports that a requested source id is not registered.
	ErrSourceNotRegistered = errors.New("model catalog: source not registered")
)

Functions

func CostSourceValues

func CostSourceValues() []string

CostSourceValues returns the closed public cost-source enum.

func CostStatusValues

func CostStatusValues() []string

CostStatusValues returns the closed public cost-status enum.

func IsValidEffort

func IsValidEffort(value string) bool

IsValidEffort reports whether value is one canonical explicit effort. Empty is deliberately invalid here: it is the separate provider-default sentinel.

func NormalizeExtensionSourceSlug

func NormalizeExtensionSourceSlug(extensionName string) (string, error)

NormalizeExtensionSourceSlug converts an extension name into the dynamic source-id slug.

func NormalizeReleaseDate

func NormalizeReleaseDate(value string) (*string, error)

NormalizeReleaseDate validates and normalizes YYYY-MM or YYYY-MM-DD metadata.

func ReasoningEffortValues

func ReasoningEffortValues() []string

ReasoningEffortValues returns the canonical explicit effort vocabulary in display order.

func ReasoningSourceValues

func ReasoningSourceValues() []string

ReasoningSourceValues returns the canonical reasoning provenance vocabulary.

func RedactString

func RedactString(value string) string

RedactString removes secret-shaped values from catalog errors.

func SourceKindExtensionID

func SourceKindExtensionID(extensionName string) (string, error)

SourceKindExtensionID returns the stable source id for an extension model source.

func SourceKindProviderLiveID

func SourceKindProviderLiveID(providerID string) string

SourceKindProviderLiveID returns the stable source id for a live provider source.

func ValidateSourceID

func ValidateSourceID(sourceID string) error

ValidateSourceID checks a stable catalog source identity.

func ValidateSourceIdentity

func ValidateSourceIdentity(sourceID string, kind SourceKind) error

ValidateSourceIdentity checks that a source id and kind describe the same source family.

Types

type ACPModelProbe

type ACPModelProbe struct{}

ACPModelProbe reads advertised model options through ACP.

func (ACPModelProbe) InspectCursorModels

InspectCursorModels creates a short-lived ACP session without changing its configuration.

type AvailabilityState

type AvailabilityState string

AvailabilityState identifies how reliable the merged availability signal is.

const (
	// AvailabilityStateAvailableLive means a fresh live source reports availability.
	AvailabilityStateAvailableLive AvailabilityState = "available_live"
	// AvailabilityStateAvailableStale means a stale live source reports availability.
	AvailabilityStateAvailableStale AvailabilityState = "available_stale"
	// AvailabilityStateUnavailableLive means a fresh live source reports unavailability.
	AvailabilityStateUnavailableLive AvailabilityState = "unavailable_live"
	// AvailabilityStateUnavailableStale means a stale live source reports unavailability.
	AvailabilityStateUnavailableStale AvailabilityState = "unavailable_stale"
	// AvailabilityStateUnknown means no live or extension source reported availability.
	AvailabilityStateUnknown AvailabilityState = "unknown"
)

type CatalogService

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

CatalogService refreshes sources and projects stored model catalog rows.

func NewService

func NewService(store Store, sources []Source, mergeOptions MergeOptions) (*CatalogService, error)

NewService creates a model catalog service from a store and source list.

func (*CatalogService) CommitRefreshPlan

func (s *CatalogService) CommitRefreshPlan(ctx context.Context, plan *RefreshPlan) error

CommitRefreshPlan atomically publishes every staged source replacement.

func (*CatalogService) ListModels

func (s *CatalogService) ListModels(ctx context.Context, opts ListOptions) ([]Model, error)

ListModels returns the merged catalog projection.

func (*CatalogService) ListSourceStatus

func (s *CatalogService) ListSourceStatus(ctx context.Context, providerID string) ([]SourceStatus, error)

ListSourceStatus returns provider-scoped source health rows.

func (*CatalogService) NewRefreshPlan

func (s *CatalogService) NewRefreshPlan() (*RefreshPlan, error)

NewRefreshPlan creates an isolated, read-through refresh generation.

func (*CatalogService) Refresh

func (s *CatalogService) Refresh(ctx context.Context, opts RefreshOptions) ([]SourceStatus, error)

Refresh updates registered sources and returns their latest statuses.

func (*CatalogService) UpdateMergeOptions

func (s *CatalogService) UpdateMergeOptions(options MergeOptions)

UpdateMergeOptions replaces provider capability inputs for subsequent projections.

type CatalogView

type CatalogView string

CatalogView identifies the public catalog projection to return.

const (
	// CatalogViewCurated returns the default operator-facing model set.
	CatalogViewCurated CatalogView = "curated"
	// CatalogViewAll returns every current model, including hidden and deprecated rows.
	CatalogViewAll CatalogView = "all"
)

type CostResult

type CostResult struct {
	Amount   float64
	Currency string
	Status   CostStatus
	Source   CostSource
}

CostResult is one truthful monetary projection for a usage update.

func EstimateCost

func EstimateCost(model *Model, usage TokenBuckets) (CostResult, bool)

EstimateCost joins usage with independent merged catalog rates for every token bucket.

type CostSource

type CostSource string

CostSource identifies the authority behind a cost result.

const (
	CostSourceAgentReported CostSource = "agent_reported"
	CostSourceCatalogConfig CostSource = "catalog_config"
	CostSourceModelsDev     CostSource = "models_dev"
	CostSourceBuiltin       CostSource = "builtin"
	CostSourceNone          CostSource = "none"
)

type CostStatus

type CostStatus string

CostStatus identifies how Compozy obtained a cost result.

const (
	CostStatusActual    CostStatus = "actual"
	CostStatusEstimated CostStatus = "estimated"
	CostStatusIncluded  CostStatus = "included"
	CostStatusUnknown   CostStatus = "unknown"
)

type CursorACPModelProbe

type CursorACPModelProbe interface {
	InspectCursorModels(context.Context, CursorACPModelProbeRequest) ([]acp.SessionConfigOption, error)
}

CursorACPModelProbe reads model options advertised by a short-lived Cursor ACP session.

type CursorACPModelProbeRequest

type CursorACPModelProbeRequest struct {
	ProviderID string
	Command    string
	Cwd        string
	Env        []string
	Timeout    time.Duration
}

CursorACPModelProbeRequest captures one Cursor ACP discovery invocation.

type DiscoveryCommandExecutor

type DiscoveryCommandExecutor interface {
	RunDiscoveryCommand(ctx context.Context, req DiscoveryCommandRequest) (DiscoveryCommandResult, error)
}

DiscoveryCommandExecutor runs a provider discovery command.

type DiscoveryCommandRequest

type DiscoveryCommandRequest struct {
	ProviderID string
	Command    string
	Args       []string
	Env        []string
	Timeout    time.Duration
}

DiscoveryCommandRequest describes one timeout-bound discovery subprocess.

type DiscoveryCommandResult

type DiscoveryCommandResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

DiscoveryCommandResult captures safe subprocess output for parsing.

type EnvSecretResolver

type EnvSecretResolver struct {
	LookupEnv func(string) (string, bool)
}

EnvSecretResolver resolves env: secret refs from an environment lookup.

func (EnvSecretResolver) ResolveRef

func (r EnvSecretResolver) ResolveRef(ctx context.Context, ref string) (string, error)

ResolveRef resolves one env-backed provider credential ref.

type ExecDiscoveryCommandExecutor

type ExecDiscoveryCommandExecutor struct{}

ExecDiscoveryCommandExecutor runs discovery commands as subprocesses.

func (ExecDiscoveryCommandExecutor) RunDiscoveryCommand

RunDiscoveryCommand runs one subprocess with the caller-supplied deadline.

type InvalidReasoningEffortError

type InvalidReasoningEffortError struct {
	ProviderID string
	ModelID    string
	Field      string
	Effort     string
}

InvalidReasoningEffortError reports a non-canonical effort at a catalog source boundary.

func (*InvalidReasoningEffortError) Error

type InvalidViewError

type InvalidViewError struct {
	View string
}

InvalidViewError reports an unsupported public catalog view.

func (*InvalidViewError) Error

func (e *InvalidViewError) Error() string

type ListOptions

type ListOptions struct {
	ProviderID         string
	SourceID           string
	View               CatalogView
	Refresh            bool
	SkipRefreshIfEmpty bool
	IncludeAll         bool
	IncludeStale       bool
	Now                time.Time
}

ListOptions filters persisted catalog source rows.

type LiveProviderSource

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

LiveProviderSource performs provider model discovery for one provider.

func NewLiveProviderSource

func NewLiveProviderSource(
	providerID string,
	provider compozyconfig.ProviderConfig,
	cfg LiveProviderSourcesConfig,
) (*LiveProviderSource, error)

NewLiveProviderSource creates one provider_live source.

func (*LiveProviderSource) BootstrapOnList

func (s *LiveProviderSource) BootstrapOnList() bool

BootstrapOnList reports whether the source should discover once before its first catalog projection.

func (*LiveProviderSource) CloneWithProvider

func (s *LiveProviderSource) CloneWithProvider(
	provider compozyconfig.ProviderConfig,
) (*LiveProviderSource, bool, error)

CloneWithProvider copies a live source with a staged provider configuration.

func (*LiveProviderSource) ID

func (s *LiveProviderSource) ID() string

ID returns the provider_live source id.

func (*LiveProviderSource) Kind

func (s *LiveProviderSource) Kind() SourceKind

Kind returns provider_live.

func (*LiveProviderSource) ListModels

func (s *LiveProviderSource) ListModels(ctx context.Context, opts ListOptions) ([]ModelRow, error)

ListModels discovers live provider models. Cursor uses a short-lived ACP session because its CLI aliases are not ACP model values.

func (*LiveProviderSource) Priority

func (s *LiveProviderSource) Priority() int

Priority returns the provider_live merge priority.

func (*LiveProviderSource) ProviderIDs

func (s *LiveProviderSource) ProviderIDs() []string

ProviderIDs returns the single CompozyOS provider id this source owns.

func (*LiveProviderSource) ReplaceProvider

func (s *LiveProviderSource) ReplaceProvider(provider compozyconfig.ProviderConfig) bool

ReplaceProvider atomically applies the provider config used by subsequent discovery calls.

type LiveProviderSourcesConfig

type LiveProviderSourcesConfig struct {
	Providers       map[string]compozyconfig.ProviderConfig
	HomePaths       compozyconfig.HomePaths
	BaseEnv         []string
	SecretResolver  ProviderSecretResolver
	HTTPClient      *http.Client
	CommandExecutor DiscoveryCommandExecutor
	CursorACPProbe  CursorACPModelProbe
	DefaultTimeout  time.Duration
}

LiveProviderSourcesConfig configures built-in provider live discovery sources.

type MergeOptions

type MergeOptions struct {
	ReasoningApply map[string]bool
}

MergeOptions supplies provider capabilities needed to keep catalog claims truthful.

type Model

type Model struct {
	ProviderID               string
	ModelID                  string
	DisplayName              string
	Sources                  []SourceRef
	Available                *bool
	AvailabilityState        AvailabilityState
	Stale                    bool
	RefreshedAt              time.Time
	ContextWindow            *int64
	MaxInputTokens           *int64
	MaxOutputTokens          *int64
	SupportsTools            *bool
	SupportsReasoning        *bool
	ReasoningEfforts         []ReasoningEffort
	DefaultReasoningEffort   *ReasoningEffort
	CostInputPerMillion      *float64
	CostOutputPerMillion     *float64
	CostCacheReadPerMillion  *float64
	CostCacheWritePerMillion *float64
	CostReasoningPerMillion  *float64
	CostInputSource          SourceKind
	CostOutputSource         SourceKind
	CostCacheReadSource      SourceKind
	CostCacheWriteSource     SourceKind
	CostReasoningSource      SourceKind
	ExplicitlyCurated        bool
	Curated                  bool
	Deprecated               bool
	Hidden                   bool
	Featured                 bool
	ReleaseDate              *string
	ReasoningSource          ReasoningSource
	LastError                string
}

Model is the deterministic merged projection for one provider/model key.

func MergeRows

func MergeRows(rows []ModelRow, opts MergeOptions) []Model

MergeRows computes deterministic model projections from source rows.

type ModelRow

type ModelRow struct {
	ProviderID               string
	ModelID                  string
	DisplayName              string
	SourceID                 string
	SourceKind               SourceKind
	Priority                 int
	Available                *bool
	Stale                    bool
	RefreshedAt              time.Time
	ExpiresAt                time.Time
	ContextWindow            *int64
	MaxInputTokens           *int64
	MaxOutputTokens          *int64
	SupportsTools            *bool
	SupportsReasoning        *bool
	ReasoningEfforts         []ReasoningEffort
	DefaultReasoningEffort   *ReasoningEffort
	CostInputPerMillion      *float64
	CostOutputPerMillion     *float64
	CostCacheReadPerMillion  *float64
	CostCacheWritePerMillion *float64
	CostReasoningPerMillion  *float64
	ExplicitlyCurated        bool
	Deprecated               *bool
	Hidden                   *bool
	Featured                 *bool
	ReleaseDate              *string
	LastError                string
}

ModelRow is one provider/model record contributed by one catalog source.

type ModelsDevSource

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

ModelsDevSource fetches catalog enrichment from models.dev.

func NewModelsDevSource

func NewModelsDevSource(
	providers map[string]compozyconfig.ProviderConfig,
	cfg compozyconfig.ModelsDevSourceConfig,
	options ...ModelsDevSourceOption,
) (*ModelsDevSource, error)

NewModelsDevSource creates a configured models.dev source.

func (*ModelsDevSource) ID

func (s *ModelsDevSource) ID() string

func (*ModelsDevSource) Kind

func (s *ModelsDevSource) Kind() SourceKind

func (*ModelsDevSource) ListModels

func (s *ModelsDevSource) ListModels(ctx context.Context, opts ListOptions) ([]ModelRow, error)

func (*ModelsDevSource) Priority

func (s *ModelsDevSource) Priority() int

func (*ModelsDevSource) ProviderIDs

func (s *ModelsDevSource) ProviderIDs() []string

func (*ModelsDevSource) TTL

func (s *ModelsDevSource) TTL() time.Duration

func (*ModelsDevSource) Timeout

func (s *ModelsDevSource) Timeout() time.Duration

Timeout returns the explicit HTTP timeout used by the source.

type ModelsDevSourceOption

type ModelsDevSourceOption func(*ModelsDevSource)

ModelsDevSourceOption customizes models.dev source construction.

func WithModelsDevHTTPClient

func WithModelsDevHTTPClient(client *http.Client) ModelsDevSourceOption

WithModelsDevHTTPClient injects the explicit-timeout HTTP client used for models.dev fetches.

type ProviderConfigSource

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

ProviderConfigSource projects one replaceable provider-config snapshot.

func NewConfigSource

func NewConfigSource(providers map[string]compozyconfig.ProviderConfig) *ProviderConfigSource

NewConfigSource creates the operator config model source.

func (*ProviderConfigSource) ID

func (s *ProviderConfigSource) ID() string

func (*ProviderConfigSource) Kind

func (s *ProviderConfigSource) Kind() SourceKind

func (*ProviderConfigSource) ListModels

func (s *ProviderConfigSource) ListModels(
	_ context.Context,
	opts ListOptions,
) ([]ModelRow, error)

func (*ProviderConfigSource) Priority

func (s *ProviderConfigSource) Priority() int

func (*ProviderConfigSource) ProviderIDs

func (s *ProviderConfigSource) ProviderIDs() []string

func (*ProviderConfigSource) ReplaceProviders

func (s *ProviderConfigSource) ReplaceProviders(providers map[string]compozyconfig.ProviderConfig)

ReplaceProviders atomically replaces the source snapshot used by subsequent refreshes.

type ProviderSecretResolver

type ProviderSecretResolver interface {
	ResolveRef(ctx context.Context, ref string) (string, error)
}

ProviderSecretResolver resolves provider credential refs for live discovery.

type ReasoningEffort

type ReasoningEffort = reasoning.Effort

ReasoningEffort identifies one canonical model reasoning level.

type ReasoningProfile

type ReasoningProfile struct {
	Supported bool
	Efforts   []ReasoningEffort
	Default   ReasoningEffort
	Source    ReasoningSource
}

ReasoningProfile is one model's effective reasoning capability.

type ReasoningSource

type ReasoningSource string

ReasoningSource identifies where a selectable reasoning profile came from.

const (
	// ReasoningSourceACP identifies an active ACP session observation.
	ReasoningSourceACP ReasoningSource = "acp"
	// ReasoningSourceCatalog identifies static or provider-discovery catalog data.
	ReasoningSourceCatalog ReasoningSource = "catalog"
)

type RefreshOptions

type RefreshOptions struct {
	ProviderID string
	SourceID   string
	Force      bool
	RequestID  string
	Now        time.Time
}

RefreshOptions controls a model catalog refresh request.

type RefreshPlan

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

RefreshPlan buffers source replacements until a whole catalog generation is ready.

func (*RefreshPlan) Refresh

func (p *RefreshPlan) Refresh(
	ctx context.Context,
	source Source,
	opts RefreshOptions,
) ([]SourceStatus, error)

Refresh stages one source refresh without publishing it to the durable store.

type RefreshState

type RefreshState string

RefreshState identifies one source refresh lifecycle state.

const (
	// RefreshStateIdle indicates a source has no active refresh state.
	RefreshStateIdle RefreshState = "idle"
	// RefreshStateRefreshing indicates a source refresh is currently running.
	RefreshStateRefreshing RefreshState = "refreshing"
	// RefreshStateSucceeded indicates the last source refresh succeeded.
	RefreshStateSucceeded RefreshState = "succeeded"
	// RefreshStateFailed indicates the last source refresh failed.
	RefreshStateFailed RefreshState = "failed"
	// RefreshStateDisabled indicates a configured source is disabled.
	RefreshStateDisabled RefreshState = "disabled"
)

type Service

type Service interface {
	ListModels(ctx context.Context, opts ListOptions) ([]Model, error)
	Refresh(ctx context.Context, opts RefreshOptions) ([]SourceStatus, error)
	ListSourceStatus(ctx context.Context, providerID string) ([]SourceStatus, error)
}

Service exposes merged model catalog projections.

type Source

type Source interface {
	ID() string
	Kind() SourceKind
	Priority() int
	ListModels(ctx context.Context, opts ListOptions) ([]ModelRow, error)
}

Source produces model rows for one catalog source.

func NewBuiltinSource

func NewBuiltinSource() Source

NewBuiltinSource creates the offline bootstrap source from Compozy built-ins.

func NewLiveProviderSources

func NewLiveProviderSources(cfg LiveProviderSourcesConfig) ([]Source, error)

NewLiveProviderSources creates provider_live sources for known provider adapters.

type SourceKind

type SourceKind string

SourceKind identifies the provenance family for a catalog source row.

const (
	// SourceKindBuiltin identifies Compozy's offline bootstrap catalog.
	SourceKindBuiltin SourceKind = "builtin"
	// SourceKindConfig identifies operator-authored provider model config.
	SourceKindConfig SourceKind = "config"
	// SourceKindModelsDev identifies enrichment from models.dev.
	SourceKindModelsDev SourceKind = "models_dev"
	// SourceKindProviderLive identifies live provider discovery.
	SourceKindProviderLive SourceKind = "provider_live"
	// SourceKindExtension identifies extension-provided model source rows.
	SourceKindExtension SourceKind = "extension"
	// SourceKindACPSession identifies session-scoped ACP observations.
	SourceKindACPSession SourceKind = "acp_session"
)

type SourceRef

type SourceRef struct {
	SourceID    string
	SourceKind  SourceKind
	Priority    int
	RefreshedAt time.Time
	Stale       bool
	LastError   string
}

SourceRef identifies one source participating in a merged catalog projection.

type SourceRowsReplacement

type SourceRowsReplacement struct {
	SourceID   string
	ProviderID string
	Rows       []ModelRow
	Status     SourceStatus
}

SourceRowsReplacement is one provider-scoped source publication.

type SourceStatus

type SourceStatus struct {
	SourceID     string
	SourceKind   SourceKind
	ProviderID   string
	Priority     int
	LastRefresh  time.Time
	NextRefresh  time.Time
	LastSuccess  time.Time
	LastError    string
	RefreshState RefreshState
	RowCount     int
	Stale        bool
}

SourceStatus reports provider-scoped source health and row counts.

type StaleFallbackError

type StaleFallbackError struct {
	SourceID string
	Err      error
}

StaleFallbackError reports a refresh failure that returned stale fallback rows.

func (*StaleFallbackError) Error

func (e *StaleFallbackError) Error() string

func (*StaleFallbackError) Unwrap

func (e *StaleFallbackError) Unwrap() error

type Store

type Store interface {
	ReplaceSourceRows(
		ctx context.Context,
		sourceID string,
		providerID string,
		rows []ModelRow,
		status SourceStatus,
	) error
	// ReplaceSourceRowsBatch publishes every replacement atomically.
	ReplaceSourceRowsBatch(ctx context.Context, replacements []SourceRowsReplacement) error
	ListRows(ctx context.Context, opts ListOptions) ([]ModelRow, error)
	ListSourceStatus(ctx context.Context, providerID string) ([]SourceStatus, error)
}

Store persists source rows and provider-scoped source status.

type TokenBuckets

type TokenBuckets struct {
	Input      *int64
	Output     *int64
	CacheRead  *int64
	CacheWrite *int64
	Reasoning  *int64
}

TokenBuckets carries the usage buckets priced by the merged model catalog.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL