GoAI

https://github.com/zendev-sh/goai
Admin
GoAI is a Go SDK for building AI applications with support for 25+ LLM providers, Model Context...
Tokens:134,573
Snippets:1,429
Trust Score:5.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start vLLM Server

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/vllm.md

Start a vLLM inference server using the command line. This example uses a specific model and port.

```bash
vllm serve meta-llama/Llama-3-8b --port 8000

```

--------------------------------

### Quick Start: Generate Text with OpenAI

Source: https://github.com/zendev-sh/goai/blob/main/README.md

Basic example of generating text using an OpenAI model. API keys are automatically read from environment variables.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/zendev-sh/goai"
	"github.com/zendev-sh/goai/provider/openai"
)

func main() {
	// Reads OPENAI_API_KEY from environment automatically.
	model := openai.Chat("gpt-4o")

	result, err := goai.GenerateText(context.Background(), model,
		goai.WithPrompt("What is the capital of France?"),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Text)
}
```

--------------------------------

### Verify Installation with OpenAI

Source: https://github.com/zendev-sh/goai/blob/main/docs/getting-started/installation.md

Create a `main.go` file to test the installation by generating text using the OpenAI provider. Ensure your API key is set as an environment variable.

```go
package main

import (
    "context"
    "fmt"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/openai"
)

func main() {
    model := openai.Chat("gpt-4o")

    result, err := goai.GenerateText(context.Background(), model,
        goai.WithPrompt("Say hello in one sentence."),
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Text)
}
```

--------------------------------

### Install GoAI

Source: https://github.com/zendev-sh/goai/blob/main/docs/compare.md

Install the GoAI library using the go get command. Ensure you are using the latest version.

```bash
go get github.com/zendev-sh/goai@latest
```

--------------------------------

### Example Message Construction and Text Generation

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/core-functions.md

This example demonstrates constructing a list of messages, including system, user, and assistant messages, before initiating a text generation request.

```go
msgs := []provider.Message{
    goai.SystemMessage("You are a helpful assistant."),
    goai.UserMessage("Hello!"),
    goai.AssistantMessage("Hi there! How can I help?"),
    goai.UserMessage("What time is it?"),
}

result, err := goai.GenerateText(ctx, model,
    goai.WithMessages(msgs...),
)
```

--------------------------------

### New Provider Initialization Example

Source: https://github.com/zendev-sh/goai/blob/main/AGENTS.md

Example of how to define a new provider's chat function and its associated methods for handling generation and streaming. This follows the pattern for adding new providers.

```go
func Chat(modelID string, opts ...Option) provider.LanguageModel { ... }

```

```go
func (m *chatModel) DoGenerate(ctx, params) (*provider.GenerateResult, error) { ... }

```

```go
func (m *chatModel) DoStream(ctx, params) (*provider.StreamResult, error) { ... }

```

--------------------------------

### Web Search Tool Examples

Source: https://github.com/zendev-sh/goai/blob/main/README.md

Examples of defining Web Search tools for different providers. Note the specific options and potential return values like grounding URLs.

```go
// OpenAI (via Responses API) - also works via Azure
def := openai.Tools.WebSearch(openai.WithSearchContextSize("medium"))
```

```go
// Anthropic (via Messages API) - also works via Bedrock
def := anthropic.Tools.WebSearch(anthropic.WithMaxUses(5))
```

```go
// Google (grounding with Google Search) - returns Sources
def := google.Tools.GoogleSearch()
// result.Sources contains grounding URLs from Google Search
```

```go
// Groq (interactive browser search)
def := groq.Tools.BrowserSearch()
```

--------------------------------

### Basic Text Generation Example

Source: https://github.com/zendev-sh/goai/blob/main/SKILL.md

Perform non-streaming text generation using the `GenerateText` function. This example sets a system prompt and a user prompt, then prints the generated text.

```go
result, err := goai.GenerateText(ctx, openai.Chat("gpt-4o"),
    goai.WithSystem("You are a helpful assistant."),
    goai.WithPrompt("What is Go?"),
)
if err != nil {
    return err
}
fmt.Println(result.Text)
```

--------------------------------

### GoAI Lifecycle Hooks Example

Source: https://context7.com/zendev-sh/goai/llms.txt

Demonstrates the usage of various GoAI lifecycle hooks for observability and interception. Includes setup for tools, model, and configuration options like WithPrompt, WithTools, WithMaxSteps, and specific hooks for request/response logging, tool call monitoring, before/after tool execution interception, and step-by-step execution control.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "strings"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/google"
)

func main() {
    ctx := context.Background()
    model := google.Chat("gemini-2.0-flash")

    readFileTool := goai.Tool{
        Name: "read_file",
        InputSchema: json.RawMessage(`{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}`),
        Execute: func(_ context.Context, input json.RawMessage) (string, error) {
            return "API_KEY=sk-secret-12345\nDB_HOST=prod.example.com", nil
        },
    }
    deleteFileTool := goai.Tool{
        Name: "delete_file",
        InputSchema: json.RawMessage(`{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}`),
        Execute: func(_ context.Context, input json.RawMessage) (string, error) {
            return "deleted", nil
        },
    }

    result, err := goai.GenerateText(ctx, model,
        goai.WithPrompt("Read the .env file, then delete temp.log."),
        goai.WithTools(readFileTool, deleteFileTool),
        goai.WithMaxSteps(5),

        // Observability: called before each API request
        goai.WithOnRequest(func(info goai.RequestInfo) {
            fmt.Printf("[REQ] model=%s msgs=%d tools=%d\n",
                info.Model, info.MessageCount, info.ToolCount)
        }),

        // Observability: called after each API response
        goai.WithOnResponse(func(info goai.ResponseInfo) {
            fmt.Printf("[RES] latency=%v tokens=%d+%d finish=%s\n",
                info.Latency, info.Usage.InputTokens, info.Usage.OutputTokens, info.FinishReason)
        }),

        // Observability: called after each tool execution
        goai.WithOnToolCall(func(info goai.ToolCallInfo) {
            status := "OK"
            if info.Skipped { status = "SKIPPED" }
            if info.Error != nil { status = "ERROR" }
            fmt.Printf("[TOOL] %s: %s (step %d, %v)\n",
                info.ToolName, status, info.Step, info.Duration)
        }),

        // Interceptor: permission gate — block dangerous tools
        goai.WithOnBeforeToolExecute(func(info goai.BeforeToolExecuteInfo) goai.BeforeToolExecuteResult {
            if info.ToolName == "delete_file" {
                return goai.BeforeToolExecuteResult{
                    Skip:   true,
                    Result: "Permission denied: delete_file is blocked.",
                }
            }
            return goai.BeforeToolExecuteResult{} // proceed normally
        }),

        // Interceptor: secret scanning — redact sensitive output before sending to LLM
        goai.WithOnAfterToolExecute(func(info goai.AfterToolExecuteInfo) goai.AfterToolExecuteResult {
            if info.Error != nil {
                return goai.AfterToolExecuteResult{}
            }
            redacted := strings.ReplaceAll(info.Output, "sk-secret-12345", "sk-***REDACTED***")
            return goai.AfterToolExecuteResult{
                Output:   redacted,
                Metadata: map[string]any{"redacted": true},
            }
        }),

        // Interceptor: inject context or stop loop between steps (step 2+ only)
        goai.WithOnBeforeStep(func(info goai.BeforeStepInfo) goai.BeforeStepResult {
            fmt.Printf("[STEP] Before step %d, %d messages in history\n",
                info.Step, len(info.Messages))
            return goai.BeforeStepResult{} // return {Stop: true} to halt
        }),

        // Observability: called once after all steps complete
        goai.WithOnFinish(func(info goai.FinishInfo) {
            status := "natural"
            if info.StepsExhausted { status = "max_steps_reached" }
            fmt.Printf("[FINISH] %s: %d steps, %d total tokens, reason=%s\n",
                status, info.TotalSteps,
                info.TotalUsage.InputTokens+info.TotalUsage.OutputTokens,
                info.FinishReason)
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("\nResult:", result.Text)
}
```

--------------------------------

### Code Execution Tool Examples

Source: https://github.com/zendev-sh/goai/blob/main/README.md

Examples for defining Code Execution tools across various providers. These tools allow the model to write and run code in a sandboxed environment.

```go
// OpenAI Code Interpreter - Python sandbox via Responses API
def := openai.Tools.CodeInterpreter()
```

```go
// Anthropic Code Execution - Python sandbox via Messages API
def := anthropic.Tools.CodeExecution() // v20260120, GA, no beta needed
```

```go
// Google Code Execution - Python sandbox via Gemini API
def := google.Tools.CodeExecution()
```

--------------------------------

### Pull and Serve Ollama Model

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/ollama.md

Before using the Ollama provider, ensure Ollama is installed and running locally. Pull a model like llama3 and then start the Ollama server.

```bash
ollama pull llama3
ollama serve
```

--------------------------------

### Run Hooks Example with Gemini

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Demonstrates lifecycle hooks for tool interception, output transformation, and loop control with Google Gemini. Requires GEMINI_API_KEY.

```bash
export GEMINI_API_KEY=...
go run examples/hooks/main.go
```

--------------------------------

### Set API Key and Run Verification

Source: https://github.com/zendev-sh/goai/blob/main/docs/getting-started/installation.md

Set the `OPENAI_API_KEY` environment variable and run the `main.go` file using `go run` to verify the installation.

```bash
export OPENAI_API_KEY="sk-..."
go run main.go
```

--------------------------------

### OpenTelemetry Setup with GoAI

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/observability.md

Install the OpenTelemetry package for GoAI and your preferred exporter. By default, `WithTracing` uses the global TracerProvider and MeterProvider, which can be overridden.

```bash
go get github.com/zendev-sh/goai/observability/otel
# Plus your preferred exporter, e.g.:
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp
go get go.opentelemetry.io/otel/sdk/trace
```

--------------------------------

### Basic Text Generation Example

Source: https://github.com/zendev-sh/goai/blob/main/SKILL.md

A simple example demonstrating how to perform non-streaming text generation using the `goai.GenerateText` function with system and prompt options.

```go
import (
    "context"
    "fmt"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/openai"
)

func main() {
    ctx := context.Background()
    result, err := goai.GenerateText(ctx, openai.Chat("gpt-4o"),
        goai.WithSystem("You are a helpful assistant."),
        goai.WithPrompt("What is Go?"),
    )
    if err != nil {
        // Handle error
        return
    }
    fmt.Println(result.Text)
}
```

--------------------------------

### Run OpenTelemetry Tracing Example

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Configures OpenTelemetry tracing with an stdout exporter for local development, compatible with Google Gemini. Requires GEMINI_API_KEY.

```bash
export GEMINI_API_KEY=...
cd examples/otel && go run .
```

--------------------------------

### Connect to MCP Server and Use Tools

Source: https://github.com/zendev-sh/goai/blob/main/docs/index.md

This example demonstrates how to connect to a Model Context Protocol (MCP) server using stdio transport, convert its tools for GoAI, and then use these tools for text generation with a specified prompt and maximum steps.

```go
transport := mcp.NewStdioTransport("npx", []string{"-y", "@modelcontextprotocol/server-github"})
client := mcp.NewClient("my-app", "1.0", mcp.WithTransport(transport))
_ = client.Connect(ctx)
defer client.Close()

tools, _ := client.ListTools(ctx, nil)
goaiTools := mcp.ConvertTools(client, tools.Tools)

result, _ := goai.GenerateText(ctx, model,
    goai.WithTools(goaiTools...),
    goai.WithPrompt("Search for popular Go repositories"),
    goai.WithMaxSteps(5),
)
```

--------------------------------

### Recipe Struct for Schema Generation Example

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/types.md

An example Go struct demonstrating how to use `json` and `jsonschema` tags to define a schema for a Recipe. This illustrates field naming, descriptions, and enumerated values.

```go
type Recipe struct {
    Name        string   `json:"name" jsonschema:"description=Recipe name"`
    Ingredients []string `json:"ingredients" jsonschema:"description=List of ingredients"`
    Steps       []string `json:"steps" jsonschema:"description=Cooking steps"`
    Difficulty  string   `json:"difficulty" jsonschema:"enum=easy|medium|hard"`
}

schema := goai.SchemaFrom[Recipe]()
```

--------------------------------

### Add OpenAI-Compatible Provider

Source: https://github.com/zendev-sh/goai/blob/main/CLAUDE.md

Example of how to add an OpenAI-compatible provider. Ensure the struct implements the LanguageModel interface and define DoGenerate and DoStream methods.

```go
var _ provider.LanguageModel = (*chatModel)(nil)

func Chat(modelID string, opts ...Option) provider.LanguageModel { ... }
func (m *chatModel) DoGenerate(ctx, params) (*provider.GenerateResult, error) { ... }
func (m *chatModel) DoStream(ctx, params) (*provider.StreamResult, error) { ... }
```

--------------------------------

### Tool Call Start Hook

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/tools.md

Implement WithOnToolCallStart to run a function before each individual tool execution. It provides information about the step, tool name, and call ID.

```go
goai.WithOnToolCallStart(func(info goai.ToolCallStartInfo) {
    fmt.Printf("[step %d] starting tool %s (call %s)\n", info.Step, info.ToolName, info.ToolCallID)
})
```

--------------------------------

### Run Langfuse Tracing Example with Gemini

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Enables Langfuse tracing for a multi-step agent with tool calls using Google Gemini. Requires API keys for Gemini and Langfuse.

```bash
export GEMINI_API_KEY=...
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
go run examples/langfuse/main.go
```

--------------------------------

### Google Service Account TokenSource Example

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/token-source.md

Sets up a TokenSource for Google Service Accounts using google.DefaultTokenSource. Note: This example is for Vertex AI provider, as the Gemini provider only accepts API keys.

```go
ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
    tokenSource, err := google.DefaultTokenSource(ctx,
        "https://www.googleapis.com/auth/cloud-platform",
    )
    if err != nil {
        return nil, err
    }
    tok, err := tokenSource.Token()
    if err != nil {
        return nil, err
    }
    return &provider.Token{
        Value:     tok.AccessToken,
        ExpiresAt: tok.Expiry,
    }, nil
})

model := vertex.Chat("gemini-2.0-flash", vertex.WithTokenSource(ts))
```

--------------------------------

### Log Tool Execution Start with OnToolCallStart Hook

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/hooks.md

The `OnToolCallStart` hook is useful for logging when a specific tool begins execution, including its name and call ID.

```go
goai.WithOnToolCallStart(func(info goai.ToolCallStartInfo) {
    log.Printf("Tool starting: %s (call %s)", info.ToolName, info.ToolCallID)
}),
```

--------------------------------

### Chat with NVIDIA NIM Model

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/nvidia.md

Example of how to initialize a chat model with NVIDIA NIM and generate text. Requires the goai and nvidia provider packages.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/zendev-sh/goai"
	"github.com/zendev-sh/goai/provider/nvidia"
)

func main() {
	model := nvidia.Chat("nvidia/llama-3.1-nemotron-70b-instruct")

	result, err := goai.GenerateText(context.Background(), model,
		goai.WithPrompt("What is the capital of France?"),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Text)
}
```

--------------------------------

### Chat with Vertex AI

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/vertex.md

Initialize a chat model with Vertex AI using a specific project and location. This example uses the gemini-2.5-pro model.

```go
model := vertex.Chat("gemini-2.5-pro",
    vertex.WithProject("my-gcp-project"),
    vertex.WithLocation("us-central1"),
)

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Explain quantum computing"))
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Text)
```

--------------------------------

### Image Generation with Vertex AI

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/vertex.md

Initialize an image generation model with Vertex AI using a specific project. This example uses the imagen-3.0-generate-002 model.

```go
imgModel := vertex.Image("imagen-3.0-generate-002",
    vertex.WithProject("my-gcp-project"),
)

result, err := goai.GenerateImage(ctx, imgModel,
    goai.WithImagePrompt("A sunset over mountains"),
    goai.WithImageCount(1),
)
```

--------------------------------

### Setup Anthropic Provider

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/anthropic.md

Initialize the Anthropic chat model. You can set the API key directly or rely on the ANTHROPIC_API_KEY environment variable. The provider also respects ANTHROPIC_BASE_URL.

```go
import "github.com/zendev-sh/goai/provider/anthropic"

model := anthropic.Chat("claude-sonnet-4-20250514", anthropic.WithAPIKey("sk-ant-..."))
```

--------------------------------

### Streaming Tool Loop with Text Output

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/streaming.md

Utilize `StreamText` with tools to create streaming tool loops. This example demonstrates handling different chunk types for text, tool calls, step boundaries, and final completion.

```go
stream, err := goai.StreamText(ctx, model,
    goai.WithPrompt("What's the weather in Tokyo and London?"),
    goai.WithTools(weatherTool),
    goai.WithMaxSteps(5),
)
if err != nil {
    log.Fatal(err)
}

for chunk := range stream.Stream() {
    switch chunk.Type {
    case provider.ChunkText:
        fmt.Print(chunk.Text)
    case provider.ChunkToolCall:
        fmt.Printf("\n[tool call: %s]\n", chunk.ToolName)
    case provider.ChunkStepFinish:
        fmt.Printf("[step done, reason=%s]\n", chunk.FinishReason)
    case provider.ChunkFinish:
        fmt.Printf("\n[finished, tokens=%d]\n", chunk.Usage.TotalTokens)
    }
}

if err := stream.Err(); err != nil {
    log.Fatal("stream error:", err)
}

result := stream.Result()
fmt.Printf("Completed in %d steps\n", len(result.Steps))
```

--------------------------------

### Production OpenTelemetry Setup with OTLP Exporter

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/observability.md

Configure an OTLP exporter for production environments, setting the endpoint and authorization headers. Ensure the TracerProvider is shut down when the application exits.

```go
import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

exporter, err := otlptracehttp.New(ctx,
    otlptracehttp.WithEndpoint("tempo.example.com:4318"),
    otlptracehttp.WithHeaders(map[string]string{
        "Authorization": "Bearer <API_KEY>",
    }),
)
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
deferr tp.Shutdown(ctx)
otel.SetTracerProvider(tp)
```

--------------------------------

### Use Provider-Defined Tools (Web Search, Code Interpreter, etc.)

Source: https://context7.com/zendev-sh/goai/llms.txt

Providers expose built-in tools that execute server-side. Use `<provider>.Tools.ToolName(opts...)` to create a definition, then wrap it as a `goai.Tool`. This example demonstrates Anthropic web search, OpenAI code interpreter, and Google Search.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/anthropic"
    "github.com/zendev-sh/goai/provider/openai"
    "github.com/zendev-sh/goai/provider/google"
)

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

    // Anthropic web search
    antModel := anthropic.Chat("claude-sonnet-4-20250514")
    wsDef := anthropic.Tools.WebSearch(anthropic.WithMaxUses(3))
    result, err := goai.GenerateText(ctx, antModel,
        goai.WithPrompt("What are the latest Go 1.25 features?"),
        goai.WithTools(goai.Tool{
            Name:                   wsDef.Name,
            ProviderDefinedType:    wsDef.ProviderDefinedType,
            ProviderDefinedOptions: wsDef.ProviderDefinedOptions,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Anthropic web search:", result.Text[:200])

    // OpenAI code interpreter
    oaiModel := openai.Chat("gpt-4o")
    ciDef := openai.Tools.CodeInterpreter()
    result2, err := goai.GenerateText(ctx, oaiModel,
        goai.WithPrompt("Calculate the first 10 Fibonacci numbers and plot them."),
        goai.WithTools(goai.Tool{
            Name:                   ciDef.Name,
            ProviderDefinedType:    ciDef.ProviderDefinedType,
            ProviderDefinedOptions: ciDef.ProviderDefinedOptions,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("OpenAI code interpreter:", result2.Text[:200])

    // Google Search grounding (returns Sources with URLs)
    gModel := google.Chat("gemini-2.5-flash")
    gsDef := google.Tools.GoogleSearch()
    result3, err := goai.GenerateText(ctx, gModel,
        goai.WithPrompt("What happened in tech news today?"),
        goai.WithTools(goai.Tool{
            Name:                   gsDef.Name,
            ProviderDefinedType:    gsDef.ProviderDefinedType,
            ProviderDefinedOptions: gsDef.ProviderDefinedOptions,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    for _, src := range result3.Sources {
        fmt.Printf("  [%s] %s\n", src.Type, src.URL)
    }
}
```

--------------------------------

### Get TextStream Result

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/core-functions.md

Call after streaming to get the final accumulated text and usage information. Can also be used to silently consume a stream.

```go
func (ts *TextStream) Result() *TextResult
```

--------------------------------

### Connect to MCP Server and List Tools

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/mcp.md

Connects to a local MCP server using the stdio transport, lists available tools, and prints their names and descriptions. Ensure the context is properly managed and the client is closed when done.

```go
import "github.com/zendev-sh/goai/mcp"

// Create a client and connect via stdio transport.
client := mcp.NewClient("my-app", "1.0",
    mcp.WithTransport(mcp.NewStdioTransport("npx", []string{"-y", "@modelcontextprotocol/server-filesystem", "/tmp"})),
)
if err := client.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer client.Close()

// List available tools.
result, err := client.ListTools(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, tool := range result.Tools {
    fmt.Printf("%s - %s\n", tool.Name, tool.Description)
}
```

--------------------------------

### Instantiate Language Models

Source: https://github.com/zendev-sh/goai/blob/main/SKILL.md

Create instances of language models from various providers like OpenAI, Anthropic, Google, and others. Some providers offer specific options for configuration.

```go
// Language models
openai.Chat("gpt-4o")
anthropic.Chat("claude-sonnet-4-20250514")
google.Chat("gemini-2.5-flash")
bedrock.Chat("anthropic.claude-sonnet-4-20250514-v1:0")
azure.Chat("gpt-4o", azure.WithEndpoint("https://my-resource.openai.azure.com"))
vertex.Chat("gemini-2.5-flash", vertex.WithProject("my-project"), vertex.WithLocation("us-central1"))
groq.Chat("llama-3.3-70b-versatile")
ollama.Chat("llama3.2")
```

--------------------------------

### Build Project

Source: https://github.com/zendev-sh/goai/blob/main/CONTRIBUTING.md

Compile the Go project to ensure it builds successfully.

```bash
go build ./...
```

--------------------------------

### Run Local MCP Client Basics

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Exercises MCP client capabilities like listing tools, prompts, and resources without an LLM. Requires a local MCP test server.

```bash
go run ./examples/mcp-local/main.go
```

--------------------------------

### Get ObjectStream Error

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/core-functions.md

Returns the first error encountered during streaming. Must be called after the stream is fully consumed.

```go
func (os *ObjectStream[T]) Err() error
```

--------------------------------

### Get TextStream Error

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/core-functions.md

Retrieve the first error encountered during streaming. Must be called after the stream is fully consumed.

```go
func (ts *TextStream) Err() error
```

--------------------------------

### Import Other Providers

Source: https://github.com/zendev-sh/goai/blob/main/docs/getting-started/installation.md

Import specific provider packages as needed. For example, import Anthropic, Google, or Bedrock providers.

```go
import "github.com/zendev-sh/goai/provider/anthropic"
import "github.com/zendev-sh/goai/provider/google"
import "github.com/zendev-sh/goai/provider/bedrock"
```

--------------------------------

### Generate Embeddings with Ollama

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/ollama.md

Create embeddings for text using a local Ollama model. This example uses the 'nomic-embed-text' model.

```go
embedModel := ollama.Embedding("nomic-embed-text")

result, err := goai.Embed(ctx, embedModel, "hello world")
```

--------------------------------

### Checking for a specific error type

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/errors.md

Example of how to check for specific error types like ContextOverflowError or APIError using errors.As.

```APIDOC
### Checking for a specific error type

```go
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("..."),
)
if err != nil {
    var overflow *goai.ContextOverflowError
    if errors.As(err, &overflow) {
        // Prompt too long - truncate conversation and retry.
        fmt.Println("Context overflow:", overflow.Message)
        return
    }

    var apiErr *goai.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error %d: %s (retryable: %v)\\n",
            apiErr.StatusCode, apiErr.Message, apiErr.IsRetryable)
        return
    }

    // Other errors (network, context cancelled, etc.)
    log.Fatal(err)
}
```
```

--------------------------------

### Import Core SDK and OpenAI Provider

Source: https://github.com/zendev-sh/goai/blob/main/docs/getting-started/installation.md

Import the core GoAI SDK and the OpenAI provider package. Each provider has its own sub-package under `provider/`.

```go
import (
    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/openai"
)
```

--------------------------------

### Generate Image with Imagen

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/google.md

Generate images using Google's Imagen models. This example uses the fast generation variant.

```go
import (
    "context"
    "fmt"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/google"
)

model := google.Image("imagen-4.0-fast-generate-001")
result, err := goai.GenerateImage(context.Background(), model,
    goai.WithImagePrompt("A serene mountain lake at sunset"),
)
if err != nil {
    panic(err)
}
fmt.Printf("Generated %d bytes\n", len(result.Images[0].Data))
```

--------------------------------

### Embeddings with Vertex AI

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/vertex.md

Initialize an embedding model with Vertex AI using a specific project. This example uses the text-embedding-004 model.

```go
embedModel := vertex.Embedding("text-embedding-004",
    vertex.WithProject("my-gcp-project"),
)

result, err := goai.Embed(ctx, embedModel, "hello world")
```

--------------------------------

### Generate Embeddings

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/bedrock.md

Examples of generating single and batch embeddings using Bedrock embedding models like Amazon Titan and Cohere.

```APIDOC
## Generate Embeddings

### Description
This section shows how to generate embeddings for text using Bedrock's embedding models. It covers both single text embedding and batch embedding generation.

### Single Embedding
```go
model := bedrock.Embedding("amazon.titan-embed-text-v2:0")
result, err := goai.Embed(context.Background(), model, "hello world")
fmt.Println(result.Embedding) // []float64
```

### Batch Embeddings
`EmbedMany` is used for batch embeddings and automatically handles chunking and parallelization for supported models.

```go
model = bedrock.Embedding("cohere.embed-english-v3")
results, err := goai.EmbedMany(context.Background(), model, []string{"foo", "bar", "baz"})
```

### Supported Embedding Models

| Model ID |
|---| 
| `amazon.titan-embed-text-v1` |
| `amazon.titan-embed-text-v2:0` |
| `amazon.titan-embed-image-v1` |
| `amazon.nova-2-multimodal-embeddings-v1:0` |
| `cohere.embed-english-v3` |
| `cohere.embed-multilingual-v3` |
| `cohere.embed-v4:0` |
| `twelvelabs.marengo-embed-2-7-v1:0` |
| `twelvelabs.marengo-embed-3-0-v1:0` |

Embeddings are generated using the `InvokeModel` API and share the same credentials and options as `bedrock.Chat`.
```

--------------------------------

### Run Multi-Step Agent Loop with Multiple Tools

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Demonstrates a multi-step agent loop involving multiple tools and callbacks for step/tool-call events. Supports history tracking and setting max steps. Requires setting the GEMINI_API_KEY environment variable.

```bash
export GEMINI_API_KEY=...
go run examples/agent-loop/main.go
```

--------------------------------

### Execute Custom Tools in Single Step

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Demonstrates a single-step tool call with a custom tool definition and `Execute` handler. Supports JSON Schema for input and setting max steps. Requires setting the GEMINI_API_KEY environment variable.

```bash
export GEMINI_API_KEY=...
go run examples/tools/main.go
```

--------------------------------

### TokenSource Interface Definition

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/token-source.md

Defines the TokenSource interface with a single method to retrieve a token. Providers use this to get credentials before each API request.

```go
type TokenSource interface {
    Token(ctx context.Context) (string, error)
}
```

--------------------------------

### Instantiate Image Generation Models

Source: https://github.com/zendev-sh/goai/blob/main/SKILL.md

Create instances of image generation models from providers like OpenAI and Google.

```go
// Image models
openai.Image("gpt-image-1")
google.Image("imagen-4.0-generate-001")
```

--------------------------------

### Benchmark Reproduction Commands

Source: https://github.com/zendev-sh/goai/blob/main/bench/RESULTS.md

Commands to reproduce the benchmarks and generate reports. Use 'make bench-all' to run both Go and TS benchmarks and create a single-run report, or 'make bench-3x' for three independent runs averaged into RESULTS.md.

```bash
cd goai/bench
make bench-all    # runs both Go + TS benchmarks and generates single-run report
make bench-3x     # 3 independent runs, averaged into RESULTS.md
make bench-go     # Go only
make bench-ts     # TS only
make report       # regenerate single-run report from existing results
```

--------------------------------

### Chat with Ollama Model

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/ollama.md

Generate text using a local Ollama model for chat. This example uses the 'llama3' model and a simple prompt.

```go
model := ollama.Chat("llama3")

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Text)
```

--------------------------------

### Azure Managed Identity TokenSource Example

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/token-source.md

Configures a TokenSource for Azure Managed Identity using azidentity.NewDefaultAzureCredential. It fetches tokens with specified scopes.

```go
ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return nil, err
    }
    token, err := cred.GetToken(ctx, policy.TokenRequestOptions{
        Scopes: []string{"https://cognitiveservices.azure.com/.default"},
    })
    if err != nil {
        return nil, err
    }
    return &provider.Token{
        Value:     token.Token,
        ExpiresAt: token.ExpiresOn,
    }, nil
})

model := azure.Chat("gpt-4o", azure.WithTokenSource(ts))
```

--------------------------------

### Configure Model with Token Source

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/providers-and-models.md

Use a dynamic token source, such as OAuth or service accounts, for authentication.

```go
model := openai.Chat("gpt-4o", openai.WithTokenSource(myTokenSource))
```

--------------------------------

### OnAfterToolExecute: Redact Secrets

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/hooks.md

Use OnAfterToolExecute to transform tool output. This example redacts secrets from the output before it's sent back to the LLM.

```go
goai.WithOnAfterToolExecute(func(info goai.AfterToolExecuteInfo) goai.AfterToolExecuteResult {
    if info.Error != nil {
        return goai.AfterToolExecuteResult{} // don't modify errors
    }
    // Redact secrets from tool output
    redacted := secretScanner.Scan(info.Output)
    if redacted != info.Output {
        return goai.AfterToolExecuteResult{Output: redacted}
    }
    return goai.AfterToolExecuteResult{} // no change
}),

```

--------------------------------

### Run Basic Chat Generation

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Demonstrates simple non-streaming text generation using `GenerateText`. Requires setting the GEMINI_API_KEY environment variable.

```bash
export GEMINI_API_KEY=...
go run examples/chat/main.go
```

--------------------------------

### Integrate MCP Client with GoAI

Source: https://context7.com/zendev-sh/goai/llms.txt

Shows how to use the MCP client to connect to an MCP server via stdio or HTTP. It demonstrates listing tools, converting them to GoAI's format, and using them in a text generation call. Requires the MCP server to be running.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/mcp"
    "github.com/zendev-sh/goai/provider/google"
)

func main() {
    ctx := context.Background()
    model := google.Chat("gemini-2.0-flash", google.WithAPIKey(os.Getenv("GEMINI_API_KEY")))

    // Connect to MCP server via stdio transport
    transport := mcp.NewStdioTransport("npx", []string{
        "-y", "@modelcontextprotocol/server-filesystem", ".",
    })
    client := mcp.NewClient("my-app", "1.0.0",
        mcp.WithTransport(transport),
        mcp.WithRequestTimeout(30*1e9),
    )
    if err := client.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    fmt.Printf("Connected to %s (protocol %s)\n",
        client.ServerInfo().Name, client.ProtocolVersion())

    // List all tools with pagination
    toolsResult, err := client.ListTools(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    allTools := toolsResult.Tools
    for toolsResult.NextCursor != "" {
        toolsResult, err = client.ListTools(ctx, &mcp.ListParams{Cursor: toolsResult.NextCursor})
        if err != nil {
            log.Fatal(err)
        }
        allTools = append(allTools, toolsResult.Tools...)
    }

    // Convert MCP tools → GoAI tools and use in LLM call
    goaiTools := mcp.ConvertTools(client, allTools)
    fmt.Printf("Available tools: %d\n", len(goaiTools))

    result, err := goai.GenerateText(ctx, model,
        goai.WithPrompt("List the Go source files in the current directory."),
        goai.WithTools(goaiTools...),
        goai.WithMaxSteps(5),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text)

    // Connect to HTTP MCP server
    httpTransport := mcp.NewHTTPTransport("https://mcp.example.com/mcp",
        mcp.WithHTTPHeader("Authorization", "Bearer "+os.Getenv("MCP_API_KEY")),
    )
    _ = httpTransport
}
```

--------------------------------

### Streaming Text with Tools

Source: https://github.com/zendev-sh/goai/blob/main/README.md

Demonstrates streaming AI responses while utilizing tools for specific actions. Limits the number of execution steps.

```go
import "github.com/zendev-sh/goai/provider"

stream, err := goai.StreamText(ctx, model,
	goai.WithPrompt("What's the weather in Tokyo?"),
	goai.WithTools(weatherTool),
	goai.WithMaxSteps(5),
)
for chunk := range stream.Stream() {
	switch chunk.Type {
	case provider.ChunkText:
		fmt.Print(chunk.Text)
	case provider.ChunkStepFinish:
		fmt.Println("\n[step complete]")
	}
}
```

--------------------------------

### Get ObjectStream Result

Source: https://github.com/zendev-sh/goai/blob/main/docs/api/core-functions.md

Blocks until the stream completes and returns the final validated object. Returns an error if JSON parsing of the accumulated text fails.

```go
func (os *ObjectStream[T]) Result() (*ObjectResult[T], error)
```

--------------------------------

### Configure Multiple Providers

Source: https://github.com/zendev-sh/goai/blob/main/docs/getting-started/quick-start.md

Import multiple provider packages to use different LLM services. Each provider follows the same pattern for model instantiation.

```go
import "github.com/zendev-sh/goai/provider/groq"
import "github.com/zendev-sh/goai/provider/mistral"
import "github.com/zendev-sh/goai/provider/deepseek"

groqModel := groq.Chat("llama-3.3-70b-versatile")
mistralModel := mistral.Chat("mistral-large-latest")
deepseekModel := deepseek.Chat("deepseek-chat")
```

--------------------------------

### StreamText Workflow (Multi-step)

Source: https://github.com/zendev-sh/goai/blob/main/docs/architecture.md

Explains the multi-step path for streaming text generation when tools are involved, highlighting the `streamWithToolLoop` and the step-by-step execution.

```go
User calls goai.StreamText(ctx, model, opts...)
  │
  ├─ Multi-step path (MaxSteps > 1 and executable tools):
  │   └─ streamWithToolLoop(ctx, model, opts, toolMap)
  │       ├─ Launch step loop goroutine
  │       │   ├─ for step = 1..MaxSteps:
  │       │   │   ├─ model.DoStream(ctx, params)
  │       │   │   ├─ drainStep: forward chunks to unified output channel
  │       │   │   ├─ if FinishReason == ToolCalls:
  │       │   │   │   ├─ executeToolsParallel(ctx, calls, toolMap, step, toolHooks{...})
  │       │   │   │   └─ appendToolRoundTrip(msgs, text, toolCalls, toolMsgs)
  │       │   │   └─ else: break
  │       │   └─ close unified output channel
  │       └─ Wrap in TextStream
```

--------------------------------

### Chat with Anthropic Claude Sonnet

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/bedrock.md

Example of using the bedrock provider to chat with an Anthropic Claude Sonnet model, including extended reasoning configuration.

```APIDOC
## Chat with Anthropic Claude Sonnet

### Description
This example demonstrates how to initialize a chat model with Anthropic Claude Sonnet and configure extended reasoning capabilities.

### Method Signature
```go
model := bedrock.Chat("anthropic.claude-sonnet-4-20250514-v1:0", bedrock.WithReasoningConfig(bedrock.ReasoningConfig{ Type: bedrock.ReasoningEnabled, BudgetTokens: 8192 }))
result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Solve this step by step: What is 127 * 43?"))
```

### Options
Several options can be used to configure the Bedrock provider, including AWS credentials, region, and custom endpoints. The `WithReasoningConfig` option is specifically used here to enable extended thinking.

#### `WithReasoningConfig`
```go
type ReasoningConfig struct {
    Type               ReasoningType
    BudgetTokens       int
    MaxReasoningEffort ReasoningEffort
}
```

This configuration can also be passed per-request using `WithProviderOptions`.
```

--------------------------------

### WebFetch Tool Configuration

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/anthropic.md

Utilize the WebFetch tool to retrieve URL content, with options to enable citations and set maximum content tokens.

```go
def := anthropic.Tools.WebFetch(
    anthropic.WithCitations(true),
    anthropic.WithMaxContentTokens(4096),
)
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Summarize the content at https://go.dev/blog"),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

--------------------------------

### Configure NVIDIA NIM with API Key and Base URL

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/nvidia.md

Demonstrates how to explicitly set the API key and base URL for the NVIDIA NIM provider. This is useful for overriding environment variables or using custom endpoints.

```go
model := nvidia.Chat("nvidia/llama-3.1-nemotron-70b-instruct",
	nvidia.WithAPIKey("nvapi-..."),
	nvidia.WithBaseURL("https://custom.endpoint.com/v1"),
)
```

--------------------------------

### Go Build and Test Commands

Source: https://github.com/zendev-sh/goai/blob/main/AGENTS.md

Common commands for building, testing, linting, and testing specific packages within the GoAI project.

```bash
go build ./...

```

```bash
go test ./...

```

```bash
go test -cover ./...

```

```bash
golangci-lint run

```

```bash
go test ./provider/openai/

```

--------------------------------

### OnBeforeToolExecute: Skip Dangerous Tools

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/hooks.md

Use OnBeforeToolExecute to implement a permission gate. This example skips the 'delete_file' tool and returns a synthetic result to the LLM.

```go
result, _ := goai.GenerateText(ctx, model,
    goai.WithPrompt("Delete the temp files and read the config"),
    goai.WithMaxSteps(5),
    goai.WithTools(readFile, deleteFile),
    goai.WithOnBeforeToolExecute(func(info goai.BeforeToolExecuteInfo) goai.BeforeToolExecuteResult {
        // Block dangerous tools
        if info.ToolName == "delete_file" {
            return goai.BeforeToolExecuteResult{
                Skip:   true,
                Result: "Permission denied: delete operations are not allowed.",
            }
        }
        return goai.BeforeToolExecuteResult{} // allow
    }),
)

```

--------------------------------

### Initialize AI Models with GoAI

Source: https://github.com/zendev-sh/goai/blob/main/docs/compare.md

Demonstrates initializing chat models from different providers like OpenAI, Anthropic, Google Gemini, and AWS Bedrock. All initialized models can be used with the same GoAI functions, such as `GenerateText`.

```go
// OpenAI
model := openai.Chat("gpt-4o")

// Anthropic
model := anthropic.Chat("claude-sonnet-4-20250514")

// Google Gemini
model := google.Chat("gemini-2.5-flash")

// AWS Bedrock
model := bedrock.Chat("anthropic.claude-sonnet-4-20250514-v1:0")

// All use the same GoAI functions:
result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
```

--------------------------------

### Generate Text with Cerebras Model

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/cerebras.md

Example of generating text using a Cerebras Llama model. Ensure the CEREBRAS_API_KEY environment variable is set or use WithAPIKey().

```go
model := cerebras.Chat("llama3.1-8b")

result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Text)
```

--------------------------------

### Interface Compliance Check Example

Source: https://github.com/zendev-sh/goai/blob/main/CLAUDE.md

This Go code demonstrates how to ensure a struct implements a specific interface at compile time. The type name may vary.

```go
var _ provider.LanguageModel = (*chatModel)(nil)
```

--------------------------------

### Import MiniMax Provider

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/minimax.md

Import the MiniMax provider package into your Go project. This is necessary before initializing any MiniMax models.

```go
import "github.com/zendev-sh/goai/provider/minimax"
```

--------------------------------

### Configure OpenAI FileSearch Tool

Source: https://github.com/zendev-sh/goai/blob/main/docs/concepts/provider-tools.md

Configure the FileSearch tool with vector store IDs and a maximum number of results for semantic search over uploaded files. Ensure the `openai` package is imported.

```go
td := openai.Tools.FileSearch(
    openai.WithVectorStoreIDs("vs_abc123"),
    openai.WithMaxNumResults(10),
)
```

--------------------------------

### Generate Structured Output with Go Generics

Source: https://github.com/zendev-sh/goai/blob/main/SKILL.md

Use GenerateObject with Go generics to get structured output directly. The SDK auto-generates a JSON schema from struct tags.

```go
type Recipe struct {
    Name        string   `json:"name" jsonschema:"description=Recipe name"
    Ingredients []string `json:"ingredients"
    Steps       []string `json:"steps"
    Difficulty  string   `json:"difficulty" jsonschema:"enum=easy|medium|hard"
}

result, err := goai.GenerateObject[Recipe](ctx, openai.Chat("gpt-4o"),
    goai.WithPrompt("Chocolate chip cookies recipe"),
)
if err != nil {
    return err
}
fmt.Println(result.Object.Name)       // typed access
fmt.Println(result.Object.Difficulty)  // "easy", "medium", or "hard"
```

--------------------------------

### Run Filesystem MCP Server Integration

Source: https://github.com/zendev-sh/goai/blob/main/docs/examples.md

Integrates with a filesystem MCP server via stdio, listing available tools and calling list_directory. Requires Node.js (npx).

```bash
go run ./examples/mcp-filesystem/main.go /tmp
```

--------------------------------

### Generate Text with Bedrock Chat Model

Source: https://github.com/zendev-sh/goai/blob/main/docs/providers/bedrock.md

Use the GenerateText function to get a response from a configured Bedrock chat model. Ensure necessary imports and context are provided.

```go
import (
    "context"
    "fmt"

    "github.com/zendev-sh/goai"
    "github.com/zendev-sh/goai/provider/bedrock"
)

func main() {
    model := bedrock.Chat("anthropic.claude-sonnet-4-20250514-v1:0")
    result, err := goai.GenerateText(context.Background(), model,
        goai.WithPrompt("Explain Go interfaces in one paragraph."),
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Text)
}
```
Tokens:
Raw