goai: Instructions file for Codex

AGENTS.md - GoAI

Instructions for AI contributors working on the GoAI codebase.

Commands

go build ./...          # Build
go test ./...           # Test all packages
go test -cover ./...    # Test with coverage
golangci-lint run       # Lint
go test ./provider/openai/  # Test single package

Architecture

GoAI is a Go SDK for AI applications - one API across 25+ LLM providers. Inspired by Vercel AI SDK, adapted to Go idioms.

goai/
├── generate.go             # GenerateText, StreamText
├── object.go               # GenerateObject[T], StreamObject[T]
├── embed.go                # Embed, EmbedMany
├── image.go                # GenerateImage
├── video.go                # GenerateVideo
├── realtime.go             # OpenRealtimeSession (experimental realtime voice sessions)
├── options.go              # WithPrompt, WithTools, etc.
├── schema.go               # SchemaFrom[T] - JSON Schema from Go structs
├── errors.go               # APIError, ContextOverflowError
├── retry.go                # Exponential backoff (errors.As, not type assertion)
├── caching.go              # Prompt cache control (copies msgs, no mutation)
├── types.go                # Tool struct
├── messages.go             # Message builders
├── hooks.go                # Telemetry hooks
├── partial_json.go         # Partial JSON parser for streaming
├── provider/
│   ├── provider.go         # LanguageModel, EmbeddingModel, ImageModel, VideoModel, RealtimeModel interfaces
│   ├── realtime.go         # Realtime audio formats, params, events, capabilities
│   ├── types.go            # Message, Part, Usage, StreamChunk
│   ├── token.go            # TokenSource, CachedTokenSource (lock-free fetch)
│   ├── openai/             # OpenAI (Chat Completions + Responses API)
│   ├── anthropic/          # Anthropic (Messages API)
│   ├── google/             # Google Gemini (REST + Live realtime)
│   ├── bedrock/            # AWS Bedrock (Converse API + SigV4 + EventStream, RWMutex for fallback; InvokeModel API for embeddings)
│   ├── vertex/             # Vertex AI
│   ├── azure/              # Azure OpenAI
│   ├── cohere/             # Cohere (Chat v2 + Embed)
│   ├── minimax/            # MiniMax (Anthropic-compat, delegates to anthropic/)
│   ├── compat/             # Generic OpenAI-compatible
│   └── <22 more>/          # Mostly OpenAI-compat (some via compat/ or anthropic/ wrappers)
│ # tools.go files: 5 files with provider-defined tools: anthropic/ (14 tools), openai/ (4 tools), google/ (5 tools), xai/ (2 tools), groq/ (1 tool)
├── internal/
│   ├── openaicompat/       # Shared codec for 22 provider implementation files
│   ├── gemini/             # Schema sanitization (Vertex, Google)
│   ├── sse/                # SSE parser
│   ├── httpc/              # HTTP helpers + ParseDataURL
│   └── realtimews/         # Provider-neutral WebSocket transport for realtime adapters
├── mcp/                    # MCP (Model Context Protocol) client
├── observability/
│   ├── langfuse/           # Langfuse observability integration (separate go.mod)
│   └── otel/               # OpenTelemetry tracing and metrics (separate go.mod)
├── examples/               # 33 runnable examples (including 8 MCP examples)
└── bench/                  # Performance benchmarks (GoAI vs Vercel AI SDK)