base

type CapabilitySpec ¶

type CapabilitySpec struct {
	// ID is a stable identifier; informational only at this layer.
	ID string
	// Type selects the implementation (e.g. openai, elevenlabs, cartesia).
	Type string
	// Model overrides the provider's default model.
	Model string
	// BaseURL overrides the provider's default API endpoint.
	BaseURL string
	// Credential carries the resolved credential.
	Credential credentials.Credential
	// AdditionalConfig carries provider-specific extras. Unknown keys
	// are ignored.
	AdditionalConfig map[string]any
}

CapabilitySpec is the unified runtime form of a typed-provider declaration (TTS, STT, embedding, image gen). The SDK's runtime-config layer translates pkg/config provider configs into this struct after resolving credentials.

Each capability package (tts, stt, embedding, image) aliases this type to preserve back-compat field-naming while sharing the factory machinery.

type EmbeddingProvider ¶

type EmbeddingProvider interface {
	Provider
	Embed(ctx context.Context, req EmbeddingRequest) (EmbeddingResponse, error)
}

EmbeddingProvider returns vectors for input texts.

type EmbeddingRequest ¶

type EmbeddingRequest struct {
	Inputs []string
	Hints  map[string]string
}

EmbeddingRequest carries text inputs for a vector embedding call.

type EmbeddingResponse ¶

type EmbeddingResponse struct {
	Vectors [][]float32
	Cost    *types.CostInfo
	Latency time.Duration
}

EmbeddingResponse holds the embedding vectors and metadata from a provider.

type Factory ¶

type Factory[T any] func(spec CapabilitySpec) (T, error)

Factory builds a typed Provider from a CapabilitySpec.

type FactoryRegistry ¶

type FactoryRegistry[T any] struct {
	// contains filtered or unexported fields
}

FactoryRegistry is a typed registry keyed by the implementation discriminator (spec.Type). Each capability package owns one registry instance.

func NewFactoryRegistry[T any]() *FactoryRegistry[T]

func (r *FactoryRegistry[T]) Create(spec CapabilitySpec) (T, error)

func (r *FactoryRegistry[T]) Register(implType string, f Factory[T])

type FlatPricing ¶ added in v1.5.5

type FlatPricing struct {
	Input  float64 // per 1K input tokens
	Output float64 // per 1K output tokens
}

FlatPricing is the legacy per-1K input/output rate a config may carry. It is mapped to canonical input_token/output_token price items when no richer descriptor is supplied. base defines its own type (rather than reusing a providers-package type) to avoid importing the providers package, which would create an import cycle.

type HTTPServiceDefaults ¶

type HTTPServiceDefaults struct {
	// Name is the provider's unique registry name (e.g. "openai-whisper").
	Name string
	// Type is the capability discriminator (inference, tts, stt, ...).
	Type ProviderType
	// Pricing is the compiled-in pricing descriptor.
	Pricing *PricingDescriptor
	// BaseURL is the default API endpoint.
	BaseURL string
	// Model is the default model identifier.
	Model string
	// Timeout is the default HTTP client timeout. Zero is treated as
	// http.DefaultClient (no timeout) — pass a positive value.
	Timeout time.Duration
}

HTTPServiceDefaults carries the construction-time defaults for an HTTP service provider (TTS, STT impls). Used by NewHTTPService to produce the standard *Implementation + *HTTPServiceFields pair every impl embeds.

type HTTPServiceFields ¶

type HTTPServiceFields struct {
	APIKey  string
	BaseURL string
	Model   string
	Client  *http.Client
}

HTTPServiceFields is the shared HTTP-call configuration embedded by service-style providers (TTS, STT impls). Each impl embeds *HTTPServiceFields to inherit APIKey/BaseURL/Model/Client storage plus the With* option helpers in this package — eliminating per-package With* boilerplate.

type HTTPServiceOption ¶

type HTTPServiceOption func(*HTTPServiceFields)

HTTPServiceOption mutates an HTTPServiceFields. Each impl re-types this for their own option signatures (e.g., type OpenAIOption = HTTPServiceOption).

func WithAPIKey(k string) HTTPServiceOption

func WithBaseURL(url string) HTTPServiceOption

func WithClient(c *http.Client) HTTPServiceOption

func WithModel(m string) HTTPServiceOption

type ImageProvider ¶

type ImageProvider interface {
	Provider
	Generate(ctx context.Context, req ImageRequest) (ImageResponse, error)
}

ImageProvider generates images from prompts.

type ImageRequest ¶

type ImageRequest struct {
	Prompt  string
	Size    string // e.g. "1024x1024"
	Quality string // e.g. "standard" | "hd"
	Count   int    // default 1
	Hints   map[string]string
}

ImageRequest carries parameters for an image generation call.

type ImageResponse ¶

type ImageResponse struct {
	Images   [][]byte
	MIMEType string
	Cost     *types.CostInfo
	Latency  time.Duration
}

ImageResponse holds generated image bytes and metadata from a provider.

type Implementation ¶

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

Implementation is an embeddable struct that supplies default Provider method implementations for a provider. Concrete impls populate the fields in their constructor and override any methods (Validate, Init, HealthCheck, Close) that need real behavior.

func NewImplementation(name string, typ ProviderType, pricing *PricingDescriptor) *Implementation

func (i *Implementation) Close() error

func (i *Implementation) HealthCheck(ctx context.Context) error

func (i *Implementation) Init(ctx context.Context) error

func (i *Implementation) Name() string

func (i *Implementation) Pricing() *PricingDescriptor

func (i *Implementation) SetPricing(p *PricingDescriptor)

func (i *Implementation) Type() ProviderType

func (i *Implementation) Validate() error

type InferenceProvider ¶

type InferenceProvider interface {
	Provider
}

InferenceProvider is the shared interface for chat / realtime / multimodal LLM providers. The full surface (Predict, PredictStream, etc.) is defined in runtime/providers/provider.go and embedded here via the existing providers.Provider interface, kept intact for back-compat.

For PR 1 this interface is forward-declared. Existing implementations satisfy it once they compose the base.Implementation helper (Task 7).

type InlinePricingResolver ¶

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

InlinePricingResolver returns descriptors registered at construction time (typically by the config loader). Lookup is keyed by (impl, model, capability).

func NewInlinePricingResolver() *InlinePricingResolver

func (r *InlinePricingResolver) Register(ref PricingRef, desc *PricingDescriptor)

func (r *InlinePricingResolver) Resolve(ctx context.Context, ref PricingRef) (*PricingDescriptor, error)

type LineItem ¶

type LineItem struct {
	Unit       string            `json:"unit"`
	Quantity   float64           `json:"quantity"`
	Rate       float64           `json:"rate"`
	USD        float64           `json:"usd"`
	Dimensions map[string]string `json:"dimensions,omitempty"`
}

LineItem is one row of a cost breakdown for reports.

func ComputeCost(desc *PricingDescriptor, info *types.CostInfo) (totalUSD float64, breakdown []LineItem, err error)

type PriceItem ¶

type PriceItem struct {
	Unit       string            `json:"unit"`
	Rate       float64           `json:"rate"`
	Dimensions map[string]string `json:"dimensions,omitempty"`
}

PriceItem is one line of a pricing table: a rate per unit, optionally scoped by dimensions (e.g. image size + quality).

func (p *PriceItem) UnmarshalJSON(data []byte) error

type PricingDescriptor ¶

type PricingDescriptor struct {
	Source           PricingSource `json:"source"`
	PricingCorrectAt time.Time     `json:"correct_at,omitempty"`
	Currency         string        `json:"currency,omitempty"` // default "usd"
	Items            []PriceItem   `json:"items"`
}

PricingDescriptor is the runtime-resolved pricing for a single provider+capability.

func PricingFromAdditionalConfig(additional map[string]any) *PricingDescriptor

func ResolveLLMPricing(
	configDesc *PricingDescriptor, flat FlatPricing,
	table map[string]*PricingDescriptor, model string,
) *PricingDescriptor

type PricingRef ¶

type PricingRef struct {
	Impl       string
	Model      string
	Capability ProviderType
	Hints      map[string]string
}

PricingRef identifies what we're pricing — the resolver maps this to a PricingDescriptor.

type PricingResolver ¶

type PricingResolver interface {
	Resolve(ctx context.Context, ref PricingRef) (*PricingDescriptor, error)
}

PricingResolver returns a PricingDescriptor for a given reference. Foundation PR ships only InlinePricingResolver; future work may add a remote impl that calls out to a service.

type PricingSource ¶

type PricingSource string

PricingSource discriminates how pricing values are obtained.

const (
	// PricingSourceInline reads pricing from the loaded YAML descriptor.
	PricingSourceInline PricingSource = "inline"
	// PricingSourceRemote is reserved; see RemotePricingResolver (future work).
	PricingSourceRemote PricingSource = "remote"
)

type Provider ¶

type Provider interface {
	Name() string
	Type() ProviderType
	Pricing() *PricingDescriptor
	Validate() error
	Init(ctx context.Context) error
	HealthCheck(ctx context.Context) error
	Close() error
}

Provider is implemented by every provider type. It carries only the cross-cutting surface that the registry, config loader, metric collector, and cost rollup need.

type ProviderType ¶

type ProviderType string

ProviderType discriminates capability types. Used as a registry key, metric label, and span attribute.

const (
	ProviderTypeInference ProviderType = "inference"
	ProviderTypeTTS       ProviderType = "tts"
	ProviderTypeSTT       ProviderType = "stt"
	ProviderTypeEmbedding ProviderType = "embedding"
	ProviderTypeImage     ProviderType = "image"
	ProviderTypeVideo     ProviderType = "video"
)

func AllProviderTypes() []ProviderType

func ParseProviderType(s string) (ProviderType, error)

type Registry ¶

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

Registry stores providers keyed by (name, capability).

func NewRegistry() *Registry

func (r *Registry) CloseAll() error

func (r *Registry) Get(name string, typ ProviderType) (Provider, error)

func (r *Registry) GetAll(typ ProviderType) []Provider

func (r *Registry) InitAll(ctx context.Context) error

func (r *Registry) PricingResolver() PricingResolver

func (r *Registry) Register(p Provider) error

func (r *Registry) SetPricingResolver(res PricingResolver)

type STTProvider ¶

type STTProvider interface {
	Provider
	Transcribe(ctx context.Context, req STTRequest) (STTResponse, error)
}

STTProvider transcribes audio to text.

type STTRequest ¶

type STTRequest struct {
	Audio    []byte
	MIMEType string
	Hints    map[string]string
}

STTRequest carries audio input for a speech-to-text transcription call.

type STTResponse ¶

type STTResponse struct {
	Text    string
	Cost    *types.CostInfo
	Latency time.Duration
}

STTResponse holds the transcribed text and metadata from an STT provider.

type SpanArgs ¶

type SpanArgs struct {
	Capability ProviderType
	Operation  string // "predict" | "synthesize" | "transcribe" | "embed" | "generate"
	Provider   string // base.Provider.Name()
	Impl       string // implementation discriminator (e.g. "openai", "imagen")
	Model      string
}

SpanArgs carries the standard attributes for a capability-scoped provider span.

type TTSProvider ¶

type TTSProvider interface {
	Provider
	SynthesizeTTS(ctx context.Context, req TTSRequest) (TTSStream, error)
}

TTSProvider produces audio from text. Streaming-first: every TTS call returns a TTSStream regardless of whether the underlying provider supports incremental synthesis. Buffered consumers can use ReadAllAudio to collect all chunks into a []byte.

The method is named SynthesizeTTS rather than Synthesize to avoid a naming conflict with the legacy tts.Service.Synthesize method that takes (text string, config SynthesisConfig). Both interfaces can be satisfied by the same concrete type simultaneously.

type TTSRequest ¶

type TTSRequest struct {
	Text       string
	Voice      string
	Speed      float32
	Format     string            // audio format hint, e.g. "mp3", "pcm" (provider-specific)
	SampleRate int               // desired output sample rate in Hz (0 = provider default)
	Hints      map[string]string // additional dimension hints passed to pricing
}

TTSRequest carries parameters for a text-to-speech synthesis call.

type TTSStream ¶

type TTSStream interface {
	// Chunks returns the channel of audio chunks. Caller must drain to
	// completion or call Close to release resources. The channel closes
	// when synthesis completes successfully or on error.
	Chunks() <-chan audio.Chunk
	// Cost returns the total cost of this synthesis. Returns nil before
	// the chunk channel has closed; returns a populated *types.CostInfo
	// afterwards. Pricing comes from the provider's PricingDescriptor.
	Cost() *types.CostInfo
	// Close cancels an in-progress stream and releases resources.
	// Safe to call multiple times.
	Close() error
}

TTSStream is the streaming output of a TTS provider's Synthesize call. It exposes the chunk channel that downstream pipeline stages consume, plus a typed accessor for the total cost (available once the chunk channel closes) and a Close method for early cancellation.

type TokenUsage ¶ added in v1.5.5

type TokenUsage struct {
	Input       int // full-price uncached input
	CacheRead   int
	CacheWrite  int
	Output      int // visible output only
	Reasoning   int
	AudioInput  int
	AudioOutput int
	// Extra carries future/uncommon units keyed by canonical unit name.
	Extra map[string]float64
}

TokenUsage is the normalized, provider-agnostic usage a provider hands to PriceUsage. Each provider maps its wire usage into these canonical meanings, absorbing its own quirks (cache-inclusive vs -exclusive input, reasoning bundled into output vs separate) so every field means the same thing here.

func (u TokenUsage) Quantities() map[string]float64

type VideoProvider ¶ added in v1.5.1

type VideoProvider interface {
	Provider
	Generate(ctx context.Context, req VideoRequest) (VideoResponse, error)
}

VideoProvider generates videos from prompts. No concrete provider implements this interface yet; it defines the shape that the video__generate tool resolves against once a provider (e.g. Veo) lands.

type VideoRequest ¶ added in v1.5.1

type VideoRequest struct {
	Prompt      string
	AspectRatio string            // e.g. "16:9"
	Hints       map[string]string // additional dimension hints passed to pricing
}

VideoRequest carries parameters for a video generation call.

type VideoResponse ¶ added in v1.5.1

type VideoResponse struct {
	Videos   [][]byte
	MIMEType string // e.g. "video/mp4"
	Cost     *types.CostInfo
	Latency  time.Duration
}

VideoResponse holds generated video bytes and metadata from a provider.