Documentation
¶
Overview ¶
Package providerregistry provides a client for fetching provider connection configs from a remote JSON registry server with in-memory caching. Package providerregistry fetches per-provider TECHNICAL CONFIG — the API-client wiring (endpoint, auth.type/env_var, streaming format, headers, retry/cost, message conversion quirks) — from the remote registry at https://sprout-foundry.github.io/sprout/ providers/{id}.json plus the index at providers/index.json.
Lifecycle:
- Published every 6h by .github/workflows/model-registry-publish.yml, which copies pkg/agent_providers/configs/*.json into providers/ with schema_version + published_at added by jq.
- Fetched at runtime by pkg/factory.refreshFromRemote, which UpsertConfigs each result into the global ProviderFactory so pkg/agent_providers.NewGenericProvider can build a working client from JSON alone (no per-provider Go code).
- Cached in-process for 5 min (positive) / 30 s (negative); SSRF + schema-validated before caching.
IMPORTANT — distinguish from pkg/providercatalog, which is a separate system with adjacent but DIFFERENT concerns:
- pkg/providercatalog: ONE combined JSON describing the curated UX layer — friendly descriptions, signup URLs, API-key help text, recommended-model justification. Used by onboarding / the model picker for human-facing copy. Refreshed by a separate workflow (.github/workflows/provider-catalog-refresh.yml).
- pkg/providerregistry (this package): per-provider TECHNICAL CONFIG that the API client actually uses to talk to a provider.
They overlap minimally (both have an id/name and a model list, in different shapes); they do not share infrastructure, schemas, or publish workflows. A consolidation has been discussed but the two systems serve different consumers (UI vs API client) so the seam is load-bearing.
Index ¶
- func ClearCache()
- func FetchAllProviders(ctx context.Context) (map[string]*RemoteProviderConfig, error)
- func IsEnabled() bool
- func SetBaseURL(url string)
- func SetHTTPTimeout(d time.Duration)
- func SetNegativeTTL(d time.Duration)
- func SetTTL(d time.Duration)
- func ValidateForPublish(id string, cfg *RemoteProviderConfig) error
- type RemoteAuthConfig
- type RemoteCostConfig
- type RemoteMessageConversion
- type RemoteModelConfig
- type RemoteModelInfo
- type RemotePatternOverride
- type RemoteProviderConfig
- type RemoteRequestDefaults
- type RemoteRetryConfig
- type RemoteStreamingConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FetchAllProviders ¶
func FetchAllProviders(ctx context.Context) (map[string]*RemoteProviderConfig, error)
FetchAllProviders fetches all provider configs from the registry.
It first fetches the index file ({baseURL}/providers/index.json), then concurrently fetches each provider file. Individual failures are silently skipped (partial results OK). If the index fetch fails, returns nil map and nil error (graceful degradation).
Returns a map keyed by provider ID.
func IsEnabled ¶
func IsEnabled() bool
IsEnabled returns true if the registry URL is configured and not disabled.
func SetBaseURL ¶
func SetBaseURL(url string)
SetBaseURL sets the registry base URL (useful for testing).
func SetHTTPTimeout ¶
SetHTTPTimeout sets the HTTP client timeout (useful for testing).
func SetNegativeTTL ¶
SetNegativeTTL sets the negative cache TTL for 404 responses (useful for testing).
func ValidateForPublish ¶ added in v0.16.8
func ValidateForPublish(id string, cfg *RemoteProviderConfig) error
ValidateForPublish runs the same structural schema check that FetchProvider applies at runtime, but is exported so the publish-time validator (cmd/validate_registry) can reject bad files BEFORE they hit GitHub Pages. The two share one rule set so what passes CI also passes at runtime.
Types ¶
type RemoteAuthConfig ¶
RemoteAuthConfig duplicates AuthConfig without the runtime-only Key field.
type RemoteCostConfig ¶
type RemoteCostConfig struct {
InputTokenCost float64 `json:"input_token_cost"`
OutputTokenCost float64 `json:"output_token_cost"`
Currency string `json:"currency"`
}
RemoteCostConfig duplicates CostConfig.
type RemoteMessageConversion ¶
type RemoteMessageConversion struct {
IncludeToolCallID bool `json:"include_tool_call_id"`
ConvertToolRoleToUser bool `json:"convert_tool_role_to_user"`
ReasoningContentField string `json:"reasoning_content_field"`
ArgumentsAsJSON bool `json:"arguments_as_json"`
SkipToolExecutionSummary bool `json:"skip_tool_execution_summary"`
ForceToolCallType string `json:"force_tool_call_type"`
}
RemoteMessageConversion duplicates MessageConversion.
type RemoteModelConfig ¶
type RemoteModelConfig struct {
DefaultContextLimit int `json:"default_context_limit"`
DefaultMaxCompletionTokens int `json:"default_max_completion_tokens,omitempty"`
ModelOverrides map[string]int `json:"model_overrides"`
MaxCompletionOverrides map[string]int `json:"max_completion_overrides,omitempty"`
PatternOverrides []RemotePatternOverride `json:"pattern_overrides"`
CompletionPatternOverrides []RemotePatternOverride `json:"completion_pattern_overrides,omitempty"`
ModelInfo []RemoteModelInfo `json:"model_info,omitempty"`
ContextLimit int `json:"context_limit,omitempty"`
SupportsVision bool `json:"supports_vision"`
VisionModel string `json:"vision_model"`
DefaultModel string `json:"default_model"`
AvailableModels []string `json:"available_models"`
}
RemoteModelConfig duplicates ModelConfig.
type RemoteModelInfo ¶
type RemoteModelInfo struct {
ID string `json:"id"`
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
ContextLength int `json:"context_length"`
Tags []string `json:"tags,omitempty"`
}
RemoteModelInfo duplicates ModelInfo.
type RemotePatternOverride ¶
type RemotePatternOverride struct {
Pattern string `json:"pattern"`
ContextLimit int `json:"context_limit"`
}
RemotePatternOverride duplicates PatternOverride.
type RemoteProviderConfig ¶
type RemoteProviderConfig struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Endpoint string `json:"endpoint"`
Auth RemoteAuthConfig `json:"auth"`
Headers map[string]string `json:"headers"`
Defaults RemoteRequestDefaults `json:"defaults"`
Conversion RemoteMessageConversion `json:"message_conversion"`
Streaming RemoteStreamingConfig `json:"streaming"`
Models RemoteModelConfig `json:"models"`
Retry RemoteRetryConfig `json:"retry"`
Cost RemoteCostConfig `json:"cost"`
}
RemoteProviderConfig duplicates ProviderConfig for remote JSON consumption.
func FetchProviderConfig ¶
func FetchProviderConfig(ctx context.Context, providerID string) (*RemoteProviderConfig, error)
FetchProviderConfig returns a provider connection config from the remote registry.
Return values:
- (config, nil): config from registry or cache
- (nil, nil): registry disabled, provider not found (404/negative cache)
- (nil, err): hard error (invalid provider ID, non-404 HTTP errors)
Caching behavior:
- Successful responses are cached for the configured TTL (default 5 minutes)
- 404 responses are cached in a negative cache for negativeTTL (default 30 seconds)
- Singleflight deduplicates concurrent requests for the same provider
- Use ClearCache() to manually invalidate all cached entries
func (*RemoteProviderConfig) ToProviderConfig ¶
func (r *RemoteProviderConfig) ToProviderConfig() *providers.ProviderConfig
ToProviderConfig converts this remote config to a providers.ProviderConfig. The Key field in Auth is left empty (runtime-only, set by the credential resolver).
type RemoteRequestDefaults ¶
type RemoteRequestDefaults struct {
Model string `json:"model"`
Temperature *float64 `json:"temperature"`
MaxTokens *int `json:"max_tokens"`
TopP *float64 `json:"top_p"`
Parameters map[string]interface{} `json:"parameters,omitempty"`
}
RemoteRequestDefaults duplicates RequestDefaults.
type RemoteRetryConfig ¶
type RemoteRetryConfig struct {
MaxAttempts int `json:"max_attempts"`
BaseDelayMs int `json:"base_delay_ms"`
BackoffMultiplier float64 `json:"backoff_multiplier"`
MaxDelayMs int `json:"max_delay_ms"`
RetryableErrors []string `json:"retryable_errors"`
}
RemoteRetryConfig duplicates RetryConfig.
type RemoteStreamingConfig ¶
type RemoteStreamingConfig struct {
Format string `json:"format"`
ChunkTimeoutMs int `json:"chunk_timeout_ms"`
DoneMarker string `json:"done_marker"`
}
RemoteStreamingConfig duplicates StreamingConfig.
Source Files