goai

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2026 License: MIT Imports: 16 Imported by: 0

README

GoAI

GoAI

AI SDK, the Go way.

Go SDK for building AI applications. One SDK, 20 providers.

Website · Docs · Providers · Examples

Inspired by the Vercel AI SDK. The same clean abstractions, idiomatically adapted for Go with generics, interfaces, and functional options.

Features

  • 7 core functions: GenerateText, StreamText, GenerateObject[T], StreamObject[T], Embed, EmbedMany, GenerateImage
  • 20+ providers: OpenAI, Anthropic, Google, Bedrock, Azure, Vertex, Mistral, xAI, Groq, Cohere, DeepSeek, Fireworks, Together, DeepInfra, OpenRouter, Perplexity, Cerebras, Ollama, vLLM, + generic OpenAI-compatible
  • Auto tool loop: Define tools with Execute handlers, set MaxSteps, GoAI handles the loop
  • Structured output: GenerateObject[T] auto-generates JSON Schema from Go types via reflection
  • Streaming: Real-time text and partial object streaming via channels
  • Dynamic auth: TokenSource interface for OAuth, rotating keys, cloud IAM, with CachedTokenSource for TTL-based caching
  • Prompt caching: Automatic cache control for supported providers (Anthropic, OpenAI, Google)
  • Citations/sources: Grounding and inline citations from xAI, Perplexity, Google, OpenAI
  • Web search: Built-in web search tools for OpenAI, Anthropic, Google, Groq. Model decides when to search
  • Code execution: Server-side Python sandboxes via OpenAI, Anthropic, Google. No local setup
  • Computer use: Anthropic computer, bash, text editor tools for autonomous desktop interaction
  • 20 provider-defined tools: Web fetch, file search, image generation, X search, and more - full list
  • Telemetry hooks: OnRequest, OnResponse, OnStepFinish, OnToolCall callbacks
  • Retry/backoff: Automatic retry with exponential backoff on 429/5xx errors
  • Minimal dependencies: Core uses only stdlib; Vertex adds golang.org/x/oauth2 for ADC

Install

go get github.com/zendev-sh/goai@latest

Requires Go 1.25+.

Quick Start

Providers auto-resolve API keys from environment variables. No explicit WithAPIKey needed:

package main

import (
	"context"
	"fmt"

	"github.com/zendev-sh/goai"
	"github.com/zendev-sh/goai/provider/openai"
)

func main() {
	// Reads OPENAI_API_KEY from environment automatically.
	model := openai.Chat("gpt-4o")

	result, err := goai.GenerateText(context.Background(), model,
		goai.WithPrompt("What is the capital of France?"),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Text)
}

Streaming

stream, err := goai.StreamText(ctx, model,
	goai.WithSystem("You are a helpful assistant."),
	goai.WithPrompt("Write a haiku about Go."),
)
if err != nil {
	panic(err)
}

for text := range stream.TextStream() {
	fmt.Print(text)
}

result := stream.Result()
fmt.Printf("\nTokens: %d in, %d out\n",
	result.TotalUsage.InputTokens, result.TotalUsage.OutputTokens)

Structured Output

Auto-generates JSON Schema from Go types. Works with OpenAI, Anthropic, and Google.

type Recipe struct {
	Name        string   `json:"name" jsonschema:"description=Recipe name"`
	Ingredients []string `json:"ingredients"`
	Steps       []string `json:"steps"`
	Difficulty  string   `json:"difficulty" jsonschema:"enum=easy|medium|hard"`
}

result, err := goai.GenerateObject[Recipe](ctx, model,
	goai.WithPrompt("Give me a recipe for chocolate chip cookies"),
)
fmt.Printf("Recipe: %s (%s)\n", result.Object.Name, result.Object.Difficulty)

Streaming partial objects:

stream, err := goai.StreamObject[Recipe](ctx, model,
	goai.WithPrompt("Give me a recipe for pancakes"),
)
for partial := range stream.PartialObjectStream() {
	fmt.Printf("\r%s (%d ingredients so far)", partial.Name, len(partial.Ingredients))
}
final, err := stream.Result()

Tools

Define tools with JSON Schema and an Execute handler. Set MaxSteps to enable the auto tool loop.

weatherTool := goai.Tool{
	Name:        "get_weather",
	Description: "Get the current weather for a city.",
	InputSchema: json.RawMessage(`{
		"type": "object",
		"properties": {"city": {"type": "string", "description": "City name"}},
		"required": ["city"]
	}`),
	Execute: func(ctx context.Context, input json.RawMessage) (string, error) {
		var args struct{ City string `json:"city"` }
		json.Unmarshal(input, &args)
		return fmt.Sprintf("22°C and sunny in %s", args.City), nil
	},
}

result, err := goai.GenerateText(ctx, model,
	goai.WithPrompt("What's the weather in Tokyo?"),
	goai.WithTools(weatherTool),
	goai.WithMaxSteps(3),
)
fmt.Println(result.Text) // "It's 22°C and sunny in Tokyo."

Citations / Sources

Providers that support grounding (Google, xAI, Perplexity) or inline citations (OpenAI) return sources:

result, err := goai.GenerateText(ctx, model,
	goai.WithPrompt("What were the major news events today?"),
)

if len(result.Sources) > 0 {
	for _, s := range result.Sources {
		fmt.Printf("[%s] %s - %s\n", s.Type, s.Title, s.URL)
	}
}

// Sources are also available per-step in multi-step tool loops.
for _, step := range result.Steps {
	for _, s := range step.Sources {
		fmt.Printf("  Step source: %s\n", s.URL)
	}
}

Computer Use

See Provider-Defined Tools > Computer Use and examples/computer-use for Anthropic computer, bash, and text editor tools. Works with both Anthropic direct API and Bedrock.

Embeddings

model := openai.Embedding("text-embedding-3-small",
	openai.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
)

// Single
result, err := goai.Embed(ctx, model, "Hello world")
fmt.Printf("Dimensions: %d\n", len(result.Embedding))

// Batch (auto-chunked, parallel)
many, err := goai.EmbedMany(ctx, model, []string{"foo", "bar", "baz"},
	goai.WithMaxParallelCalls(4),
)

Image Generation

model := openai.Image("gpt-image-1", openai.WithAPIKey(os.Getenv("OPENAI_API_KEY")))

result, err := goai.GenerateImage(ctx, model,
	goai.WithImagePrompt("A sunset over mountains, oil painting style"),
	goai.WithImageSize("1024x1024"),
)
os.WriteFile("sunset.png", result.Images[0].Data, 0644)

Also supported: Google Imagen (google.Image("imagen-4.0-generate-001")) and Vertex AI (vertex.Image(...)).

Providers

Every provider auto-resolves credentials from environment variables. Override with options when needed:

// Auto-resolved: reads OPENAI_API_KEY from env
model := openai.Chat("gpt-4o")

// Explicit key (overrides env)
model := openai.Chat("gpt-4o", openai.WithAPIKey("sk-..."))

// Cloud IAM auth (Vertex, Bedrock)
model := vertex.Chat("gemini-2.5-pro",
	vertex.WithProject("my-project"),
	vertex.WithLocation("us-central1"),
)

// AWS Bedrock (reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION from env)
model := bedrock.Chat("anthropic.claude-sonnet-4-6-v1:0")

// Local (Ollama, vLLM)
model := ollama.Chat("llama3", ollama.WithBaseURL("http://localhost:11434/v1"))

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))

Provider Table

Provider Chat Embed Image Auth E2E Import
OpenAI gpt-4o, o3, codex-* text-embedding-3-* gpt-image-1 API key, TokenSource Full provider/openai
Anthropic claude-* - - API key, TokenSource Full provider/anthropic
Google gemini-* text-embedding-004 imagen-* API key, TokenSource Full provider/google
Bedrock anthropic.*, meta.* - - AWS keys, bearer token Full provider/bedrock
Vertex gemini-* text-embedding-004 imagen-* TokenSource, ADC Full provider/vertex
Azure gpt-4o, claude-* via Azure via Azure API key, TokenSource Full provider/azure
OpenRouter various - - API key Full provider/openrouter
Mistral mistral-large, magistral-* - - API key Full provider/mistral
Groq mixtral-*, llama-* - - API key Full provider/groq
xAI grok-* - - API key Unit provider/xai
Cohere command-r-* embed-* - API key Unit provider/cohere
DeepSeek deepseek-* - - API key Unit provider/deepseek
Fireworks various - - API key Unit provider/fireworks
Together various - - API key Unit provider/together
DeepInfra various - - API key Unit provider/deepinfra
Perplexity sonar-* - - API key Unit provider/perplexity
Cerebras llama-* - - API key Full provider/cerebras
Ollama local models local models - none Unit provider/ollama
vLLM local models local models - none Unit provider/vllm
Compat any OpenAI-compatible any - configurable Unit provider/compat

E2E column: "Full" = tested with real API calls. "Unit" = tested with mock HTTP servers (100% coverage).

Tested Models

E2E tested - 96 models across 8 providers (real API calls, click to expand)

Last run: 2026-03-15. 94 generate PASS, 96 stream PASS, 0 FAIL.

Provider Models E2E tested (generate + stream)
Google (9) gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.5-pro (stream), gemini-3-flash-preview, gemini-3-pro-preview, gemini-3.1-pro-preview, gemini-2.0-flash, gemini-flash-latest, gemini-flash-lite-latest
Azure (21) claude-opus-4-6, claude-sonnet-4-6, DeepSeek-V3.2, gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-codex, gpt-5-mini, gpt-5-pro, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2, gpt-5.2-codex, gpt-5.3-codex, gpt-5.4, gpt-5.4-pro, Kimi-K2.5, model-router, o3
Bedrock (61) Anthropic: claude-sonnet-4-6, claude-sonnet-4-5, claude-sonnet-4, claude-opus-4-6-v1, claude-opus-4-5, claude-opus-4-1, claude-haiku-4-5, claude-3-5-sonnet, claude-3-5-haiku, claude-3-haiku · Amazon: nova-micro, nova-lite, nova-pro, nova-premier, nova-2-lite · Meta: llama4-scout, llama4-maverick, llama3-3-70b, llama3-2-{90,11,3,1}b, llama3-1-{70,8}b, llama3-{70,8}b · Mistral: mistral-large, mixtral-8x7b, mistral-7b, ministral-3-{14,8}b, voxtral-{mini,small} · Others: deepseek.v3, deepseek.r1, ai21.jamba-{mini,large}, cohere.command-r{-plus,}, google.gemma-3-{4,12,27}b, minimax.m2.1, moonshotai.kimi-k2.5, nvidia.nemotron-{12,9}b, openai.gpt-oss-{120,20}b{,-safeguard}, qwen.qwen3-{32,235,coder-30,coder-480}b, qwen.qwen3-next-80b, writer.palmyra-{x4,x5}, zai.glm-4.7{,-flash}
Groq (2) llama-3.1-8b-instant, llama-3.3-70b-versatile
Mistral (5) mistral-small-latest, mistral-large-latest, devstral-small-2507, codestral-latest, magistral-medium-latest
Cerebras (1) llama3.1-8b
Unit tested (mock HTTP server, 100% coverage, click to expand)
Provider Models in unit tests
OpenAI gpt-4o, o3, text-embedding-3-small, dall-e-3, gpt-image-1
Anthropic claude-sonnet-4-20250514, claude-sonnet-4-5-20241022, claude-sonnet-4-6-20260310
Google gemini-2.5-flash, gemini-2.5-flash-image, imagen-4.0-fast-generate-001, text-embedding-004
Bedrock us.anthropic.claude-sonnet-4-6, anthropic.claude-sonnet-4-20250514-v1:0, meta.llama3-70b
Azure gpt-4o, gpt-5.2-chat, dall-e-3, claude-sonnet-4-6
Vertex gemini-2.5-pro, imagen-3.0-generate-002, text-embedding-004
Cohere command-r-plus, command-a-reasoning, embed-v4.0
Mistral mistral-large-latest
Groq llama-3.3-70b-versatile
xAI grok-3
DeepSeek deepseek-chat
DeepInfra meta-llama/Llama-3.3-70B-Instruct
Fireworks accounts/fireworks/models/llama-v3p3-70b-instruct
OpenRouter anthropic/claude-sonnet-4
Perplexity sonar-pro
Together meta-llama/Llama-3.3-70B-Instruct-Turbo
Cerebras llama-3.3-70b
Ollama llama3, llama3.2:1b, nomic-embed-text
vLLM meta-llama/Llama-3-8b

Custom / Self-Hosted

Use the compat provider for any OpenAI-compatible endpoint:

model := compat.Chat("my-model",
	compat.WithBaseURL("https://my-api.example.com/v1"),
	compat.WithAPIKey("..."),
)

Dynamic Auth with TokenSource

For OAuth, rotating keys, or cloud IAM:

ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
	tok, err := fetchOAuthToken(ctx)
	return &provider.Token{
		Value:     tok.AccessToken,
		ExpiresAt: tok.Expiry,
	}, err
})

model := openai.Chat("gpt-4o", openai.WithTokenSource(ts))

CachedTokenSource handles TTL-based caching (zero ExpiresAt = cache forever), thread-safe refresh without holding locks during network calls, and retry-on-401 invalidation.

AWS Bedrock

Native Converse API with SigV4 signing (no AWS SDK dependency). Supports cross-region inference fallback, extended thinking, and image/document input:

model := bedrock.Chat("anthropic.claude-sonnet-4-6-v1:0",
	bedrock.WithRegion("us-west-2"),
	bedrock.WithReasoningConfig(bedrock.ReasoningConfig{
		Type:         bedrock.ReasoningEnabled,
		BudgetTokens: 4096,
	}),
)

Auto-resolves AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION from environment. Cross-region fallback retries with us. prefix on model ID mismatch errors.

Azure OpenAI

Supports both OpenAI models (GPT, o-series) and Claude models (routed to Azure Anthropic endpoint automatically):

// OpenAI models
model := azure.Chat("gpt-4o",
	azure.WithResourceName("my-resource"),
)

// Claude models (auto-routed to Anthropic endpoint)
model := azure.Chat("claude-sonnet-4-6",
	azure.WithResourceName("my-resource"),
)

Auto-resolves AZURE_OPENAI_API_KEY and AZURE_RESOURCE_NAME from environment.

Response Metadata

Every result includes provider response metadata:

result, _ := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
fmt.Printf("Request ID: %s\n", result.Response.ID)
fmt.Printf("Model used: %s\n", result.Response.Model)

Options Reference

Generation Options

Option Description Default
WithSystem(s) System prompt -
WithPrompt(s) Single user message -
WithMessages(...) Conversation history -
WithTools(...) Available tools -
WithMaxOutputTokens(n) Response length limit provider default
WithTemperature(t) Randomness (0.0-2.0) provider default
WithTopP(p) Nucleus sampling provider default
WithStopSequences(...) Stop triggers -
WithMaxSteps(n) Tool loop iterations 1 (no loop)
WithMaxRetries(n) Retries on 429/5xx 2
WithTimeout(d) Overall timeout none
WithHeaders(h) Per-request HTTP headers -
WithProviderOptions(m) Provider-specific params -
WithPromptCaching(b) Enable prompt caching false
WithToolChoice(tc) "auto", "none", "required", or tool name -

Telemetry Hooks

Option Description
WithOnRequest(fn) Called before each API call
WithOnResponse(fn) Called after each API call
WithOnStepFinish(fn) Called after each tool loop step
WithOnToolCall(fn) Called after each tool execution

Structured Output Options

Option Description
WithExplicitSchema(s) Override auto-generated JSON Schema
WithSchemaName(n) Schema name for provider (default "response")

Embedding Options

Option Description Default
WithMaxParallelCalls(n) Batch parallelism 4
WithEmbeddingProviderOptions(m) Embedding provider params -

Image Options

Option Description
WithImagePrompt(s) Text description
WithImageCount(n) Number of images
WithImageSize(s) Dimensions (e.g., "1024x1024")
WithAspectRatio(s) Aspect ratio (e.g., "16:9")
WithImageProviderOptions(m) Image provider params

Error Handling

GoAI returns typed errors for actionable failure modes:

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("..."))
if err != nil {
	var overflow *goai.ContextOverflowError
	var apiErr *goai.APIError
	switch {
	case errors.As(err, &overflow):
		// Prompt too long - truncate and retry
	case errors.As(err, &apiErr):
		if apiErr.IsRetryable {
			// 429 rate limit, 503 - already retried MaxRetries times
		}
		fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
	default:
		// Network error, context cancelled, etc.
	}
}

Provider-Defined Tools

Providers expose built-in tools that the model can invoke server-side. GoAI supports 20 provider-defined tools across 5 providers:

Provider Tools Import
Anthropic Computer, Computer_20251124, Bash, TextEditor, TextEditor_20250728, WebSearch, WebSearch_20260209, WebFetch, CodeExecution, CodeExecution_20250825 provider/anthropic
OpenAI WebSearch, CodeInterpreter, FileSearch, ImageGeneration provider/openai
Google GoogleSearch, URLContext, CodeExecution provider/google
xAI WebSearch, XSearch provider/xai
Groq BrowserSearch provider/groq

All tools follow the same pattern: create a definition with provider.Tools.ToolName(), then pass it as a goai.Tool:

def := provider.Tools.ToolName(options...)
result, _ := goai.GenerateText(ctx, model,
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)

The model searches the web and returns grounded responses. Available from OpenAI, Anthropic, Google, and Groq.

// OpenAI (via Responses API) - also works via Azure
def := openai.Tools.WebSearch(openai.WithSearchContextSize("medium"))

// Anthropic (via Messages API) - also works via Bedrock
def := anthropic.Tools.WebSearch(anthropic.WithMaxUses(5))

// Google (grounding with Google Search) - returns Sources
def := google.Tools.GoogleSearch()
// result.Sources contains grounding URLs from Google Search

// Groq (interactive browser search)
def := groq.Tools.BrowserSearch()

Code Execution

The model writes and runs code in a sandboxed environment. Server-side, no local setup needed.

// OpenAI Code Interpreter - Python sandbox via Responses API
def := openai.Tools.CodeInterpreter()

// Anthropic Code Execution - Python sandbox via Messages API
def := anthropic.Tools.CodeExecution() // v20260120, GA, no beta needed

// Google Code Execution - Python sandbox via Gemini API
def := google.Tools.CodeExecution()

Web Fetch

Claude fetches and processes content from specific URLs directly.

def := anthropic.Tools.WebFetch(
    anthropic.WithWebFetchMaxUses(3),
    anthropic.WithCitations(true),
)

Semantic search over uploaded files in vector stores (OpenAI Responses API).

def := openai.Tools.FileSearch(
    openai.WithVectorStoreIDs("vs_abc123"),
    openai.WithMaxNumResults(5),
)

Image Generation

LLM generates images inline during conversation (different from goai.GenerateImage() which calls the Images API directly).

def := openai.Tools.ImageGeneration(
    openai.WithImageQuality("low"),
    openai.WithImageSize("1024x1024"),
)
// On Azure, also set: azure.WithHeaders(map[string]string{
//     "x-ms-oai-image-generation-deployment": "gpt-image-1.5",
// })

Computer Use

Anthropic computer, bash, and text editor tools for autonomous desktop interaction. Client-side execution required.

computerDef := anthropic.Tools.Computer(anthropic.ComputerToolOptions{
    DisplayWidthPx: 1920, DisplayHeightPx: 1080,
})
bashDef := anthropic.Tools.Bash()
textEditorDef := anthropic.Tools.TextEditor()
// Wrap each with an Execute handler for client-side execution

URL Context

Gemini fetches and processes web content from URLs in the prompt.

def := google.Tools.URLContext()

See examples/ for complete runnable examples of each tool.

Examples

See the examples/ directory:

Project Structure

goai/                       # Core SDK
├── provider/               # Provider interface + shared types
│   ├── provider.go         # LanguageModel, EmbeddingModel, ImageModel interfaces
│   ├── types.go            # Message, Part, Usage, StreamChunk, etc.
│   ├── token.go            # TokenSource, CachedTokenSource
│   ├── openai/             # OpenAI (Chat Completions + Responses API)
│   ├── anthropic/          # Anthropic (Messages API)
│   ├── google/             # Google Gemini (REST API)
│   ├── bedrock/            # AWS Bedrock (Converse API + SigV4 + EventStream)
│   ├── vertex/             # Google Vertex AI (OpenAI-compat)
│   ├── azure/              # Azure OpenAI
│   ├── cohere/             # Cohere (Chat v2 + Embed)
│   ├── compat/             # Generic OpenAI-compatible
│   └── ...                 # 11 more OpenAI-compatible providers
├── internal/
│   ├── openaicompat/       # Shared codec for 13 OpenAI-compat providers
│   ├── sse/                # SSE line parser
│   └── httpc/              # HTTP utilities
├── examples/               # Usage examples
└── bench/                  # Performance benchmarks (GoAI vs Vercel AI SDK)
    ├── fixtures/           # Shared SSE test fixtures
    ├── go/                 # Go benchmarks (go test -bench)
    ├── ts/                 # TypeScript benchmarks (Bun + Tinybench)
    ├── collect.sh          # Result aggregation → report
    └── Makefile            # make bench-all

Contributing

See CONTRIBUTING.md.

License

MIT

Documentation

Overview

Package goai provides a unified SDK for interacting with AI language models.

This file defines error types returned by GoAI functions. They live in the root package so users can type-assert without importing internals.

Package goai provides a unified SDK for interacting with AI language models.

GoAI is a Go port of the Vercel AI SDK, providing a consistent API across multiple AI providers (OpenAI, Anthropic, Google, and more).

Core functions:

  • GenerateText: non-streaming text generation
  • StreamText: streaming text generation with multiple consumption modes
  • GenerateObject: structured output with auto-generated JSON Schema
  • StreamObject: streaming structured output with partial object emission
  • Embed: single text embedding
  • EmbedMany: batch text embeddings with auto-chunking
  • GenerateImage: image generation from text prompts

Basic usage: 

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))

stream, err := goai.StreamText(ctx, model, goai.WithPrompt("Hello"))
for text := range stream.TextStream() {
    fmt.Print(text)
}

Index

Constants

This section is empty.

Variables

View Source 
var ErrUnknownTool = errors.New("goai: unknown tool")

ErrUnknownTool is returned when a tool call references a tool not in the tool map.

Functions

func AssistantMessage 

func AssistantMessage(text string) provider.Message

AssistantMessage creates an assistant message with text content.

func ClassifyStreamError 

func ClassifyStreamError(body []byte) error

ClassifyStreamError parses a stream error event and returns the appropriate typed error (*ContextOverflowError or *APIError), or nil if the data is not a recognized error event.

func IsOverflow 

func IsOverflow(message string) bool

IsOverflow checks if an error message indicates a context overflow.

func ParseHTTPError 

func ParseHTTPError(providerID string, statusCode int, body []byte) error

ParseHTTPError classifies an HTTP error response.

func ParseHTTPErrorWithHeaders 

func ParseHTTPErrorWithHeaders(providerID string, statusCode int, body []byte, headers http.Header) error

ParseHTTPErrorWithHeaders parses an HTTP error response, preserving retry-related headers.

func SchemaFrom 

func SchemaFrom[T any]() json.RawMessage

SchemaFrom generates a JSON Schema from a Go type using reflection. The schema is compatible with OpenAI strict mode:

  • All properties are required (pointer types become nullable)
  • additionalProperties: false on all objects

Supports struct tags:

  • json:"name" for field naming, json:"-" to skip
  • jsonschema:"description=...,enum=a|b|c" for descriptions and enums

func SystemMessage 

func SystemMessage(text string) provider.Message

SystemMessage creates a system message with text content.

func ToolMessage 

func ToolMessage(toolCallID, toolName, output string) provider.Message

ToolMessage creates a tool result message.

func UserMessage 

func UserMessage(text string) provider.Message

UserMessage creates a user message with text content.

Types

type APIError 

type APIError struct {
	Message         string
	StatusCode      int
	IsRetryable     bool
	ResponseBody    string
	ResponseHeaders map[string]string
}

APIError represents a non-overflow API error.

func (*APIError) Error 

func (e *APIError) Error() string

type ContextOverflowError 

type ContextOverflowError struct {
	Message      string
	ResponseBody string
}

ContextOverflowError indicates the prompt exceeded the model's context window.

func (*ContextOverflowError) Error 

func (e *ContextOverflowError) Error() string

type EmbedManyResult 

type EmbedManyResult struct {
	// Embeddings contains the generated vectors (one per input value).
	Embeddings [][]float64

	// Usage is the aggregated token consumption.
	Usage provider.Usage
}

EmbedManyResult is the result of multiple embedding generations.

func EmbedMany 

func EmbedMany(ctx context.Context, model provider.EmbeddingModel, values []string, opts ...Option) (*EmbedManyResult, error)

EmbedMany generates embedding vectors for multiple values. Auto-chunks when values exceed the model's MaxValuesPerCall limit and processes chunks in parallel (controlled by WithMaxParallelCalls).

type EmbedResult 

type EmbedResult struct {
	// Embedding is the generated vector.
	Embedding []float64

	// Usage tracks token consumption.
	Usage provider.Usage
}

EmbedResult is the result of a single embedding generation.

func Embed 

func Embed(ctx context.Context, model provider.EmbeddingModel, value string, opts ...Option) (*EmbedResult, error)

Embed generates an embedding vector for a single value.

type ImageOption 

type ImageOption func(*imageOptions)

ImageOption configures image generation.

func WithAspectRatio 

func WithAspectRatio(ratio string) ImageOption

WithAspectRatio sets the aspect ratio (e.g. "16:9", "1:1").

func WithImageCount 

func WithImageCount(n int) ImageOption

WithImageCount sets the number of images to generate.

func WithImagePrompt 

func WithImagePrompt(prompt string) ImageOption

WithImagePrompt sets the text prompt for image generation.

func WithImageProviderOptions 

func WithImageProviderOptions(opts map[string]any) ImageOption

WithImageProviderOptions sets provider-specific options.

func WithImageSize 

func WithImageSize(size string) ImageOption

WithImageSize sets the image size (e.g. "1024x1024", "512x512").

type ImageResult 

type ImageResult struct {
	Images []provider.ImageData
}

ImageResult contains the generated images.

func GenerateImage 

func GenerateImage(ctx context.Context, model provider.ImageModel, opts ...ImageOption) (*ImageResult, error)

GenerateImage generates images from a text prompt.

type ObjectResult 

type ObjectResult[T any] struct {
	// Object is the parsed structured output.
	Object T

	// Usage tracks token consumption.
	Usage provider.Usage

	// FinishReason indicates why generation stopped.
	FinishReason provider.FinishReason

	// Response contains provider metadata (ID, Model).
	Response provider.ResponseMetadata
}

ObjectResult is the final result of a structured output generation.

func GenerateObject 

func GenerateObject[T any](ctx context.Context, model provider.LanguageModel, opts ...Option) (*ObjectResult[T], error)

GenerateObject performs a non-streaming structured output generation. The schema is auto-generated from T, or can be overridden with WithExplicitSchema.

type ObjectStream 

type ObjectStream[T any] struct {
	// contains filtered or unexported fields
}

ObjectStream is a streaming structured output response.

func StreamObject 

func StreamObject[T any](ctx context.Context, model provider.LanguageModel, opts ...Option) (*ObjectStream[T], error)

StreamObject performs a streaming structured output generation. Returns an ObjectStream that emits progressively populated partial objects.

func (*ObjectStream[T]) PartialObjectStream 

func (os *ObjectStream[T]) PartialObjectStream() <-chan *T

PartialObjectStream returns a channel that emits partial objects as JSON accumulates. Each emitted value has progressively more fields populated. Mutually exclusive with Result() -- only call one consumption method first.

func (*ObjectStream[T]) Result 

func (os *ObjectStream[T]) Result() (*ObjectResult[T], error)

Result blocks until the stream completes and returns the final validated object. Returns an error if JSON parsing of the accumulated text fails.

type Option 

type Option func(*options)

Option configures a generation call.

func WithEmbeddingProviderOptions 

func WithEmbeddingProviderOptions(opts map[string]any) Option

WithEmbeddingProviderOptions sets provider-specific parameters for embedding requests.

func WithExplicitSchema 

func WithExplicitSchema(schema json.RawMessage) Option

WithExplicitSchema overrides auto-generated JSON Schema for GenerateObject/StreamObject.

func WithFrequencyPenalty 

func WithFrequencyPenalty(p float64) Option

WithFrequencyPenalty sets the frequency penalty.

func WithHeaders 

func WithHeaders(h map[string]string) Option

WithHeaders sets additional HTTP headers.

func WithMaxOutputTokens 

func WithMaxOutputTokens(n int) Option

WithMaxOutputTokens limits the response length.

func WithMaxParallelCalls 

func WithMaxParallelCalls(n int) Option

WithMaxParallelCalls sets batch parallelism for EmbedMany.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries sets the retry count for transient errors.

func WithMaxSteps 

func WithMaxSteps(n int) Option

WithMaxSteps sets the maximum auto tool loop iterations.

func WithMessages 

func WithMessages(msgs ...provider.Message) Option

WithMessages sets the conversation history.

func WithOnRequest 

func WithOnRequest(fn func(RequestInfo)) Option

WithOnRequest sets a callback invoked before each model call.

func WithOnResponse 

func WithOnResponse(fn func(ResponseInfo)) Option

WithOnResponse sets a callback invoked after each model call completes.

func WithOnStepFinish 

func WithOnStepFinish(fn func(StepResult)) Option

WithOnStepFinish sets a callback invoked after each generation step completes.

func WithOnToolCall 

func WithOnToolCall(fn func(ToolCallInfo)) Option

WithOnToolCall sets a callback invoked after each tool execution.

func WithPresencePenalty 

func WithPresencePenalty(p float64) Option

WithPresencePenalty sets the presence penalty.

func WithPrompt 

func WithPrompt(s string) Option

WithPrompt sets a shorthand user message prompt.

func WithPromptCaching 

func WithPromptCaching(b bool) Option

WithPromptCaching enables provider-specific prompt caching.

func WithProviderOptions 

func WithProviderOptions(opts map[string]any) Option

WithProviderOptions sets provider-specific request parameters.

func WithSchemaName 

func WithSchemaName(name string) Option

WithSchemaName sets the schema name sent to providers (default "response").

func WithSeed 

func WithSeed(s int) Option

WithSeed sets the seed for deterministic generation.

func WithStopSequences 

func WithStopSequences(seqs ...string) Option

WithStopSequences sets stop sequences.

func WithSystem 

func WithSystem(s string) Option

WithSystem sets the system prompt.

func WithTemperature 

func WithTemperature(t float64) Option

WithTemperature controls randomness.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the timeout for the entire generation call.

func WithToolChoice 

func WithToolChoice(tc string) Option

WithToolChoice controls tool selection.

func WithTools 

func WithTools(tools ...Tool) Option

WithTools sets the tools available to the model.

func WithTopK 

func WithTopK(k int) Option

WithTopK limits sampling to the top K tokens.

func WithTopP 

func WithTopP(p float64) Option

WithTopP controls nucleus sampling.

type ParsedStreamError 

type ParsedStreamError struct {
	Type         StreamErrorType
	Message      string
	IsRetryable  bool
	ResponseBody string
}

ParsedStreamError represents a parsed error from an SSE stream.

func ParseStreamError 

func ParseStreamError(body []byte) *ParsedStreamError

ParseStreamError parses a stream error event (used by Anthropic/OpenAI error events).

type RequestInfo 

type RequestInfo struct {
	// Model is the model ID.
	Model string

	// MessageCount is the number of messages in the request.
	MessageCount int

	// ToolCount is the number of tools available.
	ToolCount int

	// Timestamp is when the request was initiated.
	Timestamp time.Time
}

RequestInfo is passed to the OnRequest hook before a generation call.

type ResponseInfo 

type ResponseInfo struct {
	// Latency is the time from request to response.
	Latency time.Duration

	// Usage is the token consumption for this call.
	Usage provider.Usage

	// FinishReason indicates why generation stopped.
	FinishReason provider.FinishReason

	// Error is non-nil if the call failed.
	Error error

	// StatusCode is the HTTP status code (0 if not applicable).
	StatusCode int
}

ResponseInfo is passed to the OnResponse hook after a generation call completes.

type StepResult 

type StepResult struct {
	// Number is the 1-based step index.
	Number int

	// Text generated in this step.
	Text string

	// ToolCalls requested in this step.
	ToolCalls []provider.ToolCall

	// FinishReason for this step.
	FinishReason provider.FinishReason

	// Usage for this step.
	Usage provider.Usage

	// Response contains provider metadata for this step (ID, Model).
	Response provider.ResponseMetadata

	// Sources contains citations/references from this step.
	Sources []provider.Source
}

StepResult is the result of a single generation step in a tool loop.

type StreamErrorType 

type StreamErrorType string

StreamErrorType classifies parsed stream errors. 

const (
	StreamErrorContextOverflow StreamErrorType = "context_overflow"
	StreamErrorAPI             StreamErrorType = "api_error"
)

type TextResult 

type TextResult struct {
	// Text is the accumulated generated text.
	Text string

	// ToolCalls requested by the model in the final step.
	ToolCalls []provider.ToolCall

	// Steps contains results from each generation step (for multi-step tool loops).
	Steps []StepResult

	// TotalUsage is the aggregated token usage across all steps.
	TotalUsage provider.Usage

	// FinishReason indicates why generation stopped.
	FinishReason provider.FinishReason

	// Response contains provider metadata from the last step (ID, Model).
	Response provider.ResponseMetadata

	// Sources contains citations/references extracted from the response.
	Sources []provider.Source
}

TextResult is the final result of a text generation call.

func GenerateText 

func GenerateText(ctx context.Context, model provider.LanguageModel, opts ...Option) (*TextResult, error)

GenerateText performs a non-streaming text generation. When tools with Execute functions are provided and MaxSteps > 1, it automatically runs a tool loop: generate → execute tools → re-generate.

type TextStream 

type TextStream struct {
	// contains filtered or unexported fields
}

TextStream is a streaming text generation response.

It provides three consumption modes (Stream, TextStream, Result). Stream() and TextStream() are mutually exclusive -- only call one. Result() can always be called, including after Stream() or TextStream(), to get the accumulated final result.

func StreamText 

func StreamText(ctx context.Context, model provider.LanguageModel, opts ...Option) (*TextStream, error)

StreamText performs a streaming text generation.

func (*TextStream) Result 

func (ts *TextStream) Result() *TextResult

Result blocks until the stream completes and returns the final result. Can be called after Stream() or TextStream() to get accumulated data.

func (*TextStream) Stream 

func (ts *TextStream) Stream() <-chan provider.StreamChunk

Stream returns a channel that emits raw StreamChunks from the provider. Mutually exclusive with TextStream() -- only call one streaming method.

func (*TextStream) TextStream 

func (ts *TextStream) TextStream() <-chan string

TextStream returns a channel that emits only text content strings. Mutually exclusive with Stream() -- only call one streaming method.

type Tool 

type Tool struct {
	// Name is the tool's identifier.
	Name string

	// Description explains what the tool does.
	Description string

	// InputSchema is the JSON Schema for the tool's input parameters.
	InputSchema json.RawMessage

	// ProviderDefinedType, when non-empty, marks this as a provider-defined tool
	// (e.g. "computer_20250124", "bash_20250124"). Providers emit the correct
	// API type instead of "custom".
	ProviderDefinedType string

	// ProviderDefinedOptions holds provider-specific tool configuration
	// (e.g. displayWidthPx for computer use).
	ProviderDefinedOptions map[string]any

	// Execute runs the tool with the given JSON input and returns the result text.
	Execute func(ctx context.Context, input json.RawMessage) (string, error)
}

Tool defines a tool that can be called by the model during generation. Unlike provider.ToolDefinition (wire-level schema), Tool includes an Execute function that GoAI's auto tool loop invokes.

type ToolCallInfo 

type ToolCallInfo struct {
	// ToolName is the name of the tool that was called.
	ToolName string

	// InputSize is the byte length of the tool input JSON.
	InputSize int

	// Duration is how long the tool execution took.
	Duration time.Duration

	// Error is non-nil if the tool execution failed.
	Error error
}

ToolCallInfo is passed to the OnToolCall hook after a tool executes.

Source Files

View all Source files

Directories

Path Synopsis
internal
gemini
Package gemini provides shared utilities for Google Gemini API providers.
 Package gemini provides shared utilities for Google Gemini API providers.
httpc
Package httpc provides HTTP helper functions for provider implementations.
 Package httpc provides HTTP helper functions for provider implementations.
openaicompat
Package openaicompat provides shared request building and response parsing for OpenAI-compatible API providers (OpenAI, OpenRouter, Groq, DeepInfra, etc.).
 Package openaicompat provides shared request building and response parsing for OpenAI-compatible API providers (OpenAI, OpenRouter, Groq, DeepInfra, etc.).
sse
Package sse provides a scanner for Server-Sent Events (SSE) streams.
 Package sse provides a scanner for Server-Sent Events (SSE) streams.
Package provider defines the interfaces and types that AI providers implement.
 Package provider defines the interfaces and types that AI providers implement.
anthropic
Package anthropic provides an Anthropic language model implementation for GoAI.
 Package anthropic provides an Anthropic language model implementation for GoAI.
azure
Package azure provides an Azure OpenAI language model implementation for GoAI.
 Package azure provides an Azure OpenAI language model implementation for GoAI.
bedrock
Package bedrock provides an AWS Bedrock language model implementation for GoAI.
 Package bedrock provides an AWS Bedrock language model implementation for GoAI.
cerebras
Package cerebras provides a Cerebras language model implementation for GoAI.
 Package cerebras provides a Cerebras language model implementation for GoAI.
cohere
Package cohere provides a Cohere language model and embedding implementation for GoAI.
 Package cohere provides a Cohere language model and embedding implementation for GoAI.
compat
Package compat provides a generic OpenAI-compatible language model for GoAI.
 Package compat provides a generic OpenAI-compatible language model for GoAI.
deepinfra
Package deepinfra provides a DeepInfra language model implementation for GoAI.
 Package deepinfra provides a DeepInfra language model implementation for GoAI.
deepseek
Package deepseek provides a DeepSeek language model implementation for GoAI.
 Package deepseek provides a DeepSeek language model implementation for GoAI.
fireworks
Package fireworks provides a Fireworks AI language model implementation for GoAI.
 Package fireworks provides a Fireworks AI language model implementation for GoAI.
google
Package google provides a Google Gemini language model implementation for GoAI.
 Package google provides a Google Gemini language model implementation for GoAI.
groq
Package groq provides a Groq language model implementation for GoAI.
 Package groq provides a Groq language model implementation for GoAI.
mistral
Package mistral provides a Mistral AI language model implementation for GoAI.
 Package mistral provides a Mistral AI language model implementation for GoAI.
ollama
Package ollama provides an Ollama language model implementation for GoAI.
 Package ollama provides an Ollama language model implementation for GoAI.
openai
Package openai provides an OpenAI language model implementation for GoAI.
 Package openai provides an OpenAI language model implementation for GoAI.
openrouter
Package openrouter provides an OpenRouter language model implementation for GoAI.
 Package openrouter provides an OpenRouter language model implementation for GoAI.
perplexity
Package perplexity provides a Perplexity language model implementation for GoAI.
 Package perplexity provides a Perplexity language model implementation for GoAI.
together
Package together provides a Together AI language model implementation for GoAI.
 Package together provides a Together AI language model implementation for GoAI.
vertex
Package vertex provides a Google Cloud Vertex AI language model implementation for GoAI.
 Package vertex provides a Google Cloud Vertex AI language model implementation for GoAI.
vllm
Package vllm provides a vLLM language model implementation for GoAI.
 Package vllm provides a vLLM language model implementation for GoAI.
xai
Package xai provides a xAI (Grok) language model implementation for GoAI.
 Package xai provides a xAI (Grok) language model implementation for GoAI.

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.