Last updated 2026-05-17

Package llmrouter — Configuration & Options

Every public symbol declared in options.go. Configuration is built with a functional-options pattern: each provider's New(opts ...llmrouter.Option) calls NewConfig internally to fold the options into a *Config. Most consumers only ever touch the With* helpers below.

Config

Per-provider configuration. Source: options.go#L15. 

type Config struct {
    APIKey     string
    BaseURL    string
    HTTPClient *http.Client
    Timeout    time.Duration
    Extra      map[string]any
}
APIKey
The credential sent in the Authorization (OpenAI) or x-api-key (Anthropic) header.
BaseURL
Endpoint root, trailing slashes stripped. Empty means "use the provider's default" (OpenAI: https://api.openai.com/v1; Anthropic: https://api.anthropic.com/v1).
HTTPClient
The HTTP client used for every request. Lazy default constructed by HTTP() when nil.
Timeout
Per-request timeout applied to the default HTTP client. Default: 120 * time.Second. Ignored if HTTPClient was supplied.
Extra
Free-form bag for provider-specific knobs (Azure api-version, AWS region, GCP project, …). Each provider documents the keys it reads.

Option

The functional-options type. Returned by every With* helper below. Source: options.go#L26. 

type Option func(*Config) error

An Option mutates a *Config in place. A non-nil error short-circuits NewConfig, which then surfaces the error from the provider's New. Nil Option values are skipped — useful for conditional composition.

NewConfig

Applies the given options to a fresh Config. Each provider calls this internally from its New; you don't normally call it directly. Source: options.go#L30. 

func NewConfig(opts ...Option) (*Config, error)

Behavior:

  • Initialises Config{Timeout: 120 * time.Second}.
  • Iterates the options in order, skipping any nil entry.
  • Returns the first non-nil error from an option, leaving the partial config unreturned.
  • Returns (*Config, nil) on success.

Example: composing options from a flag-set

func buildOpts(apiKey, baseURL string) []llmrouter.Option {
    opts := []llmrouter.Option{llmrouter.WithAPIKey(apiKey)}
    if baseURL != "" {
        opts = append(opts, llmrouter.WithBaseURL(baseURL))
    }
    return opts
}


p, err := openai.New(buildOpts(os.Getenv("OPENAI_API_KEY"), "")...)

Config.HTTP

Returns the configured HTTP client, constructing a default one lazily on first call. Provider implementations should always go through this method rather than reading cfg.HTTPClient directly. Source: options.go#L46. 

func (c *Config) HTTP() *http.Client

Behavior:

  • If c.HTTPClient is non-nil, returns it unchanged.
  • Otherwise constructs &http.Client{Timeout: c.Timeout}, stores it on c.HTTPClient, and returns it. Subsequent calls return the same instance.

WithAPIKey

func WithAPIKey(key string) Option

Sets the API key. Source: options.go#L55.

Validation:

  • Trims leading and trailing whitespace from key.
  • Returns errors.New("api key cannot be empty") if the trimmed result is empty.

Example

p, err := openai.New(llmrouter.WithAPIKey(os.Getenv("OPENAI_API_KEY")))

WithBaseURL

func WithBaseURL(u string) Option

Overrides the provider's default base URL. Use it to point the OpenAI provider at OpenRouter, Together, Groq, or a self-hosted endpoint; or to target a specific *.openai.azure.com resource. Source: options.go#L70.

Validation:

  • Trims leading and trailing whitespace.
  • Returns errors.New("base url cannot be empty") if the trimmed result is empty.
  • Runs the value through url.Parse and returns fmt.Errorf("invalid base url: %w", err) on parse failure.
  • Strips trailing slashes via strings.TrimRight(u, "/") before storing.

Example: point at Groq

p, err := openai.New(
    llmrouter.WithAPIKey(os.Getenv("GROQ_API_KEY")),
    llmrouter.WithBaseURL("https://api.groq.com/openai/v1"),
)

WithHTTPClient

func WithHTTPClient(client *http.Client) Option

Supplies a custom HTTP client. Source: options.go#L86.

Validation and precedence:

  • Returns errors.New("http client cannot be nil") when client is nil.
  • Stores the supplied client on Config.HTTPClient.
  • Takes precedence over WithTimeout. When you supply your own client, Config.Timeout still gets set if WithTimeout ran, but it is never read — the client's own transport governs timeouts.

Example: instrumented client with retries

import "github.com/hashicorp/go-retryablehttp"


retry := retryablehttp.NewClient()
retry.RetryMax = 3
retry.Logger = nil


p, err := openai.New(
    llmrouter.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
    llmrouter.WithHTTPClient(retry.StandardClient()),
)

WithTimeout

func WithTimeout(d time.Duration) Option

Sets the request timeout used by the default HTTP client. Source: options.go#L98.

Validation and precedence:

  • Returns errors.New("timeout must be positive") when d <= 0.
  • Stored on Config.Timeout; consumed by HTTP() when it lazily constructs the default client.
  • Ignored if WithHTTPClient is also supplied — the custom client's transport governs timeouts.

Example

p, err := openai.New(
    llmrouter.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
    llmrouter.WithTimeout(30 * time.Second),
)

WithExtra

func WithExtra(key string, value any) Option

Attaches a provider-specific config value. Each provider documents the keys it reads from Config.Extra. Source: options.go#L112.

Validation and semantics:

  • Trims whitespace from key.
  • Returns errors.New("extra key cannot be empty") if the trimmed key is empty.
  • value is not validated — nil is allowed.
  • Lazily initialises Config.Extra on first call.
  • Overwrites on duplicate key. Last call wins.

Example: Azure OpenAI

p, err := openai.New(
    llmrouter.WithAPIKey(os.Getenv("AZURE_OPENAI_KEY")),
    llmrouter.WithBaseURL("https://my-resource.openai.azure.com"),
    llmrouter.WithExtra("api-version", "2024-10-21"),
    llmrouter.WithExtra("deployment", "gpt-4o-mini"),
)

Example: AWS Bedrock

p, err := openai.New(
    llmrouter.WithAPIKey(awsAccessKey),
    llmrouter.WithExtra("region", "us-east-1"),
)