Iris Examples

Examples

These examples demonstrate production-ready patterns for building AI-powered applications with Iris. Each example includes complete, runnable code with proper error handling, multiple provider options, and real-world use cases.

What Makes These Examples Different

Unlike toy demos, these examples show:

• Complete implementations — not snippets, but full working code
• Production patterns — error handling, retries, timeouts, and graceful degradation
• Provider flexibility — each example works with multiple providers
• Real use cases — patterns extracted from production applications

Example Categories

Retrieval & Search

Build intelligent search and retrieval systems that combine embeddings, vector databases, and language models.

RAG Pipeline Complete retrieval-augmented generation with embeddings, vector search, reranking, and grounded answer synthesis. Includes citation extraction and source attribution.

Batch Embeddings Process thousands of documents efficiently with batching, rate limiting, progress tracking, and incremental persistence to vector stores.

Agents & Tools

Create autonomous agents that can reason, plan, and execute multi-step workflows using external tools.

Agent With Tools Build a support agent that investigates issues, queries databases, sends notifications, and handles multi-turn tool execution with proper state management.

Multimodal Applications

Process images, documents, and mixed media alongside text for richer AI interactions.

Multimodal QA Analyze images, diagrams, screenshots, and documents with vision models. Includes base64 encoding, URL loading, and multi-image conversations.

Streaming & Real-Time

Build responsive applications with streaming responses and real-time processing.

Streaming Summaries Stream long-form content with progress updates, cancellation support, and token-by-token rendering for responsive UIs.

Running the Examples

Each example is a complete Go program. To run any example:

# Clone the examples repository
git clone https://github.com/petal-labs/iris-examples
cd iris-examples

# Set up your API keys
iris keys set openai
iris keys set anthropic
iris keys set voyageai

# Run an example
go run rag-pipeline/main.go

Provider Recommendations

Different examples work best with different providers:

Example	Recommended Provider	Alternatives
RAG Pipeline	OpenAI + Voyage AI	Anthropic + Gemini
Batch Embeddings	Voyage AI	OpenAI, Gemini
Agent With Tools	Claude claude-sonnet-4-20250514	GPT-4o, Gemini Pro
Multimodal QA	GPT-4o	Claude claude-sonnet-4-20250514, Gemini Pro
Streaming Summaries	GPT-4o	Claude, Gemini

Tip

For cost-sensitive applications, consider using smaller models for initial processing and larger models only for final synthesis. The examples show how to implement this pattern.

Example Structure

Each example follows a consistent structure:

example-name/
├── main.go           # Entry point with CLI flags
├── config.go         # Configuration and environment setup
├── types.go          # Domain types and interfaces
├── tools.go          # Tool definitions (if applicable)
└── README.md         # Usage instructions and requirements

Common Patterns

Provider Initialization

All examples use the keystore pattern for secure API key management:

// Primary provider from keystore
provider, err := openai.NewFromKeystore()
if err != nil {
    // Fall back to environment variable
    provider, err = openai.NewFromEnv()
    if err != nil {
        log.Fatal("No API key found. Run: iris keys set openai")
    }
}

Error Handling

Examples demonstrate proper error handling with typed errors:

resp, err := client.Chat(model).User(prompt).GetResponse(ctx)
if err != nil {
    var apiErr *core.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case 429:
            // Handle rate limiting with exponential backoff
            time.Sleep(calculateBackoff(attempt))
            continue
        case 500, 503:
            // Retry on server errors
            continue
        default:
            return fmt.Errorf("API error: %w", err)
        }
    }
    return err
}

Context and Cancellation

Examples use context for timeouts and cancellation:

// Create context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// Pass context to all operations
resp, err := client.Chat(model).User(prompt).GetResponse(ctx)

Retry Policies

Examples show how to configure retry behavior:

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},
    }),
)

Next Steps

Getting Started New to Iris? Start here.

Providers Learn about available providers.

Tools Guide Deep dive into tool calling.

Streaming Guide Master streaming responses.