ai

README

ai

ai is a small, provider-agnostic interface for talking to large language model APIs, plus the shared request and response types every provider driver speaks. It is the core that goloop's provider packages (anthropic, openai, gemini, and so on) build on.

Like the standard library's database/sql with its drivers, or log/slog with its handlers, this package holds the common contract while a separate package per provider implements it. A driver depends only on ai, so the whole set stays free of third-party dependencies.

Installation

go get github.com/goloop/ai

The interface

type Client interface {
	Generate(ctx context.Context, req *Request) (*Response, error)
	Stream(ctx context.Context, req *Request) iter.Seq2[Chunk, error]
}

Types

• Role and Message (a role plus a list of content Part values).
• Part: Text, Image (multimodal), ToolUse, ToolResult (tool calling).
• Tool and ToolChoice for function calling.
• Request (model, system, messages, tools, sampling knobs).
• Response with Text() and ToolCalls() helpers; Chunk for streaming.
• Usage for token counts; APIError for normalized provider errors.

Using a provider

import (
	"github.com/goloop/ai"
	"github.com/goloop/anthropic"
)

c := anthropic.New(os.Getenv("ANTHROPIC_API_KEY"))
resp, err := c.Generate(ctx, &ai.Request{
	Model:    anthropic.ModelClaude37SonnetLatest,
	Messages: []ai.Message{ai.UserText("Hello!")},
})

Any provider client is an ai.Client, so code written against the interface works with all of them, which makes multi-provider setups straightforward.

Plumbing for drivers

Drivers reuse the shared configuration and transport:

• Options and functional options (WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithHeader), built with NewOptions.
• Options.Do - an HTTP request with retries on 429 and 5xx.
• SSEEvents - an iterator over Server-Sent Events data payloads.

Endpoints providers do not share (embeddings, images, audio, files, batches) are not part of the interface; each driver exposes them as native methods.

License

MIT - see LICENSE.

Documentation

Overview

Package ai defines a single, provider-agnostic interface for talking to large language model APIs, together with the shared request and response types every provider driver speaks.

The design mirrors the standard library's split between an interface and its drivers: like database/sql with its drivers, or log/slog with its handlers, package ai holds the common contract while a separate package per provider (anthropic, openai, gemini, and so on) implements it. A driver depends only on this package, so the whole set stays free of third-party dependencies.

The contract is the Client interface:

type Client interface {
    Generate(ctx context.Context, req *Request) (*Response, error)
    Stream(ctx context.Context, req *Request) iter.Seq2[Chunk, error]
}

A Request carries a model, an optional system prompt, a list of Messages, optional Tools and the usual sampling knobs. A Message is a role plus a list of content Parts (Text, Image, ToolUse, ToolResult), which is enough to express multimodal input and tool calling across providers. Generate returns a whole Response; Stream yields Chunks as they arrive.

Endpoints that providers do not share (embeddings, image generation, audio, files, batches, and so on) are not part of this interface. Each driver exposes those as its own native methods, so the common surface stays small and honest while provider-specific power is still available.

This package also carries the plumbing drivers reuse: Options and its functional configuration, Options.Do for HTTP requests with retries, and SSEEvents for reading Server-Sent Events streams.

Index

• Variables
• func SSEEvents(r io.Reader) iter.Seq2[string, error]
• type APIError
  • func (e *APIError) Error() string
• type Chunk
• type Client
• type Image
• type Message
  • func AssistantText(s string) Message
  • func UserText(s string) Message
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithHeader(key, value string) Option
  • func WithMaxRetries(n int) Option
  • func WithTimeout(d time.Duration) Option
• type Options
  • func NewOptions(apiKey string, opts ...Option) Options
  • func (o Options) Do(ctx context.Context, method, url string, body []byte, headers http.Header) (*http.Response, error)
• type Part
• type Request
  • func (r *Request) Validate() error
• type Response
  • func (r *Response) Text() string
  • func (r *Response) ToolCalls() []ToolUse
• type Role
• type Text
• type Tool
• type ToolChoice
• type ToolResult
• type ToolUse
• type Usage

Variables

var (
	ErrNoModel    = errors.New("ai: model is required")
	ErrNoMessages = errors.New("ai: at least one message is required")
	ErrNoAPIKey   = errors.New("ai: API key is required")
)

Sentinel errors returned before a request reaches the network.

Functions

func SSEEvents

func SSEEvents(r io.Reader) iter.Seq2[string, error]

SSEEvents returns an iterator over the data payloads of a Server-Sent Events stream read from r. Each yielded string is the concatenated "data:" content of one event, with the field prefix and the single optional leading space removed and multi-line data joined by newlines. Comment lines (starting with ":") and other fields (event:, id:, retry:) are ignored, which is enough for the streaming chat APIs the drivers target. A read error is yielded once with an empty payload, after which iteration stops.

The caller is responsible for closing r.

Types

type APIError

type APIError struct {
	Status  int             // HTTP status code
	Type    string          // provider error type, when given
	Code    string          // provider error code, when given
	Message string          // human-readable message, when given
	Raw     json.RawMessage // original error body
}

APIError is a normalized error for a non-success HTTP response from a provider. Drivers fill the fields they can parse from the provider's error body and keep the original JSON in Raw.

func (*APIError) Error

func (e *APIError) Error() string

Error implements the error interface.

type Chunk

type Chunk struct {
	Text     string
	ToolCall *ToolUse
	Usage    *Usage
	Done     bool
	Raw      json.RawMessage
}

Chunk is one increment of a streaming response from Client.Stream. Text is the incremental text delta; ToolCall is set when the chunk carries part of a tool call; Usage is set on the final chunk when the provider reports it; Done marks the last chunk. Raw keeps the provider's original event JSON.

type Client

type Client interface {
	Generate(ctx context.Context, req *Request) (*Response, error)
	Stream(ctx context.Context, req *Request) iter.Seq2[Chunk, error]
}

Client is the contract every provider driver implements. Generate performs a single request and returns the whole response. Stream performs a request and returns an iterator over response chunks; the iterator yields a zero Chunk with a non-nil error and stops if the stream fails.

type Image

type Image struct {
	MIME string // for example "image/png" or "image/jpeg"
	Data []byte // inline image bytes, or nil when URL is set
	URL  string // remote image URL, or "" when Data is set
}

Image is an image content part. Provide either inline Data with its MIME type, or a URL when the provider supports fetching remote images. Drivers encode Data as base64 as required by their wire format.

type Message

type Message struct {
	Role  Role
	Parts []Part
}

Message is one turn in a conversation: a role and its content parts.

func AssistantText

func AssistantText(s string) Message

AssistantText returns an assistant Message containing a single text part.

func UserText

func UserText(s string) Message

UserText returns a user Message containing a single text part.

type Option

type Option func(*Options)

Option configures Options. The same options work across every provider, so client construction looks the same everywhere.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the provider's default API base URL. It is useful for proxies, gateways, mock servers and self-hosted deployments.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the HTTP client used for requests. When set, its own timeout takes precedence over WithTimeout.

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds a header sent with every request, for example a custom API version or a beta feature flag.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times Options.Do retries a request on HTTP 429 or 5xx responses. Zero disables retrying.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-request timeout used when no custom HTTP client is provided.

type Options

type Options struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
	Timeout    time.Duration
	MaxRetries int
	Headers    http.Header
}

Options is the shared client configuration every driver understands. Drivers build it from an API key and functional options with NewOptions and reuse it for transport (see Options.Do).

func NewOptions

func NewOptions(apiKey string, opts ...Option) Options

NewOptions builds Options from an API key and functional options, filling in defaults: a 60s timeout, two retries and an HTTP client when none is given.

func (Options) Do

func (o Options) Do(
	ctx context.Context,
	method, url string,
	body []byte,
	headers http.Header,
) (*http.Response, error)

Do sends an HTTP request using the configured client and headers, retrying on HTTP 429 and 5xx responses up to MaxRetries with exponential backoff. The Options headers are applied first, then the per-call headers override them. The caller owns the returned response body and must close it.

type Part

type Part interface {
	// contains filtered or unexported methods
}

Part is a single piece of a Message's content. The concrete part types are Text, Image, ToolUse and ToolResult. The set is closed: Part cannot be implemented outside this package, so drivers can switch over it exhaustively.

type Request

type Request struct {
	Model       string
	System      string // optional system prompt
	Messages    []Message
	Tools       []Tool
	ToolChoice  ToolChoice
	MaxTokens   int
	Temperature *float64
	TopP        *float64
	Stop        []string
}

Request is a provider-agnostic generation request. Only Model and Messages are required; the remaining fields are applied when set. Temperature and TopP are pointers so that "unset" is distinct from an explicit zero.

func (*Request) Validate

func (r *Request) Validate() error

Validate reports whether the request has the minimum a provider needs.

type Response

type Response struct {
	Model      string
	Parts      []Part
	StopReason string
	Usage      Usage
	Raw        json.RawMessage
}

Response is the result of a non-streaming Client.Generate call. Parts holds the assistant's output blocks (text and any tool calls); Raw keeps the provider's original JSON for access to fields this package does not model.

func (*Response) Text

func (r *Response) Text() string

Text returns the concatenation of all text parts in the response.

func (*Response) ToolCalls

func (r *Response) ToolCalls() []ToolUse

ToolCalls returns the tool-call parts the model produced, in order.

type Role

type Role string

Role identifies who a Message comes from in a conversation.

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

The roles a Message can take. Providers map these onto their own wire values; RoleTool marks a message that carries tool results back to the model.

type Text

type Text struct {
	Text string
}

Text is a plain-text content part.

type Tool

type Tool struct {
	Name        string
	Description string
	Schema      json.RawMessage
}

Tool describes a function the model may call. Schema is a JSON Schema object describing the tool's input; drivers pass it through to the provider in the shape that provider expects.

type ToolChoice

type ToolChoice int

ToolChoice controls whether and how the model may call tools in a Request.

const (
	ToolAuto ToolChoice = iota
	ToolNone
	ToolRequired
)

The tool-calling strategies. ToolAuto lets the model decide, ToolNone forbids tool calls, and ToolRequired forces the model to call at least one tool.

type ToolResult

type ToolResult struct {
	ID      string
	Content string
	IsError bool
}

ToolResult carries the result of a tool call back to the model. ID must match the ToolUse it answers. Set IsError to report that the tool failed.

type ToolUse

type ToolUse struct {
	ID    string          // provider-assigned call identifier
	Name  string          // name of the tool to invoke
	Input json.RawMessage // arguments as a JSON object
}

ToolUse is a request from the assistant to call a tool. Input is the raw JSON arguments object produced by the model, validated against the matching Tool schema by the caller.

type Usage

type Usage struct {
	InputTokens  int
	OutputTokens int
}

Usage reports how many tokens a request consumed.