GoAI

Appearance

Types ​

This page documents all public types in the goai and goai/provider packages.

goai Package Types ​

Import: github.com/zendev-sh/goai

TextResult ​

The final result of a text generation call (GenerateText or TextStream.Result()).

go
type TextResult struct {
    Text         string                   // Accumulated generated text (includes reasoning text when streaming).
    ToolCalls    []provider.ToolCall       // Tool calls from the final step.
    Steps        []StepResult             // Results from each generation step.
    TotalUsage   provider.Usage           // Aggregated token usage across all steps.
    FinishReason provider.FinishReason    // Why generation stopped.
    Response     provider.ResponseMetadata // Provider metadata from the last step.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
    Sources      []provider.Source        // Citations/references from all steps.
}

StepResult ​

The result of a single generation step in a multi-step tool loop.

go
type StepResult struct {
    Number       int                      // 1-based step index.
    Text         string                   // Text generated in this step (excludes reasoning text).
    ToolCalls    []provider.ToolCall       // Tool calls requested in this step.
    FinishReason provider.FinishReason    // Finish reason for this step.
    Usage        provider.Usage           // Token usage for this step.
    Response     provider.ResponseMetadata // Provider metadata for this step.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
    Sources      []provider.Source        // Citations from this step.
}

TextStream ​

A streaming text generation response with three consumption modes.

MethodReturn TypeDescription
Stream()<-chan provider.StreamChunkRaw stream chunks (all types).
TextStream()<-chan stringText content only.
Result()*TextResultBlocks until complete, returns accumulated result.
Err()errorReturns the first stream error encountered.

Stream() and TextStream() are mutually exclusive. Result() can be called after either.

ObjectResult ​

The final result of a structured output generation.

go
type ObjectResult[T any] struct {
    Object           T                        // The parsed structured output.
    Usage            provider.Usage           // Token consumption.
    FinishReason     provider.FinishReason    // Why generation stopped.
    Response         provider.ResponseMetadata // Provider metadata.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
    Steps            []StepResult             // Results from each generation step (for multi-step tool loops).
}

ObjectStream ​

A streaming structured output response.

MethodReturn TypeDescription
PartialObjectStream()<-chan *TEmits progressively populated partial objects.
Result()(*ObjectResult[T], error)Blocks until complete, returns final validated object.
Err()errorReturns the first stream error encountered.

EmbedResult ​

The result of a single embedding generation.

go
type EmbedResult struct {
    Embedding        []float64                 // The generated vector.
    Usage            provider.Usage            // Token consumption.
    Response         provider.ResponseMetadata // Provider metadata.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
}

EmbedManyResult ​

The result of a batch embedding generation.

go
type EmbedManyResult struct {
    Embeddings       [][]float64               // One vector per input value.
    Usage            provider.Usage            // Aggregated token consumption.
    Response         provider.ResponseMetadata // Provider metadata.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
}

ImageResult ​

The result of image generation.

go
type ImageResult struct {
    Images           []provider.ImageData      // Generated images.
    Usage            provider.Usage            // Token consumption.
    Response         provider.ResponseMetadata // Provider metadata.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
}

SchemaFrom ​

Generates a JSON Schema from a Go struct type T. Used by GenerateObject and StreamObject to describe the expected output structure, and compatible with OpenAI strict-mode schemas.

go
func SchemaFrom[T any]() json.RawMessage

Supported struct tags:

TagExampleDescription
json:"name"json:"firstName"Field name in JSON output; json:"-" to skip a field.
jsonschema:"description=..."jsonschema:"description=User's full name"Adds a description to the field in the schema.
jsonschema:"enum=a|b|c"jsonschema:"enum=easy|medium|hard"Restricts the field to enumerated values.

Example:

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

schema := goai.SchemaFrom[Recipe]()

Edge cases:

  • time.Time is converted to {"type": "string", "format": "date-time"}.
  • Self-referential named slice types (e.g. type Foo []Foo) are detected and produce a schema with {"type": "array"} (no items) to avoid infinite recursion.
  • Mutually recursive named slice types (e.g. type A []B; type B []A) are not detected and will cause a stack overflow. Use struct wrappers instead of raw named-slice mutual recursion.
  • Pointer types are unwrapped and marked nullable in the schema.

See Structured Output for full usage.

Tool ​

Defines a tool that can be called by the model during generation. Includes an optional Execute function for automatic tool loop execution.

go
type Tool struct {
    Name                   string                                                    // Tool identifier.
    Description            string                                                    // What the tool does (used by the model).
    InputSchema            json.RawMessage                                           // JSON Schema for input parameters.
    ProviderDefinedType    string                                                    // Provider-defined tool type (e.g. "computer_20250124").
    ProviderDefinedOptions map[string]any                                            // Provider-specific tool configuration.
    Execute                func(ctx context.Context, input json.RawMessage) (string, error) // Tool implementation.
}

When Execute is non-nil and MaxSteps > 1, GenerateText automatically invokes the tool and feeds results back to the model.

When using provider-defined tools (web search, code execution, etc.), set ProviderDefinedType and leave Execute nil - the provider handles execution server-side.

Option ​

A function that configures a generation call. See Options for all available option functions.

go
type Option func(*options)

ImageOption ​

A function that configures an image generation call.

go
type ImageOption func(*imageOptions)

RequestInfo ​

Passed to the OnRequest hook before a generation call.

go
type RequestInfo struct {
    Model        string             // Model ID.
    MessageCount int                // Number of messages in the request.
    ToolCount    int                // Number of tools available.
    Timestamp    time.Time          // When the request was initiated.
    Messages     []provider.Message // Full conversation history sent to the model for this call.
}

ResponseInfo ​

Passed to the OnResponse hook after a generation call completes.

go
type ResponseInfo struct {
    Latency      time.Duration         // Time from request to response.
    Usage        provider.Usage        // Token consumption for this call.
    FinishReason provider.FinishReason // Why generation stopped.
    Error        error                 // Non-nil if the call failed.
    StatusCode   int                   // HTTP status code (0 if not applicable).
}

ToolCallInfo ​

Passed to the OnToolCall hook after a tool executes.

go
type ToolCallInfo struct {
    ToolCallID   string          // Provider-assigned identifier for this tool call.
    ToolName     string          // Name of the tool called.
    Step         int             // 1-based index of the generation step in which this tool was called.
    Input        json.RawMessage // Raw JSON arguments passed to the tool.
    Output       string          // String result returned by the tool.
    OutputObject any             // Parsed JSON value of Output when the tool returned valid JSON; nil otherwise.
    StartTime    time.Time       // When the tool execution began.
    Duration     time.Duration   // How long execution took.
    Error        error           // Non-nil if execution failed.
}

ToolCallStartInfo ​

Passed to the OnToolCallStart hook before a tool executes.

go
type ToolCallStartInfo struct {
    ToolCallID string          // Provider-assigned identifier for this tool call.
    ToolName   string          // Name of the tool called.
    Step       int             // 1-based index of the generation step in which this tool was called.
    Input      json.RawMessage // Raw JSON arguments passed to the tool.
}

APIError ​

Represents a non-overflow API error. See Errors.

ContextOverflowError ​

Indicates the prompt exceeded the model's context window. See Errors.

provider Package Types ​

Import: github.com/zendev-sh/goai/provider

LanguageModel ​

Interface for text generation models.

go
type LanguageModel interface {
    ModelID() string
    DoGenerate(ctx context.Context, params GenerateParams) (*GenerateResult, error)
    DoStream(ctx context.Context, params GenerateParams) (*StreamResult, error)
}

CapableModel ​

Optional interface that LanguageModel implementations can satisfy to declare capabilities. Use ModelCapabilitiesOf to query safely.

go
type CapableModel interface {
    Capabilities() ModelCapabilities
}

ModelCapabilitiesOf ​

Returns the model's capabilities if it implements CapableModel, or a zero-value ModelCapabilities otherwise.

go
func ModelCapabilitiesOf(m LanguageModel) ModelCapabilities

EmbeddingModel ​

Interface for embedding models.

go
type EmbeddingModel interface {
    ModelID() string
    DoEmbed(ctx context.Context, values []string, params EmbedParams) (*EmbedResult, error)
    MaxValuesPerCall() int
}

MaxValuesPerCall() returns the maximum number of values that can be embedded in a single call. Returns 0 if there is no limit. EmbedMany uses this to auto-chunk large batches.

ImageModel ​

Interface for image generation models.

go
type ImageModel interface {
    ModelID() string
    DoGenerate(ctx context.Context, params ImageParams) (*ImageResult, error)
}

GenerateParams ​

All parameters for a generation request. Constructed internally by GoAI from options - provider implementations receive this.

go
type GenerateParams struct {
    Messages         []Message          // Conversation history.
    System           string             // System prompt.
    Tools            []ToolDefinition   // Available tools.
    MaxOutputTokens  int                // Response length limit (0 = provider default).
    Temperature      *float64           // Randomness control (nil = provider default).
    TopP             *float64           // Nucleus sampling (nil = provider default).
    TopK             *int               // Top-K sampling (nil = provider default).
    FrequencyPenalty *float64           // Frequency penalty (nil = provider default).
    PresencePenalty  *float64           // Presence penalty (nil = provider default).
    Seed             *int               // Deterministic generation (nil = provider default).
    StopSequences    []string           // Stop generation when encountered.
    Headers          map[string]string  // Additional HTTP headers.
    ProviderOptions  map[string]any     // Provider-specific parameters.
    PromptCaching    bool               // Enable prompt caching.
    ToolChoice       string             // Tool selection: "auto", "none", "required", or tool name.
    ResponseFormat   *ResponseFormat    // Structured JSON output schema.
}

GenerateResult ​

Response from a non-streaming generation.

go
type GenerateResult struct {
    Text             string                       // Generated text.
    ToolCalls        []ToolCall                    // Tool calls requested by the model.
    Sources          []Source                      // Citations from response annotations.
    FinishReason     FinishReason                  // Why generation stopped.
    Usage            Usage                         // Token consumption.
    Response         ResponseMetadata              // Provider metadata.
    ProviderMetadata map[string]map[string]any     // Provider-specific response data.
}

StreamResult ​

Wraps a streaming response channel.

go
type StreamResult struct {
    Stream <-chan StreamChunk // Emits chunks as they arrive. Closed when the stream ends.
}

StreamChunk ​

A single event in a streaming response. The Type field determines which other fields are populated.

go
type StreamChunk struct {
    Type         StreamChunkType    // Chunk kind.
    Text         string             // Content (for ChunkText, ChunkReasoning).
    ToolCallID   string             // Tool call fields (for ChunkToolCall, ChunkToolCallStreamStart).
    ToolName     string
    ToolInput    string
    FinishReason FinishReason       // For ChunkStepFinish, ChunkFinish.
    Usage        Usage              // For ChunkFinish (may also appear on ChunkStepFinish).
    Error        error              // For ChunkError.
    Response     ResponseMetadata   // Populated on ChunkFinish (may also appear on ChunkStepFinish).
    Metadata     map[string]any     // Provider-specific data.
}

StreamChunkType ​

go
type StreamChunkType string

const (
    ChunkText                StreamChunkType = "text"
    ChunkReasoning           StreamChunkType = "reasoning"
    ChunkToolCall            StreamChunkType = "tool_call"
    ChunkToolCallDelta       StreamChunkType = "tool_call_delta"
    ChunkToolCallStreamStart StreamChunkType = "tool_call_streaming_start"
    ChunkToolResult          StreamChunkType = "tool_result" // reserved for future use; not currently emitted by any provider
    ChunkStepFinish          StreamChunkType = "step_finish"
    ChunkFinish              StreamChunkType = "finish"
    ChunkError               StreamChunkType = "error"
)

Message ​

A conversation message.

go
type Message struct {
    Role            Role           // Sender (system, user, assistant, tool).
    Content         []Part         // Content parts.
    ProviderOptions map[string]any // Provider-specific message parameters.
}

Part ​

A single content element within a message. The Type field determines which other fields are populated.

go
type Part struct {
    Type            PartType        // Part kind.
    Text            string          // For PartText, PartReasoning.
    URL             string          // For images (data:image/... format).
    ToolCallID      string          // For PartToolCall.
    ToolName        string          // For PartToolCall.
    ToolInput       json.RawMessage // For PartToolCall.
    ToolOutput      string          // For PartToolResult.
    CacheControl    string          // Cache directive (e.g. "ephemeral").
    Detail          string          // Image detail level ("low", "high", "auto").
    MediaType       string          // Content type (for PartImage, PartFile).
    Filename        string          // For PartFile.
    ProviderOptions map[string]any  // Provider-specific part parameters.
}

PartType ​

go
type PartType string

const (
    PartText       PartType = "text"
    PartReasoning  PartType = "reasoning"
    PartImage      PartType = "image"
    PartToolCall   PartType = "tool-call"
    PartToolResult PartType = "tool-result"
    PartFile       PartType = "file"
)

Role ​

go
type Role string

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

ToolDefinition ​

Wire-level tool schema sent to the provider. This is the provider-facing counterpart of goai.Tool.

go
type ToolDefinition struct {
    Name                   string         // Tool identifier.
    Description            string         // What the tool does.
    InputSchema            json.RawMessage // JSON Schema for input parameters.
    ProviderDefinedType    string         // Provider-defined tool type.
    ProviderDefinedOptions map[string]any // Provider-specific tool configuration.
}

ToolCall ​

The model's request to invoke a tool.

go
type ToolCall struct {
    ID    string          // Unique identifier for this call.
    Name  string          // Tool to invoke.
    Input json.RawMessage // JSON-encoded arguments.

    // Provider-specific data that must be preserved across tool round-trips.
    Metadata map[string]any
}

Usage ​

Token consumption for a request.

go
type Usage struct {
    InputTokens      int
    OutputTokens     int
    TotalTokens      int
    ReasoningTokens  int
    CacheReadTokens  int
    CacheWriteTokens int
}

FinishReason ​

go
type FinishReason string

const (
    FinishStop          FinishReason = "stop"           // Normal completion.
    FinishToolCalls     FinishReason = "tool-calls"     // Model wants to call tools.
    FinishLength        FinishReason = "length"         // Hit max output tokens.
    FinishContentFilter FinishReason = "content-filter" // Content policy triggered.
    FinishError         FinishReason = "error"          // Generation error.
    FinishOther         FinishReason = "other"          // Provider-specific reason.
)

ModelCapabilities ​

Describes what features a model supports.

go
type ModelCapabilities struct {
    Temperature      bool        // Accepts temperature parameter.
    Reasoning        bool        // Supports extended thinking/reasoning.
    Attachment       bool        // Supports file attachments.
    ToolCall         bool        // Supports tool/function calling.
    InputModalities  ModalitySet // Supported input types.
    OutputModalities ModalitySet // Supported output types.
}

ModalitySet ​

go
type ModalitySet struct {
    Text  bool
    Audio bool
    Image bool
    Video bool
    PDF   bool
}

ResponseMetadata ​

Provider-specific response information.

go
type ResponseMetadata struct {
    ID               string         // Provider's response identifier.
    Model            string         // Actual model used (may differ from requested).
    Headers          map[string]string // Selected response headers.
    ProviderMetadata map[string]any // Provider-specific metadata.
}

Source ​

A citation or reference from the model's response.

go
type Source struct {
    ID               string         // Source identifier.
    Type             string         // Source kind (e.g. "url", "document").
    URL              string         // Citation URL.
    Title            string         // Citation title.
    StartIndex       int            // Start character offset in the text.
    EndIndex         int            // End character offset in the text.
    ProviderMetadata map[string]any // Provider-specific source data.
}

ImageParams ​

Parameters for image generation.

go
type ImageParams struct {
    Prompt          string         // Image description.
    N               int            // Number of images to generate.
    Size            string         // Dimensions (e.g. "1024x1024").
    AspectRatio     string         // Alternative to Size (e.g. "16:9").
    ProviderOptions map[string]any // Provider-specific parameters.
}

ImageData ​

A single generated image.

go
type ImageData struct {
    Data      []byte // Raw image bytes.
    MediaType string // MIME type (e.g. "image/png").
}

ImageResult (provider) ​

Response from image generation at the provider level.

go
type ImageResult struct {
    Images           []ImageData                 // Generated images.
    ProviderMetadata map[string]map[string]any   // Provider-specific data.
    Usage            Usage                       // Token/operation usage.
    Response         ResponseMetadata            // Provider metadata.
}

ResponseFormat ​

Requests structured JSON output matching a schema.

go
type ResponseFormat struct {
    Name   string          // Schema name (used by OpenAI's json_schema mode).
    Schema json.RawMessage // JSON Schema the output must conform to.
}

EmbedParams ​

Parameters for an embedding request.

go
type EmbedParams struct {
    ProviderOptions map[string]any // Provider-specific parameters.
}

EmbedResult (provider) ​

Response from embedding generation at the provider level.

go
type EmbedResult struct {
    Embeddings       [][]float64              // Generated vectors.
    Usage            Usage                   // Token consumption.
    ProviderMetadata map[string]map[string]any // Provider-specific response data.
    Response         ResponseMetadata         // Provider metadata.
}

Token ​

An authentication token with optional expiry.

go
type Token struct {
    Value     string    // Token string (API key, OAuth access token, etc.).
    ExpiresAt time.Time // When the token expires. Zero means no expiry.
}

TokenSource ​

Interface for providing authentication tokens. See provider/token.go for built-in implementations (StaticToken, CachedTokenSource).

go
type TokenSource interface {
    Token(ctx context.Context) (string, error)
}

InvalidatingTokenSource ​

A TokenSource whose cached token can be cleared, forcing a fresh fetch. Supports application-level retry-on-401 logic.

go
type InvalidatingTokenSource interface {
    TokenSource
    Invalidate()
}

StaticToken ​

Creates a TokenSource that always returns the given key. Use for simple API key authentication.

go
func StaticToken(key string) TokenSource

CachedTokenSource ​

Creates a TokenSource that caches tokens until expiry. The fetch function is called lazily on first use and again when the cached token expires. Safe for concurrent use. The returned value also implements InvalidatingTokenSource.

go
func CachedTokenSource(fetchFn TokenFetchFunc) TokenSource

TokenFetchFunc ​

go
type TokenFetchFunc func(ctx context.Context) (*Token, error)

TrySend ​

Utility for provider implementors. Sends a chunk to a stream channel, returning false if the context is cancelled. Prevents goroutine leaks when the consumer stops reading.

go
func TrySend(ctx context.Context, out chan<- StreamChunk, chunk StreamChunk) bool

Released under the MIT License.

Copyright © 2026 GoAI