Advanced

Advanced Features

Retry with Backoff

Automatically retry on transient failures:

ai.GPT5().
    Retry(3).  // Up to 3 retries
    Ask("Hello")

Backoff is exponential: 100ms, 400ms, 900ms...

Fallback Chain

Try backup models if primary fails:

ai.GPT5().
    Fallback(ai.ModelClaudeOpus, ai.ModelGemini3Flash).
    Ask("Hello")

Combined with retry:

ai.GPT5().
    Retry(2).
    Fallback(ai.ModelClaudeOpus, ai.ModelGemini3Flash).
    Ask("Hello")
// Tries: GPT5 (3x) → Claude (3x) → Gemini (3x)

Context Injection

Add file contents as context:

// Single file
ai.Claude().
    Context("main.go").
    Ask("Review this code")

// Multiple files
ai.Claude().
    Context("main.go").
    Context("utils.go").
    Ask("How do these work together?")

// Glob pattern
ai.Claude().
    Context("src/*.go").
    Ask("Analyze this package")

// Raw string as context
ai.Claude().
    ContextString("data", `{"key": "value"}`).
    Ask("What's in this JSON?")

Context is appended to the system prompt under a # Context header.

JSON Mode

Request structured JSON responses:

// Enable JSON mode
response, _ := ai.GPT5().
    JSON().
    Ask("List 3 programming languages as JSON array")
// Returns: ["Python", "Go", "Rust"]

Parse into struct:

type Analysis struct {
    Sentiment string `json:"sentiment"`
    Score     int    `json:"score"`
    Keywords  []string `json:"keywords"`
}

var result Analysis
err := ai.GPT5().AskJSON(
    `Analyze: "I love this product!" 
     Return: {"sentiment": "...", "score": 1-10, "keywords": [...]}`,
    &result,
)

fmt.Printf("Sentiment: %s, Score: %d\n", result.Sentiment, result.Score)

Response Metadata

Get detailed response info:

meta := ai.GPT5().
    System("Be brief").
    User("Hello").
    SendWithMeta()

fmt.Printf("Content: %s\n", meta.Content)
fmt.Printf("Model: %s\n", meta.Model)
fmt.Printf("Tokens: %d (prompt: %d, completion: %d)\n", 
    meta.Tokens, meta.PromptTokens, meta.CompletionTokens)
fmt.Printf("Latency: %v\n", meta.Latency)
fmt.Printf("Retries: %d\n", meta.Retries)

if meta.Error != nil {
    fmt.Printf("Error: %v\n", meta.Error)
}

Caching

Save API calls during testing:

ai.Cache = true

ai.Ask("What is 2+2?")  // Hits API
ai.Ask("What is 2+2?")  // Returns cached response
ai.Ask("What is 2+2?")  // Returns cached response

// Check cache size
fmt.Printf("Cached responses: %d\n", ai.CacheSize())

// Clear cache
ai.ClearCache()

Statistics Tracking

Track usage across your session:

// After some requests...
ai.PrintStats()
// Output:
// ═══════════════════════════════════════════════════════════════
// 📊 Session Statistics
// ═══════════════════════════════════════════════════════════════
//   Requests:     12
//   Total Tokens: 4,567 (prompt: 1,234, completion: 3,333)
//   Avg Latency:  1.2s
//   Models Used:
//     - openai/gpt-5.2: 8
//     - anthropic/claude-opus-4.5: 4
// ═══════════════════════════════════════════════════════════════

// Get stats programmatically
stats := ai.GetStats()
fmt.Printf("Total tokens: %d\n", stats.TotalTokens)

// Estimated cost
ai.PrintCost()
// 💰 Estimated Cost: $0.0234 (4567 tokens)

// Reset stats
ai.ResetStats()

Cloning Builders

Create copies to reuse configurations:

base := ai.Claude().
    SystemFile("prompts/analyst.md").
    With(ai.Vars{"domain": "crypto"})

// Clone and use differently
b1 := base.Clone()
b1.Ask("Current trends?")

b2 := base.Clone()
b2.Var("domain", "stocks").Ask("Current trends?")

// Original unchanged
base.Ask("General update?")

Debug Mode

See exactly what's being sent/received:

// Per-request
ai.GPT5().Debug().Ask("Hello")

// Global
ai.Debug = true
ai.Ask("Hello")
ai.Debug = false

Output:

┌─────────────────────────────────────────────────────────────
│ DEBUG REQUEST → openai/gpt-5.2
├─────────────────────────────────────────────────────────────
│ [system]
│   You are a helpful assistant
│ [user]
│   Hello
└─────────────────────────────────────────────────────────────

┌─────────────────────────────────────────────────────────────
│ DEBUG RESPONSE
├─────────────────────────────────────────────────────────────
│ Hi there! How can I help you today?
├─────────────────────────────────────────────────────────────
│ Tokens: prompt=15, completion=10, total=25
└─────────────────────────────────────────────────────────────