modelcatalog

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: May 26, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// SourceIDBuiltin is AGH'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 NormalizeExtensionSourceSlug 

func NormalizeExtensionSourceSlug(extensionName string) (string, error)

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

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 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) (*CatalogService, error)

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

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) Refresh 

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

Refresh updates registered sources and returns their latest statuses.

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 

func (ExecDiscoveryCommandExecutor) RunDiscoveryCommand(
	ctx context.Context,
	req DiscoveryCommandRequest,
) (DiscoveryCommandResult, error)

RunDiscoveryCommand runs one subprocess with the caller-supplied deadline.

type ListOptions 

type ListOptions struct {
	ProviderID   string
	SourceID     string
	Refresh      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 side-effect-free model discovery for one provider.

func NewLiveProviderSource 

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

NewLiveProviderSource creates one provider_live source.

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 without touching ACP sessions.

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 AGH provider id this source owns.

type LiveProviderSourcesConfig 

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

LiveProviderSourcesConfig configures built-in provider live discovery sources.

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
	LastError              string
}

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

func MergeRows 

func MergeRows(rows []ModelRow) []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
	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]aghconfig.ProviderConfig,
	cfg aghconfig.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 ProviderSecretResolver 

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

ProviderSecretResolver resolves provider credential refs for live discovery.

type ReasoningEffort 

type ReasoningEffort string

ReasoningEffort identifies one normalized model reasoning level. 

const (
	// ReasoningEffortMinimal is the smallest supported reasoning level.
	ReasoningEffortMinimal ReasoningEffort = "minimal"
	// ReasoningEffortLow is the low reasoning level.
	ReasoningEffortLow ReasoningEffort = "low"
	// ReasoningEffortMedium is the medium reasoning level.
	ReasoningEffortMedium ReasoningEffort = "medium"
	// ReasoningEffortHigh is the high reasoning level.
	ReasoningEffortHigh ReasoningEffort = "high"
	// ReasoningEffortXHigh is the extra-high reasoning level.
	ReasoningEffortXHigh ReasoningEffort = "xhigh"
)

type RefreshOptions 

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

RefreshOptions controls a model catalog refresh request.

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 AGH built-ins.

func NewConfigSource 

func NewConfigSource(providers map[string]aghconfig.ProviderConfig) Source

NewConfigSource creates the operator config model source.

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 AGH'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 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
	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.

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.