xAI

The xAI provider connects Iris to Grok models. Grok is known for its real-time knowledge, reasoning capabilities, and unique personality that can tackle questions other models may avoid.

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/petal-labs/iris/core"
    "github.com/petal-labs/iris/providers/xai"
)

func main() {
    provider := xai.New(os.Getenv("XAI_API_KEY"))
    client := core.NewClient(provider)

    resp, err := client.Chat("grok-3").
        User("Explain quantum computing in plain English.").
        GetResponse(context.Background())

    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Output)
}

Set Your API Key

CLI Keystore
Environment Variable

# Store in the encrypted keystore (recommended)
iris keys set xai
# Prompts for: Enter API key for xai: xai-...

export XAI_API_KEY=xai-...

Import

import "github.com/petal-labs/iris/providers/xai"

Create the Provider

// From an API key string
provider := xai.New("xai-...")

// From the XAI_API_KEY environment variable
provider, err := xai.NewFromEnv()
if err != nil {
    log.Fatal("XAI_API_KEY not set:", err)
}

// From the Iris keystore (falls back to environment)
provider, err := xai.NewFromKeystore()

Configuration Options

Option	Description	Default
`WithBaseURL(url)`	Override the API base URL	`https://api.x.ai/v1`
`WithHTTPClient(client)`	Use a custom `*http.Client`	Default client
`WithHeader(key, value)`	Add a custom HTTP header	None
`WithTimeout(duration)`	Set the request timeout	60 seconds

provider := xai.New("xai-...",
    xai.WithTimeout(90 * time.Second),
)

Supported Features

Feature	Supported	Notes
Chat	✓	All Grok models
Streaming	✓	Real-time token streaming
Tool calling	✓	Function calling
Vision	✓	Image analysis with grok-vision-beta
Reasoning	✓	Deep thinking mode
Image generation		Not supported
Embeddings		Not supported

Available Models

Chat Models

Model	Context	Best For
`grok-3`	128K	Complex reasoning, latest model
`grok-3-fast`	128K	Faster responses
`grok-2`	128K	Production workloads
`grok-2-mini`	128K	Cost-effective

Vision Models

Model	Context	Best For
`grok-vision-beta`	8K	Image analysis

Basic Chat

resp, err := client.Chat("grok-3").
    System("You are a helpful assistant with a witty personality.").
    User("What's the best programming language and why is it Go?").
    Temperature(0.7).
    MaxTokens(500).
    GetResponse(ctx)

if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Output)

Streaming

stream, err := client.Chat("grok-3").
    System("You are a helpful assistant.").
    User("Explain Go's concurrency model in detail.").
    GetStream(ctx)

if err != nil {
    log.Fatal(err)
}

for chunk := range stream.Ch {
    fmt.Print(chunk.Content)
}
fmt.Println()

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

Vision

Analyze images with Grok Vision:

imageData, err := os.ReadFile("photo.png")
if err != nil {
    log.Fatal(err)
}
base64Data := base64.StdEncoding.EncodeToString(imageData)

resp, err := client.Chat("grok-vision-beta").
    UserMultimodal().
        Text("What's happening in this image?").
        ImageBase64(base64Data, "image/png").
        Done().
    GetResponse(ctx)

fmt.Println(resp.Output)

Reasoning Mode

Enable deep thinking for complex problems:

resp, err := client.Chat("grok-3").
    System("You are a brilliant problem solver.").
    User("Analyze the implications of quantum computing on cryptography.").
    Thinking(true).
    ThinkingBudget(5000).
    GetResponse(ctx)

// Access reasoning process
if resp.Thinking != "" {
    fmt.Println("=== Reasoning ===")
    fmt.Println(resp.Thinking)
}
fmt.Println("=== Answer ===")
fmt.Println(resp.Output)

Tool Calling

weatherTool := core.Tool{
    Name:        "get_weather",
    Description: "Get current weather for a location",
    Parameters: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "location": map[string]interface{}{
                "type":        "string",
                "description": "City name",
            },
        },
        "required": []string{"location"},
    },
}

resp, err := client.Chat("grok-3").
    User("What's the weather in San Francisco?").
    Tools(weatherTool).
    GetResponse(ctx)

if len(resp.ToolCalls) > 0 {
    call := resp.ToolCalls[0]
    result := getWeather(call.Arguments)

    finalResp, err := client.Chat("grok-3").
        User("What's the weather in San Francisco?").
        Tools(weatherTool).
        Assistant(resp.Output).
        ToolCall(call.ID, call.Name, call.Arguments).
        ToolResult(call.ID, result).
        GetResponse(ctx)

    fmt.Println(finalResp.Output)
}

Current Events

Grok excels at questions about current events:

resp, err := client.Chat("grok-3").
    System("You have access to real-time information from X/Twitter.").
    User("What are people saying about the latest tech news?").
    GetResponse(ctx)

Multi-Turn Conversations

resp1, _ := client.Chat("grok-3").
    System("You are a witty assistant.").
    User("Tell me a programming joke.").
    GetResponse(ctx)

resp2, _ := client.Chat("grok-3").
    System("You are a witty assistant.").
    User("Tell me a programming joke.").
    Assistant(resp1.Output).
    User("Now explain why it's funny.").
    GetResponse(ctx)

Error Handling

resp, err := client.Chat("grok-3").User(prompt).GetResponse(ctx)
if err != nil {
    var apiErr *core.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case 401:
            log.Fatal("Invalid API key")
        case 429:
            log.Printf("Rate limited. Retry after: %s", apiErr.RetryAfter)
        case 500, 503:
            log.Printf("xAI service error: %s", apiErr.Message)
        }
    }
}

Best Practices

Choose the Right Model

Task	Recommended Model
General chat	grok-2-mini
Complex reasoning	grok-3
Fast responses	grok-3-fast
Image analysis	grok-vision-beta

Handle Rate Limits

client := core.NewClient(provider,
    core.WithRetryPolicy(&core.RetryPolicy{
        MaxRetries:        3,
        InitialInterval:   1 * time.Second,
        MaxInterval:       30 * time.Second,
        BackoffMultiplier: 2.0,
        RetryOn:           []int{429, 500, 503},
    }),
)

Notes

Uses Authorization: Bearer for authentication
Grok models have access to real-time X/Twitter data
The provider is safe for concurrent use after construction
Grok tends to have a more direct and humorous communication style

Next Steps

Tools Guide

Learn advanced tool calling. Tools →

Streaming Guide

Master streaming responses. Streaming →

Providers Overview

Compare all available providers. Providers →