API Reference — Beluga AI v2

Complete API reference for all Beluga AI v2 packages. This documentation is generated from the Go source code doc comments.

Foundation

Package	Description
Core Package	Foundation primitives: streams, Runnable, events, errors, lifecycle, multi-tenancy
Schema Package	Shared types: messages, content parts, tool definitions, documents, events, sessions
Config Package	Configuration loading, validation, environment variables, and hot-reload

LLM & Agents

Package	Description
LLM Package	ChatModel interface, provider registry, middleware, hooks, structured output, routing
LLM Providers	All LLM provider implementations: OpenAI, Anthropic, Google, Ollama, Bedrock, and more
Agent Package	Agent runtime, BaseAgent, Executor, Planner strategies, handoffs, and event bus
Agent Workflows	Sequential, Parallel, and Loop workflow agents for multi-agent orchestration
Tool Package	Tool interface, FuncTool, registry, MCP client integration, and middleware

Memory & RAG

Package	Description
Memory Package	MemGPT-inspired 3-tier memory: Core, Recall, Archival, graph memory, composite
Memory Store Providers	Memory store implementations: in-memory, Redis, PostgreSQL, SQLite, MongoDB, Neo4j, Memgraph, Dragonfly
RAG Embedding	Embedder interface for converting text to vector embeddings
Embedding Providers	Embedding provider implementations: OpenAI, Cohere, Google, Jina, Mistral, Ollama, Voyage, and more
RAG Vector Store	VectorStore interface for similarity search over document embeddings
Vector Store Providers	Vector store implementations: pgvector, Pinecone, Qdrant, Weaviate, Milvus, Elasticsearch, and more
RAG Retriever	Retriever strategies: Vector, Hybrid, HyDE, CRAG, Multi-Query, Ensemble, Rerank, Adaptive
RAG Document Loaders	Document loaders for files, cloud storage, APIs, and web content
RAG Text Splitters	Text splitting strategies for chunking documents

Voice

Package	Description
Voice Package	Frame-based voice pipeline, VAD, hybrid cascade/S2S switching
Voice STT	Speech-to-text interface and providers: Deepgram, AssemblyAI, Whisper, Groq, ElevenLabs, Gladia
Voice TTS	Text-to-speech interface and providers: ElevenLabs, Cartesia, PlayHT, Fish, Groq, LMNT, Smallest
Voice S2S	Speech-to-speech interface and providers: OpenAI Realtime, Gemini Live, Nova S2S
Voice Transport	Transport layer for voice sessions: WebSocket, LiveKit, Daily, Pipecat
Voice VAD	Voice activity detection providers: Silero, WebRTC

Infrastructure

Package	Description
Guard Package	Three-stage safety pipeline: input, output, tool guards with built-in and external providers
Resilience Package	Circuit breaker, hedge, retry, and rate limiting patterns
Cache Package	Exact, semantic, and prompt caching with pluggable backends
HITL Package	Human-in-the-loop: confidence-based approval, escalation policies
Auth Package	RBAC, ABAC, and capability-based security
Eval Package	Evaluation framework: metrics, runners, and provider integrations
State Package	Shared agent state with watch and notify
Prompt Package	Prompt management, templating, and versioning
Orchestration Package	Chain, Graph, Router, Parallel, and Supervisor orchestration patterns
Workflow Package	Durable execution engine with provider integrations

Protocol & Server

Package	Description
Protocol Package	Protocol abstractions for MCP, A2A, REST, and OpenAI Agents compatibility
MCP Protocol	Model Context Protocol server/client, SDK, registry, and Composio integration
A2A Protocol	Agent-to-Agent protocol types and SDK implementation
REST & OpenAI Agents	REST/SSE API server and OpenAI Agents protocol compatibility
Server Adapters	HTTP framework adapters: Gin, Fiber, Echo, Chi, gRPC, Connect, Huma
Observability Package	OpenTelemetry GenAI conventions, tracing, and provider integrations

Design Patterns

All extensible packages in Beluga AI v2 follow consistent patterns:

Registry Pattern

Every extensible package provides:

• Register(name, factory) — register providers in init()
• New(name, config) — instantiate providers by name
• List() — discover available providers

Middleware Pattern

Wrap interfaces to add cross-cutting behavior:

model = llm.ApplyMiddleware(model,
    llm.WithLogging(logger),
    llm.WithRetry(3),
)

Hooks Pattern

Inject lifecycle callbacks without middleware:

hooks := llm.Hooks{
    BeforeGenerate: func(ctx, msgs) error { ... },
    AfterGenerate:  func(ctx, resp, err) { ... },
}
model = llm.WithHooks(model, hooks)

Streaming Pattern

All streaming uses Go 1.23+ iter.Seq2:

for chunk, err := range model.Stream(ctx, msgs) {
    if err != nil { break }
    fmt.Print(chunk.Delta)
}