Skip to main content
View as MarkdownOpen in ChatGPTOpen in Claude

Go AI SDK Core

Large Language Models (LLMs) are advanced programs that can understand, create, and engage with human language on a large scale. They are trained on vast amounts of written material to recognize patterns in language and predict what might come next in a given piece of text.

The Go AI SDK Core simplifies working with LLMs by offering a standardized way of integrating them into your Go applications - so you can focus on building great AI applications for your users, not waste time on technical details.

For example, here's how you can generate text with various models using the Go AI SDK:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/openai"
    "github.com/digitallysavvy/go-ai/pkg/providers/anthropic"
    "github.com/digitallysavvy/go-ai/pkg/providers/google"
)

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

    // OpenAI
    openaiProvider := openai.New(openai.Config{APIKey: os.Getenv("OPENAI_API_KEY")})
    gpt4, _ := openaiProvider.LanguageModel("gpt-4")

    // Anthropic
    anthropicProvider := anthropic.New(anthropic.Config{APIKey: os.Getenv("ANTHROPIC_API_KEY")})
    claude, _ := anthropicProvider.LanguageModel("claude-3-5-sonnet-20241022")

    // Google
    googleProvider := google.New(google.Config{APIKey: os.Getenv("GOOGLE_GENERATIVE_AI_API_KEY")})
    gemini, _ := googleProvider.LanguageModel("gemini-1.5-flash")

    // Same API for all providers
    result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
        Model:  gpt4, // or claude, or gemini
        Prompt: "Explain quantum computing in simple terms.",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Text)
}

Core Functions​

The Go AI SDK Core has various functions designed for text generation, structured data generation, and tool usage. These functions take a standardized approach to setting up prompts and settings, making it easier to work with different models.

Text Generation​

  • ai.GenerateText() - Generates text and tool calls. This function is ideal for non-interactive use cases such as automation tasks where you need to write text (e.g. drafting email or summarizing web pages) and for agents that use tools.

  • ai.StreamText() - Stream text and tool calls. You can use the StreamText function for interactive use cases such as chat bots and content streaming.

// Generate complete text at once
result, _ := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Write a haiku about Go programming.",
})
fmt.Println(result.Text)

// Stream text as it's generated
stream, _ := ai.StreamText(ctx, ai.StreamTextOptions{
    Model:  model,
    Prompt: "Write a story about AI.",
})
defer stream.Close()

for chunk := range stream.Chunks() {
    fmt.Print(chunk.Text)
}

Structured Data Generation​

  • ai.GenerateObject() - Generates a typed, structured object that matches a JSON schema. You can use this function to force the language model to return structured data, e.g. for information extraction, synthetic data generation, or classification tasks.

  • ai.StreamObject() - Stream a structured object that matches a JSON schema. You can use this function to stream generated structured data.

schema := map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "name": map[string]interface{}{"type": "string"},
        "age":  map[string]interface{}{"type": "number"},
    },
    "required": []string{"name", "age"},
}

result, _ := ai.GenerateObject(ctx, ai.GenerateObjectOptions{
    Model:  model,
    Schema: schema,
    Prompt: "Generate a person profile.",
})

fmt.Printf("Object: %v\n", result.Object)

Embeddings & Semantic Search​

  • ai.Embed() - Generate a single embedding vector for text.
  • ai.EmbedMany() - Generate multiple embedding vectors in batch.
  • Similarity Functions - CosineSimilarity, EuclideanDistance, DotProduct, and more.
// Single embedding
result, _ := ai.Embed(ctx, ai.EmbedOptions{
    Model: embeddingModel,
    Input: "Go is a statically typed, compiled language",
})

// Batch embeddings
results, _ := ai.EmbedMany(ctx, ai.EmbedManyOptions{
    Model:  embeddingModel,
    Inputs: []string{"text1", "text2", "text3"},
})

// Find most similar
idx, score, _ := ai.FindMostSimilar(queryEmbedding, results.Embeddings)

Document Reranking​

  • ai.Rerank() - Rerank documents based on relevance to a query.
result, _ := ai.Rerank(ctx, ai.RerankOptions{
    Model:     rerankModel,
    Query:     "What is machine learning?",
    Documents: []string{"doc1", "doc2", "doc3"},
    TopN:      3,
})

Multi-Modal Generation​

// Text to image
imageResult, _ := ai.GenerateImage(ctx, ai.GenerateImageOptions{
    Model:  imageModel,
    Prompt: "A serene mountain landscape",
})

// Text to speech
speechResult, _ := ai.GenerateSpeech(ctx, ai.GenerateSpeechOptions{
    Model: speechModel,
    Text:  "Hello, world!",
    Voice: "alloy",
})

// Speech to text
transcription, _ := ai.Transcribe(ctx, ai.TranscribeOptions{
    Model: transcriptionModel,
    Audio: audioBytes,
})

Context-Based Operations​

All Go AI SDK functions use context.Context as the first parameter, enabling:

  • Cancellation: Cancel operations in progress
  • Timeouts: Set deadlines for operations
  • Request-scoped values: Pass data through the call stack
// With timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Long generation...",
})
if err != nil {
    if ctx.Err() == context.DeadlineExceeded {
        fmt.Println("Operation timed out")
    }
}

Error Handling​

The Go AI SDK uses Go's standard error handling patterns. All functions return an error as the last return value:

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Hello",
})
if err != nil {
    // Handle error
    // providererrors is github.com/digitallysavvy/go-ai/pkg/provider/errors
    if providererrors.IsRateLimitError(err) {
        fmt.Println("Rate limit exceeded")
    }
    log.Fatal(err)
}

See Error Handling for comprehensive error handling strategies.

Configuration & Settings​

Control model behavior with settings:

result, _ := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:       model,
    Prompt:      "Generate creative text",
    Temperature: 0.8,        // Higher = more creative
    MaxTokens:   500,        // Limit response length
    TopP:        0.9,        // Nucleus sampling
    TopK:        40,         // Top-k sampling
    StopSequences: []string{"\n\n"}, // Stop at double newline
})

See Settings for all available options.

Middleware​

Add cross-cutting concerns like logging, caching, or rate limiting:

import "github.com/digitallysavvy/go-ai/pkg/middleware"

wrappedModel := middleware.WrapLanguageModel(model, []*middleware.LanguageModelMiddleware{
    loggingMiddleware,
    cachingMiddleware,
    rateLimitingMiddleware,
}, nil, nil)

See Middleware for details.

Telemetry​

Built-in OpenTelemetry support for observability:

import "github.com/digitallysavvy/go-ai/pkg/telemetry"

// Register an OpenTelemetry-backed integration once at startup.
telemetry.RegisterTelemetryIntegration(telemetry.NewLegacyOpenTelemetry(telemetry.LegacyOpenTelemetryOptions{}))

// Calls are traced when telemetry is enabled or an integration is registered.
result, _ := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:     model,
    Prompt:    "Hello",
    Telemetry: &telemetry.Options{},
})

See Telemetry for configuration options.

Go-Specific Features​

The Go AI SDK leverages Go's strengths:

Channels for Streaming​

stream, _ := ai.StreamText(ctx, ai.StreamTextOptions{
    Model:  model,
    Prompt: "Generate text",
})
defer stream.Close()

// Channels close automatically when done
for chunk := range stream.Chunks() {
    fmt.Print(chunk.Text)
}

Goroutines for Concurrency​

var wg sync.WaitGroup

for _, prompt := range prompts {
    wg.Add(1)
    go func(p string) {
        defer wg.Done()
        result, _ := ai.GenerateText(ctx, ai.GenerateTextOptions{
            Model:  model,
            Prompt: p,
        })
        fmt.Println(result.Text)
    }(prompt)
}

wg.Wait()

defer for Resource Cleanup​

stream, _ := ai.StreamText(ctx, ai.StreamTextOptions{
    Model:  model,
    Prompt: "Generate text",
})
defer stream.Close() // Always closes, even on error

for chunk := range stream.Chunks() {
    fmt.Print(chunk.Text)
}

API Reference​

For detailed API documentation, see the API Reference section:

Next Steps​

See Also​