Provider Integration Guide

# config/agents.yaml
agents:
  - name: analyzer
    role: react
    model: gpt-4-turbo
    provider: openai
    api_key: ${OPENAI_API_KEY}
    temperature: 0.7
    max_tokens: 1000

export OPENAI_API_KEY=sk-...

import "github.com/aixgo-dev/aixgo/providers/openai"

agent := aixgo.NewAgent(
    aixgo.WithName("analyzer"),
    aixgo.WithModel("gpt-4-turbo"),
    aixgo.WithProvider(openai.Provider{
        APIKey: os.Getenv("OPENAI_API_KEY"),
    }),
)

agents:
  - name: analyst
    role: react
    model: claude-3-sonnet
    provider: anthropic
    api_key: ${ANTHROPIC_API_KEY}
    temperature: 0.5
    max_tokens: 2000

export ANTHROPIC_API_KEY=sk-ant-...

import "github.com/aixgo-dev/aixgo/providers/anthropic"

agent := aixgo.NewAgent(
    aixgo.WithName("analyst"),
    aixgo.WithModel("claude-3-sonnet"),
    aixgo.WithProvider(anthropic.Provider{
        APIKey: os.Getenv("ANTHROPIC_API_KEY"),
    }),
)

agents:
  - name: processor
    role: react
    model: gemini-1.5-flash
    provider: vertexai
    project_id: ${GCP_PROJECT_ID}
    location: us-central1
    temperature: 0.8

# Service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Or use gcloud default credentials
gcloud auth application-default login

import "github.com/aixgo-dev/aixgo/providers/vertexai"

agent := aixgo.NewAgent(
    aixgo.WithName("processor"),
    aixgo.WithModel("gemini-1.5-flash"),
    aixgo.WithProvider(vertexai.Provider{
        ProjectID: os.Getenv("GCP_PROJECT_ID"),
        Location:  "us-central1",
    }),
)

agents:
  - name: classifier
    role: react
    model: meta-llama/Llama-2-70b-chat-hf
    provider: huggingface
    api_key: ${HUGGINGFACE_API_KEY}
    endpoint: https://api-inference.huggingface.co

export HUGGINGFACE_API_KEY=hf_...

import "github.com/aixgo-dev/aixgo/providers/huggingface"

agent := aixgo.NewAgent(
    aixgo.WithName("classifier"),
    aixgo.WithModel("meta-llama/Llama-2-70b-chat-hf"),
    aixgo.WithProvider(huggingface.Provider{
        APIKey:   os.Getenv("HUGGINGFACE_API_KEY"),
        Endpoint: "https://api-inference.huggingface.co",
    }),
)

agents:
  - name: researcher
    role: react
    model: gpt-4-turbo
    provider: xai
    api_key: ${XAI_API_KEY}

export XAI_API_KEY=xai-...

agents:
  - name: resilient-analyzer
    role: react
    providers:
      - model: gpt-4-turbo
        provider: openai
        api_key: ${OPENAI_API_KEY}
      - model: claude-3-sonnet
        provider: anthropic
        api_key: ${ANTHROPIC_API_KEY}
      - model: gemini-1.5-flash
        provider: vertexai
        project_id: ${GCP_PROJECT_ID}
    fallback_strategy: cascade # Try each in order

# Simple tasks: cheap model
- name: simple-classifier
  role: react
  model: gpt-3.5-turbo
  provider: openai

# Complex reasoning: capable model
- name: complex-analyzer
  role: react
  model: gpt-4-turbo
  provider: openai

# US region: Vertex AI (low latency)
- name: us-agent
  role: react
  model: gemini-1.5-flash
  provider: vertexai
  location: us-central1

# EU region: OpenAI EU endpoint
- name: eu-agent
  role: react
  model: gpt-4-turbo
  provider: openai
  endpoint: https://api.openai.com/v1 # or EU-specific endpoint

Documents → Embeddings Service → Vector Database → Semantic Search

embeddings:
  provider: openai
  openai:
    api_key: ${OPENAI_API_KEY}
    model: text-embedding-3-small # or text-embedding-3-large

import "github.com/aixgo-dev/aixgo/pkg/embeddings"

config := embeddings.Config{
    Provider: "openai",
    OpenAI: &embeddings.OpenAIConfig{
        APIKey: os.Getenv("OPENAI_API_KEY"),
        Model:  "text-embedding-3-small",
    },
}

embSvc, err := embeddings.New(config)
if err != nil {
    log.Fatal(err)
}
defer embSvc.Close()

// Generate embedding
embedding, err := embSvc.Embed(ctx, "Your text here")

embeddings:
  provider: huggingface
  huggingface:
    model: sentence-transformers/all-MiniLM-L6-v2
    api_key: ${HUGGINGFACE_API_KEY} # Optional
    wait_for_model: true
    use_cache: true

docker run -d \
  --name tei \
  -p 8080:8080 \
  --gpus all \
  ghcr.io/huggingface/text-embeddings-inference:latest \
  --model-id BAAI/bge-large-en-v1.5

embeddings:
  provider: huggingface_tei
  huggingface_tei:
    endpoint: http://localhost:8080
    model: BAAI/bge-large-en-v1.5
    normalize: true

# Enable Firestore
gcloud services enable firestore.googleapis.com

# Create vector index
gcloud firestore indexes composite create \
  --collection-group=embeddings \
  --query-scope=COLLECTION \
  --field-config=field-path=embedding,vector-config='{"dimension":"384","flat":{}}'

vectorstore:
  provider: firestore
  embedding_dimensions: 384
  firestore:
    project_id: ${GCP_PROJECT_ID}
    collection: embeddings
    credentials_file: /path/to/key.json # Optional

import "github.com/aixgo-dev/aixgo/pkg/vectorstore"

config := vectorstore.Config{
    Provider:            "firestore",
    EmbeddingDimensions: 384,
    Firestore: &vectorstore.FirestoreConfig{
        ProjectID:  os.Getenv("GCP_PROJECT_ID"),
        Collection: "embeddings",
    },
}

store, err := vectorstore.New(config)
if err != nil {
    log.Fatal(err)
}
defer store.Close()

// Upsert documents
doc := vectorstore.Document{
    ID:        "doc-1",
    Content:   "Your document content",
    Embedding: embedding,
    Metadata: map[string]interface{}{
        "category": "documentation",
    },
}
store.Upsert(ctx, []vectorstore.Document{doc})

// Search
results, err := store.Search(ctx, vectorstore.SearchQuery{
    Embedding: queryEmbedding,
    TopK:      5,
    MinScore:  0.7,
})

vectorstore:
  provider: memory
  embedding_dimensions: 384
  memory:
    max_documents: 10000

# Coming soon
vectorstore:
  provider: qdrant
  embedding_dimensions: 384
  qdrant:
    host: localhost
    port: 6333
    collection: knowledge_base

# Coming soon
vectorstore:
  provider: pgvector
  embedding_dimensions: 384
  pgvector:
    connection_string: postgresql://user:pass@localhost/db
    table: embeddings

package main

import (
    "context"
    "log"

    "github.com/aixgo-dev/aixgo/pkg/embeddings"
    "github.com/aixgo-dev/aixgo/pkg/vectorstore"
)

func main() {
    ctx := context.Background()

    // Setup embeddings
    embConfig := embeddings.Config{
        Provider: "huggingface",
        HuggingFace: &embeddings.HuggingFaceConfig{
            Model: "sentence-transformers/all-MiniLM-L6-v2",
        },
    }
    embSvc, _ := embeddings.New(embConfig)
    defer embSvc.Close()

    // Setup vector store
    storeConfig := vectorstore.Config{
        Provider:            "firestore",
        EmbeddingDimensions: embSvc.Dimensions(),
        Firestore: &vectorstore.FirestoreConfig{
            ProjectID:  "my-project",
            Collection: "knowledge_base",
        },
    }
    store, _ := vectorstore.New(storeConfig)
    defer store.Close()

    // Index documents
    docs := []string{
        "Aixgo is a production-grade AI framework",
        "RAG combines retrieval with generation",
    }

    for i, content := range docs {
        emb, _ := embSvc.Embed(ctx, content)
        doc := vectorstore.Document{
            ID:        fmt.Sprintf("doc-%d", i),
            Content:   content,
            Embedding: emb,
        }
        store.Upsert(ctx, []vectorstore.Document{doc})
    }

    // Search
    query := "What is Aixgo?"
    queryEmb, _ := embSvc.Embed(ctx, query)
    results, _ := store.Search(ctx, vectorstore.SearchQuery{
        Embedding: queryEmb,
        TopK:      3,
    })

    for _, result := range results {
        fmt.Printf("Score: %.2f - %s\n", result.Score, result.Document.Content)
    }
}

# .env file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GCP_PROJECT_ID=my-project
HUGGINGFACE_API_KEY=hf_...

export $(cat .env | xargs)

kubectl create secret generic llm-keys \
  --from-literal=OPENAI_API_KEY=sk-... \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-...

env:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: llm-keys
        key: OPENAI_API_KEY

import "cloud.google.com/go/secretmanager/apiv1"

func getAPIKey(ctx context.Context, secretName string) (string, error) {
    client, _ := secretmanager.NewClient(ctx)
    result, _ := client.AccessSecretVersion(ctx, &secretmanagerpb.AccessSecretVersionRequest{
        Name: secretName,
    })
    return string(result.Payload.Data), nil
}

agents:
  - name: resilient-agent
    role: react
    model: gpt-4-turbo
    provider: openai
    retry:
      max_attempts: 3
      initial_backoff: 1s
      max_backoff: 10s
      multiplier: 2
      retry_on:
        - rate_limit
        - timeout
        - server_error

import "github.com/prometheus/client_golang/prometheus"

var providerLatency = prometheus.NewHistogramVec(
    prometheus.HistogramOpts{
        Name: "llm_provider_latency_seconds",
        Help: "LLM API call latency by provider",
    },
    []string{"provider", "model"},
)

// Aixgo tracks this automatically

observability:
  cost_tracking: true
  cost_alert_threshold: 100 # Alert if daily cost > $100

# Development
OPENAI_API_KEY=sk-dev-...

# Production
OPENAI_API_KEY=sk-prod-...

observability:
  llm_observability:
    enabled: true
    track_tokens: true
    daily_token_limit: 1000000

import "github.com/aixgo-dev/aixgo/cache"

agent := aixgo.NewAgent(
    aixgo.WithName("cached-analyzer"),
    aixgo.WithCache(cache.NewRedisCache("localhost:6379")),
    aixgo.WithCacheTTL(1 * time.Hour),
)

agents:
  - name: patient-agent
    role: react
    model: gpt-4-turbo
    timeout: 60s # Increase timeout