ai

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 23 Imported by: 0

README

AI SDK Plugin for Nimbus

A comprehensive AI backend framework for Go — providing unified abstractions for text generation, streaming, embeddings, agents, RAG, structured output, workflows, image/video generation, and observability.

Inspired by Laravel AI SDK, Vercel AI SDK, and LangChain — but Go-native and framework-integrated.

Installation

go get github.com/CodeSyncr/nimbus/plugins/ai

Add the plugin in your bin/server.go:

app := nimbus.New()
app.Use(ai.New())

Configuration

AI_PROVIDER=openai       # openai | anthropic | gemini | mistral | cohere | xai | ollama
AI_MODEL=gpt-4o
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
Variable Description Default
AI_PROVIDER Provider backend openai
AI_MODEL Default model gpt-4o
OPENAI_API_KEY OpenAI API key required for OpenAI
ANTHROPIC_API_KEY Anthropic API key required for Anthropic
GEMINI_API_KEY Google Gemini API key required for Gemini
MISTRAL_API_KEY Mistral API key required for Mistral
COHERE_API_KEY Cohere API key required for Cohere
XAI_API_KEY xAI Grok API key required for xAI
OLLAMA_HOST Ollama server URL http://localhost:11434

Core API

Text Generation
response, err := ai.Generate(ctx, "Explain quantum computing")
fmt.Println(response.Text)
fmt.Println(response.Usage.TotalTokens)
Streaming
textCh, errCh := ai.Stream(ctx, "Write a haiku about Go")
for text := range textCh {
    fmt.Print(text)
}
if err := <-errCh; err != nil {
    log.Fatal(err)
}
Options
resp, err := ai.Generate(ctx, "Hello",
    ai.WithModel("gpt-4o-mini"),
    ai.WithMaxTokens(500),
    ai.WithTemperature(0.7),
    ai.WithSystem("You are a pirate."),
)

Structured Output (Extract)

Extract typed Go structs from unstructured text:

type Invoice struct {
    Merchant string
    Amount   float64
    Date     string
}

invoice, err := ai.Extract[Invoice](ctx, receiptText)
// invoice.Merchant = "Starbucks"
// invoice.Amount = 5.50

Extract slices:

items, err := ai.ExtractSlice[LineItem](ctx, invoiceText)

Classify text:

label, err := ai.Classify(ctx, "I love this product!", []string{"positive", "negative", "neutral"})
// label = "positive"

Agents

Agents combine instructions, tools, memory, and a reasoning loop:

agent := ai.NewAgent("You are a Go programming expert").
    WithTools("weather", "calculator").
    MaxSteps(10)

response, err := agent.Prompt(ctx, "What's the weather in NYC and what's 42 * 73?")
Streaming agent
stream, err := agent.Stream(ctx, "Write a detailed explanation of Go channels")
for chunk := range stream.Chunks {
    fmt.Print(chunk.Text)
}
Agent with memory
agent := ai.NewAgent("You are a helpful assistant").
    WithMemory(ai.MemoryStore(), "session:user123")

// Conversation persists across calls:
agent.Prompt(ctx, "My name is Alice")
agent.Prompt(ctx, "What's my name?") // "Your name is Alice"

Tools (Function Calling)

Register Go functions that agents can call:

type WeatherInput struct {
    City string `description:"City name"`
}
type WeatherOutput struct {
    Temp    int
    Summary string
}

ai.RegisterTool(ai.Tool{
    Name:        "weather",
    Description: "Get current weather for a city",
    Run: func(ctx context.Context, in WeatherInput) (WeatherOutput, error) {
        return WeatherOutput{Temp: 72, Summary: "Sunny"}, nil
    },
})

Fluent builder:

ai.NewTool("calculator").
    Desc("Evaluate a math expression").
    Handler(func(ctx context.Context, in CalcInput) (CalcOutput, error) { ... }).
    Register()

Embeddings

vector, err := ai.Embed(ctx, "hello world")

// Batch
resp, err := ai.EmbedBatch(ctx, []string{"hello", "world"})

// Similarity
score := ai.CosineSimilarity(vecA, vecB)

Vector Store

store := ai.VectorStoreInstance("knowledge")

store.Add(ctx, "doc1", "How Go channels work")
store.Add(ctx, "doc2", "Go concurrency patterns")

results, err := store.Search(ctx, "goroutines", 5)
for _, doc := range results {
    fmt.Printf("[%.2f] %s: %s\n", doc.Score, doc.ID, doc.Text)
}

Backends: in-memory (built-in), pgvector, Qdrant, Redis (bring your own VectorStoreBackend).

RAG (Retrieval-Augmented Generation)

rag := ai.NewRAG(store).
    TopK(5).
    MinScore(0.7).
    WithCitations(true)

answer, err := rag.Ask(ctx, "Explain Go concurrency")
fmt.Println(answer.Answer)
fmt.Println(answer.Sources) // source documents

Streaming RAG:

stream, sources, err := rag.AskStream(ctx, "How do goroutines work?")

Prompt Templates

prompt := ai.Template("Summarize the following:\n\n{{.text}}")
resp, err := prompt.Generate(ctx, map[string]any{"text": article})

Few-shot prompting:

classifier := ai.FewShot("Classify the sentiment of the text.").
    Add("I love this!", "positive").
    Add("This is terrible.", "negative")

resp, err := classifier.Generate(ctx, "The product is okay I guess.")

Composable chains:

resp, err := ai.Chain(
    ai.SystemTemplate("You are a {{.role}} expert."),
    ai.Template("Explain {{.topic}}."),
).Generate(ctx, map[string]any{"role": "Go", "topic": "channels"})

Workflows (Multi-Step Pipelines)

wf := ai.NewWorkflow("content").
    Step("outline", generateOutline).
    Step("draft", writeDraft).
    Parallel("media",
        ai.StepFunc("images", genImages),
        ai.StepFunc("audio", genAudio),
    ).
    Step("final", finalize)

result, err := wf.Run(ctx, ai.WorkflowInput{"topic": "Go concurrency"})

Conditional branching:

wf.Branch("route", func(wc *ai.WorkflowContext) string {
    if wc.GetString("quality") == "low" { return "rewrite" }
    return "publish"
}, map[string]ai.StepHandler{
    "rewrite": rewriteStep,
    "publish": publishStep,
})

Image Generation

img, err := ai.Image().
    Model("dall-e-3").
    Prompt("cyberpunk city at night").
    Size("1024x1024").
    Generate(ctx)

Video Generation

video, err := ai.Video().
    Model("kling-2.5").
    Prompt("camera pans over mountains").
    Duration(5).
    Generate(ctx)

Document Processing

// Summarize (auto map-reduce for long texts)
summary, err := ai.Summarize(ctx, longText, ai.SummarizeStyle("bullet-points"))

// Chunk text for ingestion
chunks := ai.ChunkText(text, ai.ChunkSize(500), ai.ChunkOverlap(50))

// Batch ingest into vector store
ai.IngestDocuments(ctx, store, map[string]string{
    "doc1": text1,
    "doc2": text2,
})

// Q&A over a single document
qa := ai.DocumentQA(contractText)
answer, err := qa.Ask(ctx, "What are the payment terms?")

Guardrails

g := ai.NewGuardrails().
    MaxLength(5000).
    BlockPatterns(`(?i)password`, `\b\d{16}\b`).
    SetContentFilter(ai.FilterPII).
    CustomCheck(func(output string) error {
        if strings.Contains(output, "TODO") {
            return fmt.Errorf("output contains TODO")
        }
        return nil
    })

resp, err := ai.Generate(ctx, prompt)
if err := g.Validate(resp.Text); err != nil {
    // response violated guardrails
}

Observability

// Log every request
ai.OnRequest(func(e ai.RequestEvent) {
    log.Printf("model=%s tokens=%d latency=%s", e.Model, e.Usage.TotalTokens, e.Latency)
})

// Track errors
ai.OnError(func(e ai.RequestEvent) {
    sentry.CaptureException(e.Error)
})

// Get aggregate metrics
metrics := ai.GetMetrics()
fmt.Println(ai.UsageReport())

Memory

Backend Constructor Use Case
In-memory ai.MemoryStore() Dev/testing
Redis ai.RedisMemory(rdb) Production, multi-instance
Database ai.DatabaseMemory(db) Persistent, auditable
Sliding window ai.SlidingWindowMemory(inner, 50) Keep last N messages
Summary ai.SummaryMemory(inner, 100) Auto-compress old messages
Redis Memory
import "github.com/redis/go-redis/v9"

rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
mem := ai.RedisMemory(rdb,
    ai.WithRedisPrefix("myapp:ai:"),
    ai.WithRedisTTL(24 * time.Hour),
)
agent := ai.NewAgent("You are a helpful assistant").
    WithMemory(mem, "session:user123")
Database Memory (GORM)
mem := ai.DatabaseMemory(db) // auto-creates ai_conversations table
agent := ai.NewAgent("You are a helpful assistant").
    WithMemory(mem, "session:user123")

Vector Store Backends

Backend Constructor Use Case
In-memory ai.NewMemoryVectorStore() Dev/testing
pgvector ai.NewPgvectorStore(db) PostgreSQL production
Qdrant ai.NewQdrantStore(url, collection) Dedicated vector DB
Pinecone ai.NewPineconeStore(host, apiKey) Managed cloud
pgvector (PostgreSQL)
import "gorm.io/driver/postgres"

db, _ := gorm.Open(postgres.Open(dsn), &gorm.Config{})
backend := ai.NewPgvectorStore(db,
    ai.WithPgvectorTable("embeddings"),
    ai.WithPgvectorDimension(1536),
)
store := ai.VectorStoreInstance("knowledge", backend)
Qdrant
backend := ai.NewQdrantStore("http://localhost:6333", "documents",
    ai.WithQdrantDimension(1536),
)
store := ai.VectorStoreInstance("knowledge", backend)
Pinecone
backend := ai.NewPineconeStore(
    "https://my-index-xxx.svc.xxx.pinecone.io",
    os.Getenv("PINECONE_API_KEY"),
    ai.WithPineconeNamespace("production"),
)
store := ai.VectorStoreInstance("knowledge", backend)

Tracing (OpenTelemetry)

// Enable tracing — auto-instruments all AI operations
ai.EnableTracing(ai.TracingConfig{
    ServiceName:     "my-app",
    RecordPrompts:   false, // disable in prod for privacy
    RecordResponses: false,
})

// Add exporters
ai.AddSpanExporter(&ai.LogExporter{})          // dev: print to console
ai.AddSpanExporter(&ai.OTLPExporter{           // prod: send to collector
    Endpoint: "http://localhost:4318/v1/traces",
})

// Inspect recent spans
spans := ai.GetTraceSpans(10)

// Propagate trace context
ctx = ai.WithTraceContext(ctx, ai.TraceContext{TraceID: "abc123"})

Cost Tracking

// Enable cost tracking with budget alerts
ai.EnableCostTracking(ai.CostConfig{
    MonthlyBudget: 500.00,
    AlertThresholds: []float64{50, 75, 90, 100},
    OnBudgetAlert: func(usage ai.CostSummary) {
        log.Printf("⚠️ AI budget at %.0f%% ($%.2f / $%.2f)",
            usage.BudgetPercent, usage.TotalCost, usage.MonthlyBudget)
    },
})

// Get dashboard data (JSON-serializable)
dashboard := ai.GetCostDashboard()

// Per-model and per-provider breakdowns
for _, m := range dashboard.CostByModel {
    fmt.Printf("%s: %d reqs, $%.4f\n", m.Model, m.Requests, m.TotalCost)
}

// Formatted report
fmt.Println(ai.CostReport())

// Set custom pricing for fine-tuned models
ai.SetModelPricing("ft:gpt-4o-mini:my-org", ai.ModelPricing{
    PromptPer1K: 0.0003, CompletionPer1K: 0.0012,
})

Model Evaluation & Benchmarking

// Define a test suite
suite := ai.NewEvalSuite("qa-quality").
    AddCase("greeting", "Say hello in a friendly way",
        ai.ExpectContains("hello"),
        ai.ExpectMinLength(10),
    ).
    AddCase("math", "What is 15 * 23?",
        ai.ExpectContains("345"),
    ).
    AddCase("json_output", "Return a JSON object with name and age",
        ai.ExpectJSON(),
    ).
    AddCaseWithSystem("role", "You are a pirate", "Introduce yourself",
        ai.ExpectContains("arr"),
    )

// Run against default model
report := suite.Run(ctx)
fmt.Println(report.Summary())

// Compare multiple models
comparison := ai.CompareModels(ctx, suite,
    "gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022",
)
fmt.Println(comparison.Summary())

// Use LLM-as-judge for subjective quality
suite.AddCase("creative", "Write a haiku about Go",
    ai.LLMJudge("creativity and adherence to haiku format"),
    ai.ExpectMinLength(10),
)

// Custom scoring function
suite.AddCase("format", "List 3 items",
    ai.CustomCheck("has_list", func(resp string) (float64, string) {
        lines := strings.Split(resp, "\n")
        if len(lines) >= 3 { return 1.0, "has 3+ lines" }
        return float64(len(lines)) / 3.0, fmt.Sprintf("only %d lines", len(lines))
    }),
)

HTTP Middleware

// Rate-limit AI endpoints
router.Use(ai.RateLimit(10, time.Second))

// Guard against cost overruns
router.Use(ai.CostGuard(100000)) // max 100K tokens per request

// Request logging
router.Use(ai.Logger())

Architecture

plugins/ai/
├── types.go               # Core types: Message, Request/Response, StreamChunk, Usage
├── providers.go           # Provider interface, registry, factory pattern
├── adapter.go             # Legacy provider adapters
├── client_v2.go           # Client with observability, guardrails
├── config.go              # Configuration
├── plugin.go              # Nimbus plugin integration
│
├── agent_v2.go            # Agent runtime with tool loops, memory, streaming
├── memory.go              # In-memory, sliding window, summary memory
├── memory_redis.go        # Redis + GORM database memory backends
├── tool.go                # Tool system (registration, schema gen, execution)
│
├── extract.go             # Structured output: Extract[T], ExtractSlice[T], Classify
├── template.go            # Prompt templates, chains, few-shot
├── document.go            # Document processing: chunking, summarization, Q&A
│
├── embed.go               # Embedding facade
├── vectorstore.go         # Vector store abstraction + in-memory backend
├── vectorstore_pgvector.go # pgvector backend (PostgreSQL)
├── vectorstore_qdrant.go  # Qdrant backend
├── vectorstore_pinecone.go # Pinecone backend
├── rag.go                 # RAG engine
│
├── workflow.go            # Multi-step workflow engine
├── image.go               # Image generation builder
├── video.go               # Video generation builder
│
├── middleware.go          # HTTP middleware + observability hooks + metrics
├── guardrails.go          # Output validation guardrails
├── tracing.go             # OpenTelemetry tracing integration
├── cost.go                # Cost tracking dashboard
├── eval.go                # Model evaluation & benchmarking
│
├── openai.go              # OpenAI provider
├── anthropic.go           # Anthropic provider
├── gemini.go              # Gemini provider
├── mistral.go             # Mistral provider
├── cohere.go              # Cohere provider
├── ollama.go              # Ollama provider
└── xai.go                 # xAI provider (OpenAI-compatible)

Extending with Custom Providers

func init() {
    ai.RegisterProvider("my-provider", func(cfg *ai.Config) (ai.Provider, error) {
        return &myProvider{}, nil
    })
}

type myProvider struct{}

func (p *myProvider) Name() string { return "my-provider" }
func (p *myProvider) Generate(ctx context.Context, req *ai.GenerateRequest) (*ai.GenerateResponse, error) { ... }
func (p *myProvider) Stream(ctx context.Context, req *ai.GenerateRequest) (*ai.StreamResponse, error) { ... }

// Optional: implement ai.EmbeddingProvider, ai.ImageProvider, ai.VideoProvider

Providers

Provider Generate Stream Embeddings Image
OpenAI ✅ ✅ ✅ ✅
xAI (Grok) ✅ ✅ — —
Ollama ✅ ✅ — —
Anthropic ✅ ✅ — —
Gemini ✅ ✅ — —
Mistral ✅ ✅ — —
Cohere ✅ ✅ — —

Roadmap

  • Structured output (Extract)
  • Tool/function calling
  • Agents with reasoning loops
  • Embeddings & vector store
  • RAG engine
  • Prompt templates & chains
  • Multi-step workflows
  • Image & video generation
  • Observability & metrics
  • Guardrails
  • Agent memory
  • Document processing
  • MCP (Model Context Protocol) — see plugins/mcp
  • Redis/database-backed memory
  • pgvector / Qdrant / Pinecone backends
  • OpenTelemetry tracing integration
  • Cost tracking dashboard
  • Model evaluation & benchmarking
  • Multi-modal (vision, audio) support
  • Fine-tuning management API
  • A/B testing for prompts
  • Prompt versioning & registry

Documentation

Index

Constants

View Source 
const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

Role constants for chat messages.

Variables

View Source 
var (
	FormatTikTok    = OutputFormat{Name: "tiktok", Width: 1080, Height: 1920, Aspect: "9:16"}
	FormatInstagram = OutputFormat{Name: "instagram_reel", Width: 1080, Height: 1920, Aspect: "9:16"}
	FormatYouTube   = OutputFormat{Name: "youtube_short", Width: 1080, Height: 1920, Aspect: "9:16"}
	FormatSquare    = OutputFormat{Name: "square", Width: 1080, Height: 1080, Aspect: "1:1"}
	FormatWide      = OutputFormat{Name: "wide", Width: 1920, Height: 1080, Aspect: "16:9"}
	FormatCinematic = OutputFormat{Name: "cinematic", Width: 1920, Height: 816, Aspect: "2.35:1"}
)

Pre-defined social-media output formats.

View Source 
var DefaultPricing = map[string]ModelPricing{

	"gpt-4o":        {PromptPer1K: 0.0025, CompletionPer1K: 0.010},
	"gpt-4o-mini":   {PromptPer1K: 0.00015, CompletionPer1K: 0.0006},
	"gpt-4-turbo":   {PromptPer1K: 0.010, CompletionPer1K: 0.030},
	"gpt-4":         {PromptPer1K: 0.030, CompletionPer1K: 0.060},
	"gpt-3.5-turbo": {PromptPer1K: 0.0005, CompletionPer1K: 0.0015},
	"o1":            {PromptPer1K: 0.015, CompletionPer1K: 0.060},
	"o1-mini":       {PromptPer1K: 0.003, CompletionPer1K: 0.012},
	"o3-mini":       {PromptPer1K: 0.0011, CompletionPer1K: 0.0044},

	"claude-3-5-sonnet-20241022": {PromptPer1K: 0.003, CompletionPer1K: 0.015},
	"claude-3-5-haiku-20241022":  {PromptPer1K: 0.0008, CompletionPer1K: 0.004},
	"claude-3-opus-20240229":     {PromptPer1K: 0.015, CompletionPer1K: 0.075},
	"claude-sonnet-4-20250514":   {PromptPer1K: 0.003, CompletionPer1K: 0.015},
	"claude-opus-4-20250514":     {PromptPer1K: 0.015, CompletionPer1K: 0.075},

	"gemini-2.0-flash": {PromptPer1K: 0.0001, CompletionPer1K: 0.0004},
	"gemini-1.5-pro":   {PromptPer1K: 0.00125, CompletionPer1K: 0.005},
	"gemini-1.5-flash": {PromptPer1K: 0.000075, CompletionPer1K: 0.0003},

	"mistral-large-latest": {PromptPer1K: 0.002, CompletionPer1K: 0.006},
	"mistral-small-latest": {PromptPer1K: 0.0002, CompletionPer1K: 0.0006},

	"command-r-plus": {PromptPer1K: 0.003, CompletionPer1K: 0.015},
	"command-r":      {PromptPer1K: 0.0005, CompletionPer1K: 0.0015},

	"grok-2":      {PromptPer1K: 0.002, CompletionPer1K: 0.010},
	"grok-2-mini": {PromptPer1K: 0.0002, CompletionPer1K: 0.001},

	"_default": {PromptPer1K: 0.001, CompletionPer1K: 0.002},
}

DefaultPricing is the built-in pricing table (USD per 1K tokens). Override or extend with SetModelPricing.

View Source 
var ExportFormats = map[string]OutputFormat{
	"tiktok":    FormatTikTok,
	"instagram": FormatInstagram,
	"youtube":   FormatYouTube,
	"square":    FormatSquare,
	"wide":      FormatWide,
	"cinematic": FormatCinematic,
}

ExportFormats defines the standard social media output set.

Functions

func AddSpanExporter 

func AddSpanExporter(exp SpanExporter)

AddSpanExporter registers an exporter that receives completed spans. Use this to send spans to Jaeger, OTLP, Zipkin, etc.

func AllProviders 

func AllProviders() []string

AllProviders returns all registered provider names.

func ChunkText 

func ChunkText(text string, opts ...ChunkOption) []string

ChunkText splits text into chunks of roughly equal size.

func Classify 

func Classify(ctx context.Context, text string, labels []string, opts ...ExtractOption) (string, error)

Classify asks the model to choose one of the given labels for the text.

func CosineSimilarity 

func CosineSimilarity(a, b []float32) float32

CosineSimilarity computes the cosine similarity between two vectors. Returns a value in [-1, 1]; higher = more similar.

func CostGuard 

func CostGuard(maxCostUSD float64) httpMiddleware

CostGuard returns middleware that blocks requests when estimated cost exceeds the budget. Uses a simple token-cost model.

func CostReport 

func CostReport() string

CostReport returns a formatted cost report string.

func Embed 

func Embed(ctx context.Context, text string, opts ...GenerateOption) ([]float32, error)

Embed generates a vector embedding for a single text input.

func EmitRequestEvent 

func EmitRequestEvent(e RequestEvent)

EmitRequestEvent fires all registered hooks for a request event. Called internally by the client after each API call.

func EnableCostTracking 

func EnableCostTracking(cfg CostConfig)

EnableCostTracking activates cost tracking with the given config.

func EnableTracing 

func EnableTracing(cfg TracingConfig)

EnableTracing activates OpenTelemetry-compatible tracing for all AI operations. Installs observability hooks that generate spans.

func ExecuteTool 

func ExecuteTool(ctx context.Context, name string, args json.RawMessage) (json.RawMessage, error)

ExecuteTool finds and runs a tool by name with raw JSON arguments.

func Extract 

func Extract[T any](ctx context.Context, text string, opts ...ExtractOption) (*T, error)

Extract asks the AI model to extract structured data from text and return it as a typed Go value. Uses JSON schema to constrain the model's output and retries on parse failure.

func ExtractSlice 

func ExtractSlice[T any](ctx context.Context, text string, opts ...ExtractOption) ([]T, error)

ExtractSlice extracts multiple items of the given type from text.

func GenerateConcatFileContent 

func GenerateConcatFileContent(scenes []Scene) string

GenerateConcatFileContent returns the FFmpeg concat file content.

func GenerateFFmpegResizeCommand 

func GenerateFFmpegResizeCommand(inputPath string, format OutputFormat, outputPath string) []string

GenerateFFmpegResizeCommand generates an FFmpeg command to re-scale a video to a different output format.

func GenerateStitchCommand 

func GenerateStitchCommand(scenes []Scene, cfg StitchConfig) []string

GenerateStitchCommand builds an FFmpeg concat command for the scenes.

func GetTotalCost 

func GetTotalCost() float64

GetTotalCost returns the current total cost.

func IngestDocuments 

func IngestDocuments(ctx context.Context, store *Store, documents map[string]string, opts ...ChunkOption) error

IngestDocuments chunks and embeds a collection of texts into a vector store.

func IsConfigured 

func IsConfigured() bool

IsConfigured returns true if the global client is set.

func Logger 

func Logger() httpMiddleware

Logger returns middleware that logs AI requests.

func OnCompletion 

func OnCompletion(h RequestHook)

OnCompletion registers a hook called on successful completion.

func OnError 

func OnError(h RequestHook)

OnError registers a hook called when an AI request fails.

func OnRequest 

func OnRequest(h RequestHook)

OnRequest registers a hook called for every AI API request.

func RateLimit 

func RateLimit(maxRequests int, window time.Duration) httpMiddleware

RateLimit returns middleware that limits AI requests per window.

func RegisterProvider 

func RegisterProvider(name string, factory ProviderFactory)

RegisterProvider makes a provider available by name. Call from init() in each provider file (e.g. openai.go, ollama.go).

func RegisterTool 

func RegisterTool(t Tool)

RegisterTool adds a tool to the global registry. It validates the handler signature and pre-computes the input JSON schema.

func ResetCosts 

func ResetCosts()

ResetCosts resets all cost tracking counters (e.g., monthly reset).

func SetModelPricing 

func SetModelPricing(model string, pricing ModelPricing)

SetModelPricing sets or updates pricing for a model.

func Stream 

func Stream(ctx context.Context, prompt string, opts ...GenerateOption) (<-chan string, <-chan error)

Stream is a convenience that uses the global client.

func Summarize 

func Summarize(ctx context.Context, text string, opts ...SummarizeOption) (string, error)

Summarize generates a summary of the given text. For long texts, it uses a map-reduce approach: chunk → summarize each → combine.

func UsageReport 

func UsageReport() string

UsageReport returns a formatted string of current AI usage metrics.

func WithTraceContext 

func WithTraceContext(ctx context.Context, tc TraceContext) context.Context

WithTraceContext adds trace context to a Go context for propagation.

Types

type Agent 

type Agent struct {
	// contains filtered or unexported fields
}

Agent is an AI entity with instructions, tools, and optional conversational memory.

func NewAgent 

func NewAgent(instructions string) *Agent

NewAgent creates an agent with system instructions.

func (*Agent) MaxSteps 

func (a *Agent) MaxSteps(n int) *Agent

MaxSteps limits the number of tool-call → result round-trips.

func (*Agent) OnStep 

func (a *Agent) OnStep(h AgentHook) *Agent

OnStep registers a hook called at each reasoning step.

func (*Agent) Prompt 

func (a *Agent) Prompt(ctx context.Context, userMessage string, opts ...GenerateOption) (*GenerateResponse, error)

Prompt sends a user message and runs the full reasoning loop (tool-call → execute → feed-back) until the model produces a text answer or maxSteps is exhausted.

func (*Agent) Stream 

func (a *Agent) Stream(ctx context.Context, userMessage string, opts ...GenerateOption) (*StreamResponse, error)

Stream runs the agent loop but streams the final text response. Intermediate tool-call steps are executed internally; only the final answer is streamed to the caller.

func (*Agent) WithClient 

func (a *Agent) WithClient(c *Client) *Agent

WithClient overrides the default global client.

func (*Agent) WithMemory 

func (a *Agent) WithMemory(m Memory, key string) *Agent

WithMemory enables persistent memory backed by the given Memory implementation. The key scopes the conversation (e.g. session ID).

func (*Agent) WithMessages 

func (a *Agent) WithMessages(msgs []Message) *Agent

WithMessages sets initial conversation history directly.

func (*Agent) WithModel 

func (a *Agent) WithModel(model string) *Agent

WithModel overrides the provider's default model for this agent.

func (*Agent) WithToolObjects 

func (a *Agent) WithToolObjects(tools ...*Tool) *Agent

WithToolObjects attaches tool instances directly.

func (*Agent) WithTools 

func (a *Agent) WithTools(names ...string) *Agent

WithTools attaches named tools (from the global registry).

type AgentHook 

type AgentHook func(step int, msg Message)

AgentHook is called at each step of the agent's reasoning loop.

type CameraMove 

type CameraMove string

CameraMove is a prompt modifier for camera motion. 

const (
	CameraDolly    CameraMove = "slow cinematic dolly in"
	CameraOrbit    CameraMove = "smooth orbit around subject"
	CameraPan      CameraMove = "slow horizontal pan"
	CameraDrone    CameraMove = "aerial drone flyover"
	CameraHandheld CameraMove = "handheld camera movement with subtle shake"
	CameraMacro    CameraMove = "extreme macro close-up with rack focus"
	CameraZoomIn   CameraMove = "slow cinematic zoom in"
	CameraZoomOut  CameraMove = "slow cinematic zoom out"
	CameraStatic   CameraMove = "locked off static shot"
	CameraCrane    CameraMove = "crane up reveal"
	CameraTracking CameraMove = "tracking shot following subject"
)

type ChunkOption 

type ChunkOption func(*chunkConfig)

ChunkOption configures text chunking.

func ChunkOverlap 

func ChunkOverlap(n int) ChunkOption

ChunkOverlap sets the overlap between consecutive chunks.

func ChunkSeparator 

func ChunkSeparator(sep string) ChunkOption

ChunkSeparator sets the preferred split point (e.g. "\n\n" for paragraphs).

func ChunkSize 

func ChunkSize(n int) ChunkOption

ChunkSize sets the target chunk size in characters.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main AI client that delegates to the configured provider.

func GetClient 

func GetClient() *Client

GetClient returns the global AI client. Panics if the plugin is not registered.

func NewClient 

func NewClient(cfg *Config) (*Client, error)

NewClient creates a new AI client from the given config.

func WithGuardrailsClient 

func WithGuardrailsClient(c *Client, g *Guardrails) *Client

WithGuardrails returns a new client that validates all responses.

func (*Client) Generate 

func (c *Client) Generate(ctx context.Context, prompt string, opts ...GenerateOption) (*GenerateResponse, error)

Generate produces a completion for the given prompt.

func (*Client) GenerateRequest 

func (c *Client) GenerateRequest(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)

GenerateRequest produces a completion for the given request.

func (*Client) Provider 

func (c *Client) Provider() Provider

Provider returns the underlying provider.

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, prompt string, opts ...GenerateOption) (<-chan string, <-chan error)

Stream produces a streaming completion.

func (*Client) StreamRequest 

func (c *Client) StreamRequest(ctx context.Context, req *GenerateRequest) (*StreamResponse, error)

StreamRequest produces a v2 StreamResponse.

type ComparisonReport 

type ComparisonReport struct {
	Suite   string       `json:"suite"`
	Reports []EvalReport `json:"reports"`
}

ComparisonReport compares evaluation results across models.

func CompareModels 

func CompareModels(ctx context.Context, suite *EvalSuite, models ...string) *ComparisonReport

CompareModels runs the same eval suite across multiple models and returns a comparison report.

func (*ComparisonReport) Summary 

func (cr *ComparisonReport) Summary() string

Summary returns a comparison summary.

type Config 

type Config struct {
	Provider  string
	Model     string
	Timeout   int
	MaxTokens int
	// Text generation providers
	OpenAIKey    string
	AnthropicKey string
	CohereKey    string
	GeminiKey    string
	MistralKey   string
	XAIKey       string
	// Ollama uses OLLAMA_HOST (default localhost:11434), no key
	OllamaHost string
	// Embeddings / specialized (for future use)
	JinaKey       string
	VoyageAIKey   string
	ElevenLabsKey string
}

Config holds AI plugin configuration. API keys are read from environment variables (see README).

type ContentFilter 

type ContentFilter int

ContentFilter is a bitmask for built-in content categories. 

const (
	FilterNone ContentFilter = 0
	FilterHate ContentFilter = 1 << iota
	FilterViolence
	FilterSexual
	FilterSelfHarm
	FilterPII
)

type ConversationRecord 

type ConversationRecord struct {
	ID        uint      `gorm:"primarykey"`
	Key       string    `gorm:"index;size:255;not null"`
	Messages  string    `gorm:"type:text;not null"` // JSON-encoded []Message
	CreatedAt time.Time `gorm:"autoCreateTime"`
	UpdatedAt time.Time `gorm:"autoUpdateTime"`
}

ConversationRecord is the GORM model for storing conversation history.

func (ConversationRecord) TableName 

func (ConversationRecord) TableName() string

TableName returns the database table name.

type CostConfig 

type CostConfig struct {
	// MonthlyBudget is the monthly budget in USD. 0 = unlimited.
	MonthlyBudget float64

	// AlertThresholds are budget percentages that trigger alerts.
	// Default: [50, 75, 90, 100].
	AlertThresholds []float64

	// OnBudgetAlert is called when a threshold is crossed.
	OnBudgetAlert func(CostSummary)

	// CustomPricing overrides or extends default pricing.
	CustomPricing map[string]ModelPricing
}

CostConfig configures cost tracking.

type CostEntry 

type CostEntry struct {
	Timestamp        time.Time `json:"timestamp"`
	Provider         string    `json:"provider"`
	Model            string    `json:"model"`
	PromptTokens     int       `json:"prompt_tokens"`
	CompletionTokens int       `json:"completion_tokens"`
	TotalTokens      int       `json:"total_tokens"`
	PromptCost       float64   `json:"prompt_cost"`
	CompletionCost   float64   `json:"completion_cost"`
	TotalCost        float64   `json:"total_cost"`
}

CostEntry records a single API call's cost.

type CostSummary 

type CostSummary struct {
	// Totals
	TotalCost       float64 `json:"total_cost"`
	TotalRequests   int64   `json:"total_requests"`
	TotalTokens     int64   `json:"total_tokens"`
	MonthlyBudget   float64 `json:"monthly_budget"`
	BudgetPercent   float64 `json:"budget_percent"`
	BudgetRemaining float64 `json:"budget_remaining"`

	// Per-model breakdown
	CostByModel map[string]*ModelCostSummary `json:"cost_by_model"`

	// Per-provider breakdown
	CostByProvider map[string]*ProviderCostSummary `json:"cost_by_provider"`

	// Time-series (hourly buckets for the current day)
	HourlyCosts [24]float64 `json:"hourly_costs"`

	// Recent entries for detailed view
	RecentEntries []CostEntry `json:"recent_entries"`
}

CostSummary is the aggregate cost data for the dashboard.

func GetCostDashboard 

func GetCostDashboard() CostSummary

GetCostDashboard returns the current cost summary for dashboard display.

type DatabaseMemoryOption 

type DatabaseMemoryOption func(*databaseMemory)

DatabaseMemoryOption configures the database memory backend.

func WithAutoMigrate 

func WithAutoMigrate(enabled bool) DatabaseMemoryOption

WithAutoMigrate enables automatic table creation (default: true).

type DocQA 

type DocQA struct {
	// contains filtered or unexported fields
}

DocQA answers questions about a document without a vector store. Best for single-document Q&A where the document fits in context.

func DocumentQA 

func DocumentQA(text string) *DocQA

DocumentQA creates a Q&A interface over a document.

func (*DocQA) Ask 

func (d *DocQA) Ask(ctx context.Context, question string) (string, error)

Ask answers a question about the document.

func (*DocQA) Model 

func (d *DocQA) Model(m string) *DocQA

Model sets the model for Q&A.

func (*DocQA) SystemPrompt 

func (d *DocQA) SystemPrompt(s string) *DocQA

SystemPrompt overrides the default system prompt.

type Document 

type Document struct {
	ID       string            `json:"id"`
	Text     string            `json:"text"`
	Vector   []float32         `json:"vector,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
	Score    float32           `json:"score,omitempty"` // populated on search results
}

Document represents a stored vector with its metadata and text.

type EmbeddingProvider 

type EmbeddingProvider interface {
	Embed(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
}

EmbeddingProvider generates vector embeddings.

type EmbeddingRequest 

type EmbeddingRequest struct {
	Input []string `json:"input"`
	Model string   `json:"model,omitempty"`
}

EmbeddingRequest asks a provider for vector embeddings.

type EmbeddingResponse 

type EmbeddingResponse struct {
	Embeddings [][]float32 `json:"embeddings"`
	Model      string      `json:"model"`
	Usage      *Usage      `json:"usage,omitempty"`
}

EmbeddingResponse wraps one or more embedding vectors.

func EmbedBatch 

func EmbedBatch(ctx context.Context, texts []string, opts ...GenerateOption) (*EmbeddingResponse, error)

EmbedBatch generates vector embeddings for multiple text inputs.

type EvalCase 

type EvalCase struct {
	Name     string            `json:"name"`
	Prompt   string            `json:"prompt"`
	System   string            `json:"system,omitempty"`
	Options  []GenerateOption  `json:"-"`
	Checks   []EvalCheck       `json:"-"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

EvalCase is a single test case for model evaluation.

type EvalCheck 

type EvalCheck func(response string) EvalScore

EvalCheck is a function that scores an AI response. Returns a score between 0.0 and 1.0, and an explanation.

func CustomCheck 

func CustomCheck(name string, fn func(response string) (float64, string)) EvalCheck

CustomCheck creates an EvalCheck from a custom scoring function.

func ExpectContains 

func ExpectContains(substr string) EvalCheck

ExpectContains checks that the response contains the expected substring.

func ExpectJSON 

func ExpectJSON() EvalCheck

ExpectJSON checks that the response is valid JSON.

func ExpectMaxLength 

func ExpectMaxLength(n int) EvalCheck

ExpectMaxLength checks the response is at most n characters.

func ExpectMinLength 

func ExpectMinLength(n int) EvalCheck

ExpectMinLength checks the response is at least n characters.

func ExpectNotContains 

func ExpectNotContains(substr string) EvalCheck

ExpectNotContains checks the response does NOT contain.

func ExpectSimilarity 

func ExpectSimilarity(expected string, threshold float64) EvalCheck

ExpectSimilarity uses the AI model itself to judge response quality. The expected string is compared semantically (costs an extra API call).

func LLMJudge 

func LLMJudge(criteria string) EvalCheck

LLMJudge uses a separate LLM call to evaluate the response quality.

type EvalReport 

type EvalReport struct {
	Suite      string        `json:"suite"`
	Model      string        `json:"model"`
	Provider   string        `json:"provider"`
	Results    []EvalResult  `json:"results"`
	TotalCases int           `json:"total_cases"`
	Passed     int           `json:"passed"`
	Failed     int           `json:"failed"`
	Errors     int           `json:"errors"`
	AvgScore   float64       `json:"avg_score"`
	AvgLatency time.Duration `json:"avg_latency"`
	TotalCost  float64       `json:"total_cost"`
	Duration   time.Duration `json:"duration"`
	Timestamp  time.Time     `json:"timestamp"`
}

EvalReport is the full report from running a benchmark suite.

func (*EvalReport) Summary 

func (r *EvalReport) Summary() string

Summary returns a human-readable summary of the evaluation report.

type EvalResult 

type EvalResult struct {
	Case     string        `json:"case"`
	Prompt   string        `json:"prompt"`
	Response string        `json:"response"`
	Model    string        `json:"model"`
	Provider string        `json:"provider"`
	Scores   []EvalScore   `json:"scores"`
	AvgScore float64       `json:"avg_score"`
	Passed   bool          `json:"passed"`
	Latency  time.Duration `json:"latency"`
	Tokens   int           `json:"tokens"`
	Cost     float64       `json:"cost"`
	Error    string        `json:"error,omitempty"`
}

EvalResult is the result of evaluating one case.

type EvalScore 

type EvalScore struct {
	Name    string  `json:"name"`
	Score   float64 `json:"score"`   // 0.0 to 1.0
	Passed  bool    `json:"passed"`  // true if score >= threshold
	Details string  `json:"details"` // human-readable explanation
}

EvalScore is the result of one evaluation check.

type EvalSuite 

type EvalSuite struct {
	// contains filtered or unexported fields
}

EvalSuite is a collection of evaluation cases.

func NewEvalSuite 

func NewEvalSuite(name string) *EvalSuite

NewEvalSuite creates a new evaluation suite.

func (*EvalSuite) AddCase 

func (s *EvalSuite) AddCase(name, prompt string, checks ...EvalCheck) *EvalSuite

AddCase adds a test case to the suite.

func (*EvalSuite) AddCaseWithSystem 

func (s *EvalSuite) AddCaseWithSystem(name, system, prompt string, checks ...EvalCheck) *EvalSuite

AddCaseWithSystem adds a test case with a system prompt.

func (*EvalSuite) Parallel 

func (s *EvalSuite) Parallel(n int) *EvalSuite

Parallel sets the concurrency level for running cases.

func (*EvalSuite) Run 

func (s *EvalSuite) Run(ctx context.Context) *EvalReport

Run executes all cases and returns the report.

func (*EvalSuite) WithModel 

func (s *EvalSuite) WithModel(model string) *EvalSuite

WithModel sets the model to evaluate.

func (*EvalSuite) WithOptions 

func (s *EvalSuite) WithOptions(opts ...GenerateOption) *EvalSuite

WithOptions sets default options for all cases.

type Example 

type Example struct {
	Input  string
	Output string
}

Example represents a single few-shot example.

type ExtractOption 

type ExtractOption func(*extractConfig)

ExtractOption configures the extraction process.

func WithExtractModel 

func WithExtractModel(model string) ExtractOption

WithExtractModel sets the model for extraction.

func WithExtractSystem 

func WithExtractSystem(system string) ExtractOption

WithExtractSystem overrides the system prompt for extraction.

func WithMaxRetries 

func WithMaxRetries(n int) ExtractOption

WithMaxRetries sets the number of retry attempts on malformed JSON.

type FewShotTemplate 

type FewShotTemplate struct {
	// contains filtered or unexported fields
}

FewShotTemplate builds a prompt with few-shot examples.

func FewShot 

func FewShot(instruction string) *FewShotTemplate

FewShot creates a few-shot prompt builder.

func (*FewShotTemplate) Add 

func (f *FewShotTemplate) Add(input, output string) *FewShotTemplate

Add adds a few-shot example.

func (*FewShotTemplate) Format 

func (f *FewShotTemplate) Format(input string) string

Format builds the prompt string.

func (*FewShotTemplate) Generate 

func (f *FewShotTemplate) Generate(ctx context.Context, input string, opts ...GenerateOption) (*GenerateResponse, error)

Generate formats and generates.

func (*FewShotTemplate) Separator 

func (f *FewShotTemplate) Separator(sep string) *FewShotTemplate

Separator sets the separator between examples.

type GenerateOption 

type GenerateOption func(*GenerateRequest)

GenerateOption is a functional option applied to GenerateRequest.

func WithImages 

func WithImages(images []string) GenerateOption

WithImages attaches image references (data URIs, http(s) URLs, or provider-resolvable paths) to the current user turn. Agent.Prompt moves them onto the user Message so vision-capable providers can send them.

func WithMaxTokens 

func WithMaxTokens(n int) GenerateOption

WithMaxTokens overrides max tokens.

func WithMessages 

func WithMessages(msgs []Message) GenerateOption

WithMessages sets the full message list (overrides prompt).

func WithModel 

func WithModel(model string) GenerateOption

WithModel overrides the model.

func WithSchema 

func WithSchema(schema json.RawMessage) GenerateOption

WithSchema sets the JSON schema for structured output.

func WithStop 

func WithStop(stop ...string) GenerateOption

WithStop sets stop sequences.

func WithSystem 

func WithSystem(s string) GenerateOption

WithSystem sets the system prompt.

func WithTemperature 

func WithTemperature(t float32) GenerateOption

WithTemperature sets the sampling temperature.

func WithTopP 

func WithTopP(p float32) GenerateOption

WithTopP sets the nucleus sampling parameter.

type GenerateRequest 

type GenerateRequest struct {
	Messages    []Message       `json:"messages"`
	Model       string          `json:"model,omitempty"`
	MaxTokens   int             `json:"max_tokens,omitempty"`
	Temperature float32         `json:"temperature,omitempty"`
	TopP        float32         `json:"top_p,omitempty"`
	System      string          `json:"system,omitempty"`
	Tools       []ToolSpec      `json:"tools,omitempty"`
	Schema      json.RawMessage `json:"response_format,omitempty"` // JSON schema for structured output
	Stop        []string        `json:"stop,omitempty"`
	Stream      bool            `json:"stream,omitempty"`
	// Images carries attachments for the current user turn (data URIs, http(s)
	// URLs, or provider-resolvable paths). The Agent moves these onto the
	// current user Message; providers serialize them as multimodal content.
	Images []string `json:"-"`
}

GenerateRequest holds everything needed for a generation call.

type GenerateResponse 

type GenerateResponse struct {
	Text         string     `json:"text"`
	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
	Usage        *Usage     `json:"usage,omitempty"`
	Model        string     `json:"model"`
	FinishReason string     `json:"finish_reason,omitempty"`
}

GenerateResponse is the result of a non-streaming generation.

func Generate 

func Generate(ctx context.Context, prompt string, opts ...GenerateOption) (*GenerateResponse, error)

Generate is a convenience that uses the global client.

type GuardrailCheck 

type GuardrailCheck func(output string) error

GuardrailCheck is a custom validation function. Return an error if the output violates the guardrail.

type Guardrails 

type Guardrails struct {
	// contains filtered or unexported fields
}

Guardrails validates AI outputs against safety and quality rules.

func NewGuardrails 

func NewGuardrails() *Guardrails

NewGuardrails creates an empty guardrails configuration.

func (*Guardrails) BlockPatterns 

func (g *Guardrails) BlockPatterns(patterns ...string) *Guardrails

BlockPatterns adds regex patterns that must NOT appear in the output.

func (*Guardrails) CustomCheck 

func (g *Guardrails) CustomCheck(fn GuardrailCheck) *Guardrails

CustomCheck adds a custom guardrail check.

func (*Guardrails) MaxLength 

func (g *Guardrails) MaxLength(n int) *Guardrails

MaxLength sets the maximum allowed output length.

func (*Guardrails) MinLength 

func (g *Guardrails) MinLength(n int) *Guardrails

MinLength sets the minimum required output length.

func (*Guardrails) RequireKeywords 

func (g *Guardrails) RequireKeywords(keywords ...string) *Guardrails

RequireKeywords ensures the output contains all specified keywords.

func (*Guardrails) SetContentFilter 

func (g *Guardrails) SetContentFilter(f ContentFilter) *Guardrails

ContentFilter sets the content safety filter bitmask.

func (*Guardrails) Validate 

func (g *Guardrails) Validate(output string) error

Validate checks the output against all configured guardrails. Returns nil if the output passes all checks.

func (*Guardrails) ValidateResponse 

func (g *Guardrails) ValidateResponse(resp *GenerateResponse) error

ValidateResponse is a convenience that validates a GenerateResponse.

type ImageBuilder 

type ImageBuilder struct {
	// contains filtered or unexported fields
}

ImageBuilder provides a fluent API for configuring and generating images.

func Image 

func Image() *ImageBuilder

Image starts building an image generation request.

func (*ImageBuilder) Count 

func (b *ImageBuilder) Count(n int) *ImageBuilder

Count sets the number of images to generate.

func (*ImageBuilder) Generate 

func (b *ImageBuilder) Generate(ctx context.Context) (*ImageResponse, error)

Generate produces the image(s).

func (*ImageBuilder) Model 

func (b *ImageBuilder) Model(model string) *ImageBuilder

Model sets the image generation model.

func (*ImageBuilder) Prompt 

func (b *ImageBuilder) Prompt(prompt string) *ImageBuilder

Prompt sets the image description prompt.

func (*ImageBuilder) Size 

func (b *ImageBuilder) Size(size string) *ImageBuilder

Size sets the output image size (e.g. "1024x1024", "512x512").

func (*ImageBuilder) Style 

func (b *ImageBuilder) Style(style string) *ImageBuilder

Style sets the image style (e.g. "natural", "vivid").

func (*ImageBuilder) WithClient 

func (b *ImageBuilder) WithClient(c *Client) *ImageBuilder

WithClient overrides the default client.

type ImageData 

type ImageData struct {
	URL     string `json:"url,omitempty"`
	B64JSON string `json:"b64_json,omitempty"`
}

ImageData holds a single generated image.

type ImageProvider 

type ImageProvider interface {
	GenerateImage(ctx context.Context, req *ImageRequest) (*ImageResponse, error)
}

ImageProvider generates images.

type ImageRequest 

type ImageRequest struct {
	Prompt string `json:"prompt"`
	Model  string `json:"model,omitempty"`
	N      int    `json:"n,omitempty"`
	Size   string `json:"size,omitempty"` // e.g. "1024x1024"
	Style  string `json:"style,omitempty"`
}

ImageRequest configures an image generation call.

type ImageResponse 

type ImageResponse struct {
	Images []ImageData `json:"images"`
	Model  string      `json:"model"`
}

ImageResponse wraps the generated image data.

type LegacyStreamProvider 

type LegacyStreamProvider interface {
	Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)
	LegacyStream(ctx context.Context, req *GenerateRequest) (<-chan string, <-chan error)
}

LegacyStreamProvider is the original Stream signature.

type LogExporter 

type LogExporter struct{}

LogExporter prints spans to the logger (useful for development).

func (*LogExporter) ExportSpan 

func (e *LogExporter) ExportSpan(_ context.Context, span Span) error

ExportSpan logs the span details.

type Memory 

type Memory interface {
	// Load retrieves the conversation history for the given key.
	Load(ctx context.Context, key string) ([]Message, error)

	// Save persists the conversation history for the given key.
	Save(ctx context.Context, key string, messages []Message) error

	// Clear removes the conversation history for the given key.
	Clear(ctx context.Context, key string) error
}

Memory persists and retrieves conversation history for agents.

func DatabaseMemory 

func DatabaseMemory(db *lucid.DB, opts ...DatabaseMemoryOption) Memory

DatabaseMemory creates a database-backed memory store using GORM. Conversation history is persisted in an `ai_conversations` table. 

mem := ai.DatabaseMemory(db)
agent.WithMemory(mem, "session:user123")

func MemoryStore 

func MemoryStore(opts ...MemoryStoreOption) Memory

MemoryStore returns a simple in-memory Memory (lost on restart). Useful for development and testing.

func RedisMemory 

func RedisMemory(client *redis.Client, opts ...RedisMemoryOption) Memory

RedisMemory creates a Redis-backed memory store. Conversation history is stored as JSON in Redis keys with configurable TTL and prefix. 

rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
mem := ai.RedisMemory(rdb, ai.WithRedisTTL(24*time.Hour))
agent.WithMemory(mem, "session:user123")

func SlidingWindowMemory 

func SlidingWindowMemory(inner Memory, maxMessages int) Memory

SlidingWindowMemory wraps another Memory and keeps only the last N messages (plus the system prompt), preventing unbounded growth.

func SummaryMemory 

func SummaryMemory(inner Memory, threshold int) Memory

SummaryMemory wraps another Memory and auto-summarises old messages when the history exceeds the threshold. Uses the AI client itself to produce summaries.

type MemoryStoreOption 

type MemoryStoreOption func(*memoryStore)

MemoryStoreOption configures the in-memory store.

func WithMemoryTTL 

func WithMemoryTTL(ttl time.Duration) MemoryStoreOption

WithTTL sets the time-to-live for stored conversations. Note: TTL cleanup is lazy (checked on Load).

type Message 

type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	Images     []string   `json:"images,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

Message represents a single turn in a conversation. Content is the text payload; ToolCalls and ToolCallID enable the function-calling loop.

type Metrics 

type Metrics struct {
	TotalRequests   int64         `json:"total_requests"`
	TotalTokens     int64         `json:"total_tokens"`
	TotalErrors     int64         `json:"total_errors"`
	TotalLatency    time.Duration `json:"total_latency_ms"`
	RequestsByModel sync.Map      `json:"-"`
}

Metrics holds aggregate AI usage statistics.

func GetMetrics 

func GetMetrics() *Metrics

GetMetrics returns the global AI metrics.

type ModelCostSummary 

type ModelCostSummary struct {
	Model            string  `json:"model"`
	Requests         int64   `json:"requests"`
	PromptTokens     int64   `json:"prompt_tokens"`
	CompletionTokens int64   `json:"completion_tokens"`
	TotalCost        float64 `json:"total_cost"`
	AvgCostPerReq    float64 `json:"avg_cost_per_request"`
}

ModelCostSummary tracks costs for a specific model.

type ModelPricing 

type ModelPricing struct {
	PromptPer1K     float64 `json:"prompt_per_1k"`
	CompletionPer1K float64 `json:"completion_per_1k"`
}

ModelPricing holds per-1K token prices for a model.

type NamedStep 

type NamedStep struct {
	Name    string
	Handler StepHandler
}

NamedStep associates a name with a step handler.

func StepFunc 

func StepFunc(name string, handler StepHandler) NamedStep

StepFunc creates a NamedStep from a name and handler.

type OTLPExporter 

type OTLPExporter struct {
	Endpoint string // e.g. "http://localhost:4318/v1/traces"
}

OTLPExporter exports spans to an OpenTelemetry collector via HTTP.

func (*OTLPExporter) ExportSpan 

func (e *OTLPExporter) ExportSpan(_ context.Context, span Span) error

ExportSpan sends the span to the OTLP endpoint.

type OutputFormat 

type OutputFormat struct {
	Name   string `json:"name"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
	Aspect string `json:"aspect"` // e.g. "9:16"
}

OutputFormat defines the aspect ratio and sizing for the final render.

type PgvectorOption 

type PgvectorOption func(*pgvectorStore)

PgvectorOption configures the pgvector backend.

func WithPgvectorDimension 

func WithPgvectorDimension(d int) PgvectorOption

WithPgvectorDimension sets the vector dimension (default: 1536 for OpenAI).

func WithPgvectorTable 

func WithPgvectorTable(name string) PgvectorOption

WithPgvectorTable sets the table name (default: "ai_vectors").

type PgvectorRecord 

type PgvectorRecord struct {
	ID       string `gorm:"primarykey;size:255"`
	Text     string `gorm:"type:text"`
	Vector   string `gorm:"type:text"` // stored as text representation of float array
	Metadata string `gorm:"type:text"` // JSON metadata
}

PgvectorRecord is the GORM model for the vector store table.

type PineconeOption 

type PineconeOption func(*pineconeStore)

PineconeOption configures the Pinecone backend.

func WithPineconeNamespace 

func WithPineconeNamespace(ns string) PineconeOption

WithPineconeNamespace sets the Pinecone namespace for multi-tenancy.

type Plugin 

type Plugin struct {
	nimbus.BasePlugin
	// contains filtered or unexported fields
}

Plugin integrates the AI SDK with Nimbus.

func New 

func New() *Plugin

New creates a new AI plugin instance.

func (*Plugin) Boot 

func (p *Plugin) Boot(app *nimbus.App) error

Boot performs post-registration setup (no-op for now).

func (*Plugin) DefaultConfig 

func (p *Plugin) DefaultConfig() map[string]any

DefaultConfig returns the default configuration for the AI plugin.

func (*Plugin) Register 

func (p *Plugin) Register(app *nimbus.App) error

Register binds the AI client to the container.

type PromptChain 

type PromptChain struct {
	// contains filtered or unexported fields
}

PromptChain composes multiple templates into a single generation call.

func Chain 

func Chain(templates ...*PromptTemplate) *PromptChain

Chain creates a prompt chain from one or more templates.

func (*PromptChain) Generate 

func (c *PromptChain) Generate(ctx context.Context, vars map[string]any, opts ...GenerateOption) (*GenerateResponse, error)

Generate renders all templates and builds a multi-message request.

type PromptTemplate 

type PromptTemplate struct {
	// contains filtered or unexported fields
}

PromptTemplate is a reusable prompt with variable interpolation.

func SystemTemplate 

func SystemTemplate(s string) *PromptTemplate

SystemTemplate creates a system-role prompt template.

func Template 

func Template(s string) *PromptTemplate

Template creates a new prompt template from the given string. Uses Go text/template syntax ({{.varName}}).

func (*PromptTemplate) Format 

func (p *PromptTemplate) Format(vars map[string]any) (string, error)

Format renders the template with the given variables.

func (*PromptTemplate) Generate 

func (p *PromptTemplate) Generate(ctx context.Context, vars map[string]any, opts ...GenerateOption) (*GenerateResponse, error)

Generate renders the template and sends it to the AI.

func (*PromptTemplate) MustFormat 

func (p *PromptTemplate) MustFormat(vars map[string]any) string

MustFormat renders or panics. Useful in init() or tests.

func (*PromptTemplate) Role 

func (p *PromptTemplate) Role(role string) *PromptTemplate

Role sets the message role for this template.

type Provider 

type Provider interface {
	// Name returns the provider identifier (e.g. "openai", "anthropic").
	Name() string

	// Generate produces a single completion.
	Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)

	// Stream produces a streaming completion. If the provider does not
	// support native streaming, the default implementation calls
	// Generate and wraps the result in a single-chunk stream.
	Stream(ctx context.Context, req *GenerateRequest) (*StreamResponse, error)
}

Provider is the minimum contract every AI backend must satisfy.

type ProviderCostSummary 

type ProviderCostSummary struct {
	Provider  string  `json:"provider"`
	Requests  int64   `json:"requests"`
	TotalCost float64 `json:"total_cost"`
}

ProviderCostSummary tracks costs for a specific provider.

type ProviderFactory 

type ProviderFactory func(cfg *Config) (Provider, error)

ProviderFactory creates a Provider from a Config.

func GetProviderFactory 

func GetProviderFactory(name string) (ProviderFactory, bool)

GetProviderFactory returns the factory for the named provider.

type QdrantOption 

type QdrantOption func(*qdrantStore)

QdrantOption configures the Qdrant backend.

func WithQdrantAPIKey 

func WithQdrantAPIKey(key string) QdrantOption

WithQdrantAPIKey sets the Qdrant API key for cloud deployments.

func WithQdrantDimension 

func WithQdrantDimension(d int) QdrantOption

WithQdrantDimension sets the vector dimension (default: 1536).

type RAG 

type RAG struct {
	// contains filtered or unexported fields
}

RAG is a retrieval-augmented generation engine.

func NewRAG 

func NewRAG(store *Store) *RAG

NewRAG creates a RAG engine backed by the given vector store.

func (*RAG) Ask 

func (r *RAG) Ask(ctx context.Context, question string, opts ...GenerateOption) (*RAGResponse, error)

Ask runs the full RAG pipeline: embed → search → augment → generate.

func (*RAG) AskStream 

func (r *RAG) AskStream(ctx context.Context, question string, opts ...GenerateOption) (*StreamResponse, []Document, error)

AskStream runs the RAG pipeline but streams the final answer.

func (*RAG) MinScore 

func (r *RAG) MinScore(score float32) *RAG

MinScore sets the minimum similarity score threshold.

func (*RAG) Model 

func (r *RAG) Model(m string) *RAG

Model overrides the default model.

func (*RAG) OnPostprocess 

func (r *RAG) OnPostprocess(fn func(string, []Document) string) *RAG

OnPostprocess sets a function to transform the answer after generation.

func (*RAG) OnPreprocess 

func (r *RAG) OnPreprocess(fn func(string) string) *RAG

OnPreprocess sets a function to transform the query before embedding.

func (*RAG) SystemPrompt 

func (r *RAG) SystemPrompt(s string) *RAG

SystemPrompt overrides the default system prompt.

func (*RAG) TopK 

func (r *RAG) TopK(k int) *RAG

TopK sets the number of documents to retrieve.

func (*RAG) WithCitations 

func (r *RAG) WithCitations(enabled bool) *RAG

WithCitations enables source citation in the response.

func (*RAG) WithClient 

func (r *RAG) WithClient(c *Client) *RAG

WithClient overrides the default global AI client.

type RAGResponse 

type RAGResponse struct {
	Answer  string     `json:"answer"`
	Sources []Document `json:"sources"`
	Usage   *Usage     `json:"usage,omitempty"`
}

RAGResponse wraps the generated answer with source documents.

type RedisMemoryOption 

type RedisMemoryOption func(*redisMemory)

RedisMemoryOption configures the Redis memory backend.

func WithRedisPrefix 

func WithRedisPrefix(prefix string) RedisMemoryOption

WithRedisPrefix sets the key prefix (default "ai:memory:").

func WithRedisTTL 

func WithRedisTTL(ttl time.Duration) RedisMemoryOption

WithRedisTTL sets per-key expiration in Redis.

type RequestEvent 

type RequestEvent struct {
	Provider  string        `json:"provider"`
	Model     string        `json:"model"`
	Prompt    string        `json:"prompt,omitempty"`
	Messages  []Message     `json:"messages,omitempty"`
	Usage     *Usage        `json:"usage,omitempty"`
	Latency   time.Duration `json:"latency_ms"`
	Error     error         `json:"error,omitempty"`
	Timestamp time.Time     `json:"timestamp"`
}

RequestEvent is emitted for every AI API call. Middleware and observability hooks receive this.

type RequestHook 

type RequestHook func(RequestEvent)

RequestHook is a callback for AI request events.

type Scene 

type Scene struct {
	Index       int            `json:"index"`
	Prompt      string         `json:"prompt"`
	Camera      CameraMove     `json:"camera"`
	Duration    int            `json:"duration"` // seconds
	KeyframeURL string         `json:"keyframe_url,omitempty"`
	VideoURL    string         `json:"video_url,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Scene represents one segment of the planned video.

type ScenePlan 

type ScenePlan struct {
	OriginalPrompt string  `json:"original_prompt"`
	ExpandedPrompt string  `json:"expanded_prompt"`
	GlobalStyle    string  `json:"global_style"`
	Scenes         []Scene `json:"scenes"`
}

ScenePlan is the output of the scene planner.

type SocialPackage 

type SocialPackage struct {
	Caption      string            `json:"caption"`
	Hashtags     []string          `json:"hashtags"`
	ThumbnailURL string            `json:"thumbnail_url,omitempty"`
	Formats      map[string]string `json:"formats"` // format name → video URL
}

SocialPackage holds auto-generated social media assets.

type Span 

type Span struct {
	TraceID    string            `json:"trace_id"`
	SpanID     string            `json:"span_id"`
	ParentID   string            `json:"parent_id,omitempty"`
	Name       string            `json:"name"`
	Kind       string            `json:"kind"` // "client", "internal"
	StartTime  time.Time         `json:"start_time"`
	EndTime    time.Time         `json:"end_time"`
	Duration   time.Duration     `json:"duration"`
	Status     string            `json:"status"` // "ok", "error"
	Attributes map[string]string `json:"attributes"`
	Events     []SpanEvent       `json:"events,omitempty"`
	Error      string            `json:"error,omitempty"`
}

Span represents a trace span for AI operations.

func GetTraceSpans 

func GetTraceSpans(limit int) []Span

GetTraceSpans returns recent trace spans for inspection.

type SpanEvent 

type SpanEvent struct {
	Name       string            `json:"name"`
	Timestamp  time.Time         `json:"timestamp"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

SpanEvent is a timestamped annotation on a span.

type SpanExporter 

type SpanExporter interface {
	ExportSpan(ctx context.Context, span Span) error
}

SpanExporter receives completed spans for export.

type StepHandler 

type StepHandler func(wc *WorkflowContext) error

StepHandler is a function that executes a workflow step. It receives the accumulated context and should call wc.Set() to contribute results.

type StepResult 

type StepResult struct {
	Name     string        `json:"name"`
	Duration time.Duration `json:"duration"`
	Error    error         `json:"error,omitempty"`
}

StepResult records the outcome of a single step.

type StitchConfig 

type StitchConfig struct {
	FadeSeconds float64 `json:"fade_seconds"`
	MusicPath   string  `json:"music_path,omitempty"`
	CaptionText string  `json:"caption_text,omitempty"`
	OutputPath  string  `json:"output_path"`
	ConcatFile  string  `json:"concat_file"` // path to write the file list
}

StitchCommand generates the FFmpeg command to concatenate scene videos with optional transitions. The caller is responsible for executing it.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store wraps a backend and handles automatic embedding of text.

func VectorStoreInstance 

func VectorStoreInstance(name string, backend ...VectorStoreBackend) *Store

VectorStoreInstance creates a new Store for the given namespace. Uses the registered backend or defaults to in-memory.

func (*Store) Add 

func (s *Store) Add(ctx context.Context, id, text string, metadata ...map[string]string) error

Add embeds the text and stores it.

func (*Store) AddBatch 

func (s *Store) AddBatch(ctx context.Context, items []struct{ ID, Text string }) error

AddBatch embeds and stores multiple texts.

func (*Store) AddDocument 

func (s *Store) AddDocument(ctx context.Context, doc Document) error

AddDocument stores a pre-embedded document.

func (*Store) Count 

func (s *Store) Count(ctx context.Context) (int, error)

Count returns the number of stored documents.

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, id string) error

Delete removes a document.

func (*Store) Search 

func (s *Store) Search(ctx context.Context, query string, topK int) ([]Document, error)

Search embeds the query and finds the top-k most similar documents.

func (*Store) SearchVector 

func (s *Store) SearchVector(ctx context.Context, vector []float32, topK int) ([]Document, error)

SearchVector finds similar documents using a pre-computed vector.

type StreamChunk 

type StreamChunk struct {
	Text      string     `json:"text,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	Usage     *Usage     `json:"usage,omitempty"`
	Done      bool       `json:"done,omitempty"`
}

StreamChunk is one piece of a streaming response.

type StreamResponse 

type StreamResponse struct {
	// Chunks delivers text/tool-call chunks until closed.
	Chunks <-chan StreamChunk
	// Err is buffered (cap=1). A nil send signals clean completion.
	Err <-chan error
}

StreamResponse wraps a streaming channel plus a done channel.

func GenerateToStream 

func GenerateToStream(ctx context.Context, p Provider, req *GenerateRequest) (*StreamResponse, error)

GenerateToStream wraps a Generate call as a single-chunk StreamResponse. Use inside Stream() implementations for providers that lack native streaming.

func (*StreamResponse) Collect 

func (s *StreamResponse) Collect(ctx context.Context) (*GenerateResponse, error)

Collect drains the stream and returns the concatenated text and final usage. Blocks until the stream is finished.

type SummarizeOption 

type SummarizeOption func(*summarizeConfig)

SummarizeOption configures summarization.

func SummarizeMaxLength 

func SummarizeMaxLength(n int) SummarizeOption

SummarizeMaxLength limits the summary length.

func SummarizeModel 

func SummarizeModel(m string) SummarizeOption

SummarizeModel sets the model.

func SummarizeStyle 

func SummarizeStyle(s string) SummarizeOption

SummarizeStyle sets the summary style.

type Tool 

type Tool struct {
	Name        string `json:"name"`
	Description string `json:"description"`

	// Run is the handler function. It must have the signature:
	//   func(ctx context.Context, input T) (U, error)
	// where T is the input struct (used to generate JSON schema)
	// and U is the output (marshaled to JSON for the model).
	Run any `json:"-"`
	// contains filtered or unexported fields
}

Tool represents a callable function that an AI agent can invoke.

func AllTools 

func AllTools() []*Tool

AllTools returns all registered tools.

func GetTool 

func GetTool(name string) (*Tool, bool)

GetTool retrieves a registered tool by name.

func (*Tool) Execute 

func (t *Tool) Execute(ctx context.Context, argsJSON json.RawMessage) (json.RawMessage, error)

Execute invokes the tool handler with JSON arguments.

func (*Tool) Schema 

func (t *Tool) Schema() json.RawMessage

Schema returns the JSON-Schema representation of the tool's input parameters, suitable for sending to model APIs.

func (*Tool) ToSpec 

func (t *Tool) ToSpec() ToolSpec

ToSpec converts to a ToolSpec for wire-format.

type ToolBuilder 

type ToolBuilder struct {
	// contains filtered or unexported fields
}

ToolBuilder provides a fluent API for constructing tools.

func NewTool 

func NewTool(name string) *ToolBuilder

NewTool starts building a tool with the given name.

func (*ToolBuilder) Build 

func (b *ToolBuilder) Build() (*Tool, error)

Build validates and returns the tool.

func (*ToolBuilder) Desc 

func (b *ToolBuilder) Desc(desc string) *ToolBuilder

Desc sets the tool description.

func (*ToolBuilder) Handler 

func (b *ToolBuilder) Handler(fn any) *ToolBuilder

Handler sets the typed handler function.

func (*ToolBuilder) Register 

func (b *ToolBuilder) Register() error

Register validates and registers the tool globally.

type ToolCall 

type ToolCall struct {
	ID   string          `json:"id"`
	Name string          `json:"name"`
	Args json.RawMessage `json:"arguments"`
}

ToolCall represents a function call requested by the model.

type ToolSpec 

type ToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"` // JSON Schema
}

ToolSpec describes a tool the model may call. Mirrors the OpenAI function-calling schema so providers can translate as needed.

func ToolSpecs 

func ToolSpecs() []ToolSpec

ToolSpecs returns ToolSpec for all registered tools (for provider APIs).

type TraceContext 

type TraceContext struct {
	TraceID  string
	SpanID   string
	ParentID string
}

TraceContext holds trace propagation info.

func GetTraceContext 

func GetTraceContext(ctx context.Context) (TraceContext, bool)

GetTraceContext retrieves trace context from a Go context.

type TracingConfig 

type TracingConfig struct {
	// ServiceName is the service name for the tracer (default: "nimbus-ai").
	ServiceName string

	// Enabled turns tracing on/off (default: true when EnableTracing called).
	Enabled bool

	// RecordPrompts controls whether prompt text is recorded in span
	// attributes. Disable in production for privacy (default: false).
	RecordPrompts bool

	// RecordResponses controls whether response text is recorded.
	// Disable for privacy (default: false).
	RecordResponses bool
}

TracingConfig configures OpenTelemetry tracing for the AI SDK.

type Usage 

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

Usage holds token usage information.

type VectorStoreBackend 

type VectorStoreBackend interface {
	// Add stores a document with its embedding vector.
	Add(ctx context.Context, doc Document) error

	// AddBatch stores multiple documents.
	AddBatch(ctx context.Context, docs []Document) error

	// Search finds the top-k most similar documents to the query vector.
	Search(ctx context.Context, vector []float32, topK int) ([]Document, error)

	// Delete removes a document by ID.
	Delete(ctx context.Context, id string) error

	// Count returns the total number of documents.
	Count(ctx context.Context) (int, error)
}

VectorStoreBackend is the interface for vector storage backends.

func NewMemoryVectorStore 

func NewMemoryVectorStore() VectorStoreBackend

NewMemoryVectorStore creates an in-memory vector store for development and testing. Not suitable for production.

func NewPgvectorStore 

func NewPgvectorStore(db *lucid.DB, opts ...PgvectorOption) VectorStoreBackend

NewPgvectorStore creates a pgvector-backed VectorStoreBackend. Requires the `pgvector` extension on PostgreSQL. 

db, _ := lucid.Open(postgres.Open(dsn), &lucid.Config{})
backend := ai.NewPgvectorStore(db)
store := ai.VectorStoreInstance("docs", backend)

func NewPineconeStore 

func NewPineconeStore(host, apiKey string, opts ...PineconeOption) VectorStoreBackend

NewPineconeStore creates a Pinecone-backed VectorStoreBackend. 

backend := ai.NewPineconeStore(
    "https://my-index-xxx.svc.xxx.pinecone.io",
    "your-api-key",
)
store := ai.VectorStoreInstance("knowledge", backend)

func NewQdrantStore 

func NewQdrantStore(baseURL, collection string, opts ...QdrantOption) VectorStoreBackend

NewQdrantStore creates a Qdrant-backed VectorStoreBackend. 

backend := ai.NewQdrantStore("http://localhost:6333", "documents")
store := ai.VectorStoreInstance("knowledge", backend)

type VideoBuilder 

type VideoBuilder struct {
	// contains filtered or unexported fields
}

VideoBuilder provides a fluent API for video generation.

func Video 

func Video() *VideoBuilder

Video starts building a video generation request.

func (*VideoBuilder) Duration 

func (b *VideoBuilder) Duration(seconds int) *VideoBuilder

Duration sets the video duration in seconds.

func (*VideoBuilder) FPS 

func (b *VideoBuilder) FPS(fps int) *VideoBuilder

FPS sets the frames per second.

func (*VideoBuilder) FromImage 

func (b *VideoBuilder) FromImage(url string) *VideoBuilder

FromImage sets a source image for image-to-video generation.

func (*VideoBuilder) Generate 

func (b *VideoBuilder) Generate(ctx context.Context) (*VideoResponse, error)

Generate produces the video.

func (*VideoBuilder) Model 

func (b *VideoBuilder) Model(model string) *VideoBuilder

Model sets the video generation model.

func (*VideoBuilder) Prompt 

func (b *VideoBuilder) Prompt(prompt string) *VideoBuilder

Prompt sets the video description.

func (*VideoBuilder) Size 

func (b *VideoBuilder) Size(size string) *VideoBuilder

Size sets the output resolution.

func (*VideoBuilder) WithClient 

func (b *VideoBuilder) WithClient(c *Client) *VideoBuilder

WithClient overrides the default client.

type VideoPipeline 

type VideoPipeline struct {
	// contains filtered or unexported fields
}

VideoPipeline orchestrates the full video production flow.

func NewVideoPipeline 

func NewVideoPipeline() *VideoPipeline

NewVideoPipeline creates a new pipeline with sensible defaults.

func (*VideoPipeline) ConcurrentScenes 

func (p *VideoPipeline) ConcurrentScenes(n int) *VideoPipeline

ConcurrentScenes sets parallelism for scene rendering.

func (*VideoPipeline) DefaultDuration 

func (p *VideoPipeline) DefaultDuration(seconds int) *VideoPipeline

DefaultDuration sets the per-scene duration in seconds.

func (*VideoPipeline) DraftMode 

func (p *VideoPipeline) DraftMode(draft bool) *VideoPipeline

DraftMode enables shorter preview clips for cost optimization.

func (*VideoPipeline) ExpanderModel 

func (p *VideoPipeline) ExpanderModel(model string) *VideoPipeline

ExpanderModel sets the LLM used for prompt expansion.

func (*VideoPipeline) Generate 

func (p *VideoPipeline) Generate(ctx context.Context, prompt string) (*VideoProject, error)

Generate runs the entire video production pipeline: expand → plan → keyframes → videos → stitch.

func (*VideoPipeline) GenerateWithSocial 

func (p *VideoPipeline) GenerateWithSocial(ctx context.Context, prompt string) (*VideoProject, error)

GenerateWithSocial runs the pipeline and also generates social media packaging.

func (*VideoPipeline) GlobalStyle 

func (p *VideoPipeline) GlobalStyle(style string) *VideoPipeline

GlobalStyle sets the style prompt appended to every scene.

func (*VideoPipeline) ImageModel 

func (p *VideoPipeline) ImageModel(model string) *VideoPipeline

ImageModel sets the model for keyframe image generation.

func (*VideoPipeline) MaxScenes 

func (p *VideoPipeline) MaxScenes(n int) *VideoPipeline

MaxScenes limits the number of scenes generated.

func (*VideoPipeline) OnScene 

func (p *VideoPipeline) OnScene(fn func(scene Scene, stage string)) *VideoPipeline

OnScene registers a progress callback fired at each pipeline stage.

func (*VideoPipeline) OutputFmt 

func (p *VideoPipeline) OutputFmt(format OutputFormat) *VideoPipeline

OutputFmt sets the output video format/aspect ratio.

func (*VideoPipeline) PlannerModel 

func (p *VideoPipeline) PlannerModel(model string) *VideoPipeline

PlannerModel sets the LLM used for scene planning.

func (*VideoPipeline) SeedVariants 

func (p *VideoPipeline) SeedVariants(n int) *VideoPipeline

SeedVariants sets how many keyframe variants to generate per scene.

func (*VideoPipeline) VideoModel 

func (p *VideoPipeline) VideoModel(model string) *VideoPipeline

VideoModel sets the model for video synthesis.

func (*VideoPipeline) WithClient 

func (p *VideoPipeline) WithClient(c *Client) *VideoPipeline

WithClient overrides the default AI client.

type VideoPipelineConfig 

type VideoPipelineConfig struct {
	ImageModel      string                          `json:"image_model"`
	VideoModel      string                          `json:"video_model"`
	PlannerModel    string                          `json:"planner_model"`  // LLM for scene planning
	ExpanderModel   string                          `json:"expander_model"` // LLM for prompt expansion
	GlobalStyle     string                          `json:"global_style"`
	MaxScenes       int                             `json:"max_scenes"`
	DefaultDuration int                             `json:"default_duration"` // per-scene seconds
	DraftMode       bool                            `json:"draft_mode"`       // shorter preview clips
	Format          OutputFormat                    `json:"format"`
	Parallelism     int                             `json:"parallelism"` // concurrent scene renders
	Seeds           int                             `json:"seeds"`       // keyframe seed variants
	OnScene         func(scene Scene, stage string) // progress callback
}

VideoPipelineConfig holds all settings for the video pipeline.

type VideoProject 

type VideoProject struct {
	ID             string         `json:"id"`
	Prompt         string         `json:"prompt"`
	Plan           *ScenePlan     `json:"plan"`
	Scenes         []Scene        `json:"scenes"`
	FinalVideoURL  string         `json:"final_video_url,omitempty"`
	Format         OutputFormat   `json:"format"`
	Duration       time.Duration  `json:"duration"`
	Social         *SocialPackage `json:"social,omitempty"`
	RenderDuration time.Duration  `json:"render_duration"`
}

VideoProject is the output of a full pipeline run.

type VideoProvider 

type VideoProvider interface {
	GenerateVideo(ctx context.Context, req *VideoRequest) (*VideoResponse, error)
}

VideoProvider is the capability interface for video generation.

type VideoRequest 

type VideoRequest struct {
	Prompt   string `json:"prompt"`
	Model    string `json:"model,omitempty"`
	ImageURL string `json:"image_url,omitempty"` // for image-to-video
	Duration int    `json:"duration,omitempty"`  // seconds
	FPS      int    `json:"fps,omitempty"`
	Size     string `json:"size,omitempty"` // e.g. "1920x1080"
}

VideoRequest configures a video generation call.

type VideoResponse 

type VideoResponse struct {
	URL      string `json:"url"`
	Model    string `json:"model"`
	Duration int    `json:"duration"`
}

VideoResponse wraps the generated video.

type Workflow 

type Workflow struct {
	// contains filtered or unexported fields
}

Workflow is a named multi-step AI pipeline.

func NewWorkflow 

func NewWorkflow(name string) *Workflow

NewWorkflow creates a named workflow.

func (*Workflow) Branch 

func (w *Workflow) Branch(name string, selector func(wc *WorkflowContext) string, branches map[string]StepHandler) *Workflow

Branch adds a conditional branching step.

func (*Workflow) OnStep 

func (w *Workflow) OnStep(h WorkflowHook) *Workflow

OnStep registers a hook for step lifecycle events.

func (*Workflow) Parallel 

func (w *Workflow) Parallel(name string, steps ...NamedStep) *Workflow

Parallel adds a set of steps that execute concurrently.

func (*Workflow) Run 

func (w *Workflow) Run(ctx context.Context, input WorkflowInput) (*WorkflowResult, error)

Run executes the workflow with the given input and returns the result.

func (*Workflow) Step 

func (w *Workflow) Step(name string, handler StepHandler) *Workflow

Step adds a sequential step to the workflow.

type WorkflowContext 

type WorkflowContext struct {
	context.Context
	// contains filtered or unexported fields
}

WorkflowContext carries accumulated state through the pipeline.

func (*WorkflowContext) All 

func (wc *WorkflowContext) All() map[string]any

All returns a copy of all data.

func (*WorkflowContext) Get 

func (wc *WorkflowContext) Get(key string) any

Get retrieves a value from the workflow context.

func (*WorkflowContext) GetString 

func (wc *WorkflowContext) GetString(key string) string

GetString retrieves a string value.

func (*WorkflowContext) Set 

func (wc *WorkflowContext) Set(key string, value any)

Set stores a value in the workflow context.

type WorkflowHook 

type WorkflowHook func(step string, event string, wc *WorkflowContext)

WorkflowHook is called before/after steps.

type WorkflowInput 

type WorkflowInput map[string]any

WorkflowInput is the initial data map passed to a workflow.

type WorkflowResult 

type WorkflowResult struct {
	Data     map[string]any `json:"data"`
	Duration time.Duration  `json:"duration"`
	Steps    []StepResult   `json:"steps"`
}

WorkflowResult is the final output of a workflow run.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.