Go AI Client Library

A comprehensive, multi-provider Go library for interacting with various AI models through unified interfaces. Supports LLMs, embeddings, image generation, audio generation, speech-to-text, and rerankers from 10+ providers with streaming, tool calling, structured output, and MCP integration.

Documentation | API Reference

Features

• Multi-Provider Support — Unified interface for 10+ AI providers
• LLM Support — Chat completions, streaming, tool calling, structured output
• Agent Framework — Multi-agent orchestration with sub-agents, handoffs, fan-out, session management, persistent memory, and context strategies
• Embedding Models — Text, multimodal, and contextualized embeddings
• Image Generation — Text-to-image with OpenAI, Gemini, and xAI
• Audio — Text-to-speech (ElevenLabs, OpenAI, Google Cloud, Azure Speech) and speech-to-text (OpenAI Whisper, ElevenLabs Scribe, Deepgram, AssemblyAI, Google Cloud)
• Rerankers — Document reranking with Voyage AI and Cohere
• MCP Integration — Model Context Protocol support for advanced tooling
• Cost Tracking — Built-in token and character usage with cost calculation

Installation

go get github.com/joakimcarlsson/ai

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/joakimcarlsson/ai/message"
    "github.com/joakimcarlsson/ai/model"
    llm "github.com/joakimcarlsson/ai/providers"
)

func main() {
    client, err := llm.NewLLM(
        model.ProviderOpenAI,
        llm.WithAPIKey("api-key"),
        llm.WithModel(model.OpenAIModels[model.GPT4o]),
    )
    if err != nil {
        log.Fatal(err)
    }

    messages := []message.Message{
        message.NewUserMessage("Hello, how are you?"),
    }

    response, err := client.SendMessages(context.Background(), messages, nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(response.Content)
}

Supported Providers

Agent Framework

import (
    "github.com/joakimcarlsson/ai/agent"
    "github.com/joakimcarlsson/ai/agent/session"
)

myAgent := agent.New(llmClient,
    agent.WithSystemPrompt("You are a helpful assistant."),
    agent.WithTools(&weatherTool{}),
    agent.WithSession("user-123", session.FileStore("./sessions")),
)

response, _ := myAgent.Chat(ctx, "What's the weather in Tokyo?")

The agent framework supports sub-agents, handoffs, fan-out, continue/resume, context strategies, persistent memory, and instruction templates.

Versioning

Each module is versioned independently using path-prefixed git tags. The tag
prefix must match the subdirectory path exactly — this is how the Go module
system resolves versions.

All modules follow semantic versioning. The root module
and integration modules are versioned independently.

Release Process

Releases follow the AWS SDK v2 pattern: CI on main is the safety net, git tags
drive go get resolution, and dated GitHub Releases provide changelogs.

1. Ensure main is green

CI must pass on the latest commit before tagging.

2. Tag modules that changed

# Tag a single module (dry-run — creates local tag only)
scripts/release.sh tag -m postgres -v v0.1.0

# Tag and push
make release-tag MODULE=postgres VERSION=v0.1.0

For integration modules, the require version for the root module in
integrations/<name>/go.mod must match the latest published root tag.
The script warns if this is stale.

3. Warm the Go module proxy

scripts/release.sh warm -t integrations/postgres/v0.1.0

This ensures the tagged version is immediately available via go get.

4. Create a dated GitHub Release

# Dry-run (shows what would be published)
scripts/release.sh release

# Publish
make release-publish

This creates a release-YYYY-MM-DD tag and a GitHub Release listing all
module versions tagged since the previous release.

License

See LICENSE file.