### Run Google Search Example

Source: https://goai.sh/examples

Executes the Google Search grounding example with Gemini.

```bash
export GEMINI_API_KEY=...
go run examples/google-search/main.go
```

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

### Run Tools Example

Source: https://goai.sh/examples

Executes the single-step tool call example using Google Gemini.

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

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

### Run Anthropic computer-use example

Source: https://goai.sh/examples

Sets the API key and executes the computer-use tool example.

```bash
export ANTHROPIC_API_KEY=...
go run examples/computer-use/main.go anthropic
```

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

### Run Web Fetch Example

Source: https://goai.sh/examples

Executes the web fetch tool example using Anthropic.

```bash
export ANTHROPIC_API_KEY=...
go run examples/web-fetch/main.go anthropic
```

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

### Run Multi-turn Tools Example

Source: https://goai.sh/examples

Executes the multi-turn conversation example with tool usage using Google Gemini.

```bash
export GEMINI_API_KEY=...
go run examples/multi-turn/main.go
```

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

### Run Web Search Example

Source: https://goai.sh/examples

Executes the web search example across OpenAI, Anthropic, and Google providers.

```bash
export OPENAI_API_KEY=...
go run examples/web-search/main.go openai

export ANTHROPIC_API_KEY=...
go run examples/web-search/main.go anthropic

export GEMINI_API_KEY=...
go run examples/web-search/main.go google
```

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

### Run Streaming Example

Source: https://goai.sh/examples

Executes the streaming text generation example using Google Gemini.

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

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

### Switching to Other Providers

Source: https://goai.sh/getting-started/quick-start

Example of initializing models from multiple other providers.

```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")
```

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

### Verify Installation with main.go

Source: https://goai.sh/getting-started/installation.html

Create a main.go file to test the SDK functionality.

```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)
}
```

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

### Run Chat Example

Source: https://goai.sh/examples

Executes the non-streaming text generation example using Google Gemini.

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

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

### Install GoAI SDK

Source: https://goai.sh/compare

Command to install the GoAI SDK package.

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

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

### Run Structured Output Example

Source: https://goai.sh/examples

Executes the structured output example using typed Go structs with Google Gemini.

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

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

### Run Agent Loop Example

Source: https://goai.sh/examples

Executes the multi-step agent loop example with multiple tools using Google Gemini.

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

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

### Run Citations Example

Source: https://goai.sh/examples

Executes the grounded AI response example to access sources using Google Gemini.

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

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

### Run OpenAI file-search example

Source: https://goai.sh/examples

Sets the API key and executes the file search tool example. Requires a pre-created vector store ID.

```bash
export OPENAI_API_KEY=...
go run examples/file-search/main.go openai <vector-store-id>
```

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

### GenerateVideo usage example

Source: https://goai.sh/api/core-functions.html

Example of calling GenerateVideo with a specific model, prompt, aspect ratio, and duration.

```go
result, err := goai.GenerateVideo(ctx, google.Video("veo-3.1-generate-preview"),
    goai.WithVideoPrompt("A cinematic ocean scene"),
    goai.WithVideoAspectRatio("16:9"),
    goai.WithVideoDuration(8*time.Second),
)
```

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

### Run OpenAI code-interpreter example

Source: https://goai.sh/examples

Sets the API key and executes the OpenAI code interpreter tool example.

```bash
export OPENAI_API_KEY=...
go run examples/code-interpreter/main.go openai
```

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

### SchemaFrom usage example

Source: https://goai.sh/api/core-functions.html

Example of generating a schema from a City struct.

```go
type City struct {
    Name       string  `json:"name" jsonschema:"description=City name"`
    Population int     `json:"population"`
    Country    string  `json:"country" jsonschema:"enum=US|UK|FR|DE"`
    Nickname   *string `json:"nickname"` // nullable
}

schema := goai.SchemaFrom[City]()
// Produces: {"type":"object","properties":{...},"required":["name","population","country","nickname"],"additionalProperties":false}
```

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

### GenerateText usage example

Source: https://goai.sh/api/core-functions.html

An example demonstrating how to initialize a model and call GenerateText with system and user prompts.

```go
model := google.Chat("gemini-3-flash-preview") // auto-reads GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY

result, err := goai.GenerateText(context.Background(), model,
    goai.WithSystem("You are a helpful assistant. Be concise."),
    goai.WithPrompt("What is the capital of France?"),
)
if err != nil {
    log.Fatal(err)
}

fmt.Println(result.Text)
fmt.Printf("Tokens: %d in, %d out\n", result.TotalUsage.InputTokens, result.TotalUsage.OutputTokens)
```

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

### Run OpenAI image-generation example

Source: https://goai.sh/examples

Sets the API key and executes the OpenAI image generation tool example.

```bash
export OPENAI_API_KEY=...
go run examples/image-generation/main.go openai
```

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

### Start vLLM server

Source: https://goai.sh/providers/vllm.html

Command to launch a vLLM server instance.

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

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

### Run Google Gemini code-execution example

Source: https://goai.sh/examples

Sets the API key and executes the Google Gemini code execution tool example.

```bash
export GEMINI_API_KEY=...
go run examples/google-code-execution/main.go
```

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

### Basic Text Generation in main.go

Source: https://goai.sh/

A complete example showing how to initialize a context, call GenerateText with an OpenAI provider, and print the result.

```go
package main

import (
    "context"
    "fmt"

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

func main() {
    result, _ := goai.GenerateText(
        context.Background(),
        openai.Chat("gpt-4o"),
        goai.WithPrompt("Explain goroutines."),
    )
    fmt.Println(result.Text)
}
```

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

### Run Lifecycle Hooks Example

Source: https://goai.sh/examples

Executes the lifecycle hooks example for Google Gemini, requiring the GEMINI_API_KEY environment variable.

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

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

### Start Ollama server

Source: https://goai.sh/providers/ollama.html

Commands to pull a model and start the local Ollama server.

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

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

### Run Langfuse Tracing Example

Source: https://goai.sh/examples

Executes the Langfuse tracing example for a multi-step agent, requiring Gemini and Langfuse credentials.

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

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

### Run Embedding Example

Source: https://goai.sh/examples

Executes the text embedding and cosine similarity example using Google Gemini.

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

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

### Install OpenTelemetry Dependencies

Source: https://goai.sh/concepts/observability

Install the GoAI OpenTelemetry package and your preferred OTLP exporter and SDK.

```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
```

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

### Run OpenTelemetry Tracing Example

Source: https://goai.sh/examples

Executes the OpenTelemetry tracing example with a stdout exporter, requiring the GEMINI_API_KEY environment variable.

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

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

### GenerateImage usage example

Source: https://goai.sh/api/core-functions.html

Example of calling GenerateImage with prompt, size, and count options, including error handling.

```go
result, err := goai.GenerateImage(ctx, model,
    goai.WithImagePrompt("A sunset over mountains, oil painting style"),
    goai.WithImageSize("1024x1024"),
    goai.WithImageCount(1),
)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Generated %d image(s)\n", len(result.Images))
```

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

### Message construction example

Source: https://goai.sh/api/core-functions.html

Demonstrates constructing a slice of messages and using them with GenerateText.

```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...),
)
```

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

### Run Streaming Tools Example

Source: https://goai.sh/examples

Executes the streaming text generation with multi-step tool loops using OpenAI.

```bash
export OPENAI_API_KEY=...
go run examples/streaming-tools/main.go
```

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

### NewTool Usage Example

Source: https://goai.sh/api/types

Demonstrates creating a weather tool using a struct for typed input parameters.

```go
weatherTool := goai.NewTool("get_weather", "Get the current weather for a city.",
    func(ctx context.Context, in struct {
        City string `json:"city" jsonschema:"description=City name"`
    }) (string, error) {
        return forecast(in.City), nil
    })
```

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

### GenerateObject Usage Example

Source: https://goai.sh/api/core-functions.html

Demonstrates generating a structured Recipe object from a prompt.

```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"`
}

result, err := goai.GenerateObject[Recipe](ctx, model,
    goai.WithPrompt("Give me a recipe for chocolate chip cookies"),
)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Recipe: %s\n", result.Object.Name)
fmt.Printf("Difficulty: %s\n", result.Object.Difficulty)
```

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

### Embed usage example

Source: https://goai.sh/api/core-functions.html

Example showing how to initialize an embedding model and generate an embedding for a single string.

```go
model := google.Embedding("text-embedding-004", google.WithAPIKey(apiKey))

result, err := goai.Embed(ctx, model, "The quick brown fox jumps over the lazy dog")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Dimensions: %d\n", len(result.Embedding))
```

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

### Generate text with OpenAI provider

Source: https://goai.sh/

A basic example demonstrating how to initialize a text generation request using the OpenAI provider.

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    result, err := goai.GenerateText(context.Background(),
        openai.Chat("gpt-4o"),
        goai.WithPrompt("Explain Go interfaces in one sentence."),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text)
}
```

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

### Run Anthropic code-execution example

Source: https://goai.sh/examples

Sets the API key and executes the sandboxed Python code execution tool example.

```bash
export ANTHROPIC_API_KEY=...
go run examples/code-execution/main.go anthropic
```

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

### StreamText with tools

Source: https://goai.sh/api/core-functions.html

Example of streaming text generation with tool support and step handling.

```go
stream, err := goai.StreamText(ctx, model,
    goai.WithPrompt("What's the weather in Tokyo?"),
    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.ChunkStepFinish:
        fmt.Println("\n[step complete]")
    }
}

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

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

### SchemaFrom usage example

Source: https://goai.sh/api/types

Demonstrates defining a struct with JSON schema tags and generating the schema.

```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]()
```

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

### OnToolCallStart and OnToolCall Observability

Source: https://goai.sh/concepts/hooks

Tracks the lifecycle of tool calls, including start events and final status (OK, SKIPPED, or ERROR).

```go
goai.WithOnToolCallStart(func(info goai.ToolCallStartInfo) {
    log.Printf("Tool starting: %s (call %s)", info.ToolName, info.ToolCallID)
}),
goai.WithOnToolCall(func(info goai.ToolCallInfo) {
    status := "OK"
    if info.Skipped {
        status = "SKIPPED"
    } else if info.Error != nil {
        status = "ERROR"
    }
    log.Printf("Tool done: %s %s (%s)", info.ToolName, status, info.Duration)
}),
```

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

### Configure authenticated vLLM server

Source: https://goai.sh/providers/vllm.html

Example of configuring a model with an API key and custom base URL.

```go
model := vllm.Chat("meta-llama/Llama-3-8b",
    vllm.WithAPIKey("your-api-key"),
    vllm.WithBaseURL("https://my-vllm-server.example.com/v1"),
)
```

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

### OpenAI Tool Factory Usage

Source: https://goai.sh/concepts/provider-tools

Examples of initializing OpenAI tools such as web search, code interpreter, file search, and image generation.

```go
// Each factory returns a provider.ToolDefinition. Wrap with goai.Tool{} before passing to WithTools.

// Web search with location
td := openai.Tools.WebSearch(
    openai.WithSearchContextSize("medium"),
    openai.WithUserLocation(openai.WebSearchLocation{
        Country:  "US",
        City:     "San Francisco",
        Timezone: "America/Los_Angeles",
    }),
)

// Code interpreter with container
td := openai.Tools.CodeInterpreter(
    openai.WithContainerID("container-id"),
)

// File search with vector stores
td := openai.Tools.FileSearch(
    openai.WithVectorStoreIDs("vs_abc123"),
    openai.WithMaxNumResults(10),
)

// Image generation
td := openai.Tools.ImageGeneration(
    openai.WithImageQuality("high"),
    openai.WithImageSize("1024x1024"),
)
```

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

### StreamObject Usage Example

Source: https://goai.sh/api/core-functions.html

Demonstrates streaming a structured Recipe object and accessing partial updates.

```go
stream, err := goai.StreamObject[Recipe](ctx, model,
    goai.WithPrompt("Give me a recipe for pancakes"),
)
if err != nil {
    log.Fatal(err)
}

for partial := range stream.PartialObjectStream() {
    if partial.Name != "" {
        fmt.Printf("\rStreaming: %s (%d ingredients)", partial.Name, len(partial.Ingredients))
    }
}
fmt.Println()

final, err := stream.Result()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Usage: %d input, %d output tokens\n", final.Usage.InputTokens, final.Usage.OutputTokens)
```

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

### Generate Text with LangChainGo

Source: https://goai.sh/compare

Example of generating text using the LangChainGo library.

```go
llm, err := openaillm.New()
resp, err := llms.GenerateFromSinglePrompt(ctx, llm, "Hello")
fmt.Println(resp)
```

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

### Anthropic Tool Factory Usage

Source: https://goai.sh/concepts/provider-tools

Examples of initializing various Anthropic tools including computer use, web search with domain filtering, and code execution. Each factory returns a provider.ToolDefinition.

```go
// Each factory returns a provider.ToolDefinition. Wrap with goai.Tool{} before passing to WithTools.

// Computer use
td := anthropic.Tools.Computer(anthropic.ComputerToolOptions{
    DisplayWidthPx:  1920,
    DisplayHeightPx: 1080,
})

// Web search with domain filtering
td := anthropic.Tools.WebSearch(
    anthropic.WithAllowedDomains("docs.go.dev", "pkg.go.dev"),
    anthropic.WithMaxUses(5),
)

// Additional web search options:
td = anthropic.Tools.WebSearch(
    // Exclude domains from results
    anthropic.WithBlockedDomains("example.com"),
    // Set user location for geographically relevant results
    anthropic.WithWebSearchUserLocation(anthropic.WebSearchLocation{
        City:     "San Francisco",
        Region:   "California",
        Country:  "US",
        Timezone: "America/Los_Angeles",
    }),
)

// Code execution (no options needed)
td := anthropic.Tools.CodeExecution()
```

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

### Hook into Tool Execution Start with WithOnToolCallStart

Source: https://goai.sh/concepts/tools.html

WithOnToolCallStart executes before each individual tool call, providing access to the step number, 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)
})
```

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

### EmbedMany usage example

Source: https://goai.sh/api/core-functions.html

Example showing how to generate embedding vectors for a slice of strings.

```go
texts := []string{
    "I love programming",
    "Software engineering is great",
    "The weather is nice today",
}

result, err := goai.EmbedMany(ctx, model, texts)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Generated %d embeddings\n", len(result.Embeddings))
```

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

### Connect to MCP server and call tools

Source: https://goai.sh/concepts/mcp.html

Demonstrates initializing an MCP client with a Stdio transport, listing available tools, and executing a specific tool.

```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)
}

// Call a tool directly.
callResult, err := client.CallTool(ctx, "read_file", map[string]any{"path": "/tmp/hello.txt"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(mcp.FormatContent(callResult.Content, callResult.IsError))
```

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

### Custom OAuth Token Source

Source: https://goai.sh/concepts/token-source.html

Example of implementing a custom token source by fetching an OAuth2 token via HTTP POST.

```go
ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
    resp, err := http.PostForm("https://auth.example.com/token", url.Values{
        "grant_type":    {"client_credentials"},
        "client_id":     {clientID},
        "client_secret": {clientSecret},
    })
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var body struct {
        AccessToken string `json:"access_token"`
        ExpiresIn   int    `json:"expires_in"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
        return nil, err
    }
    return &provider.Token{
        Value:     body.AccessToken,
        ExpiresAt: time.Now().Add(time.Duration(body.ExpiresIn) * time.Second),
    }, nil
})
```

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

### Google Provider Tool Factories

Source: https://goai.sh/concepts/provider-tools

Examples of configuring Google tools including search, URL context, code execution, and computer use.

```go
// Each factory returns a provider.ToolDefinition. Wrap with goai.Tool{} before passing to WithTools.

// Google Search with time range filter
td := google.Tools.GoogleSearch(
    google.WithTimeRange("2025-01-01T00:00:00Z", "2025-12-31T23:59:59Z"),
)

// Additional Google Search options:
td = google.Tools.GoogleSearch(
    // Enable web search (enabled by default in grounding)
    google.WithWebSearch(),
    // Enable image search results
    google.WithImageSearch(),
    // Or combine both
    google.WithWebSearch(),
    google.WithImageSearch(),
)

// URL context (no options)
td := google.Tools.URLContext()

// Code execution (no options)
td := google.Tools.CodeExecution()

// Computer use
td = google.Tools.ComputerUse(
    google.WithEnvironment("browser"),
    google.WithExcludedFunctions("drag_and_drop"),
)
```

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

### StreamText basic usage

Source: https://goai.sh/api/core-functions.html

Example of basic streaming text generation and consuming the result.

```go
stream, err := goai.StreamText(context.Background(), model,
    goai.WithPrompt("Write a haiku about Go programming."),
)
if err != nil {
    log.Fatal(err)
}

for text := range stream.TextStream() {
    fmt.Print(text)
}
fmt.Println()

result := stream.Result()
fmt.Printf("Tokens: %d in, %d out\n", result.TotalUsage.InputTokens, result.TotalUsage.OutputTokens)
```

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

### Chat with OpenAI Model

Source: https://goai.sh/providers/azure.html

Example of generating text using an OpenAI model via the Azure provider.

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

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

func main() {
    model := azure.Chat("gpt-4o")
    result, err := goai.GenerateText(context.Background(), model,
        goai.WithPrompt("Explain Go interfaces in one paragraph."),
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(result.Text)
}
```

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

### Configure remote Ollama server

Source: https://goai.sh/providers/ollama.html

Example of connecting to a remote Ollama instance by overriding the base URL.

```go
model := ollama.Chat("llama3",
    ollama.WithBaseURL("http://192.168.1.100:11434"),
)
```

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

### xAI Provider Tool Factories

Source: https://goai.sh/concepts/provider-tools

Examples of configuring xAI tools for web search and X (Twitter) search.

```go
// Each factory returns a provider.ToolDefinition. Wrap with goai.Tool{} before passing to WithTools.

// Web search with domain filtering
td := xai.Tools.WebSearch(
    xai.WithAllowedDomains("go.dev", "github.com"),
)

// Additional web search options:
td = xai.Tools.WebSearch(
    // Exclude domains from results
    xai.WithExcludedDomains("example.com"),
    // Enable image understanding in search results
    xai.WithWebSearchImageUnderstanding(true),
)

// X search with date range and handle filtering
td = xai.Tools.XSearch(
    xai.WithAllowedXHandles("@golang"),
    xai.WithXSearchDateRange("2025-01-01", "2025-12-31"),
)

// Additional X search options:
td = xai.Tools.XSearch(
    // Exclude posts from these handles
    xai.WithExcludedXHandles("@spam"),
    // Enable image understanding in X posts
    xai.WithXSearchImageUnderstanding(true),
    // Enable video understanding in X posts
    xai.WithXSearchVideoUnderstanding(true),
)
```

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

### Generate Text with GoAI SDK

Source: https://goai.sh/compare

Example of generating text using the GoAI SDK with an OpenAI model.

```go
result, err := goai.GenerateText(ctx,
    openai.Chat("gpt-4o"),
    goai.WithPrompt("Hello"),
)
fmt.Println(result.Text)
```

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

### Configure and use WebSearch tool

Source: https://goai.sh/providers/openai.html

Demonstrates initializing the WebSearch tool with context size and location options, then passing it to the GenerateText function.

```go
def := openai.Tools.WebSearch(
    openai.WithSearchContextSize("medium"),
    openai.WithUserLocation(openai.WebSearchLocation{
        Country: "US",
        City:    "San Francisco",
    }),
)
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("What happened in tech news today?"),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

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

### Configure and use ImageGeneration tool

Source: https://goai.sh/providers/openai.html

Demonstrates initializing the ImageGeneration tool with quality and size options, then passing it to the GenerateText function.

```go
def := openai.Tools.ImageGeneration(
    openai.WithImageQuality("high"),
    openai.WithImageSize("1024x1024"),
)
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Generate an image of a sunset over mountains."),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

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

### Configure and use FileSearch tool

Source: https://goai.sh/providers/openai.html

Demonstrates initializing the FileSearch tool with vector store IDs and result limits, then passing it to the GenerateText function.

```go
def := openai.Tools.FileSearch(
    openai.WithVectorStoreIDs("vs_abc123"),
    openai.WithMaxNumResults(5),
)
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Find information about error handling."),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

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

### WithSystem Option

Source: https://goai.sh/api/options

Sets the system prompt for the model. The default is an empty string.

```go
func WithSystem(s string) Option
```

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

### Generate embeddings

Source: https://goai.sh/providers/ollama.html

Example of generating embeddings using the nomic-embed-text model.

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

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

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

### Generate Embeddings

Source: https://goai.sh/providers/nvidia.html

Example of generating embeddings using the nvidia/nv-embedqa-e5-v5 model.

```go
model := nvidia.Embedding("nvidia/nv-embedqa-e5-v5")

result, err := goai.Embed(context.Background(), model, "Hello world")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Dimensions: %d\n", len(result.Embedding))
```

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

### Initialize Groq BrowserSearch tool

Source: https://goai.sh/concepts/provider-tools

Use the BrowserSearch factory to create a tool definition. Wrap the result with goai.Tool{} before passing it to WithTools.

```go
// Returns a provider.ToolDefinition. Wrap with goai.Tool{} before passing to WithTools.
td := groq.Tools.BrowserSearch()
```

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

### Generate embeddings with vLLM

Source: https://goai.sh/providers/vllm.html

Example of generating embeddings using an embedding model.

```go
embedModel := vllm.Embedding("BAAI/bge-small-en-v1.5")

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

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

### Connect to MCP server and use tools

Source: https://goai.sh/

Demonstrates connecting to an MCP server via stdio transport and using its tools within a GoAI generation request.

```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),
)
```

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

### Generate text with vLLM

Source: https://goai.sh/providers/vllm.html

Example of generating text using a chat model.

```go
model := vllm.Chat("meta-llama/Llama-3-8b")

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

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

### Configure OpenAI Provider Authentication and HTTP Client

Source: https://goai.sh/concepts/providers-and-models

Demonstrates how to configure an OpenAI model using an explicit API key, a dynamic token source, or a custom HTTP client.

```go
// Explicit API key
model := openai.Chat("gpt-4o", openai.WithAPIKey("sk-..."))

// Dynamic token source (OAuth, service accounts)
model := openai.Chat("gpt-4o", openai.WithTokenSource(myTokenSource))

// Custom HTTP client (proxies, logging, URL rewrite)
model := openai.Chat("gpt-4o", openai.WithHTTPClient(myClient))
```

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

### Chat with Ollama

Source: https://goai.sh/providers/ollama.html

Example of generating text using the Ollama chat model.

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

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

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

### Use Reasoning Models

Source: https://goai.sh/providers/cohere.html

Enable thinking/reasoning for the command-a-reasoning model using provider options.

```go
model := cohere.Chat("command-a-reasoning")

result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Solve this step by step: what is 127 * 53?"),
    goai.WithProviderOptions(map[string]any{
        "thinking": map[string]any{
            "type":        "enabled",
            "budgetTokens": 4096,
        },
    }),
)
```

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

### Chat with NVIDIA NIM

Source: https://goai.sh/providers/nvidia.html

Example of generating text using the nvidia/llama-3.1-nemotron-70b-instruct model.

```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)
}
```

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

### Generate Video with Veo

Source: https://goai.sh/providers/google.html

Demonstrates how to initiate an asynchronous video generation task using the Veo model and retrieve the result.

```go
model := google.Video("veo-3.1-generate-preview")
result, err := goai.GenerateVideo(ctx, model,
    goai.WithVideoPrompt("A paper plane taking flight at sunrise"),
    goai.WithVideoAspectRatio("16:9"),
    goai.WithVideoResolution("720p"),
    goai.WithVideoDuration(8*time.Second),
    goai.WithVideoAudio(true),
)
if err != nil {
    panic(err)
}
fmt.Printf("Generated %d bytes\n", len(result.Video.Data))
```

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

### Check for ErrUnknownTool

Source: https://goai.sh/concepts/error-handling

Example of checking for the ErrUnknownTool sentinel error during tool execution.

```go
var overflow *goai.ContextOverflowError
if errors.As(err, &overflow) {
    // Truncate messages and retry, or switch to a model with a larger context.
    fmt.Println("Context overflow:", overflow.Message)
}

// Check for unknown tool
if errors.Is(err, goai.ErrUnknownTool) {
    // Tool was called that wasn't registered
}
```

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

### Handle ContextOverflowError

Source: https://goai.sh/concepts/error-handling

Example of using errors.As to detect and handle a context overflow error.

```go
var overflow *goai.ContextOverflowError
if errors.As(err, &overflow) {
    // Truncate messages and retry, or switch to a model with a larger context.
    fmt.Println("Context overflow:", overflow.Message)
}
```

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

### Configure WebFetch Tool

Source: https://goai.sh/providers/anthropic.html

Use the WebFetch tool to summarize content from URLs with citation and token limit options.

```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,
    }),
)
```

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

### Set API Key and Run Application

Source: https://goai.sh/getting-started/installation.html

Set the required environment variable and execute the application.

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

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

### Inspect APIError with errors.As

Source: https://goai.sh/concepts/error-handling

Example of using errors.As to inspect an APIError returned from a generation call.

```go
result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
if err != nil {
    var apiErr *goai.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("HTTP %d: %s (retryable: %v)\n",
            apiErr.StatusCode, apiErr.Message, apiErr.IsRetryable)
    }
}
```

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

### WithOnToolCallStart Option

Source: https://goai.sh/api/options

Sets a callback invoked before each tool execution. If the callback panics, the tool does not execute and the panic is reported through OnPanic.

```go
func WithOnToolCallStart(fn func(ToolCallStartInfo)) Option
```

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

### Import GoAI Core and OpenAI Provider

Source: https://goai.sh/getting-started/installation.html

Import the core SDK and the OpenAI provider sub-package.

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

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

### Azure Managed Identity Token Source

Source: https://goai.sh/concepts/token-source.html

Example of using CachedTokenSource with Azure DefaultAzureCredential for Cognitive Services.

```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 Production OTLP Exporter

Source: https://goai.sh/concepts/observability

Set up a production TracerProvider using the OTLP HTTP exporter.

```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))
defer tp.Shutdown(ctx)
otel.SetTracerProvider(tp)
```

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

### Switching to Anthropic Provider

Source: https://goai.sh/getting-started/quick-start

Initialize a model using the Anthropic provider.

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

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

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

### Stream Text with GoAI SDK

Source: https://goai.sh/compare

Example of streaming text responses using GoAI SDK channels.

```go
stream, err := goai.StreamText(ctx,
    openai.Chat("gpt-4o"),
    goai.WithPrompt("Tell me a story"),
)
for chunk := range stream.TextStream() {
    fmt.Print(chunk)
}
```

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

### Implement Computer Use tool

Source: https://goai.sh/providers/anthropic.html

Configures the Computer tool for client-side execution, requiring the application to handle tool calls returned by the model.

```go
def := anthropic.Tools.Computer(anthropic.ComputerToolOptions{
    DisplayWidthPx:  1920,
    DisplayHeightPx: 1080,
})
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Open the browser and navigate to example.com"),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
// Handle tool calls in result.ToolCalls - execute actions and return results
```

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

### Run MCP client basics without an LLM

Source: https://goai.sh/examples

Exercises MCP capabilities including tools, prompts, and resources. Requires a local MCP test server implementation.

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

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

### GET /v1/models

Source: https://goai.sh/providers/fptcloud.html

Retrieves a list of available models in the specified region using the OpenAI-compatible discovery endpoint.

```APIDOC
## GET /v1/models

### Description
Lists the models available for use in the selected FPT Smart Cloud region.

### Method
GET

### Endpoint
https://mkp-api.fptcloud.com/v1/models (Global) or https://mkp-api.fptcloud.jp/v1/models (Japan)

### Request Example
curl -H "Authorization: Bearer $FPT_API_KEY" https://mkp-api.fptcloud.jp/v1/models
```

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

### WithPrompt Option

Source: https://goai.sh/api/options

Sets a shorthand single user message, which is auto-wrapped as a UserMessage. The default is an empty string.

```go
func WithPrompt(s string) Option
```

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

### Azure Auto-Routing Examples

Source: https://goai.sh/providers/azure.html

The provider automatically routes requests to the appropriate endpoint based on the model ID prefix.

```go
// OpenAI model - uses Responses API via azureRoundTripper
gpt := azure.Chat("gpt-4o")

// Claude model - routes to Anthropic Messages API on Azure
claude := azure.Chat("claude-sonnet-4-6")

// DeepSeek model - routes to Azure AI Services endpoint
deepseek := azure.Chat("DeepSeek-V3.2")
```

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

### Use BrowserSearch tool

Source: https://goai.sh/providers/groq.html

Configure and use the BrowserSearch tool with a Groq model for web search capabilities.

```go
def := groq.Tools.BrowserSearch()

result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Find the latest Go release notes"),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

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

### Common Generation Options

Source: https://goai.sh/getting-started/quick-start

Configure generation behavior using various options like system prompts, temperature, and token limits.

```go
result, err := goai.GenerateText(ctx, model,
    goai.WithSystem("You are a concise assistant."),
    goai.WithPrompt("Explain goroutines."),
    goai.WithMaxOutputTokens(200),
    goai.WithTemperature(0.7),
)
```

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

### Image Generation with DALL-E 3

Source: https://goai.sh/providers/azure.html

Example of generating images using the DALL-E 3 model via the Azure provider.

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

model := azure.Image("dall-e-3",
    azure.WithAPIKey("your-api-key"),
    azure.WithEndpoint("https://your-resource.openai.azure.com"),
)
result, err := goai.GenerateImage(ctx, model,
    goai.WithImagePrompt("A mountain landscape"),
)
```

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

### Configure Bash and TextEditor Tools

Source: https://goai.sh/providers/anthropic.html

Use the standard Bash and TextEditor tools to interact with the file system and edit text files.

```go
bashDef := anthropic.Tools.Bash()
editorDef := anthropic.Tools.TextEditor()
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("List files in the current directory"),
    goai.WithTools(
        goai.Tool{Name: bashDef.Name, ProviderDefinedType: bashDef.ProviderDefinedType, ProviderDefinedOptions: bashDef.ProviderDefinedOptions},
        goai.Tool{Name: editorDef.Name, ProviderDefinedType: editorDef.ProviderDefinedType, ProviderDefinedOptions: editorDef.ProviderDefinedOptions},
    ),
)
```

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

### Generate Structured Object with GoAI SDK

Source: https://goai.sh/compare

Example of generating a type-safe structured object using Go generics in GoAI SDK.

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

result, err := goai.GenerateObject[Recipe](ctx,
    openai.Chat("gpt-4o"),
    goai.WithPrompt("A pasta recipe"),
)
fmt.Println(result.Object.Name) // type-safe access
```

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

### Configure the compat provider

Source: https://goai.sh/concepts/providers-and-models

Use the compat provider to connect to any OpenAI-compatible API by specifying the base URL and API key.

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

model := compat.Chat("my-model",
    compat.WithBaseURL("https://my-api.example.com/v1"),
    compat.WithAPIKey("my-key"),
)
```

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

### Cross-Region Inference Configuration

Source: https://goai.sh/providers/bedrock.html

Examples of configuring the Bedrock chat model with geographic prefixes for US, EU, AP, and global cross-region inference.

```go
// US cross-region inference
model := bedrock.Chat("us.anthropic.claude-sonnet-4-6")

// EU cross-region inference
model := bedrock.Chat("eu.anthropic.claude-sonnet-4-6")

// AP cross-region inference
model := bedrock.Chat("ap.anthropic.claude-sonnet-4-6")

// Global cross-region inference
model := bedrock.Chat("global.anthropic.claude-sonnet-4-6")
```

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

### Initialize an OpenAI model

Source: https://goai.sh/concepts/providers-and-models

Use the provider package's Chat function to instantiate a specific model.

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

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

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

### Run Filesystem MCP server integration

Source: https://goai.sh/examples

Lists available tools and calls list_directory on the official MCP filesystem server via stdio. Requires Node.js (npx).

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

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

### WithSystem

Source: https://goai.sh/api/options

Sets the system prompt for the model.

```APIDOC
## func WithSystem(s string) Option

### Description
Sets the system prompt. Default is empty (no system prompt).
```

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

### Configure WithOnBeforeStep hook

Source: https://goai.sh/api/options

Called before each LLM call in a multi-step tool loop starting from step 2. It allows injecting messages or stopping the loop, and panics surface as *PanicError.

```go
goai.WithOnBeforeStep(func(info goai.BeforeStepInfo) goai.BeforeStepResult {
    // Return ExtraMessages to inject, or Stop: true to end loop
    return goai.BeforeStepResult{}
})
```

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

### goai.WithOnToolCallStart

Source: https://goai.sh/concepts/tools.html

Registers a callback that executes immediately before an individual tool is invoked.

```APIDOC
## goai.WithOnToolCallStart(callback func(info goai.ToolCallStartInfo))

### Description
Registers a callback triggered before each individual tool execution.
```

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

### Initialize Vertex Chat with API Key

Source: https://goai.sh/providers/vertex.html

Configures the provider to route to the Gemini API using an API key when no GCP project is specified.

```go
model := vertex.Chat("gemini-2.5-flash",
    vertex.WithAPIKey("your-api-key"),
)
```

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

### Configure FileSearch with google.Tools.FileSearch

Source: https://goai.sh/providers/google.html

Initializes the FileSearch tool with a dynamic threshold and a specific corpus ID for grounding responses.

```go
def := google.Tools.FileSearch(
    google.WithDynamicThreshold(0.6),
    google.WithCorpus("projects/.../corpora/my-corpus"),
)
```

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

### Google Service Account Token Source

Source: https://goai.sh/concepts/token-source.html

Example of using CachedTokenSource with Vertex AI. Note that the Google Gemini provider requires API keys, so Vertex AI is used for OAuth2 Bearer authentication.

```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-3-flash-preview", vertex.WithTokenSource(ts))
```

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

### WithTools Option

Source: https://goai.sh/api/options

Sets the tools available to the model. Pass goai.Tool values with Name, Description, InputSchema, and optionally Execute.

```go
func WithTools(tools ...Tool) Option
```

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

### Initialize Google Gemini client

Source: https://goai.sh/providers/google.html

Initialize the Gemini chat model by importing the provider and passing the API key explicitly.

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

model := google.Chat("gemini-2.5-flash", google.WithAPIKey("..."))
```

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

### Generate Text with System Prompt

Source: https://goai.sh/getting-started/quick-start

Use the WithSystem option to set a system prompt for the model.

```go
ctx := context.Background()

result, err := goai.GenerateText(ctx, model,
    goai.WithSystem("You are a helpful assistant that responds in haiku."),
    goai.WithPrompt("Tell me about Go."),
)
```

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

### Chat with compat provider

Source: https://goai.sh/providers/compat.html

Initialize a chat model with a base URL and optional API key, then generate text.

```go
model := compat.Chat("my-model",
    compat.WithBaseURL("https://my-api.example.com/v1"),
    compat.WithAPIKey("optional-api-key"),
)

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

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

### Use URLContext Tool

Source: https://goai.sh/providers/google.html

Enables the model to fetch and summarize content from a provided URL.

```go
def := google.Tools.URLContext()
result, err := goai.GenerateText(ctx, model,
    goai.WithPrompt("Summarize the content at https://go.dev/doc/effective_go"),
    goai.WithTools(goai.Tool{
        Name:                   def.Name,
        ProviderDefinedType:    def.ProviderDefinedType,
        ProviderDefinedOptions: def.ProviderDefinedOptions,
    }),
)
```

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

### Import GoAI OpenTelemetry Package

Source: https://goai.sh/concepts/observability

Import the observability package to enable OpenTelemetry support.

```go
import goaiotel "github.com/zendev-sh/goai/observability/otel"
```