Documentation
¶
Overview ¶
Package provider owns the unified provider registry.
Every provider is an explicit ProviderInstance database row, regardless of whether its TypeKey is served by a Lua plugin or by a built-in Go adapter ("custom", "virtual").
Index ¶
- Constants
- Variables
- func IsCreatableTypeKey(typeKey string) bool
- type Completer
- type CreateOptions
- type Embedder
- type GoAdapter
- type ImageGenerator
- type Resolved
- type Service
- func (s *Service) CleanupOrphanedCredentials() (int, error)
- func (s *Service) ConfigSchema(typeKey string) ([]*models.UINode, error)
- func (s *Service) Create(opts CreateOptions) (*models.ProviderInstance, error)
- func (s *Service) CreateCustom(name, baseURL, iconURL string) (*models.ProviderInstance, error)
- func (s *Service) CredentialSchema(typeKey string) ([]*models.UINode, error)
- func (s *Service) Delete(id string) error
- func (s *Service) DeleteCustom(id string) error
- func (s *Service) EnsureSeeded() error
- func (s *Service) Get(id string) (*models.ProviderInstance, error)
- func (s *Service) GetByType(typeKey string) ([]*models.ProviderInstance, error)
- func (s *Service) GetByTypeAndQualifier(typeKey, qualifier string) (*models.ProviderInstance, error)
- func (s *Service) GetCustom(id string) (*models.ProviderInstance, error)
- func (s *Service) GoAdapterFor(typeKey string) (GoAdapter, bool)
- func (s *Service) GoAdapterTypes() []string
- func (s *Service) IsTypeAvailable(typeKey string) bool
- func (s *Service) List() ([]*models.ProviderInstance, error)
- func (s *Service) LuaService() *luaplugin.Service
- func (s *Service) RegisterGoAdapter(a GoAdapter)
- func (s *Service) SetLogger(l *slog.Logger)
- func (s *Service) SetLuaService(svc *luaplugin.Service)
- func (s *Service) SetOnChanged(fn func(providerID string))
- func (s *Service) SupportsAuthFlow(typeKey string) bool
- func (s *Service) SyncDefaultProviders() error
- func (s *Service) SystemDisable(id, reason string) error
- func (s *Service) TypeKeys() []string
- func (s *Service) Update(id string, opts UpdateOptions) (*models.ProviderInstance, error)
- func (s *Service) UpdateCustom(id, name, baseURL, iconURL string) (*models.ProviderInstance, error)
- type Speaker
- type Transcriber
- type UpdateOptions
Constants ¶
const ( TypeCustom = "custom" TypeVirtual = "virtual" )
Built-in type keys served by Go code.
Variables ¶
var ErrNotRefreshable = errors.New("credential type does not support refresh")
ErrNotRefreshable is returned by Go adapters that never refresh credentials.
Functions ¶
func IsCreatableTypeKey ¶
IsCreatableTypeKey reports whether users may create provider rows of a type through the UI. The agents singleton is core-managed and excluded; every other known type stays creatable (qualifier rows included).
Types ¶
type Completer ¶ added in v0.1.2
type Completer interface {
Complete(ctx context.Context, req *models.ChatCompletionRequest, token *models.RouterToken) (*models.ChatCompletionResponse, error)
CompleteStream(ctx context.Context, req *models.ChatCompletionRequest, w io.Writer, token *models.RouterToken) error
// LikelyExhausted is a cheap, best-effort pre-check: true means model
// carries a model-wide limit key and is worth skipping without an
// attempt. False is not a guarantee of success. Implementations with no
// exhausted store wired always return false.
LikelyExhausted(model models.ModelId) bool
// HasUsableCredential reports whether at least one credential for the
// model is not rate-limited. True means the model is worth attempting;
// false means every credential is in cooldown. Implementations with no
// exhausted store wired always return true.
HasUsableCredential(model models.ModelId) bool
}
Completer routes chat completions through the credential pool. It is implemented by the router service. Virtual models fan out through it instead of holding a concrete router dependency, breaking the provider → router → provider construction cycle.
type CreateOptions ¶
type CreateOptions struct {
Name string
TypeKey string
Qualifier string
Config map[string]any
IconURL string
}
CreateOptions holds parameters for creating a provider instance.
type Embedder ¶ added in v0.0.5
type Embedder interface {
Embed(ctx context.Context, creds []*models.Credential, req *models.EmbeddingsRequest, providerConfig map[string]any) (*models.EmbeddingsResponse, error)
}
Embedder is an optional GoAdapter capability serving POST /v1/embeddings. Lua plugin types implement the equivalent via the embed handler.
type GoAdapter ¶
type GoAdapter interface {
TypeKey() string
ValidateCredentials(data map[string]any) error
Complete(ctx context.Context, creds []*models.Credential, req *models.ChatCompletionRequest, providerConfig map[string]any) (*models.ChatCompletionResponse, error)
CompleteStream(ctx context.Context, creds []*models.Credential, req *models.ChatCompletionRequest, w io.Writer, providerConfig map[string]any) error
NeedsRefresh(cred *models.Credential) bool
RefreshCredential(ctx context.Context, cred *models.Credential) (map[string]any, error)
GetModelInfos(ctx context.Context, cred *models.Credential, providerConfig map[string]any) ([]models.ModelInfo, error)
}
GoAdapter is implemented by built-in Go backends ("custom", "virtual"). Lua plugin types are served by luaplugin.Service instead.
Request methods take the whole sorted credential pool: the backend tries keys in order, at most once each, and returns a single result. Key-level failures never leave the backend; there are no repeat passes or backoff pauses in the request path.
type ImageGenerator ¶ added in v0.0.5
type ImageGenerator interface {
GenerateImage(ctx context.Context, creds []*models.Credential, req *models.ImageGenerationRequest, providerConfig map[string]any) (*models.ImageGenerationResponse, error)
}
ImageGenerator is an optional GoAdapter capability serving POST /v1/images/generations. Lua plugin types implement the equivalent via the generate_image handler.
type Resolved ¶
type Resolved struct {
Instance *models.ProviderInstance
Plugin *luaplugin.PluginRecord
Go GoAdapter
}
Resolved is the dispatch bundle for one provider: its instance plus either a Lua plugin record or a built-in Go adapter.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service exposes unified ProviderInstance CRUD.
func NewService ¶
NewService constructs a provider Service. Construction performs no I/O: legacy migration runs in EnsureSeeded, where failures surface as errors.
func (*Service) CleanupOrphanedCredentials ¶
CleanupOrphanedCredentials deletes credentials whose provider no longer exists.
func (*Service) ConfigSchema ¶
ConfigSchema returns the config UI tree for a type key. Go types serve static trees; Lua types delegate to config_schema. ErrHandlerNotFound-equivalent (nil, nil) means "raw JSON fallback".
func (*Service) Create ¶
func (s *Service) Create(opts CreateOptions) (*models.ProviderInstance, error)
Create persists a new provider instance with a generated unique ID.
func (*Service) CreateCustom ¶
func (s *Service) CreateCustom(name, baseURL, iconURL string) (*models.ProviderInstance, error)
CreateCustom creates a custom provider. Kept for existing callers.
func (*Service) CredentialSchema ¶
CredentialSchema returns the credential UI tree for a type key.
func (*Service) DeleteCustom ¶
DeleteCustom deletes a custom provider by slug or full ID.
func (*Service) EnsureSeeded ¶
EnsureSeeded creates the built-in agents provider row and one provider row per enabled Lua plugin type key when none exists yet, keeping fresh installs routable without manual provider setup. Missing icons on existing rows are backfilled from the plugin; user-set icons are never overwritten. Seeded rows are marked UI-readonly (set automatically by the core, never from Lua or the dashboard); the virtual-models row is additionally UI-hidden.
Legacy custom rows migrate first: seeding must see the post-migration state, and migration failures surface here instead of hiding in the constructor.
func (*Service) Get ¶
func (s *Service) Get(id string) (*models.ProviderInstance, error)
Get returns a provider instance by ID.
func (*Service) GetByType ¶
func (s *Service) GetByType(typeKey string) ([]*models.ProviderInstance, error)
GetByType returns all providers served by a type key.
func (*Service) GetByTypeAndQualifier ¶
func (s *Service) GetByTypeAndQualifier(typeKey, qualifier string) (*models.ProviderInstance, error)
GetByTypeAndQualifier returns a specific provider by type and qualifier.
func (*Service) GetCustom ¶
func (s *Service) GetCustom(id string) (*models.ProviderInstance, error)
GetCustom retrieves a custom provider by slug or full ID.
func (*Service) GoAdapterFor ¶
GoAdapterFor returns the Go backend for a type key, if one is registered.
func (*Service) GoAdapterTypes ¶
GoAdapterTypes returns sorted registered Go type keys.
func (*Service) IsTypeAvailable ¶
IsTypeAvailable reports whether a backend serves typeKey right now: a built-in Go adapter or a currently registered Lua plugin type. Rows with unavailable types stay in the database so reinstalling the plugin restores them, but the dashboard hides them.
func (*Service) List ¶
func (s *Service) List() ([]*models.ProviderInstance, error)
List returns all provider instances sorted by ID.
func (*Service) LuaService ¶
LuaService returns the wired Lua plugin service, if any.
func (*Service) RegisterGoAdapter ¶
RegisterGoAdapter registers a built-in Go backend.
func (*Service) SetLuaService ¶
SetLuaService wires the Lua plugin service for plugin-backed types.
func (*Service) SetOnChanged ¶
SetOnChanged registers a callback fired after provider create/update/delete.
func (*Service) SupportsAuthFlow ¶
SupportsAuthFlow reports whether a type offers a multi-step auth wizard.
func (*Service) SyncDefaultProviders ¶
SyncDefaultProviders is a no-op kept for backward compatibility. Providers are explicit database rows; nothing is synthesized.
func (*Service) SystemDisable ¶ added in v0.2.0
SystemDisable disables a provider on structural_fault outcomes. First wins: an already-disabled provider keeps its original cause, so a late duplicate error cannot rewrite the admin-visible reason. Manual admin re-enable clears the flag; the next failure disables again with a fresh cause.
func (*Service) TypeKeys ¶
TypeKeys returns every known provider type: Go backends plus enabled Lua plugin type keys.
func (*Service) Update ¶
func (s *Service) Update(id string, opts UpdateOptions) (*models.ProviderInstance, error)
Update replaces a provider's mutable fields.
func (*Service) UpdateCustom ¶
func (s *Service) UpdateCustom(id, name, baseURL, iconURL string) (*models.ProviderInstance, error)
UpdateCustom updates a custom provider by slug or full ID.
type Speaker ¶ added in v0.0.5
type Speaker interface {
Speech(ctx context.Context, creds []*models.Credential, req *models.SpeechRequest, providerConfig map[string]any) (*models.SpeechResponse, error)
}
Speaker is an optional GoAdapter capability serving POST /v1/audio/speech. Lua plugin types implement the equivalent via the speech handler.
type Transcriber ¶ added in v0.0.5
type Transcriber interface {
Transcribe(ctx context.Context, creds []*models.Credential, req *models.TranscriptionRequest, providerConfig map[string]any) (*models.TranscriptionResponse, error)
}
Transcriber is an optional GoAdapter capability serving POST /v1/audio/transcriptions. Lua plugin types implement the equivalent via the transcribe handler.