AI SDK

Enterprise-grade AI SDK for Go that surpasses popular JavaScript SDKs with advanced features, complete type safety, and production-ready components.

73% test coverage • 416+ passing tests • 19,913 lines of code • 26 features

Why Forge AI SDK?

Architecture

┌──────────────────────────────────────────────┐
│              Forge AI SDK                     │
├──────────────────────────────────────────────┤
│                                               │
│  ┌────────────────┐  ┌────────────────┐     │
│  │   Builders     │  │  Multi-Modal   │     │
│  │ • Generate     │  │ • Images       │     │
│  │ • Stream       │  │ • Audio        │     │
│  │ • Object       │  │ • Video        │     │
│  └────────────────┘  └────────────────┘     │
│                                               │
│  ┌────────────────┐  ┌────────────────┐     │
│  │    Agents      │  │  Self-Healing  │     │
│  │ • Stateful     │  │ • Auto-retry   │     │
│  │ • Memory       │  │ • Learning     │     │
│  │ • Tools        │  │ • Strategies   │     │
│  └────────────────┘  └────────────────┘     │
│                                               │
│  ┌────────────────┐  ┌────────────────┐     │
│  │      RAG       │  │     Memory     │     │
│  │ • Chunking     │  │ • Working      │     │
│  │ • Embedding    │  │ • Short-term   │     │
│  │ • Retrieval    │  │ • Long-term    │     │
│  │ • Reranking    │  │ • Episodic     │     │
│  └────────────────┘  └────────────────┘     │
│                                               │
│  ┌────────────────┐  ┌────────────────┐     │
│  │   Enterprise   │  │   Deployment   │     │
│  │ • Cost Mgmt    │  │ • REST API     │     │
│  │ • Resilience   │  │ • Dashboard    │     │
│  │ • Caching      │  │ • Monitoring   │     │
│  │ • Batching     │  │ • Health       │     │
│  └────────────────┘  └────────────────┘     │
│                                               │
└──────────────────────────────────────────────┘

Complete Feature List

Core Features (8)

✅ Fluent Builders - Type-safe method chaining
✅ Text Generation - Simple text completion
✅ Structured Output - JSON schema with validation
✅ Enhanced Streaming - Token-by-token with reasoning
✅ Multi-Modal - Images, audio, video processing
✅ Vision Analysis - OCR, object detection, comparison
✅ Audio Transcription - With timestamps
✅ Callbacks - Lifecycle hooks for all operations

Advanced Features (6)

✅ Stateful Agents - Persistent state and history
✅ Self-Healing - ML-based error recovery
✅ RAG Pipeline - Full retrieval-augmented generation
✅ Multi-Tier Memory - 4-level memory system
✅ Tool System - Dynamic discovery and execution
✅ DAG Workflows - Multi-agent orchestration

Enterprise Features (8)

✅ Cost Management - Budget tracking and optimization
✅ Circuit Breakers - Automatic failure isolation
✅ Retry Strategies - Exponential backoff
✅ Rate Limiting - Token bucket algorithm
✅ Semantic Caching - Vector similarity matching
✅ Batch Processing - Automatic batching
✅ Plugin System - Dynamic extensibility
✅ Observability - Tracing, profiling, debugging

Deployment Features (4)

✅ REST API Server - Optional HTTP endpoints
✅ Web Dashboard - Tailwind CSS UI
✅ Health Checks - Comprehensive monitoring
✅ Metrics - Prometheus-compatible

Quick Start

package main

import (
    "context"
    "fmt"
    "github.com/xraph/forge/extensions/ai/sdk"
)

func main() {
    result, err := sdk.NewGenerateBuilder(
        context.Background(),
        llmManager,
        logger,
        metrics,
    ).
        WithPrompt("Explain quantum computing").
        WithModel("gpt-4").
        WithTemperature(0.7).
        Execute()
    
    if err != nil {
        panic(err)
    }
    
    fmt.Println(result.Content)
}

type Person struct {
    Name    string   `json:"name"`
    Age     int      `json:"age"`
    Hobbies []string `json:"hobbies"`
}

person, err := sdk.NewGenerateObjectBuilder[Person](
    ctx, llmManager, logger, metrics,
).
    WithPrompt("Extract: John Doe, 30, loves reading").
    Execute()

fmt.Printf("%+v\n", person)
// Output: &{Name:John Doe Age:30 Hobbies:[reading]}

result, err := sdk.NewStreamBuilder(ctx, llmManager, logger, metrics).
    WithPrompt("Write a haiku about Go").
    WithReasoning(true).
    OnToken(func(token string) {
        fmt.Print(token)
    }).
    OnReasoning(func(step string) {
        fmt.Printf("[Thinking: %s]\n", step)
    }).
    Stream()

Integration with Forge

The SDK integrates seamlessly with Forge's DI container:

package main

import (
    "context"
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/ai"
    "github.com/xraph/forge/extensions/ai/sdk"
)

func main() {
    app := forge.NewApp()
    
    // Register AI extension
    app.RegisterExtension(ai.NewExtension())
    
    // Use SDK in handlers
    app.GET("/generate", func(c forge.Context) error {
        container := c.App().Container()
        
        llmManager, _ := container.Resolve("llmManager")
        logger, _ := container.Resolve("logger")
        metrics, _ := container.Resolve("metrics")
        
        result, err := sdk.NewGenerateBuilder(
            c.Context(),
            llmManager.(sdk.LLMManager),
            logger.(forge.Logger),
            metrics.(forge.Metrics),
        ).
            WithPrompt(c.Query("prompt")).
            Execute()
        
        if err != nil {
            return c.JSON(500, map[string]string{"error": err.Error()})
        }
        
        return c.JSON(200, result)
    })
    
    app.Start(context.Background())
}

Key Innovations

Self-Healing Agents

Automatically recovers from errors using machine learning:

healer := sdk.NewSelfHealingAgent(agent, sdk.SelfHealingConfig{
    MaxRetries:      3,
    AutoRecover:     true,
    EnableLearning:  true,
}, logger, metrics)

// Automatically retries with smart recovery strategies
response, _ := healer.Process(ctx, input)

Semantic Caching

Vector-based similarity matching for cache hits:

cache := sdk.NewSemanticCache(vectorStore, cacheStore, logger, metrics,
    sdk.SemanticCacheConfig{
        SimilarityThreshold: 0.95,
        TTL: 1 * time.Hour,
    },
)

// Returns cached results for similar queries
if entry, _ := cache.Get(ctx, query, embedding); entry != nil {
    return entry.Response // 95%+ similar - cache hit!
}

Multi-Tier Memory

4-level memory system with automatic consolidation:

memory := sdk.NewMemoryManager(vectorStore, logger, metrics,
    sdk.MemoryConfig{
        WorkingCapacity:   5,    // Working memory
        ShortTermTTL:      1h,   // Short-term memory
        LongTermThreshold: 0.8,  // Long-term importance
    },
)

// Automatically manages memory across tiers
memory.Store(ctx, memory)
memory.Promote(ctx, memoryID, sdk.LongTerm)

DAG Workflows

Multi-agent orchestration with dependencies:

workflow := sdk.NewWorkflowEngine(logger, metrics)

// Define workflow with dependencies
workflow.AddNode("research", researchAgent, nil)
workflow.AddNode("write", writeAgent, []string{"research"})
workflow.AddNode("review", reviewAgent, []string{"write"})

// Execute with automatic dependency resolution
result, _ := workflow.Execute(ctx, input)

Next Steps

Quickstart Guide

Get started with the SDK in 5 minutes

Builders

Master text, streaming, and structured generation

Multi-Modal

Process images, audio, and video with AI

Agents

Build autonomous agents with memory and tools

API Server

Deploy REST API and dashboard

Examples

View 20+ production-ready examples

Installation

go get github.com/xraph/forge/extensions/ai/sdk

AI SDK Overview