AI Provider Setup¶

Global AI features (like documentation Q&A) require a configured AI provider.

Step 1: Enable AI¶

In your main.go, ensure that the AI feature is enabled:

        Features: props.SetFeatures(
            props.Enable(props.AiCmd),
        ),

Step 2: Configure Provider¶

Run your tool's built-in initialization command specifically for AI:

mytool init ai

This will launch an interactive form where you can: 1. Select your preferred provider (Claude, OpenAI, Gemini, Claude Local, or an OpenAI-compatible endpoint). 2. Enter your API key (not required for Claude Local).

The configuration will be saved to your local config.yaml under the appropriate provider section.

Environment Variable Overrides¶

For CI/CD environments or temporary overrides, you can configure the AI client using environment variables. These always take precedence over the config.yaml.

Step 3: Use AI Documentation¶

Once configured, you can query your tool's documentation using natural language:

mytool docs ask "How do I add a new command?"

The tool will use the configured provider to analyze the local documentation and provide a structured, relevant answer.

Provider-Specific Configuration¶

Each AI provider has its own characteristics. This section provides guidance for optimal configuration with each.

OpenAI¶

OpenAI offers excellent general-purpose performance. It is the fallback provider when no AI_PROVIDER environment variable or ai.provider config key is set.

Recommended Models:

Configuration Example:

# config.yaml
ai:
  provider: openai
openai:
  api:
    key: "sk-..."
  model: gpt-4o

Environment Variables:

export AI_PROVIDER=openai
export OPENAI_API_KEY=sk-...

Claude (Anthropic)¶

Claude excels at nuanced understanding and following complex instructions.

Recommended Models:

Configuration Example:

# config.yaml
ai:
  provider: claude
anthropic:
  api:
    key: "sk-ant-..."
  model: claude-sonnet-4-6

Environment Variables:

export AI_PROVIDER=claude
export ANTHROPIC_API_KEY=sk-ant-...

Gemini (Google)¶

Gemini offers strong performance and massive context windows.

Recommended Models:

Configuration Example:

# config.yaml
ai:
  provider: gemini
gemini:
  api:
    key: "AIza..."
  model: gemini-2.0-flash

Environment Variables:

export AI_PROVIDER=gemini
export GEMINI_API_KEY=AIza...

Claude Local¶

ProviderClaudeLocal routes requests through the locally installed claude CLI binary instead of the Anthropic API. This is valuable in secure or air-gapped environments where direct outbound HTTPS to api.anthropic.com is blocked, but the pre-authenticated claude binary is permitted.

Requirements: - claude CLI installed and authenticated (claude login) - Binary must be in PATH - No API key required

Installation:

# Install the Claude CLI (macOS/Linux)
npm install -g @anthropic-ai/claude-code

# Authenticate once
claude login

Configuration Example:

# config.yaml
ai:
  provider: claude-local
  model: claude-sonnet-4-6  # optional; uses claude's default if empty

Environment Variables:

export AI_PROVIDER=claude-local
# No API key needed

OpenAI-Compatible Endpoints¶

ProviderOpenAICompatible targets any backend that exposes an OpenAI-compatible API. This unlocks a wide range of local and cloud backends without additional per-provider code.

Supported backends include: Ollama, Groq, Fireworks AI, Together AI, LM Studio, vLLM, and others.

Requirements: - BaseURL must be set (the endpoint's base URL) - Model must be set (no default — model names are backend-specific)

Ollama (Local)¶

# config.yaml
ai:
  provider: openai-compatible
  base_url: "http://localhost:11434/v1"
  model: llama3.2
openai:
  api:
    key: "ollama"  # Ollama ignores the token; any non-empty value works

export AI_PROVIDER=openai-compatible
# BaseURL and model must be set via config or programmatically

Groq (Cloud)¶

# config.yaml
ai:
  provider: openai-compatible
  base_url: "https://api.groq.com/openai/v1"
  model: llama-3.3-70b-versatile
openai:
  api:
    key: "gsk_..."  # Your Groq API key

Programmatic Usage¶

Beyond the docs ask command, you can use the AI chat client directly in your code:

Basic Chat¶

import "github.com/phpboyscout/gtb/pkg/chat"

func analyzeError(ctx context.Context, p *props.Props, errorLog string) (string, error) {
    client, err := chat.New(ctx, p, chat.Config{
        Provider:     chat.ProviderClaude,
        Model:        "claude-sonnet-4-6",
        SystemPrompt: "You are an expert at analyzing error logs and suggesting fixes.",
    })
    if err != nil {
        return "", err
    }

    return client.Chat(ctx, fmt.Sprintf("Analyze this error:\n%s", errorLog))
}

Structured Responses¶

Force the AI to return structured data:

type ErrorAnalysis struct {
    Severity    string   `json:"severity" jsonschema:"enum=low,enum=medium,enum=high"`
    RootCause   string   `json:"root_cause"`
    Suggestions []string `json:"suggestions"`
}

func analyzeErrorStructured(ctx context.Context, p *props.Props, errorLog string) (*ErrorAnalysis, error) {
    client, err := chat.New(ctx, p, chat.Config{
        Provider:     chat.ProviderOpenAI,
        Model:        "gpt-4o",
        SystemPrompt: "Analyze errors and provide structured feedback.",
    })
    if err != nil {
        return nil, err
    }

    var result ErrorAnalysis
    err = client.Ask(fmt.Sprintf("Analyze: %s", errorLog), &result)
    return &result, err
}

Troubleshooting¶

Common Issues¶

Testing Configuration¶

Verify your AI configuration is working:

# Quick test with docs ask
mytool docs ask "Say hello"

# Check current provider (if using debug mode)
mytool docs ask --provider openai "What provider am I using?"