base

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Feb 8, 2026 License: Apache-2.0 Imports: 19 Imported by: 1

Documentation

Overview

Package base is awesome sauce to reduce code duplication across most providers.

It is not meant to be used by end users.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTransport http.RoundTripper = &roundtrippers.Retry{
	Transport: http.DefaultTransport,
	Policy: &roundtrippers.ExponentialBackoff{
		MaxTryCount: 10,
		MaxDuration: 60 * time.Second,
		Exp:         1.5,
	},
}

DefaultTransport integrates HTTP retries.

It uses a quite long retry count. If latency matters for you, you may want to use a shorter retry policy. Do this by passing the `wrapper` argument in the `New()` function and ignore the `http.RoundTripper` passed in.

Functions

func MimeByExt 

func MimeByExt(ext string) string

MimeByExt wraps mime.TypeByExtension.

It overrides audio entries because they vary surprisingly a lot across OSes!

func SimulateStream 

func SimulateStream(ctx context.Context, c genai.Provider, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))

SimulateStream simulates GenStream for APIs that do not support streaming.

Types

type ErrAPI 

type ErrAPI interface {
	error
	IsAPIError() bool
}

ErrAPI is returned when the API returns a structured error.

type ErrAPIKeyRequired 

type ErrAPIKeyRequired struct {
	EnvVar string
	URL    string
}

ErrAPIKeyRequired is returned by the providers New() function when no key was found.

func (*ErrAPIKeyRequired) Error 

func (e *ErrAPIKeyRequired) Error() string

type ErrNotSupported 

type ErrNotSupported struct {
	Options []string
}

ErrNotSupported is returned when a method or option is not implemented because the provider doesn't support it.

If the API doesn't support an option, the option will be added to the Options field.

For example:

  • Anthropic doesn't support Seed. In this case, Options will contain "GenOptionText.Seed".
  • Perplexity doesn't have an API to lists its supported models (this may change in the future).

func (*ErrNotSupported) Error 

func (e *ErrNotSupported) Error() string

type InitializableRequest 

type InitializableRequest interface {
	// Init initializes the request with messages, options, and model.
	Init(msgs genai.Messages, model string, opts ...genai.GenOption) error
	// SetStream set the stream mode.
	SetStream(bool)
}

InitializableRequest is an interface for request types that can be initialized.

type NotImplemented 

type NotImplemented struct{}

NotImplemented implements remote genai.Provider methods, all returning ErrNotSupported.

func (*NotImplemented) CacheAddRequest 

func (*NotImplemented) CacheAddRequest(ctx context.Context, msgs genai.Messages, name, displayName string, ttl time.Duration, opts ...genai.GenOption) (string, error)

CacheAddRequest implements genai.Provider.

func (*NotImplemented) CacheDelete 

func (*NotImplemented) CacheDelete(ctx context.Context, name string) error

CacheDelete implements genai.Provider.

func (*NotImplemented) CacheList 

func (*NotImplemented) CacheList(ctx context.Context) ([]genai.CacheEntry, error)

CacheList implements genai.Provider.

func (*NotImplemented) Capabilities 

func (*NotImplemented) Capabilities() genai.ProviderCapabilities

Capabilities implements genai.Provider.

func (*NotImplemented) GenAsync 

func (*NotImplemented) GenAsync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (genai.Job, error)

GenAsync implements genai.Provider.

func (*NotImplemented) GenStream 

func (*NotImplemented) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))

GenStream implements genai.Provider.

func (*NotImplemented) GenSync 

func (*NotImplemented) GenSync(context.Context, genai.Messages, ...genai.GenOption) (genai.Result, error)

GenSync implements genai.Provider.

func (*NotImplemented) ListModels 

func (*NotImplemented) ListModels(context.Context) ([]genai.Model, error)

ListModels implements genai.Provider.

func (*NotImplemented) PokeResult 

func (*NotImplemented) PokeResult(ctx context.Context, job genai.Job) (genai.Result, error)

PokeResult implements genai.Provider.

type Obj 

type Obj interface{ any }

Obj is a generic interface for chat-related types (both requests and responses).

type Provider 

type Provider[PErrorResponse ErrAPI, PGenRequest InitializableRequest, PGenResponse ResultConverter, GenStreamChunkResponse Obj] struct {
	ProviderBase[PErrorResponse]
	// GenSyncURL is the endpoint URL for chat API requests
	GenSyncURL string
	// GenStreamURL is the endpoint URL for chat stream API requests. It defaults to GenURL if unset.
	GenStreamURL string
	// ProcessStream is the function that processes stream packets created by GenStreamRaw to be used in
	// GenStream.
	ProcessStream func(it iter.Seq[GenStreamChunkResponse]) (iter.Seq[genai.Reply], func() (genai.Usage, [][]genai.Logprob, error))
	// ProcessHeaders is the function that processes HTTP headers to extract rate limit information.
	ProcessHeaders func(http.Header) []genai.RateLimit
	// LieToolCalls lie the FinishReason on tool calls.
	LieToolCalls bool
	// PreloadedModels is a list of preloaded models provided by the user to save on HTTP requests for
	// ListModels.
	PreloadedModels []genai.Model
	// contains filtered or unexported fields
}

Provider implements genai.Provider.

It includes common functionality for clients that provide chat capabilities.

It only accepts text modality.

func (*Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenStream 

func (c *Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))

GenStream implements genai.Provider.

func (*Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenStreamRaw 

func (c *Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenStreamRaw(ctx context.Context, in PGenRequest) (iter.Seq[GenStreamChunkResponse], func() error)

GenStreamRaw is the generic raw implementation for streaming Gen API endpoints. It sets Stream to true, enables stream options if available, and handles the SSE response.

func (*Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenSync 

func (c *Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (genai.Result, error)

GenSync implements genai.Provider.

func (*Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenSyncRaw 

func (c *Provider[PErrorResponse, PGenRequest, PGenResponse, GenStreamChunkResponse]) GenSyncRaw(ctx context.Context, in PGenRequest, out PGenResponse) error

GenSyncRaw is the generic raw implementation for the generation API endpoint. It sets Stream to false and sends a request to the chat URL.

type ProviderBase 

type ProviderBase[PErrorResponse ErrAPI] struct {
	// Client is exported for testing replay purposes.
	Client http.Client
	// Lenient allows unknown fields in the response.
	//
	// This inhibits from calling DisallowUnknownFields() on the JSON decoder, which will generally return a
	// *UnknownFieldError.
	//
	// Use this in production so that your client doesn't break when the server
	// add new fields.
	Lenient bool
	// APIKeyURL is the URL to present to the user upon authentication error.
	APIKeyURL string
	// Model is the default model used for chat requests
	Model string
	// OutputModalities is the output modalities supported by the provider.
	OutputModalities genai.Modalities
	// ModelOptional is true if a model name is not required to use the provider.
	ModelOptional bool
	// contains filtered or unexported fields
}

ProviderBase implements the basse functionality to help implementing a base.Provider.

It contains the shared HTTP client functionality used across all API clients.

func (*ProviderBase[PErrorResponse]) DecodeError 

func (c *ProviderBase[PErrorResponse]) DecodeError(url string, resp *http.Response) error

DecodeError handles HTTP error responses from API calls.

It handles JSON decoding of error responses and provides appropriate error messages with context such as API key URLs for unauthorized errors.

func (*ProviderBase[PErrorResponse]) DecodeResponse 

func (c *ProviderBase[PErrorResponse]) DecodeResponse(resp *http.Response, url string, out any) error

DecodeResponse decodes an HTTP response into the output struct.

func (*ProviderBase[PErrorResponse]) DoRequest 

func (c *ProviderBase[PErrorResponse]) DoRequest(ctx context.Context, method, url string, in, out any) error

DoRequest performs an HTTP request and handles error responses.

It takes care of sending the request, decoding the response, and handling errors. All API clients should use this method for their HTTP communication needs.

func (*ProviderBase[PErrorResponse]) JSONRequest 

func (c *ProviderBase[PErrorResponse]) JSONRequest(ctx context.Context, method, url string, in any) (*http.Response, error)

JSONRequest simplifies doing an HTTP PATCH/DELETE/PUT in JSON.

In is optional.

It initiates the requests and returns the response back for further processing. Buffers post data in memory.

func (*ProviderBase[PErrorResponse]) LastResponseHeaders 

func (c *ProviderBase[PErrorResponse]) LastResponseHeaders() http.Header

LastResponseHeaders returns the HTTP headers of the last response.

func (*ProviderBase[PErrorResponse]) Validate 

func (c *ProviderBase[PErrorResponse]) Validate() error

Validate checks that the provider is properly configured.

type ResultConverter 

type ResultConverter interface {
	ToResult() (genai.Result, error)
}

ResultConverter converts a provider-specific result to a genai.Result.

type Time 

type Time int64

Time is a JSON encoded unix timestamp. This is used by many providers.

func (*Time) AsTime 

func (t *Time) AsTime() time.Time

AsTime returns the time as UTC so its string value doesn't depend on the local time zone.

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes JSON numbers as unix timestamps, converting float64 to int64 by rounding.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.