aiclient

AI Client - Ultra-Configurable Multi-Provider AI Library

A production-ready Go library for interfacing with multiple AI providers through a unified, simple API. Designed to be used in any Go project requiring AI provider integration.

📋 Table of Contents

• Installation
• Quick Start
• Supported Providers
• Configuration
• Streaming Support
• Examples
• Documentation
• Contributing
• Security
• License

📦 Installation

Requirements

• Go 1.21 or later
• Git (for go get)

Install

go get github.com/flowcmd/ai-client

Verify Installation

go mod tidy
go build ./...

🚀 Quick Start

Simple Usage

package main

import (
    "fmt"
    "github.com/flowcmd/ai-client"
)

func main() {
    response, err := aiclient.New(aiclient.Config{
        Token:   "sk-proj-1234567890",
        Model:   "gpt-4o",
        BaseURL: "https://api.openai.com/v1",
        SystemPrompt: "You are a helpful assistant.",
        Messages: []aiclient.Message{
            {Role: "user", Content: "What is Go programming language?"},
        },
        Options: map[string]interface{}{
            "temperature": 0.7,
            "max_tokens":  100,
        },
    })

    if err != nil {
        panic(err)
    }

    fmt.Printf("Response: %s\n", response.Content)
}

Multi-Provider Client

client := aiclient.NewClient()

// Register multiple providers
client.RegisterProvider("openai", aiclient.NewOpenAIProvider())
client.RegisterProvider("claude", aiclient.NewAnthropicProvider())
client.RegisterProvider("ollama", aiclient.NewOllamaProvider())

// Use with automatic failover
response, err := client.GenerateWithFallback(
    context.Background(),
    []string{"openai", "claude"}, // try OpenAI first, then Claude
    config,
)

🌟 Supported Providers

Provider Features Comparison

📋 Configuration Options

Core Configuration

type Config struct {
    Token          string                 // API token/key
    Model          string                 // Model name (e.g., "gpt-4o")
    BaseURL        string                 // Provider API base URL
    ResponseFormat string                 // "json" or "text"
    Schema         map[string]interface{} // JSON schema for structured output
    SystemPrompt   string                 // System prompt for the conversation
    Messages       []Message              // Conversation messages
    Options        map[string]interface{} // Provider-specific options
    Timeout        time.Duration          // Request timeout
}

Universal Options

All providers support these common options (mapped appropriately):

Options: map[string]interface{}{
    "temperature":        0.7,     // Randomness (0.0-2.0)
    "max_tokens":         100,     // Maximum output tokens
    "top_p":              0.9,     // Nucleus sampling
    "frequency_penalty":  0.0,     // Reduce repetition
    "presence_penalty":   0.0,     // Encourage new topics
    "stopwords":          []string{"STOP"}, // Stop sequences
}

🔄 Streaming Support

stream, err := client.GenerateStream(context.Background(), config)
if err != nil {
    panic(err)
}

for chunk := range stream {
    if chunk.Error != nil {
        fmt.Printf("Error: %v\n", chunk.Error)
        break
    }

    fmt.Print(chunk.Delta) // Print incremental content

    if chunk.Done {
        fmt.Printf("\nFinal content: %s\n", chunk.Content)
        break
    }
}

🎯 Provider-Specific Examples

OpenAI with Structured Output

response, err := aiclient.New(aiclient.Config{
    Token:          "sk-proj-1234567890",
    Model:          "gpt-4o",
    BaseURL:        "https://api.openai.com/v1",
    ResponseFormat: "json",
    Schema: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "title":       map[string]string{"type": "string"},
            "description": map[string]string{"type": "string"},
        },
    },
    SystemPrompt: "Extract title and description from the following text.",
    Messages: []aiclient.Message{
        {Role: "user", Content: "The new AI client supports multiple providers with a unified interface."},
    },
})

Anthropic Claude

response, err := aiclient.New(aiclient.Config{
    Token:   "ant-api-key-12345",
    Model:   "claude-3-sonnet-20240229",
    BaseURL: "https://api.anthropic.com",
    SystemPrompt: "You are Claude, created by Anthropic. You're helpful, harmless, and honest.",
    Messages: []aiclient.Message{
        {Role: "user", Content: "Explain quantum computing briefly."},
    },
    Options: map[string]interface{}{
        "max_tokens":  200,
        "temperature": 0.5,
    },
})

Ollama (Local)

response, err := aiclient.New(aiclient.Config{
    Model:   "llama3.2",
    BaseURL: "http://localhost:11434",
    SystemPrompt: "You are a local AI assistant.",
    Messages: []aiclient.Message{
        {Role: "user", Content: "What's the advantage of running models locally?"},
    },
    Options: map[string]interface{}{
        "temperature": 0.8,
        "max_tokens":  100,
    },
})

🛡️ Error Handling & Resilience

Automatic Failover

// Try multiple providers in order
response, err := client.GenerateWithFallback(
    ctx,
    []string{"openai", "anthropic", "ollama"},
    config,
)

Manual Error Handling

response, err := client.Generate(ctx, config)
if err != nil {
    // Handle specific error types
    switch {
    case strings.Contains(err.Error(), "rate limit"):
        // Wait and retry
    case strings.Contains(err.Error(), "401"):
        // Check API key
    default:
        // Generic error handling
    }
}

🏗️ Architecture

The library is built with a clean provider abstraction:

ai-client/
├── aiclient.go          # Main client interface
├── types.go             # Core types and interfaces
├── adapters.go          # Provider adapters
└── providers/
    ├── openai/          # OpenAI implementation
    ├── anthropic/       # Anthropic implementation
    ├── ollama/          # Ollama implementation
    └── ...              # More providers

Adding New Providers

1. Create a new provider package in providers/
2. Implement the provider interface:

type Provider interface {
    Name() string
    Generate(ctx context.Context, config Config) (*Response, error)
    GenerateStream(ctx context.Context, config Config) (<-chan StreamChunk, error)
    ValidateConfig(config Config) error
}

1. Add provider detection logic in detectAndCreateProvider()

🚦 Production Considerations

Rate Limiting

The client respects provider rate limits and implements exponential backoff:

config.Timeout = 30 * time.Second  // Per-request timeout

Token Management

Store tokens securely and rotate them regularly:

// Never hardcode tokens
config.Token = os.Getenv("OPENAI_API_KEY")

Monitoring

Monitor usage and costs:

fmt.Printf("Tokens used: %v\n", response.Usage)
fmt.Printf("Provider: %s\n", response.Provider)

📖 Documentation

API Reference

• Package Documentation - Complete API reference
• Provider Documentation - Provider-specific guides
• Examples - Working code examples

Guides

• Getting Started - Detailed setup guide
• Provider Setup - Provider-specific configuration
• Best Practices - Production usage guidelines

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Read our Contributing Guide
2. Check out Good First Issues
3. Fork the repository and create a feature branch
4. Add tests for new functionality
5. Ensure all tests pass: go test ./...
6. Submit a pull request

Community

• GitHub Discussions - Ask questions and share ideas
• Issues - Report bugs and request features
• Contributors - Hall of fame for contributors

🛡️ Security

Security is important to us. Please see our Security Policy for:

• Reporting vulnerabilities
• Security best practices
• Supported versions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

Project

• Repository
• Releases
• Changelog
• Issues
• Discussions

Documentation

• API Reference
• GitHub Pages
• Wiki

Built with ❤️ for the Go community