🔷Go SDK

v0.2.0

Production Ready

Zaguan Go SDK

The official Go SDK for Zaguan CoreX. Build production-ready AI applications with idiomatic Go patterns, full type safety, context.Context support, and comprehensive testing. Perfect for high-performance backend services and microservices architectures.

View on GitHub pkg.go.dev

Quality Metrics

63%

Test Coverage

221 tests

Security Issues

gosec verified

Code Quality Issues

staticcheck clean

Race Conditions

race detector verified

Installation

Install via go get:

go get github.com/ZaguanLabs/zaguan-sdk-go/sdk

Requirements:

•Go 1.18 or higher
•Zero dependencies (stdlib + google/uuid)

Quick Start

Basic Chat Completion

package main

import (
    "context"
    "fmt"
    "log"
    
    zaguansdk "github.com/ZaguanLabs/zaguan-sdk-go/sdk"
)

func main() {
    // Create a client
    client := zaguansdk.NewClient(zaguansdk.Config{
        BaseURL: "https://api.zaguanai.com",
        APIKey:  "your-api-key",
    })
    
    // Chat completion
    resp, err := client.Chat(context.Background(), zaguansdk.ChatRequest{
        Model: "openai/gpt-4o",
        Messages: []zaguansdk.Message{
            {Role: "user", Content: "Hello, world!"},
        },
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println(resp.Choices[0].Message.Content)
}

Streaming Responses

// Stream responses in real-time
stream, err := client.ChatStream(context.Background(), 
    zaguansdk.ChatRequest{
        Model: "openai/gpt-4o-mini",
        Messages: []zaguansdk.Message{
            {Role: "user", Content: "Tell me a story"},
        },
    }, nil)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for stream.Next() {
    chunk := stream.Chunk()
    if len(chunk.Choices) > 0 && chunk.Choices[0].Delta.Content != "" {
        fmt.Print(chunk.Choices[0].Delta.Content)
    }
}

if err := stream.Err(); err != nil {
    log.Fatal(err)
}

Context & Timeouts

// Use context for cancellation and timeouts
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

resp, err := client.Chat(ctx, zaguansdk.ChatRequest{
    Model: "anthropic/claude-3-5-sonnet",
    Messages: []zaguansdk.Message{
        {Role: "user", Content: "Complex task..."},
    },
}, nil)

Key Features

Idiomatic Go

•Context-aware with context.Context
•Functional options pattern
•Full type safety with structs
•Structured error types
•Logger interface for observability

Production Ready

•OpenAI & Anthropic native support
•Streaming with SSE
•Credits tracking & analytics
•Provider-specific extensions
•Comprehensive test coverage

Advanced Examples

Anthropic Messages API

// Native Anthropic Messages API with extended thinking
resp, err := client.CreateMessage(context.Background(), 
    zaguansdk.MessageRequest{
        Model: "anthropic/claude-3-5-sonnet",
        Messages: []zaguansdk.AnthropicMessage{
            {
                Role: "user",
                Content: "Solve this complex problem...",
            },
        },
        MaxTokens: 4096,
        Thinking: &zaguansdk.ThinkingConfig{
            Type:         "enabled",
            BudgetTokens: 5000,
        },
    }, nil)

// Access thinking content
for _, block := range resp.Content {
    if block.Type == "thinking" {
        fmt.Println("Model's reasoning:", block.Thinking)
    }
}

Credits Tracking

// Check credits balance
balance, err := client.GetCreditsBalance(context.Background(), nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Credits remaining: %d\n", balance.CreditsRemaining)
fmt.Printf("Tier: %s\n", balance.Tier)

// Get usage history
history, err := client.GetCreditsHistory(context.Background(), 
    &zaguansdk.CreditsHistoryOptions{
        Page:     1,
        PageSize: 10,
        Model:    "openai/gpt-4o-mini",
    }, nil)

for _, entry := range history.Entries {
    fmt.Printf("%s: %d credits\n", entry.Model, entry.CreditsUsed)
}

Custom Logger

// Implement custom logger for observability
type MyLogger struct{}

func (l *MyLogger) Debug(msg string, fields ...interface{}) {
    log.Printf("[DEBUG] %s %v", msg, fields)
}

func (l *MyLogger) Info(msg string, fields ...interface{}) {
    log.Printf("[INFO] %s %v", msg, fields)
}

func (l *MyLogger) Error(msg string, fields ...interface{}) {
    log.Printf("[ERROR] %s %v", msg, fields)
}

// Use custom logger
client := zaguansdk.NewClient(zaguansdk.Config{
    BaseURL: "https://api.zaguanai.com",
    APIKey:  "your-api-key",
    Logger:  &MyLogger{},
})

Request Options

// Per-request options override
resp, err := client.Chat(ctx, request, &zaguansdk.RequestOptions{
    Timeout:       30 * time.Second,
    MaxRetries:    3,
    RetryDelay:    time.Second,
    CustomHeaders: map[string]string{
        "X-Custom-Header": "value",
    },
})

SDK Architecture

The SDK follows a modular design with clear separation of concerns:

zaguan-sdk-go/
├── sdk/                    - Core SDK package
│   ├── client.go           - Client configuration and HTTP handling
│   ├── option.go           - Request options and functional patterns
│   ├── chat.go             - OpenAI-compatible chat completions
│   ├── messages.go         - Anthropic-native Messages API
│   ├── models.go           - Model listing and discovery
│   ├── capabilities.go     - Model capability queries
│   ├── credits.go          - Usage tracking and billing
│   ├── errors.go           - Structured error types
│   ├── stream.go           - Streaming support (SSE)
│   └── internal/           - Internal utilities
├── examples/               - Usage examples
└── docs/                   - Documentation

Supported Providers

Access 15+ AI providers through one unified API:

OpenAI

GPT-4o, o1, o3

Anthropic

Claude 3.5 Sonnet

Google

Gemini 2.0 Flash

DeepSeek

DeepSeek V3, R1

Alibaba

Qwen 2.5

xAI

Grok 2

Perplexity

Sonar

Groq

Llama 3, Mixtral

Mistral

Mistral Large

Design Principles

Idiomatic Go

Uses standard patterns like context.Context, functional options, and interfaces for maximum compatibility.

Type-Safe

Leverages Go's type system for compile-time safety and better IDE support.

Comprehensive

Covers all Zaguan features: credits, routing, provider-specific parameters.

Zero Dependencies

Core SDK uses only standard library plus google/uuid for minimal footprint.

Resources & Support

Need help? Check out the examples directory or contact us at [email protected]