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
- type Completer
- type CreateOptions
- type Embedder
- type GoAdapter
- type ImageGenerator
- type Moderator
- 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) CredentialSchema(typeKey string) ([]*models.UINode, error)
- func (s *Service) CredentialsEnabled(typeKey string) bool
- func (s *Service) Delete(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) GoAdapterFor(typeKey string) (GoAdapter, bool)
- func (s *Service) IsTypeAvailable(typeKey string) bool
- func (s *Service) JobSpecs(typeKey string) map[string]luaplugin.JobSpec
- func (s *Service) List() ([]*models.ProviderInstance, error)
- func (s *Service) LuaService() *luaplugin.Service
- func (s *Service) ProxiesEnabled(typeKey string) bool
- func (s *Service) ProxySchema(typeKey string) ([]*models.UINode, error)
- 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) SettingsSchema(typeKey string) ([]*models.UINode, error)
- func (s *Service) SupportsAuthFlow(typeKey string) bool
- func (s *Service) SyncDefaultProviders() error
- func (s *Service) SystemDisable(id, reason string) error
- func (s *Service) Update(id string, opts UpdateOptions) (*models.ProviderInstance, error)
- type Speaker
- type Transcriber
- type UpdateOptions
- type VideoGenerator
- type VideoSubmitter
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 ¶
This section is empty.
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
// SubmitVideo routes one video generation submit and persists the
// router-side job row.
SubmitVideo(ctx context.Context, req *models.VideoGenerationRequest, token *models.RouterToken) (*models.VideoGenerationResponse, error)
}
Completer routes chat completions through single-pass delegation. 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 Moderator ¶ added in v0.3.8
type Moderator interface {
Moderate(ctx context.Context, creds []*models.Credential, req *models.ModerationRequest, providerConfig map[string]any) (*models.ModerationResponse, error)
}
Moderator is an optional GoAdapter capability serving POST /v1/moderations. Lua plugin types implement the equivalent via the moderate 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) CredentialSchema ¶
CredentialSchema returns the credential UI tree for a type key.
func (*Service) CredentialsEnabled ¶ added in v0.3.8
CredentialsEnabled reports whether a type serves the credential table: a credential_schema table or an auth flow is present.
func (*Service) EnsureSeeded ¶
EnsureSeeded creates the virtual-models 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.
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. The qualifier runs through the same slugify as uniqueID, so lookups use the stored form ("My Qual" finds type:my-qual). Dedup-suffixed duplicates (type:qual-2) resolve only by exact ID via Get.
func (*Service) GoAdapterFor ¶
GoAdapterFor returns the Go backend for a type key, if one is registered.
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) JobSpecs ¶ added in v0.3.8
JobSpecs returns the stored job schedules for a type key.
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) ProxiesEnabled ¶ added in v0.3.8
ProxiesEnabled reports whether a type serves proxy settings.
func (*Service) ProxySchema ¶ added in v0.3.8
ProxySchema returns the extra proxy settings UI tree for a type key. Nil means the plugin declares no proxy surface.
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) SettingsSchema ¶ added in v0.3.8
SettingsSchema returns the plugin settings UI tree for a type key. Nil means the plugin declares no settings section.
func (*Service) SupportsAuthFlow ¶
SupportsAuthFlow reports whether a type offers a multi-step auth wizard.
func (*Service) SyncDefaultProviders ¶
SyncDefaultProviders seeds the built-in provider rows.
func (*Service) SystemDisable ¶ added in v0.2.0
SystemDisable disables a provider on explicit system request (doctor fix for backend-less types). Traffic outcomes never call it. First wins: an already-disabled provider keeps its original cause, so a late duplicate cannot rewrite the admin-visible reason. Manual admin re-enable clears the flag.
func (*Service) Update ¶
func (s *Service) Update(id string, opts UpdateOptions) (*models.ProviderInstance, error)
Update replaces a provider's mutable fields.
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.
type UpdateOptions ¶
UpdateOptions holds mutable provider fields.
type VideoGenerator ¶ added in v0.3.8
type VideoGenerator interface {
VideoSubmitter
PollVideo(ctx context.Context, creds []*models.Credential, model models.ModelId, upstreamJobID string, providerConfig map[string]any) (*models.VideoGenerationResponse, error)
VideoContent(ctx context.Context, creds []*models.Credential, model models.ModelId, upstreamJobID string, index int, providerConfig map[string]any) (*models.VideoContentResponse, error)
}
VideoGenerator is an optional GoAdapter capability serving /v1/videos. Lua plugin types implement the equivalent via the generate_video, poll_video and video_content handlers.
type VideoSubmitter ¶ added in v0.3.8
type VideoSubmitter interface {
SubmitVideo(ctx context.Context, creds []*models.Credential, req *models.VideoGenerationRequest, providerConfig map[string]any) (*models.VideoGenerationResponse, error)
}
VideoSubmitter is the narrow video capability virtual fan-out needs: submit one video job. Full backends implement VideoGenerator.