Documentation
¶
Index ¶
- Constants
- Variables
- func NormalizeExtensionSourceSlug(extensionName string) (string, error)
- func RedactString(value string) string
- func SourceKindExtensionID(extensionName string) (string, error)
- func SourceKindProviderLiveID(providerID string) string
- func ValidateSourceID(sourceID string) error
- func ValidateSourceIdentity(sourceID string, kind SourceKind) error
- type AvailabilityState
- type CatalogService
- type DiscoveryCommandExecutor
- type DiscoveryCommandRequest
- type DiscoveryCommandResult
- type EnvSecretResolver
- type ExecDiscoveryCommandExecutor
- type ListOptions
- type LiveProviderSource
- type LiveProviderSourcesConfig
- type Model
- type ModelRow
- type ModelsDevSource
- func (s *ModelsDevSource) ID() string
- func (s *ModelsDevSource) Kind() SourceKind
- func (s *ModelsDevSource) ListModels(ctx context.Context, opts ListOptions) ([]ModelRow, error)
- func (s *ModelsDevSource) Priority() int
- func (s *ModelsDevSource) ProviderIDs() []string
- func (s *ModelsDevSource) TTL() time.Duration
- func (s *ModelsDevSource) Timeout() time.Duration
- type ModelsDevSourceOption
- type ProviderSecretResolver
- type ReasoningEffort
- type RefreshOptions
- type RefreshState
- type Service
- type Source
- type SourceKind
- type SourceRef
- type SourceStatus
- type StaleFallbackError
- type Store
Constants ¶
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" )
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 ¶
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 ¶
NormalizeExtensionSourceSlug converts an extension name into the dynamic source-id slug.
func RedactString ¶
RedactString removes secret-shaped values from catalog errors.
func SourceKindExtensionID ¶
SourceKindExtensionID returns the stable source id for an extension model source.
func SourceKindProviderLiveID ¶
SourceKindProviderLiveID returns the stable source id for a live provider source.
func ValidateSourceID ¶
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 AvailabilityState = "unavailable_live" 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 ¶
DiscoveryCommandResult captures safe subprocess output for parsing.
type EnvSecretResolver ¶
EnvSecretResolver resolves env: secret refs from an environment lookup.
func (EnvSecretResolver) ResolveRef ¶
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.
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 ¶
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.