provider

package
v0.3.7 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 17 Imported by: 0

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

View Source
const (
	TypeCustom  = "custom"
	TypeVirtual = "virtual"
)

Built-in type keys served by Go code.

Variables

View Source
var ErrNotRefreshable = errors.New("credential type does not support refresh")

ErrNotRefreshable is returned by Go adapters that never refresh credentials.

Functions

func IsCreatableTypeKey

func IsCreatableTypeKey(typeKey string) bool

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.

func Resolve

func Resolve(svc *Service, providerID string) (*Resolved, error)

Resolve looks up a provider by ID and its backend in one operation.

func (*Resolved) IsLua

func (r *Resolved) IsLua() bool

IsLua reports whether the provider is served by a Lua plugin.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service exposes unified ProviderInstance CRUD.

func NewService

func NewService(database *db.DB) *Service

NewService constructs a provider Service. Construction performs no I/O: legacy migration runs in EnsureSeeded, where failures surface as errors.

func (*Service) CleanupOrphanedCredentials

func (s *Service) CleanupOrphanedCredentials() (int, error)

CleanupOrphanedCredentials deletes credentials whose provider no longer exists.

func (*Service) ConfigSchema

func (s *Service) ConfigSchema(typeKey string) ([]*models.UINode, error)

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

func (s *Service) CredentialSchema(typeKey string) ([]*models.UINode, error)

CredentialSchema returns the credential UI tree for a type key.

func (*Service) Delete

func (s *Service) Delete(id string) error

Delete removes a provider and cascades its credentials in one transaction.

func (*Service) DeleteCustom

func (s *Service) DeleteCustom(id string) error

DeleteCustom deletes a custom provider by slug or full ID.

func (*Service) EnsureSeeded

func (s *Service) EnsureSeeded() error

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. 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) GetCustom

func (s *Service) GetCustom(id string) (*models.ProviderInstance, error)

GetCustom retrieves a custom provider by slug or full ID.

func (*Service) GoAdapterFor

func (s *Service) GoAdapterFor(typeKey string) (GoAdapter, bool)

GoAdapterFor returns the Go backend for a type key, if one is registered.

func (*Service) GoAdapterTypes

func (s *Service) GoAdapterTypes() []string

GoAdapterTypes returns sorted registered Go type keys.

func (*Service) IsTypeAvailable

func (s *Service) IsTypeAvailable(typeKey string) bool

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

func (s *Service) LuaService() *luaplugin.Service

LuaService returns the wired Lua plugin service, if any.

func (*Service) RegisterGoAdapter

func (s *Service) RegisterGoAdapter(a GoAdapter)

RegisterGoAdapter registers a built-in Go backend.

func (*Service) SetLogger

func (s *Service) SetLogger(l *slog.Logger)

SetLogger wires structured logging for CRUD.

func (*Service) SetLuaService

func (s *Service) SetLuaService(svc *luaplugin.Service)

SetLuaService wires the Lua plugin service for plugin-backed types.

func (*Service) SetOnChanged

func (s *Service) SetOnChanged(fn func(providerID string))

SetOnChanged registers a callback fired after provider create/update/delete.

func (*Service) SupportsAuthFlow

func (s *Service) SupportsAuthFlow(typeKey string) bool

SupportsAuthFlow reports whether a type offers a multi-step auth wizard.

func (*Service) SyncDefaultProviders

func (s *Service) SyncDefaultProviders() error

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

func (s *Service) SystemDisable(id, reason string) error

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

func (s *Service) TypeKeys() []string

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.

type UpdateOptions

type UpdateOptions struct {
	Name     string
	Config   map[string]any
	IconURL  string
	Disabled *bool
}

UpdateOptions holds mutable provider fields.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL