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.
go get github.com/goloop/aitype Client interface {
Generate(ctx context.Context, req *Request) (*Response, error)
Stream(ctx context.Context, req *Request) iter.Seq2[Chunk, error]
}RoleandMessage(a role plus a list of contentPartvalues).Part:Text,Image(multimodal),ToolUse,ToolResult(tool calling).ToolandToolChoicefor function calling.Request(model, system, messages, tools, sampling knobs).Formatfor structured output: ask for JSON, or JSON matching a schema.Hostedfor work the provider runs itself, such as web search, withCitationfor the sources it came back with andHostedReportfor whether it ran at all.ResponsewithText(),JSON(&v),ToolCalls()andCitations()helpers;Chunkfor streaming.Usagefor token counts;APIErrorfor normalized provider errors.
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.
Drivers reuse the shared configuration and transport:
Optionsand functional options (WithBaseURL,WithHTTPClient,WithTimeout,WithMaxRetries,WithHeader), built withNewOptions.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.
Full reference: DOC.md (Ukrainian: DOC.UK.md).
MIT - see LICENSE.
Preserve empty SSE data, cap Retry-After before converting to a duration, and avoid unnecessary text allocations.