ai

README

togo-framework/ai

Part of the togo framework.

Install

togo install togo-framework/ai

togo · ai

The AI plugin for togo — a unified LLM interface with a pluggable provider driver registry. Install a provider plugin and select it with AI_DRIVER.

togo install togo-framework/ai
togo install togo-framework/ai-openai   # then set AI_DRIVER=openai, OPENAI_API_KEY=…

Interface

type Provider interface {
    Chat(ctx, ChatRequest) (ChatResponse, error)
    Embed(ctx, EmbedRequest) (EmbedResponse, error)
}
// optional: Streamer { ChatStream(ctx, req, onChunk) }

Usage

svc, _ := ai.FromKernel(k)
resp, _ := svc.Chat(ctx, ai.ChatRequest{Messages: []ai.Message{{Role: ai.RoleUser, Content: "Hi"}}})
fmt.Println(resp.Content, resp.Usage.TotalTokens)

REST: mount ai.Handler(k) under /api/ai → POST /chat, POST /embed.

Providers

ai-openai · ai-anthropic · ai-gemini · ai-ollama · ai-grok · ai-deepseek · ai-qwen · ai-adk · ai-agno. Capabilities: ai-rag, ai-agentops. The built-in echo driver is the safe dev default (no external calls).

MIT

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package ai is the togo AI plugin: a unified LLM interface with a pluggable driver registry. Provider plugins (ai-openai, ai-anthropic, ai-gemini, ai-ollama, …) register a driver via init(); select one with AI_DRIVER. Mirrors the mail/storage driver-plugin pattern. A safe "echo" driver is the dev default.

Index

• Constants
• func Drivers() []string
• func Handler(k *togo.Kernel) http.Handler
• func RegisterDriver(name string, f DriverFactory)
• type ChatRequest
• type ChatResponse
• type Chunk
• type DriverFactory
• type EmbedRequest
• type EmbedResponse
• type Message
• type Provider
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)
  • func (s *Service) ChatStream(ctx context.Context, req ChatRequest, onChunk func(Chunk) error) error
  • func (s *Service) Driver() string
  • func (s *Service) Embed(ctx context.Context, req EmbedRequest) (EmbedResponse, error)
• type Streamer
• type Tool
• type ToolCall
• type Usage

Constants

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

Chat roles.

Functions

func Drivers

func Drivers() []string

Drivers returns the registered driver names.

func Handler

func Handler(k *togo.Kernel) http.Handler

Handler exposes the AI service over REST. Mount under /api/ai in your app:

mux.Handle("/api/ai/", http.StripPrefix("/api/ai", ai.Handler(k)))

Routes: POST /chat (ChatRequest -> ChatResponse), POST /embed (EmbedRequest -> EmbedResponse).

func RegisterDriver

func RegisterDriver(name string, f DriverFactory)

RegisterDriver registers an AI provider driver (called from a provider plugin's init()).

Types

type ChatRequest

type ChatRequest struct {
	Model       string    `json:"model,omitempty"`
	Messages    []Message `json:"messages"`
	Temperature float64   `json:"temperature,omitempty"`
	MaxTokens   int       `json:"max_tokens,omitempty"`
	Tools       []Tool    `json:"tools,omitempty"`
}

ChatRequest is a chat-completion request.

type ChatResponse

type ChatResponse struct {
	Content   string     `json:"content"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	Model     string     `json:"model,omitempty"`
	Usage     Usage      `json:"usage"`
}

ChatResponse is a chat-completion result.

type Chunk

type Chunk struct {
	Delta string `json:"delta"`
	Done  bool   `json:"done"`
}

Chunk is a streamed delta.

type DriverFactory

type DriverFactory func(k *togo.Kernel) (Provider, error)

DriverFactory builds a Provider from the kernel/env.

type EmbedRequest

type EmbedRequest struct {
	Model  string   `json:"model,omitempty"`
	Inputs []string `json:"inputs"`
}

EmbedRequest requests embeddings for one or more inputs.

type EmbedResponse

type EmbedResponse struct {
	Vectors [][]float32 `json:"vectors"`
	Usage   Usage       `json:"usage"`
}

EmbedResponse holds the resulting vectors.

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
	Name    string `json:"name,omitempty"`
}

Message is a single chat message.

type Provider

type Provider interface {
	Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)
	Embed(ctx context.Context, req EmbedRequest) (EmbedResponse, error)
}

Provider is the LLM driver interface every ai-* provider plugin implements.

type Service

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

Service is the kernel-bound AI service.

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the AI service bound to the kernel.

func (*Service) Chat

func (s *Service) Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)

Chat performs a chat completion via the configured provider.

func (*Service) ChatStream

func (s *Service) ChatStream(ctx context.Context, req ChatRequest, onChunk func(Chunk) error) error

ChatStream streams a chat completion; falls back to a single chunk if the provider doesn't implement Streamer.

func (*Service) Driver

func (s *Service) Driver() string

Driver returns the active driver name.

func (*Service) Embed

func (s *Service) Embed(ctx context.Context, req EmbedRequest) (EmbedResponse, error)

Embed returns embeddings via the configured provider.

type Streamer

type Streamer interface {
	ChatStream(ctx context.Context, req ChatRequest, onChunk func(Chunk) error) error
}

Streamer is an optional interface for streaming chat completions.

type Tool

type Tool struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters,omitempty"`
}

Tool describes a function the model may call.

type ToolCall

type ToolCall struct {
	Name string `json:"name"`
	Args string `json:"arguments"`
}

ToolCall is a model's request to call a tool (arguments are JSON).

type Usage

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

Usage reports token consumption (consumed by the billing plugin).