Integration Guide

Learn how the AI SDK integrates seamlessly with Forge's architecture.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                  Forge Application                       │
│  ┌───────────────────────────────────────────────────┐  │
│  │             DI Container                          │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐       │  │
│  │  │ Logger   │  │ Metrics  │  │ Router   │       │  │
│  │  └──────────┘  └──────────┘  └──────────┘       │  │
│  └───────────────────────────────────────────────────┘  │
│                        │                                 │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │           AI Extension                            │  │
│  │  ┌──────────────┐  ┌──────────────┐              │  │
│  │  │ LLM Manager  │  │ Agent Store  │              │  │
│  │  └──────────────┘  └──────────────┘              │  │
│  │         │                  │                      │  │
│  │         └──────────┬───────┘                      │  │
│  │                    ↓                              │  │
│  │         ┌──────────────────┐                      │  │
│  │         │   AI Manager     │                      │  │
│  │         └──────────────────┘                      │  │
│  └───────────────────────────────────────────────────┘  │
│                        │                                 │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │               AI SDK                              │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐       │  │
│  │  │ Builders │  │ Agents   │  │ RAG      │       │  │
│  │  └──────────┘  └──────────┘  └──────────┘       │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐       │  │
│  │  │ Memory   │  │ Tools    │  │ Workflow │       │  │
│  │  └──────────┘  └──────────┘  └──────────┘       │  │
│  └───────────────────────────────────────────────────┘  │
│                        │                                 │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │      SDK API Server (Optional)                    │  │
│  │  ┌──────────────┐  ┌──────────────┐              │  │
│  │  │ REST API     │  │ Dashboard    │              │  │
│  │  └──────────────┘  └──────────────┘              │  │
│  └───────────────────────────────────────────────────┘  │
│                        │                                 │
│                        ↓                                 │
│  ┌───────────────────────────────────────────────────┐  │
│  │         LLM Providers                             │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐       │  │
│  │  │ OpenAI   │  │ Anthropic│  │ Cohere   │       │  │
│  │  └──────────┘  └──────────┘  └──────────┘       │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Integration Points

DI Container

The SDK resolves dependencies from Forge's DI container:

func useSDK(c forge.Context) error {
    container := c.App().Container()
    
    // Resolve from DI container
    llmManager, _ := container.Resolve("llmManager")
    logger, _ := container.Resolve("logger")
    metrics, _ := container.Resolve("metrics")
    vectorStore, _ := container.Resolve("vectorStore")
    stateStore, _ := container.Resolve("stateStore")
    
    // Use SDK builders
    result, err := sdk.NewGenerateBuilder(
        c.Context(),
        llmManager.(sdk.LLMManager),
        logger.(forge.Logger),
        metrics.(forge.Metrics),
    ).WithPrompt("Hello").Execute()
    
    return c.JSON(200, result)
}

AI Extension Methods

Access SDK features through the AI extension:

func main() {
    app := forge.NewApp()
    
    // Register AI extension
    aiExt := ai.NewExtension()
    app.RegisterExtension(aiExt)
    
    // Access AI Manager (which uses SDK internally)
    app.GET("/agent/:id", func(c forge.Context) error {
        container := c.App().Container()
        aiManager, _ := container.Resolve("aiManager")
        
        // Get agent (uses SDK Agent internally)
        agent, err := aiManager.(*ai.Manager).GetAgent(c.Param("id"))
        if err != nil {
            return c.JSON(404, map[string]string{"error": "agent not found"})
        }
        
        return c.JSON(200, agent)
    })
    
    app.Start(context.Background())
}

Complete Integration Example

main.go

package main

import (
    "context"
    "encoding/base64"
    "io"
    "os"
    
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/ai"
    "github.com/xraph/forge/extensions/ai/sdk"
    "github.com/xraph/forge/extensions/ai/sdk/server"
)

func main() {
    // Create Forge app
    app := forge.NewApp()
    
    // Register AI extension
    aiExt := ai.NewExtension()
    app.RegisterExtension(aiExt)
    
    // Get router
    router := app.Router()
    container := app.Container()
    
    // Optional: Mount SDK API Server
    llmManager, _ := container.Resolve("llmManager")
    logger, _ := container.Resolve("logger")
    metrics, _ := container.Resolve("metrics")
    
    sdkServer := server.NewServer(
        llmManager.(sdk.LLMManager),
        logger.(forge.Logger),
        metrics.(forge.Metrics),
        server.ServerConfig{
            BasePath:       "/api/sdk",
            EnableAuth:     true,
            RateLimitRPS:   100,
        },
    )
    sdkServer.MountRoutes(router)
    
    // Optional: Mount Dashboard
    dashboard := server.NewDashboard(
        metrics.(forge.Metrics),
        logger.(forge.Logger),
    )
    dashboard.MountRoutes(router)
    
    // Custom handlers using SDK
    router.POST("/generate", handleGenerate(container))
    router.POST("/chat", handleChat(container))
    router.POST("/analyze-image", handleImageAnalysis(container))
    
    // Start application
    if err := app.Start(context.Background()); err != nil {
        panic(err)
    }
}

// Handler: Simple text generation
func handleGenerate(container forge.Container) forge.HandlerFunc {
    return func(c forge.Context) error {
        var req struct {
            Prompt      string  `json:"prompt"`
            Model       string  `json:"model"`
            Temperature float64 `json:"temperature"`
        }
        
        if err := c.BindJSON(&req); err != nil {
            return c.JSON(400, map[string]string{"error": err.Error()})
        }
        
        // Resolve dependencies
        llmManager, _ := container.Resolve("llmManager")
        logger, _ := container.Resolve("logger")
        metrics, _ := container.Resolve("metrics")
        
        // Use SDK
        result, err := sdk.NewGenerateBuilder(
            c.Context(),
            llmManager.(sdk.LLMManager),
            logger.(forge.Logger),
            metrics.(forge.Metrics),
        ).
            WithPrompt(req.Prompt).
            WithModel(req.Model).
            WithTemperature(req.Temperature).
            Execute()
        
        if err != nil {
            return c.JSON(500, map[string]string{"error": err.Error()})
        }
        
        return c.JSON(200, map[string]interface{}{
            "content": result.Content,
            "tokens":  result.Usage.TotalTokens,
            "model":   result.Model,
        })
    }
}

// Handler: Chat with agent
func handleChat(container forge.Container) forge.HandlerFunc {
    return func(c forge.Context) error {
        var req struct {
            AgentID string `json:"agent_id"`
            Message string `json:"message"`
        }
        
        if err := c.BindJSON(&req); err != nil {
            return c.JSON(400, map[string]string{"error": err.Error()})
        }
        
        // Resolve dependencies
        llmManager, _ := container.Resolve("llmManager")
        logger, _ := container.Resolve("logger")
        metrics, _ := container.Resolve("metrics")
        stateStore, _ := container.Resolve("stateStore")
        
        // Create agent
        agent := sdk.NewAgent(
            req.AgentID,
            llmManager.(sdk.LLMManager),
            logger.(forge.Logger),
            metrics.(forge.Metrics),
            &sdk.AgentOptions{
                Model:       "gpt-4",
                Temperature: 0.7,
                StateStore:  stateStore.(sdk.StateStore),
                MaxHistory:  50,
            },
        )
        
        // Execute
        result, err := agent.Execute(c.Context(), req.Message)
        if err != nil {
            return c.JSON(500, map[string]string{"error": err.Error()})
        }
        
        return c.JSON(200, map[string]interface{}{
            "response": result.Content,
            "tokens":   result.Usage.TotalTokens,
        })
    }
}

// Handler: Image analysis
func handleImageAnalysis(container forge.Container) forge.HandlerFunc {
    return func(c forge.Context) error {
        // Get image from form
        file, err := c.FormFile("image")
        if err != nil {
            return c.JSON(400, map[string]string{"error": "image required"})
        }
        
        src, _ := file.Open()
        defer src.Close()
        
        // Read image data
        data, _ := io.ReadAll(src)
        imageData := base64.StdEncoding.EncodeToString(data)
        
        // Resolve dependencies
        llmManager, _ := container.Resolve("llmManager")
        logger, _ := container.Resolve("logger")
        metrics, _ := container.Resolve("metrics")
        
        // Use multi-modal builder
        result, err := sdk.NewMultiModalBuilder(
            c.Context(),
            llmManager.(sdk.LLMManager),
            logger.(forge.Logger),
            metrics.(forge.Metrics),
        ).
            WithImage(imageData, "image/jpeg").
            WithText(c.FormValue("question")).
            WithModel("gpt-4-vision").
            Execute()
        
        if err != nil {
            return c.JSON(500, map[string]string{"error": err.Error()})
        }
        
        return c.JSON(200, map[string]interface{}{
            "analysis": result.Text,
            "tokens":   result.Usage.TotalTokens,
        })
    }
}

Available API Endpoints (After Integration)

SDK Direct Usage

Endpoint	Method	Description
`/generate`	POST	Custom text generation
`/chat`	POST	Chat with agents
`/analyze-image`	POST	Image analysis

SDK API Server (Optional)

Endpoint	Method	Description
`/api/sdk/generate`	POST	Text generation
`/api/sdk/generate/stream`	POST	Streaming generation
`/api/sdk/generate/object`	POST	Structured output
`/api/sdk/multimodal`	POST	Multi-modal processing
`/api/sdk/agents`	GET/POST	Agent management
`/api/sdk/rag`	POST	RAG queries
`/api/sdk/cost`	GET	Cost tracking
`/api/sdk/health`	GET	Health check
`/api/sdk/metrics`	GET	Prometheus metrics

Dashboard (Optional)

Endpoint	Description
`/dashboard`	Web UI for monitoring
`/dashboard/static/*`	Static assets

Configuration via Forge Config

config.yaml

extensions:
  ai:
    enabled: true
    providers:
      - name: openai
        type: openai
        api_key: ${OPENAI_API_KEY}
      - name: anthropic
        type: anthropic
        api_key: ${ANTHROPIC_API_KEY}
    
    sdk:
      # API Server (optional)
      api_server:
        enabled: true
        base_path: /api/sdk
        enable_auth: true
        rate_limit_rps: 100
      
      # Dashboard (optional)
      dashboard:
        enabled: true
        base_path: /dashboard
      
      # Caching
      caching:
        enabled: true
        semantic_threshold: 0.95
        ttl: 1h
      
      # Memory
      memory:
        working_capacity: 5
        short_term_ttl: 1h
        long_term_threshold: 0.8
      
      # Cost Management
      cost:
        tracking_enabled: true
        monthly_budget: 1000.00
        alert_threshold: 0.8
      
      # Resilience
      resilience:
        circuit_breaker:
          max_failures: 5
          reset_timeout: 60s
        retry:
          max_retries: 3
          initial_delay: 1s
        rate_limit:
          requests_per_second: 100

Integration Benefits

Unified Logging

All SDK operations use Forge's logger:

logger.Info("generating text", 
    "model", model,
    "tokens", tokens,
    "duration", duration,
)

Centralized Metrics

Metrics automatically flow to Prometheus:

metrics.Counter("ai.sdk.requests", "model", model).Inc()
metrics.Gauge("ai.sdk.tokens", "type", "total").Set(float64(tokens))
metrics.Histogram("ai.sdk.latency", "model", model).Observe(duration.Seconds())

Health Checks

SDK health integrates with Forge health system:

app.GET("/health", func(c forge.Context) error {
    health := map[string]interface{}{
        "status": "healthy",
        "sdk": map[string]interface{}{
            "models":  []string{"gpt-4", "claude-3-opus"},
            "agents":  activeAgents,
            "cache":   cacheHitRate,
        },
    }
    return c.JSON(200, health)
})

Middleware Support

SDK routes can use Forge middleware:

// Add auth middleware to SDK routes
router.Use(forge.WithMiddleware(authMiddleware))

Next Steps

Builders - Use all builder patterns
API Server - Deploy REST API
Dashboard - Monitor with web UI
Examples - View integration examples

Integration Guide

On this page