# AI Setup & Configuration

Get AI-powered log analysis working in minutes. This guide covers everything from basic API key setup to advanced configuration options for all supported AI providers.

{% hint style="success" %}
**Quick Start:** Set `OPENAI_API_KEY` environment variable and run `gonzo -f your-logs.log --ai-model="gpt-4"`. That's it!
{% endhint %}

### Choose Your Setup Path

Select the approach that best fits your needs:

{% tabs %}
{% tab title="Local AI (Ollama)" %}
**Best for: Privacy, unlimited usage, no API costs**

**Requirements:**

* 8GB+ RAM (16GB+ recommended)
* Local compute resources
* Ollama installation

**Setup time:** 10-15 minutes
{% endtab %}

{% tab title="Local AI (LM Studio)" %}
**Best for: Development, testing, easy local setup**

**Requirements:**

* 8GB+ RAM
* LM Studio application
* Downloaded model

**Setup time:** 5-10 minutes
{% endtab %}

{% tab title="OpenAI API" %}
**Best for: Production use, reliability, best AI quality**

**Requirements:**

* OpenAI API account
* Valid API key with credits
* Internet connection

**Setup time:** 2-3 minutes
{% endtab %}

{% tab title="Custom API" %}
**Best for: Enterprise, existing AI infrastructure**

**Requirements:**

* OpenAI-compatible API endpoint
* Authentication credentials
* Network access to API

**Setup time:** 5-15 minutes
{% endtab %}
{% endtabs %}

### OpenAI Setup

#### Step 1: Get Your API Key

1. **Visit** [**OpenAI API Platform**](https://platform.openai.com/)
2. **Create account or sign in**
3. **Navigate to API Keys** (<https://platform.openai.com/api-keys>)
4. **Create new secret key**
5. **Copy the key** (starts with `sk-`)

{% hint style="warning" %}
**Important:** Save your API key securely. OpenAI only shows it once, and you'll need it for Gonzo configuration.
{% endhint %}

#### Step 2: Configure Environment

**Method 1: Environment Variable (Recommended)**

```bash
# Add to your ~/.bashrc, ~/.zshrc, or ~/.profile
export OPENAI_API_KEY="sk-your-actual-api-key-here"

# Reload your shell configuration
source ~/.bashrc  # or ~/.zshrc
```

**Method 2: Session Variable**

```bash
# Set for current session only
export OPENAI_API_KEY="sk-your-actual-api-key-here"

# Verify it's set
echo $OPENAI_API_KEY
```

**Method 3: Configuration File**

```bash
# Create Gonzo config file
mkdir -p ~/.config/gonzo
cat > ~/.config/gonzo/config.yml << EOF
# AI Configuration
ai-model: "gpt-4"

# Environment variables can also be set in config
# But API keys are more secure as environment variables
EOF
```

#### Step 3: Test Your Setup

```bash
# Test with automatic model selection
gonzo -f your-logs.log

# Test with specific model
gonzo -f your-logs.log --ai-model="gpt-4"

# Test with cheaper model for development
gonzo -f your-logs.log --ai-model="gpt-3.5-turbo"
```

#### Step 4: Verify AI Features Work

```bash
# 1. Start Gonzo with your logs
gonzo -f application.log --ai-model="gpt-4"

# 2. Navigate to a log entry and press 'i'
# You should see AI analysis of the log entry

# 3. Try the model switcher with 'm'
# You should see available OpenAI models

# 4. Test AI chat with 'c' in log details
# You should be able to have a conversation about the logs
```

### Local AI Setup (Ollama)

#### Step 1: Install Ollama

{% tabs %}
{% tab title="Linux" %}

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Verify installation
ollama --version
```

{% endtab %}

{% tab title="macOS" %}

```bash
# Option 1: Download from website
# Visit https://ollama.ai/download and download macOS installer

# Option 2: Homebrew
brew install ollama

# Verify installation
ollama --version
```

{% endtab %}

{% tab title="Windows" %}

```bash
# Download from https://ollama.ai/download
# Run the installer
# Open PowerShell or Command Prompt

# Verify installation
ollama --version
```

{% endtab %}
{% endtabs %}

#### Step 2: Start Ollama Service

```bash
# Start Ollama server (required for Gonzo to connect)
ollama serve

# This should show:
# Ollama is running on http://localhost:11434
```

{% hint style="info" %}
**Keep this running:** The `ollama serve` command needs to stay running for Gonzo to access AI features. Consider running it in a separate terminal or as a background service.
{% endhint %}

#### Step 3: Download AI Models

```bash
# Download recommended models for log analysis
ollama pull llama3        # Good general-purpose model (4.7GB)
ollama pull mistral       # Faster, smaller model (4.1GB)
ollama pull codellama     # Good for technical logs (3.8GB)

# Or download a larger, more capable model
ollama pull llama3:70b    # Very capable but requires 40GB+ RAM

# List available models
ollama list
```

**Model Recommendations by System:**

| RAM   | Recommended Model | Size  | Performance                    |
| ----- | ----------------- | ----- | ------------------------------ |
| 8GB   | mistral           | 4.1GB | Good for basic analysis        |
| 16GB  | llama3            | 4.7GB | Excellent for most use cases   |
| 32GB+ | llama3:70b        | 40GB  | Best quality, production-ready |

#### Step 4: Configure Gonzo for Ollama

```bash
# Set environment variables for Ollama
export OPENAI_API_KEY="ollama"                    # Special key for Ollama
export OPENAI_API_BASE="http://localhost:11434"   # Ollama endpoint

# Verify Ollama is accessible
curl http://localhost:11434/api/tags
```

#### Step 5: Test Ollama Integration

```bash
# Test with automatic model selection
gonzo -f your-logs.log

# Test with specific model
gonzo -f your-logs.log --ai-model="llama3"

# Test model switching
# Press 'm' in Gonzo to see available Ollama models
```

### Local LM Studio Setup

#### Step 1: Install LM Studio

1. **Download LM Studio** from <https://lmstudio.ai/>
2. **Install the application** for your operating system
3. **Launch LM Studio**

#### Step 2: Download Models

1. **Open LM Studio**
2. **Go to "Discover" tab**
3. **Search and download recommended models:**
   * `microsoft/DialoGPT-medium` (lightweight, good for testing)
   * `meta-llama/Llama-2-7b-chat-hf` (balanced performance)
   * `meta-llama/Llama-2-13b-chat-hf` (better quality, needs more RAM)

#### Step 3: Start Model Server

1. **Go to "Local Server" tab in LM Studio**
2. **Select your downloaded model**
3. **Click "Start Server"**
4. **Note the server URL** (usually `http://localhost:1234`)

#### Step 4: Configure Gonzo for LM Studio

```bash
# Set environment variables for LM Studio
export OPENAI_API_KEY="local-key"                     # Any non-empty value
export OPENAI_API_BASE="http://localhost:1234/v1"     # Note the /v1 suffix

# Test connectivity
curl http://localhost:1234/v1/models
```

#### Step 5: Test LM Studio Integration

```bash
# Test with LM Studio
gonzo -f your-logs.log

# The model will be auto-selected from whatever's running in LM Studio
# Use 'm' to see available models
```

### Custom API Setup

#### Enterprise AI Services

**Azure OpenAI Service:**

```bash
export OPENAI_API_KEY="your-azure-key"
export OPENAI_API_BASE="https://your-resource.openai.azure.com/"
export OPENAI_API_TYPE="azure"
export OPENAI_API_VERSION="2023-05-15"
```

**AWS Bedrock (via compatible proxy):**

```bash
export OPENAI_API_KEY="your-aws-access-key"
export OPENAI_API_BASE="https://your-bedrock-proxy.amazonaws.com/v1"
```

**Custom OpenAI-Compatible API:**

```bash
export OPENAI_API_KEY="your-custom-api-key"
export OPENAI_API_BASE="https://your-ai-service.com/v1"
```

#### Testing Custom APIs

```bash
# Test API connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     "$OPENAI_API_BASE/models"

# Test with Gonzo
gonzo -f test-logs.log --ai-model="your-model-name"
```

### Real-World Examples

See AI features in action:

* [AI and a TUI: Practical Logging Tools for SREs](https://www.controltheory.com/blog/ai-and-a-tui-practical-logging-tools-for-sres/) - Practical AI use cases for incident response

### Advanced Configuration

#### Configuration File Setup

Create a comprehensive configuration file for persistent settings:

```bash
# Create configuration directory
mkdir -p ~/.config/gonzo

# Create comprehensive config file
cat > ~/.config/gonzo/config.yml << EOF
# AI Configuration
ai-model: "gpt-4"                    # Default model
ai-auto-select: true                 # Auto-select best available model

# File and performance settings
files:
  - "/var/log/app/*.log"
follow: true
update-interval: 2s
log-buffer: 5000

# AI-specific performance settings
ai-context-size: 4000               # Maximum context for AI analysis
ai-response-timeout: 30s            # Timeout for AI responses
ai-max-retries: 3                   # Retry failed AI requests

# Development vs Production settings
profiles:
  development:
    ai-model: "gpt-3.5-turbo"       # Cheaper model for dev
    update-interval: 1s              # Faster updates
  production:
    ai-model: "gpt-4"               # Best model for production
    update-interval: 5s              # Conservative updates
EOF
```

#### Environment-Specific Configurations

**Development Environment:**

```bash
# ~/.config/gonzo/dev-config.yml
ai-model: "gpt-3.5-turbo"           # Cost-effective
update-interval: 1s                  # Responsive
log-buffer: 2000                     # Smaller buffer
ai-context-size: 2000               # Reduce token usage
```

**Production Environment:**

```bash
# ~/.config/gonzo/prod-config.yml
ai-model: "gpt-4"                   # Best quality
update-interval: 5s                  # Conservative
log-buffer: 10000                   # Larger buffer
ai-context-size: 8000               # More context
ai-response-timeout: 60s            # Longer timeout
```

**Usage:**

```bash
# Use specific configuration
gonzo --config ~/.config/gonzo/dev-config.yml -f logs/debug.log
gonzo --config ~/.config/gonzo/prod-config.yml -f /var/log/app.log
```

### Multi-Provider Setup

#### Switching Between Providers

**Script for Easy Provider Switching:**

```bash
#!/bin/bash
# ai-provider-switch.sh

switch_to_openai() {
    export OPENAI_API_KEY="sk-your-openai-key"
    export OPENAI_API_BASE=""
    echo "Switched to OpenAI"
}

switch_to_ollama() {
    export OPENAI_API_KEY="ollama"
    export OPENAI_API_BASE="http://localhost:11434"
    echo "Switched to Ollama"
}

switch_to_lmstudio() {
    export OPENAI_API_KEY="local-key"
    export OPENAI_API_BASE="http://localhost:1234/v1"
    echo "Switched to LM Studio"
}

# Usage: source ai-provider-switch.sh && switch_to_openai
```

#### Provider-Specific Aliases

```bash
# Add to ~/.bashrc or ~/.zshrc

# OpenAI for production incidents
alias gonzo-openai='OPENAI_API_KEY="sk-your-key" \
                    OPENAI_API_BASE="" \
                    gonzo --ai-model="gpt-4"'

# Ollama for development
alias gonzo-local='OPENAI_API_KEY="ollama" \
                   OPENAI_API_BASE="http://localhost:11434" \
                   gonzo --ai-model="llama3"'

# LM Studio for testing
alias gonzo-lms='OPENAI_API_KEY="local-key" \
                 OPENAI_API_BASE="http://localhost:1234/v1" \
                 gonzo'
```

### Troubleshooting Setup Issues

#### OpenAI Issues

**"Invalid API Key" Error:**

```bash
# Check API key is set correctly
echo $OPENAI_API_KEY

# Verify API key format (should start with 'sk-')
# Test API key directly
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     https://api.openai.com/v1/models
```

**"Rate limit exceeded" Error:**

```bash
# Check your OpenAI usage limits
# Visit https://platform.openai.com/account/usage

# Use cheaper model temporarily
gonzo -f logs.log --ai-model="gpt-3.5-turbo"

# Add delays between requests (automatic in Gonzo)
```

**"Insufficient credits" Error:**

```bash
# Add credits to your OpenAI account
# Visit https://platform.openai.com/account/billing

# Check current balance
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     https://api.openai.com/v1/dashboard/billing/subscription
```

#### Ollama Issues

**"Connection refused" Error:**

```bash
# Check if Ollama is running
ps aux | grep ollama

# Start Ollama if not running
ollama serve

# Check if port is accessible
curl http://localhost:11434/api/tags
```

**"Model not found" Error:**

```bash
# List available models
ollama list

# Download missing model
ollama pull llama3

# Verify model is available
ollama show llama3
```

**High Memory Usage:**

```bash
# Use smaller model
ollama pull mistral  # 4.1GB instead of 7GB+

# Monitor memory usage
htop

# Restart Ollama if memory issues persist
killall ollama
ollama serve
```

#### LM Studio Issues

**"No models available" Error:**

```bash
# Check LM Studio is running with server started
# Verify model is loaded in LM Studio
# Check server URL is correct (usually :1234)

# Test connectivity
curl http://localhost:1234/v1/models
```

**"Model loading failed" Error:**

```bash
# Check available RAM
free -h

# Try smaller model in LM Studio
# Restart LM Studio application
# Verify model file isn't corrupted
```

#### Network and Firewall Issues

**Corporate Firewall:**

```bash
# Test connectivity to AI providers
curl -I https://api.openai.com
curl -I http://localhost:11434  # For Ollama
curl -I http://localhost:1234   # For LM Studio

# Configure proxy if needed
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
```

**SSL Certificate Issues:**

```bash
# Skip SSL verification (not recommended for production)
export PYTHONHTTPSVERIFY=0

# Or install proper certificates
# Contact your IT department for certificate installation
```

### What's Next?

Now that you have AI configured, explore these guides:

* **AI Providers Guide** - Detailed setup for specific providers
* **Using AI Features** - Master AI-powered workflows and analysis
* **Log Analysis** - Combine AI with algorithmic analysis

Or start using AI features immediately:

```bash
# Start analyzing with AI
gonzo -f your-logs.log --ai-model="gpt-4"

# Try these AI features:
# - Press 'i' on any log entry for analysis
# - Press 'c' in log details for interactive chat
# - Press 'm' to switch between AI models
```

***

**Your AI-powered log analysis is ready!** 🤖 You can now get intelligent insights, natural language explanations, and automated pattern recognition for any log analysis task.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.controltheory.com/backup/ai-setup-and-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.