API Reference

Exported interfaces, configuration types, response shapes, and helper functions in go-llm-router.

`core.Agent`

type Agent interface {
    Name() string
    Send(
        ctx context.Context,
        messages []Message,
        toolDefs []Tool,
        reasoning Reasoning,
        mode Mode,
    ) (*Output, int, error)
}

Method	Description
`Name`	Returns the current model name
`Send`	Sends messages and optional tools; returns `*Output`, the HTTP status code, and an error

`core.StreamAgent`

type StreamAgent interface {
    SendStream(
        ctx context.Context,
        messages []Message,
        toolDefs []Tool,
        reasoning Reasoning,
        mode Mode,
    ) (<-chan StreamEvent, error)
}

Implemented by core/claude and core/copilot; reach it with a type assertion.

type StreamEvent struct {
    Type           StreamEventType
    TextDelta      string
    ReasoningDelta string
    ToolCall       *ToolCallDelta
    Usage          *Usage
    FinishReason   string
    Err            error
}

`StreamEventType`	Populated field
`StreamEventText`	`TextDelta`
`StreamEventReasoning`	`ReasoningDelta`
`StreamEventToolCall`	`ToolCall` (`Index`, `ID`, `Name`, `Arguments`)
`StreamEventUsage`	`Usage`
`StreamEventDone`	`FinishReason`
`StreamEventError`	`Err`

`router.New`

func New(config Config) (core.Agent, error)

Parses config.Name, selects the matching factory, and returns a unified Agent. Unknown provider keys return an error.

`router.Config`

Field	Purpose
`Name`	`<provider>@<model>` routing key
`APIKey`	API-key providers
`Token`	OAuth token (`CopilotToken` / `CodexToken` / `*GrokToken`)
`BaseURL`	`compat` only
`AccountID` / `GatewayID`	`cloudflare` only

Provider keys

Key	Credential / special fields	Package
`claude`	`APIKey`	`core/claude`
`openai`	`APIKey`	`core/openai`
`gemini`	`APIKey`	`core/gemini`
`grok`	`APIKey`	`core/grok`
`deepseek`	`APIKey`	`core/deepseek`
`nvidia`	`APIKey`	`core/nvidia`
`openrouter`	`APIKey`	`core/openRouter`
`cloudflare`	`APIKey`, `AccountID`, `GatewayID`	`core/cloudflare`
`compat`	`APIKey`, `BaseURL`	`core/compat`
`copilot`	`Token`	`core/copilot`
`codex`	`Token`	`core/openaiCodex`
`grok-oauth`	`Token`	`core/grokOauth`

`core.Config`

Field	Purpose
`Model`	Model name without the provider prefix
`APIKey`	Provider API key
`Token`	Provider-specific OAuth token object
`BaseURL`	Custom endpoint base URL
`AccountID` / `GatewayID`	Cloudflare-only fields
`Thinking` / `Efforts` / `Endpoints`	Capability hints carried over from model listings

Reasoning

type Reasoning int

const (
    ReasoningNone Reasoning = iota
    ReasoningLow
    ReasoningMedium
    ReasoningHigh
    ReasoningXHigh
    ReasoningMax
)

const ReasoningDefault = ReasoningMedium

Function / type	Description
`Reasoning.String()`	Returns the literal; out-of-range values return `invalid`
`ParseReasoning(s)`	Parses literals and the `minimal` / `extra` / `ultra` aliases; returns `(Reasoning, bool)`
`ClampReasoning(r, lo, hi, provider, model)`	Caps the level to a range and logs a debug record when clamping occurs
`ReasoningAgent`	Interface through which a provider publishes `ReasoningLimits() (min, max Reasoning)`
`OpenAIEffortRange(model)`	Returns reasoning bounds for OpenAI-family models

Execution mode

type Mode int

const (
    ModeDefault Mode = iota
    ModeFast
)

Function	Description
`Mode.String()`	Returns `default` or `fast`
`ParseMode(s)`	Parses `default` and `fast`; returns `(Mode, bool)`
`SupportFast(provider, model)`	Whether the pair has a fast tier; adapters use it to decide whether to add the native field
`WarnFastDowngrade(provider, model, tier)`	Logs a warning when the reported tier is neither fast nor priority; an empty string means nothing was reported and stays silent

Capability helpers

Function	Description
`SupportTemperature(provider, model)`	Whether the model accepts temperature
`ResponsesAPI(provider, model)`	Whether the OpenAI Responses path is selected
`IsTextModel(id)`	Whether the model is text-only
`NewHTTPClient()`	Creates the shared HTTP client with a ten-minute timeout

Message and tool types

Type	Key fields
`Message`	`Role`, `Content`, `ReasoningContent`, `ToolCalls`, `ToolCallID`
`ContentPart`	Multimodal part: `text` or `image_url`
`ImageURL`	`URL`, optional `Detail`
`Tool`	OpenAI-style function-calling envelope
`ToolFunction`	`Name`, `Description`, JSON Schema `Parameters`
`ToolCall`	Model-emitted call with `ID`, `Type`, the function payload, and Gemini's `ThoughtSignature`

type Message struct {
    Role             string
    Content          any
    ReasoningContent string
    ToolCalls        []ToolCall
    ToolCallID       string
}

type Tool struct {
    Type     string
    Function ToolFunction
}

type ToolFunction struct {
    Name        string
    Description string
    Parameters  json.RawMessage
}

Response types

Type	Description
`Output`	Normalized response with `Choices`, `Usage`, `ServiceTier`, and optional `Error`
`OutputChoices`	Contains `Message`, streaming `Delta`, and `FinishReason`
`Usage`	Normalized counters: `Input`, `Output`, `CacheCreate`, `CacheRead`

Output.ServiceTier carries the tier the provider reports (for example default or priority) and is the only trustworthy signal that a fast request was actually served at that tier.

Usage.UnmarshalJSON absorbs provider-specific token field names:

input_tokens / output_tokens
prompt_tokens / completion_tokens
cache_creation_input_tokens
cache_read_input_tokens and prompt_tokens_details.cached_tokens

The normalized result is:

Field	Meaning
`Input`	Non-cached input tokens
`Output`	Generated output tokens
`CacheCreate`	Tokens written to a prompt cache
`CacheRead`	Cached input tokens read by the request

Model listings

func Models(ctx context.Context, config core.Config, filter core.ModelFilter) ([]string, error)
func ModelInfos(ctx context.Context, config core.Config, filter core.ModelFilter) ([]core.ModelInfo, error)

Models exists in claude, openai, gemini, grok, grokOauth, deepseek, nvidia, openRouter, cloudflare, copilot, and openaiCodex. ModelInfos is provided by copilot and gemini.

Type	Fields
`ModelFilter`	`TextOnly` — drops non-text models through `IsTextModel`
`ModelInfo`	`ID`, `Thinking`, `Efforts`, `Endpoints`

OAuth token types

Type	Description
`CopilotToken`	Access token, token type, scope, and expiry
`CodexToken`	Access / refresh / ID tokens, account ID, and expiry; exposes `Expired()`
`GrokToken`	Access / refresh tokens and expiry; exposes `Expired()`

Package	Purpose
`core/oauth/copilot`	GitHub device flow, keychain load / clear, session refresh
`core/oauth/codex`	Codex OAuth login, load, refresh
`core/oauth/grok`	Grok OAuth login, load, refresh

Codex image generation

The core/openaiCodex Agent additionally exposes:

func (a *Agent) GenerateImage(
    ctx context.Context,
    prompt string,
    opts ImageOptions,
) (base64Image string, revisedPrompt string, err error)

`ImageOptions` field	Purpose
`Size`	Output size, for example `1024x1024`
`Quality`	Output quality, for example `high`
`RefImageB64`	Optional reference image as base64
`RefMime`	MIME type of the reference image

Package layout

Package	Description
`core`	Shared types, the Agent contract, reasoning and fast-tier policy
`core/router`	String-keyed Agent factory
`core/claude` … `core/compat`	Provider implementations
`core/oauth/*`	OAuth login, load, refresh, and clear flows
`cmd/test`	Local OpenAI-compatible test server

Getting Started — install and send a first request.
Configuration — credentials and routing names.
Core Concepts — shared contracts and normalization rules.