Help us shape the future of Go! Take the 2026 Go Developer Survey

base

package
v0.10.2 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 22 Imported by: 2

Documentation

Overview

Package base provides shared infrastructure for implementing genai 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 CheckDuplicateGenOptions added in v0.8.1 

func CheckDuplicateGenOptions(opts []genai.GenOption) error

CheckDuplicateGenOptions returns an error if the same GenOption concrete type appears more than once.

func CheckDuplicateProviderOptions added in v0.8.1 

func CheckDuplicateProviderOptions(opts []genai.ProviderOption) error

CheckDuplicateProviderOptions returns an error if the same ProviderOption concrete type appears more than once.

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 DurationMS added in v0.7.0 

type DurationMS float64

DurationMS is a JSON encoded duration in milliseconds.

func (*DurationMS) AsDuration added in v0.7.0 

func (d *DurationMS) AsDuration() time.Duration

AsDuration returns the duration truncated to nanoseconds.

type DurationS added in v0.7.0 

type DurationS float64

DurationS is a JSON encoded duration in seconds.

func (*DurationS) AsDuration added in v0.7.0 

func (d *DurationS) AsDuration() time.Duration

AsDuration returns the duration truncated to nanoseconds.

type EmbeddingVector added in v0.10.2 

type EmbeddingVector []float32

EmbeddingVector decodes numeric arrays or packed float32 JSON strings into vector values.

func (*EmbeddingVector) UnmarshalJSON added in v0.10.2 

func (v *EmbeddingVector) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a vector without changing its numeric values.

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 Float64 added in v0.4.0 

type Float64 float64

Float64 is a float64 that can be unmarshalled from both JSON numbers and strings.

func (*Float64) UnmarshalJSON added in v0.4.0 

func (f *Float64) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

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) Embed added in v0.10.2 

func (*NotImplemented) Embed(context.Context, *genai.EmbeddingRequest) (*genai.EmbeddingResponse, error)

Embed 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.

func (*NotImplemented) SystemOne added in v0.10.0 

func (*NotImplemented) SystemOne(context.Context, *genai.SystemOneRequest) (*genai.SystemOneResponse, error)

SystemOne 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 base 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 TimeMS added in v0.7.0 

type TimeMS float64

TimeMS is a JSON encoded unix timestamp in milliseconds.

func (*TimeMS) AsTime added in v0.7.0 

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

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

func (TimeMS) IsZero added in v0.7.0 

func (t TimeMS) IsZero() bool

IsZero reports whether the timestamp is absent.

type TimeS added in v0.7.0 

type TimeS float64

TimeS is a JSON encoded unix timestamp in seconds.

func (*TimeS) AsTime added in v0.7.0 

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

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

func (TimeS) IsZero added in v0.7.0 

func (t TimeS) IsZero() bool

IsZero reports whether the timestamp is absent.

type Unknown added in v0.9.0 

type Unknown json.RawMessage

Unknown preserves JSON for a provider field whose structure is not yet implemented.

When internal.BeLenient is false, decoding panics unless the value is null or an empty object. This makes populated placeholder fields visible in tests. JSON null resets the value to nil without allocating. Fields that intentionally accept arbitrary JSON should use json.RawMessage instead.

func (Unknown) MarshalJSON added in v0.9.0 

func (u Unknown) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, preserving the raw JSON value.

func (*Unknown) UnmarshalJSON added in v0.9.0 

func (u *Unknown) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

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.