bucephalus

Bucephalus

A Go LLM client library that provides a unified API across multiple providers (OpenAI, Anthropic, Gemini).

Installation

go get github.com/i2y/bucephalus

Quick Start

package main

import (
    "context"
    "fmt"

    _ "github.com/i2y/bucephalus/anthropic"
    "github.com/i2y/bucephalus/llm"
)

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

    resp, err := llm.Call(ctx, "Hello, world!",
        llm.WithProvider("anthropic"),
        llm.WithModel("claude-sonnet-4-5-20250929"),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(resp.Text())
}

Features

Basic Calls

// Simple call
resp, _ := llm.Call(ctx, "What is Go?",
    llm.WithProvider("openai"),
    llm.WithModel("o4-mini"),
)
fmt.Println(resp.Text())

// Call with message array
messages := []llm.Message{
    llm.SystemMessage("You are a helpful assistant."),
    llm.UserMessage("Hello!"),
}
resp, _ := llm.CallMessages(ctx, messages, opts...)

Structured Output

type Recipe struct {
    Name        string   `json:"name"`
    Ingredients []string `json:"ingredients"`
}

resp, _ := llm.CallParse[Recipe](ctx, "Give me a pasta recipe", opts...)
recipe, _ := resp.Parsed()
fmt.Println(recipe.Name)

Streaming

stream, _ := llm.CallStream(ctx, "Tell me a story", opts...)
for chunk, err := range stream {
    if err != nil {
        break
    }
    fmt.Print(chunk.Text())
}

Multi-turn Conversations (Resume)

resp1, _ := llm.Call(ctx, "Recommend a book", opts...)
fmt.Println(resp1.Text())

// Continue the conversation
resp2, _ := resp1.Resume(ctx, "Why did you recommend that?")
fmt.Println(resp2.Text())

Tool Calling

weatherTool := llm.NewTool(
    "get_weather",
    "Get weather for a city",
    func(ctx context.Context, args struct{ City string }) (string, error) {
        return fmt.Sprintf("Weather in %s: Sunny, 22°C", args.City), nil
    },
)

resp, _ := llm.Call(ctx, "What's the weather in Tokyo?",
    llm.WithTools(weatherTool),
    opts...,
)

if resp.HasToolCalls() {
    results, _ := llm.ExecuteToolCalls(ctx, resp.ToolCalls(), registry)
    resp2, _ := resp.ResumeWithToolOutputs(ctx, results)
    fmt.Println(resp2.Text())
}

Built-in Tools

The tools package provides ready-to-use tools for common operations.

import "github.com/i2y/bucephalus/tools"

// Use all built-in tools
resp, _ := llm.Call(ctx, "Find all Go files with 'TODO' comments",
    llm.WithProvider("anthropic"),
    llm.WithModel("claude-sonnet-4-5-20250929"),
    llm.WithTools(tools.AllTools()...),
)

// Use specific tool groups
resp, _ := llm.Call(ctx, "Read the README.md file",
    llm.WithTools(tools.FileTools()...),
)

// Search Wikipedia
resp, _ := llm.Call(ctx, "What is Go programming language?",
    llm.WithTools(tools.KnowledgeTools()...),
)

Available Tools:

Tool Groups:

MCP Integration

Integrate with Model Context Protocol servers using the official Go SDK.

import "github.com/i2y/bucephalus/mcp"

// Get tools from an MCP server
tools, cleanup, err := mcp.ToolsFromMCP(ctx, "./my-mcp-server", nil)
if err != nil {
    return err
}
defer cleanup()

// Use MCP tools with LLM
resp, _ := llm.Call(ctx, "List files in current directory",
    llm.WithProvider("openai"),
    llm.WithModel("o4-mini"),
    llm.WithTools(tools...),
)

Plugin Support (Claude Code-style)

Load plugins using a directory structure similar to Claude Code.

import "github.com/i2y/bucephalus/plugin"

p, _ := plugin.Load("./my-plugin")

// Command expansion with $ARGUMENTS substitution
expanded, _ := p.ExpandCommand("/translate Hello World")
resp, _ := llm.Call(ctx, expanded.Arguments, expanded.ToOption())

// Auto-detect slash commands
opt, userMsg, _ := p.ProcessInput("/greet John")
resp, _ := llm.Call(ctx, userMsg, opt, otherOpts...)

// Use skill context
skill := p.GetSkill("code-review")
resp, _ := llm.Call(ctx, "Review this code", skill.ToOption())

// Run agent with conversation context
agent := p.GetAgent("helper")
runner := agent.NewRunner(
    plugin.WithAgentProvider("anthropic"),
    plugin.WithAgentModel("claude-sonnet-4-5-20250929"),
    plugin.WithAgentTools(tools...),  // Filtered by agent.Tools
    // Pass additional llm.Options for all Run() calls
    plugin.WithAgentLLMOptions(
        llm.WithTopP(0.9),
        llm.WithSystemMessage(p.SkillsIndexSystemMessage()),
    ),
)

// Multi-turn conversation - context is maintained across calls
resp1, _ := runner.Run(ctx, "My name is Alice")
resp2, _ := runner.Run(ctx, "What is my name?")  // Remembers "Alice"

// Pass options for a specific Run() call only
resp3, _ := runner.Run(ctx, "Help me with this task",
    plugin.WithRunSystemMessage("Extra context for this call"),
    plugin.WithRunLLMOptions(llm.WithTemperature(0.5)),
)

// Access conversation history and state
history := runner.Context().History()
runner.Context().SetState("user_id", 123)
runner.ClearHistory()  // Clear conversation, keep state

// Progressive Disclosure (Claude Code style)
// Include only metadata in system prompt, load full content when needed
indexMsg := p.PluginIndexSystemMessage()  // ~60% smaller than full content
resp, _ := llm.Call(ctx, "Help me with code quality",
    llm.WithSystemMessage(indexMsg),  // Compact skills/commands list
)

Supported structure:

• .claude-plugin/plugin.json - Manifest
• commands/*.md - Slash commands (with $ARGUMENTS substitution)
• agents/*.md - Sub-agents (with conversation context)
• skills/*/SKILL.md - Skills

Options

LLM Call Options

AgentRunner Options

Run Options (per-call)

Package Structure

llm/          # Public API
provider/     # Provider interface
openai/       # OpenAI implementation
anthropic/    # Anthropic implementation
gemini/       # Google Gemini implementation
schema/       # JSON schema generation
mcp/          # Model Context Protocol integration (official Go SDK)
plugin/       # Claude Code Plugin loader
tools/        # Built-in tools (Read, Write, Glob, Grep, Bash, Web)

License

MIT