gains

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2025 License: MIT Imports: 6 Imported by: 0

README

gains mascot

gains

Go AI Native Scaffold - A Go-idiomatic generative AI library. Not yet production ready.

gains provides a unified interface for building AI applications across Anthropic, OpenAI, and Google. Inspired by langchain and langgraph, but built from the ground up for Go with first-class streaming, tool orchestration, and composable workflows.

Features

  • Model-Centric Routing - Models know their provider; client routes automatically
  • Unified Client - Single interface for chat, embeddings, and image generation
  • Agent Orchestration - Autonomous tool-calling loops with approval workflows
  • Composable Workflows - Chain, Parallel, and Router patterns for complex pipelines
  • Streaming First - Channel-based streaming throughout the entire API
  • Functional Options - Go-idiomatic configuration with type-safe model selection
  • Automatic Retry - Exponential backoff with jitter for transient errors

Installation

go get github.com/spetersoncode/gains

Import Convention

We recommend importing with the ai alias for cleaner, more readable code:

import ai "github.com/spetersoncode/gains"

// Now you can write:
msg := ai.Message{Role: ai.RoleUser, Content: "Hello"}

All examples in this documentation use this convention.

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    ai "github.com/spetersoncode/gains"
    "github.com/spetersoncode/gains/client"
    "github.com/spetersoncode/gains/model"
)

func main() {
    ctx := context.Background()

    c := client.New(client.Config{
        APIKeys: client.APIKeys{
            Anthropic: os.Getenv("ANTHROPIC_API_KEY"),
        },
        Defaults: client.Defaults{
            Chat: model.ClaudeSonnet45,
        },
    })

    resp, _ := c.Chat(ctx, []ai.Message{
        {Role: ai.RoleUser, Content: "Hello!"},
    })

    fmt.Println(resp.Content)
}

Providers

Models determine their provider automatically. Configure API keys for the providers you use:

Provider Chat Images Embeddings
Anthropic ✓ - -
OpenAI ✓ ✓ ✓
Google ✓ ✓ ✓ 
c := client.New(client.Config{
    APIKeys: client.APIKeys{
        Anthropic: os.Getenv("ANTHROPIC_API_KEY"),
        OpenAI:    os.Getenv("OPENAI_API_KEY"),
        Google:    os.Getenv("GOOGLE_API_KEY"),
    },
    Defaults: client.Defaults{
        Chat:      model.ClaudeSonnet45,      // Routes to Anthropic
        Embedding: model.TextEmbedding3Small, // Routes to OpenAI
        Image:     model.Imagen4,             // Routes to Google
    },
})

// Uses default model (ClaudeSonnet45 -> Anthropic)
resp, _ := c.Chat(ctx, messages)

// Override with different model (routes to OpenAI)
resp, _ := c.Chat(ctx, messages, ai.WithModel(model.GPT52))

Chat & Streaming

// Basic chat
resp, _ := c.Chat(ctx, messages)
fmt.Println(resp.Content)

// Streaming
stream, _ := c.ChatStream(ctx, messages)
for event := range stream {
    if event.Err != nil {
        break
    }
    fmt.Print(event.Delta)
}

Tool Calling

Define tools using the fluent schema builder:

import "github.com/spetersoncode/gains/schema"

tools := []ai.Tool{{
    Name:        "get_weather",
    Description: "Get current weather for a location",
    Parameters: schema.Object().
        Field("location", schema.String().Desc("The city name").Required()).
        Field("unit", schema.String().Desc("Temperature unit").Enum("celsius", "fahrenheit")).
        MustBuild(),
}}

resp, _ := c.Chat(ctx, messages, ai.WithTools(tools))

for _, call := range resp.ToolCalls {
    fmt.Printf("Tool: %s, Args: %s\n", call.Name, call.Arguments)
}

Agent Orchestration

The agent package handles autonomous tool-calling loops with typed handlers:

import (
    "github.com/spetersoncode/gains/agent"
    "github.com/spetersoncode/gains/schema"
)

type SearchArgs struct {
    Query string `json:"query"`
}

// Create a tool registry with typed handler
registry := agent.NewRegistry()
agent.MustRegisterFunc(registry, "search", "Search the web",
    schema.Object().
        Field("query", schema.String().Desc("Search query").Required()).
        MustBuild(),
    func(ctx context.Context, args SearchArgs) (string, error) {
        return results, nil
    },
)

// Create and run agent
a := agent.New(c, registry)

result, _ := a.Run(ctx, messages,
    agent.WithMaxSteps(10),
    agent.WithTimeout(2*time.Minute),
)
fmt.Println(result.Response.Content)
Human-in-the-Loop

Require approval for sensitive operations:

a := agent.New(c, registry)

result, _ := a.Run(ctx, messages,
    agent.WithApprovalRequired("delete_file", "send_email"),
    agent.WithApprover(func(ctx context.Context, call ai.ToolCall) (bool, string) {
        fmt.Printf("Allow %s? [y/n]: ", call.Name)
        // Get user input...
        return approved, ""
    }),
)

Workflows

Build complex pipelines with composable patterns:

import "github.com/spetersoncode/gains/workflow"

// Chain - sequential execution
chain := workflow.NewChain("pipeline",
    workflow.NewPromptStep("analyze", c, analyzePrompt, "analysis"),
    workflow.NewPromptStep("summarize", c, summarizePrompt, "summary"),
)

// Parallel - concurrent execution
parallel := workflow.NewParallel("multi-analysis",
    []workflow.Step{step1, step2, step3},
    aggregator,
)

// Router - conditional branching
router := workflow.NewRouter("classifier",
    []workflow.Route{
        {
            Name:      "question",
            Condition: func(ctx context.Context, s *workflow.State) bool {
                return s.GetString("type") == "question"
            },
            Step: questionHandler,
        },
    },
    defaultHandler,
)

// Execute workflow
wf := workflow.New("my-workflow", chain)
result, _ := wf.Run(ctx, initialState)

Embeddings

resp, _ := c.Embed(ctx, []string{"Hello world"})
fmt.Printf("Dimensions: %d\n", len(resp.Embeddings[0]))

Image Generation

resp, _ := c.GenerateImage(ctx, "A sunset over mountains",
    ai.WithImageSize(ai.ImageSize1024x1024),
)
fmt.Println(resp.Images[0].URL)

Structured Output

Force JSON output or use schema validation:

import "github.com/spetersoncode/gains/schema"

// Simple JSON mode
resp, _ := c.Chat(ctx, messages, ai.WithJSONMode())

// With schema validation
resp, _ := c.Chat(ctx, messages,
    ai.WithResponseSchema(ai.ResponseSchema{
        Name: "result",
        Schema: schema.Object().
            Field("name", schema.String().Required()).
            Field("score", schema.Number().Min(0).Max(100)).
            MustBuild(),
    }),
)

Schema Builder

The schema package provides a fluent API for building JSON schemas:

import "github.com/spetersoncode/gains/schema"

// String with constraints
schema.String().MinLength(1).MaxLength(100).Pattern(`^\w+$`)

// Integer with range
schema.Int().Min(1).Max(100).Default(10)

// Enum values
schema.String().Enum("low", "medium", "high")

// Arrays
schema.Array(schema.String()).MinItems(1).MaxItems(10).UniqueItems()

// Complex objects
schema.Object().
    Field("query", schema.String().Desc("Search query").Required()).
    Field("limit", schema.Int().Min(1).Max(100).Default(10)).
    Field("filters", schema.Object().
        Field("tags", schema.Array(schema.String())).
        Field("active", schema.Bool().Default(true))).
    MustBuild()

Use Build() for error handling or MustBuild() to panic on invalid schemas.

Models

The model package provides type-safe model selection with pricing info:

import "github.com/spetersoncode/gains/model"

// Auto-updating aliases (recommended)
ai.WithModel(model.ClaudeSonnet45)    // Anthropic
ai.WithModel(model.GPT52)             // OpenAI
ai.WithModel(model.Gemini25Flash)     // Google

// Pinned versions for production stability
ai.WithModel(model.ClaudeSonnet45_20250929)
ai.WithModel(model.Gemini3Pro)

Request Options

resp, _ := c.Chat(ctx, messages,
    ai.WithModel(model.ClaudeOpus45),
    ai.WithMaxTokens(4096),
    ai.WithTemperature(0.7),
    ai.WithTools(tools),
    ai.WithToolChoice(ai.ToolChoiceAuto),
)

Retry Configuration

c := client.New(client.Config{
    APIKeys: client.APIKeys{OpenAI: os.Getenv("OPENAI_API_KEY")},
    RetryConfig: &retry.Config{
        MaxAttempts:  5,
        InitialDelay: time.Second,
        MaxDelay:     30 * time.Second,
    },
})

Events

Observe operations at multiple levels:

// Client events via channel
events := make(chan client.Event, 100)
c := client.New(client.Config{
    APIKeys: client.APIKeys{OpenAI: os.Getenv("OPENAI_API_KEY")},
    Events:  events,
})

go func() {
    for e := range events {
        fmt.Printf("[%s] %s %v\n", e.Type, e.Operation, e.Duration)
    }
}()

// Agent events via streaming
a := agent.New(c, registry)
stream := a.RunStream(ctx, messages)
for event := range stream {
    switch event.Type {
    case agent.EventToolCallStarted:
        fmt.Printf("Calling tool: %s\n", event.ToolCall.Name)
    case agent.EventStreamDelta:
        fmt.Print(event.Delta)
    }
}

Environment Variables

Provider Variable
Anthropic ANTHROPIC_API_KEY
OpenAI OPENAI_API_KEY
Google GOOGLE_API_KEY

Examples

See the cmd/demo directory for complete examples.

License

MIT

Documentation

Overview

Package gains provides a unified interface for interacting with LLM providers.

The gains library abstracts away provider-specific APIs, allowing you to write code once and use models from Anthropic (Claude), OpenAI (GPT), and Google (Gemini). Models know their provider, so routing happens automatically.

Import Convention

We recommend importing with the "ai" alias for cleaner code: 

import ai "github.com/spetersoncode/gains"

All examples in this documentation use this convention.

Core Types

The library defines these key types:

  • Provider: Identifies a provider (Anthropic, OpenAI, Google)
  • Model: Interface for models that know their provider
  • Message: Conversation messages with roles and content
  • Response: Chat responses with content, tool calls, and usage

Use the github.com/spetersoncode/gains/client package as the entry point and the github.com/spetersoncode/gains/model package for model selection.

Basic Usage

Create a client with API keys and default models: 

c := client.New(client.Config{
    APIKeys: client.APIKeys{
        Anthropic: os.Getenv("ANTHROPIC_API_KEY"),
    },
    Defaults: client.Defaults{
        Chat: model.ClaudeSonnet45,
    },
})

messages := []ai.Message{
    {Role: ai.RoleUser, Content: "What is the capital of France?"},
}

resp, err := c.Chat(ctx, messages)
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Content)

Model-Centric Routing

Models determine their provider. Override the default with WithModel: 

// Uses default (routes to Anthropic)
resp, _ := c.Chat(ctx, messages)

// Override with GPT (routes to OpenAI)
resp, _ := c.Chat(ctx, messages, ai.WithModel(model.GPT52))

Streaming Responses

For real-time output, use ChatStream: 

stream, err := c.ChatStream(ctx, messages)
if err != nil {
    log.Fatal(err)
}

for event := range stream {
    if event.Err != nil {
        log.Fatal(event.Err)
    }
    fmt.Print(event.Delta)
}

Configuration Options

Customize requests with functional options: 

resp, err := c.Chat(ctx, messages,
    ai.WithModel(model.ClaudeOpus45),
    ai.WithMaxTokens(1000),
    ai.WithTemperature(0.7),
)

Tool Calling

Define tools that the model can invoke: 

tools := []ai.Tool{
    {
        Name:        "get_weather",
        Description: "Get current weather for a location",
        Parameters:  json.RawMessage(`{
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
        }`),
    },
}

resp, err := c.Chat(ctx, messages, ai.WithTools(tools))

Higher-Level Abstractions

For more complex use cases, see:

Index

Constants

This section is empty.

Variables

View Source 
var ErrEmptyInput = errors.New("empty input")

ErrEmptyInput is returned when a required input slice is empty.

Functions

This section is empty.

Types

type ChatProvider 

type ChatProvider interface {
	// Chat sends a conversation and returns a complete response.
	Chat(ctx context.Context, messages []Message, opts ...Option) (*Response, error)

	// ChatStream sends a conversation and returns a channel of streaming events.
	// The channel is closed when the stream is complete or an error occurs.
	// Callers should check StreamEvent.Err for any errors.
	ChatStream(ctx context.Context, messages []Message, opts ...Option) (<-chan StreamEvent, error)
}

ChatProvider defines the interface for AI chat providers.

type ContentPart 

type ContentPart struct {
	// Type indicates the content type: "text" or "image".
	Type ContentPartType
	// Text contains the text content. Only used when Type is "text".
	Text string
	// ImageURL contains a URL to an image. Only used when Type is "image".
	// Mutually exclusive with Base64.
	ImageURL string
	// Base64 contains base64-encoded image data. Only used when Type is "image".
	// Mutually exclusive with ImageURL.
	Base64 string
	// MimeType specifies the image format (e.g., "image/jpeg", "image/png").
	// Required when using Base64, optional for ImageURL (may be inferred).
	MimeType string
}

ContentPart represents a single part of multimodal content. Use either Text (for text parts) or ImageURL/Base64 (for image parts).

func NewImageBase64Part 

func NewImageBase64Part(base64Data, mimeType string) ContentPart

NewImageBase64Part creates an image content part from base64 data.

func NewImageURLPart 

func NewImageURLPart(url string) ContentPart

NewImageURLPart creates an image content part from a URL.

func NewTextPart 

func NewTextPart(text string) ContentPart

NewTextPart creates a text content part.

type ContentPartType 

type ContentPartType string

ContentPartType represents the type of content in a multimodal message part. 

const (
	ContentPartTypeText  ContentPartType = "text"
	ContentPartTypeImage ContentPartType = "image"
)

type EmbeddingOption 

type EmbeddingOption func(*EmbeddingOptions)

EmbeddingOption is a functional option for configuring embedding requests.

func WithEmbeddingDimensions 

func WithEmbeddingDimensions(dims int) EmbeddingOption

WithEmbeddingDimensions sets the output dimensions for the embedding vectors. Note: Only supported by OpenAI (text-embedding-3-*) and Google. For OpenAI, valid values depend on the model (e.g., 256, 512, 1024, 1536, 3072).

func WithEmbeddingModel 

func WithEmbeddingModel(model Model) EmbeddingOption

WithEmbeddingModel sets the model to use for embedding generation.

func WithEmbeddingTaskType 

func WithEmbeddingTaskType(taskType EmbeddingTaskType) EmbeddingOption

WithEmbeddingTaskType sets the intended task type for embeddings. This helps the model optimize the embedding for specific use cases. Note: Only supported by Google; ignored by OpenAI.

type EmbeddingOptions 

type EmbeddingOptions struct {
	Model      Model
	Dimensions int
	TaskType   EmbeddingTaskType
}

EmbeddingOptions contains configuration for an embedding request.

func ApplyEmbeddingOptions 

func ApplyEmbeddingOptions(opts ...EmbeddingOption) *EmbeddingOptions

ApplyEmbeddingOptions applies functional options to an EmbeddingOptions struct.

type EmbeddingProvider 

type EmbeddingProvider interface {
	// Embed generates embeddings for the provided texts.
	// Returns an error if texts is empty.
	Embed(ctx context.Context, texts []string, opts ...EmbeddingOption) (*EmbeddingResponse, error)
}

EmbeddingProvider defines the interface for AI embedding providers.

type EmbeddingResponse 

type EmbeddingResponse struct {
	// Embeddings contains one embedding vector per input text.
	// The order matches the input texts order.
	Embeddings [][]float64
	// Usage contains token usage information.
	Usage Usage
}

EmbeddingResponse represents a complete response from an embedding provider.

type EmbeddingTaskType 

type EmbeddingTaskType string

EmbeddingTaskType specifies the intended use case for embeddings. This helps the model optimize the embedding for specific tasks. Note: Only supported by Google; ignored by OpenAI. 

const (
	// EmbeddingTaskTypeRetrievalQuery optimizes for search queries.
	EmbeddingTaskTypeRetrievalQuery EmbeddingTaskType = "RETRIEVAL_QUERY"
	// EmbeddingTaskTypeRetrievalDocument optimizes for documents to be searched.
	EmbeddingTaskTypeRetrievalDocument EmbeddingTaskType = "RETRIEVAL_DOCUMENT"
	// EmbeddingTaskTypeSemanticSimilarity optimizes for measuring text similarity.
	EmbeddingTaskTypeSemanticSimilarity EmbeddingTaskType = "SEMANTIC_SIMILARITY"
	// EmbeddingTaskTypeClassification optimizes for classification tasks.
	EmbeddingTaskTypeClassification EmbeddingTaskType = "CLASSIFICATION"
	// EmbeddingTaskTypeClustering optimizes for clustering tasks.
	EmbeddingTaskTypeClustering EmbeddingTaskType = "CLUSTERING"
)

type GeneratedImage 

type GeneratedImage struct {
	// URL contains the URL to the generated image (if URL format was requested).
	URL string
	// Base64 contains the base64-encoded image data (if Base64 format was requested).
	Base64 string
	// RevisedPrompt contains the prompt that was actually used.
	// DALL-E 3 rewrites prompts for better results.
	RevisedPrompt string
}

GeneratedImage represents a single generated image.

type ImageError 

type ImageError struct {
	Op  string // "decode" or "fetch"
	URL string // the image URL or "base64"
	Err error  // underlying error
}

ImageError represents an error during image processing.

func (*ImageError) Error 

func (e *ImageError) Error() string

Error returns a formatted error message describing the image processing failure.

func (*ImageError) Unwrap 

func (e *ImageError) Unwrap() error

Unwrap returns the underlying error for use with errors.Is and errors.As.

type ImageFormat 

type ImageFormat string

ImageFormat specifies the output format for generated images. 

const (
	// ImageFormatURL returns images as URLs.
	ImageFormatURL ImageFormat = "url"
	// ImageFormatBase64 returns images as base64-encoded data.
	ImageFormatBase64 ImageFormat = "b64_json"
)

type ImageOption 

type ImageOption func(*ImageOptions)

ImageOption is a functional option for configuring image generation requests.

func WithImageCount 

func WithImageCount(n int) ImageOption

WithImageCount sets the number of images to generate. Note: DALL-E 3 only supports n=1; Google Imagen supports up to 4.

func WithImageFormat 

func WithImageFormat(f ImageFormat) ImageOption

WithImageFormat sets the output format for generated images. Supported values: "url", "b64_json"

func WithImageModel 

func WithImageModel(model Model) ImageOption

WithImageModel sets the model to use for image generation.

func WithImageQuality 

func WithImageQuality(q ImageQuality) ImageOption

WithImageQuality sets the quality level for generated images. Supported values: "standard", "hd" Note: Only supported by DALL-E 3.

func WithImageSize 

func WithImageSize(size ImageSize) ImageOption

WithImageSize sets the dimensions for generated images.

func WithImageStyle 

func WithImageStyle(s ImageStyle) ImageOption

WithImageStyle sets the visual style for generated images. Supported values: "vivid", "natural" Note: Only supported by DALL-E 3.

type ImageOptions 

type ImageOptions struct {
	Model   Model
	Size    ImageSize
	Count   int
	Quality ImageQuality
	Style   ImageStyle
	Format  ImageFormat
}

ImageOptions contains configuration for an image generation request.

func ApplyImageOptions 

func ApplyImageOptions(opts ...ImageOption) *ImageOptions

ApplyImageOptions applies functional options to an ImageOptions struct.

type ImageProvider 

type ImageProvider interface {
	// GenerateImage creates images from a text prompt.
	GenerateImage(ctx context.Context, prompt string, opts ...ImageOption) (*ImageResponse, error)
}

ImageProvider defines the interface for AI image generation providers.

type ImageQuality 

type ImageQuality string

ImageQuality specifies the quality level for generated images. Note: Only supported by DALL-E 3. 

const (
	ImageQualityStandard ImageQuality = "standard"
	ImageQualityHD       ImageQuality = "hd"
)

type ImageResponse 

type ImageResponse struct {
	Images []GeneratedImage
}

ImageResponse represents a complete response from an image generation provider.

type ImageSize 

type ImageSize string

ImageSize represents predefined image dimensions. 

const (
	ImageSize1024x1024 ImageSize = "1024x1024"
	ImageSize1024x1792 ImageSize = "1024x1792" // Portrait
	ImageSize1792x1024 ImageSize = "1792x1024" // Landscape
)

type ImageStyle 

type ImageStyle string

ImageStyle specifies the visual style for generated images. Note: Only supported by DALL-E 3. 

const (
	ImageStyleVivid   ImageStyle = "vivid"
	ImageStyleNatural ImageStyle = "natural"
)

type Message 

type Message struct {
	Role    Role
	Content string
	// Parts contains multimodal content parts (text, images).
	// If populated, Content is ignored for providers that support multimodal.
	Parts []ContentPart
	// ToolCalls contains tool invocation requests from an assistant message.
	// Only populated when Role is RoleAssistant and the model wants to use tools.
	ToolCalls []ToolCall
	// ToolResults contains results from tool executions.
	// Only populated when Role is RoleTool.
	ToolResults []ToolResult
}

Message represents a single message in a conversation.

func NewToolResultMessage 

func NewToolResultMessage(results ...ToolResult) Message

NewToolResultMessage creates a message containing tool results. This is a convenience function for returning tool results to the model.

func (Message) HasParts 

func (m Message) HasParts() bool

HasParts returns true if the message has multimodal content parts.

type Model 

type Model interface {
	String() string
	Provider() Provider
}

Model is an interface implemented by all provider model types. It allows strongly-typed model selection while maintaining a unified API. Every model must identify its provider for automatic routing.

type Option 

type Option func(*Options)

Option is a functional option for configuring chat requests.

func WithJSONMode 

func WithJSONMode() Option

WithJSONMode forces the model to output valid JSON. Note: For Anthropic, this uses a tool-based approach since native JSON mode is not available.

func WithMaxTokens 

func WithMaxTokens(n int) Option

WithMaxTokens sets the maximum number of tokens to generate.

func WithModel 

func WithModel(model Model) Option

WithModel sets the model to use for the request.

func WithResponseSchema 

func WithResponseSchema(schema ResponseSchema) Option

WithResponseSchema sets a JSON schema for structured output. This automatically enables JSON mode.

func WithTemperature 

func WithTemperature(t float64) Option

WithTemperature sets the sampling temperature (0.0 to 2.0).

func WithToolChoice 

func WithToolChoice(choice ToolChoice) Option

WithToolChoice controls how the model uses tools.

func WithTools 

func WithTools(tools []Tool) Option

WithTools sets the tools available to the model.

type Options 

type Options struct {
	Model          Model
	MaxTokens      int
	Temperature    *float64
	Tools          []Tool
	ToolChoice     ToolChoice
	ResponseFormat ResponseFormat
	ResponseSchema *ResponseSchema
}

Options contains configuration for a chat request.

func ApplyOptions 

func ApplyOptions(opts ...Option) *Options

ApplyOptions applies functional options to an Options struct.

type Provider 

type Provider string

Provider identifies an AI provider. 

const (
	ProviderAnthropic Provider = "anthropic"
	ProviderOpenAI    Provider = "openai"
	ProviderGoogle    Provider = "google"
)

Supported providers.

func (Provider) String 

func (p Provider) String() string

String returns the provider identifier.

type Response 

type Response struct {
	Content      string
	FinishReason string
	Usage        Usage
	// ToolCalls contains any tool invocation requests from the model.
	// Check if len(ToolCalls) > 0 to determine if tools should be executed.
	ToolCalls []ToolCall
}

Response represents a complete response from a chat provider.

type ResponseFormat 

type ResponseFormat string

ResponseFormat specifies how the model should format its response. 

const (
	// ResponseFormatText is the default text response format.
	ResponseFormatText ResponseFormat = "text"
	// ResponseFormatJSON forces the model to output valid JSON.
	ResponseFormatJSON ResponseFormat = "json"
)

type ResponseSchema 

type ResponseSchema struct {
	// Name is a descriptive name for the schema (required by some providers).
	Name string
	// Description explains what this schema represents (optional).
	Description string
	// Schema is the JSON Schema definition.
	Schema json.RawMessage
	// Strict enables strict schema enforcement (OpenAI only, defaults to true).
	Strict bool
}

ResponseSchema defines a JSON schema for structured output.

type Role 

type Role string

Role represents the role of a message sender in a conversation. 

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

type SchemaBuilder 

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

SchemaBuilder provides a fluent API for constructing JSON Schema objects from Go structs for use as AI tool parameters. Use SchemaFrom to create a builder from a struct type, then chain methods to add metadata.

func SchemaFrom deprecated 

func SchemaFrom[T any]() *SchemaBuilder

SchemaFrom creates a SchemaBuilder by reflecting on the given struct type. Field names are derived from json tags (or field names if no tag).

Deprecated: SchemaFrom uses reflection and string-based field references which can silently fail on typos. Use the schema package for programmatic schema building: 

import "github.com/yourusername/gains/schema"
params := schema.Object().
    Field("query", schema.String().Desc("Search query").Required()).
    Field("limit", schema.Int().Min(1).Max(100)).
    MustBuild()

Type mappings:

  • string → "string"
  • int, int64, uint, etc. → "integer"
  • float32, float64 → "number"
  • bool → "boolean"
  • []T → "array" with items
  • struct → "object" with properties

Example: 

type Args struct {
    Query string `json:"query"`
    Limit int    `json:"limit"`
}
schema := SchemaFrom[Args]().
    Desc("query", "Search query").Required("query").
    Build()

func (*SchemaBuilder) Build 

func (s *SchemaBuilder) Build() json.RawMessage

Build generates the JSON Schema as json.RawMessage, suitable for [Tool.Parameters].

func (*SchemaBuilder) Desc 

func (s *SchemaBuilder) Desc(field, description string) *SchemaBuilder

Desc sets the description for a field. Unknown fields are ignored.

func (*SchemaBuilder) Enum 

func (s *SchemaBuilder) Enum(field string, values ...string) *SchemaBuilder

Enum sets the allowed values for a field. Unknown fields are ignored.

func (*SchemaBuilder) Required 

func (s *SchemaBuilder) Required(fields ...string) *SchemaBuilder

Required marks the specified fields as required. Unknown fields are ignored.

type StreamEvent 

type StreamEvent struct {
	// Delta contains the incremental content for this event.
	Delta string
	// Done indicates if this is the final event in the stream.
	Done bool
	// Response contains the final response data when Done is true.
	Response *Response
	// Err contains any error that occurred during streaming.
	Err error
}

StreamEvent represents a single event in a streaming response.

type Tool 

type Tool struct {
	// Name is the unique identifier for the tool.
	Name string
	// Description explains what the tool does (helps the model decide when to use it).
	Description string
	// Parameters is a JSON Schema object defining the function parameters.
	Parameters json.RawMessage
}

Tool defines a function that can be called by the model.

type ToolCall 

type ToolCall struct {
	// ID is a unique identifier for this tool call (used to match results).
	ID string
	// Name is the name of the tool to invoke.
	Name string
	// Arguments is a JSON string containing the arguments to pass.
	Arguments string
}

ToolCall represents a request from the model to invoke a tool.

type ToolChoice 

type ToolChoice string

ToolChoice controls how the model uses tools. 

const (
	// ToolChoiceAuto lets the model decide when to use tools (default).
	ToolChoiceAuto ToolChoice = "auto"
	// ToolChoiceNone disables tool use for the request.
	ToolChoiceNone ToolChoice = "none"
	// ToolChoiceRequired forces the model to use a tool.
	ToolChoiceRequired ToolChoice = "required"
)

type ToolResult 

type ToolResult struct {
	// ToolCallID matches the ID from the corresponding ToolCall.
	ToolCallID string
	// Content is the result content to return to the model.
	Content string
	// IsError indicates if the result represents an error.
	IsError bool
}

ToolResult represents the result of executing a tool call.

type Usage 

type Usage struct {
	InputTokens  int
	OutputTokens int
}

Usage contains token usage information for a request.

Source Files

View all Source files

Directories

Path Synopsis
Package agent provides autonomous tool-calling agent functionality for the gains library.
 Package agent provides autonomous tool-calling agent functionality for the gains library.
Package client provides a unified multi-provider client for AI capabilities.
 Package client provides a unified multi-provider client for AI capabilities.
cmd
demo command
internal
provider/anthropic
Package anthropic provides an Anthropic Claude API client implementing [gains.ChatProvider].
 Package anthropic provides an Anthropic Claude API client implementing [gains.ChatProvider].
provider/google
Package google provides a Google Gemini API client implementing gains provider interfaces.
 Package google provides a Google Gemini API client implementing gains provider interfaces.
provider/openai
Package openai provides an OpenAI API client implementing gains provider interfaces.
 Package openai provides an OpenAI API client implementing gains provider interfaces.
retry
Package retry provides retry logic with exponential backoff for transient errors.
 Package retry provides retry logic with exponential backoff for transient errors.
store
Package store provides pluggable state management for gains workflows and agents.
 Package store provides pluggable state management for gains workflows and agents.
Package model provides model constants for all supported AI providers.
 Package model provides model constants for all supported AI providers.
Package schema provides a fluent API for building JSON Schema objects for use with AI tool parameters and structured output.
 Package schema provides a fluent API for building JSON Schema objects for use with AI tool parameters and structured output.
Package workflow provides composable patterns for orchestrating AI-powered pipelines.
 Package workflow provides composable patterns for orchestrating AI-powered pipelines.

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.