Model Configuration Guide

Overview

The Aitana platform supports multiple AI models with different capabilities and access levels. This guide provides comprehensive information on configuring and using available models.

Available Models

Anthropic Models

Claude 3.7 Sonnet (Default)

  • Model ID: claude-3-7-sonnet-20250219
  • Smart Tool Key: anthropic-3.7-sonnet
  • Access Level: General availability
  • Use Cases: General conversations, code analysis, document processing
  • Features: Web search integration, balanced performance

Claude 3.5 Sonnet

  • Model ID: claude-3-5-sonnet-20241022
  • Smart Tool Key: anthropic-3.5-sonnet
  • Access Level: General availability
  • Use Cases: Fast responses, lightweight tasks
  • Features: Quick processing, web search integration

Claude 4.0 Sonnet

  • Model ID: claude-sonnet-4-20250514
  • Smart Tool Key: anthropic-4.0-sonnet
  • Access Level: General availability
  • Use Cases: Complex reasoning, advanced analysis
  • Features: Enhanced capabilities, web search integration

Claude 4.0 Opus

  • Model ID: claude-opus-4-20250514
  • Smart Tool Key: anthropic-4.0-opus
  • Access Level: Admin access required (admin-tools tag)
  • Use Cases: Most complex tasks, research, detailed analysis
  • Features: Highest reasoning capability, web search integration

Google Gemini Models

Gemini 2.5 Flash (Default Gemini)

  • Model ID: gemini-2.5-flash
  • Smart Tool Key: gemini-2.5-flash
  • Access Level: General availability
  • Use Cases: Fast responses, code execution, multimodal tasks
  • Features: Code execution, quick processing

Gemini 2.5 Flash Thinking

  • Model ID: gemini-2.5-flash
  • Smart Tool Key: gemini-2.5-flash-thinking
  • Access Level: Beta access required (beta-testers tag)
  • Use Cases: Fast responses with enhanced reasoning
  • Features: Code execution, thinking mode, step-by-step reasoning

Gemini 2.5 Pro

  • Model ID: gemini-2.5-pro
  • Smart Tool Key: gemini-2.5-pro
  • Access Level: General availability
  • Use Cases: Advanced tasks, complex code generation, multimodal processing
  • Features: Code execution, enhanced capabilities

Gemini 2.5 Pro Thinking

  • Model ID: gemini-2.5-pro
  • Smart Tool Key: gemini-2.5-pro-thinking
  • Access Level: Beta access required (beta-testers tag)
  • Use Cases: Most complex tasks with detailed reasoning
  • Features: Code execution, thinking mode, advanced reasoning

OpenAI Models

OpenAI GPT-5

  • Model ID: gpt-4o (fallback until GPT-5 available)
  • Smart Tool Key: openai-gpt-5
  • Access Level: Beta access required (beta-testers tag)
  • Use Cases: Advanced language understanding, complex reasoning
  • Features: Multimodal capabilities, function calling

OpenAI GPT-5 Mini

  • Model ID: gpt-4o-mini (fallback until GPT-5 Mini available)
  • Smart Tool Key: openai-gpt-5-mini
  • Access Level: General availability
  • Use Cases: Fast responses, cost-efficient processing
  • Features: Lightweight model, function calling

OpenAI GPT-5 Nano

  • Model ID: gpt-3.5-turbo (fallback until GPT-5 Nano available)
  • Smart Tool Key: openai-gpt-5-nano
  • Access Level: General availability
  • Use Cases: Very fast responses, simple tasks
  • Features: Ultra-lightweight, basic function calling

OpenAI O3

  • Model ID: o1-preview (fallback until O3 available)
  • Smart Tool Key: openai-o3
  • Access Level: Beta access required (beta-testers tag)
  • Use Cases: Complex reasoning, mathematical problems, code generation
  • Features: Advanced reasoning capabilities, step-by-step thinking

OpenAI O3 Mini

  • Model ID: o1-mini (fallback until O3 Mini available)
  • Smart Tool Key: openai-o3-mini
  • Access Level: General availability
  • Use Cases: Reasoning tasks, cost-efficient advanced processing
  • Features: Reasoning capabilities, efficient processing

Configuration Methods

Frontend Configuration

Via Advanced Models Tool

In the frontend, models are configured through the Advanced Models tool in ToolSelector.tsx:

{
  id: 'advanced_models',
  name: 'Advanced Models',
  description: 'Select which AI model to use for responses',
  category: 'behaviour',
  icon: Brain,
  configuration: {
    smart_tool: {
      type: 'select',
      label: 'Model Selection',
      options: [
        { value: 'anthropic-4.0-opus', label: 'Anthropic 4.0 Opus', requiresTags: ['admin-tools'] },
        { value: 'anthropic-4.0-sonnet', label: 'Anthropic 4.0 Sonnet' },
        { value: 'anthropic-3.7-sonnet', label: 'Anthropic 3.7' },
        { value: 'anthropic-3.5-sonnet', label: 'Anthropic 3.5' },
        { value: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro' },
        { value: 'gemini-2.5-pro-thinking', label: 'Gemini 2.5 Pro Thinking', requiresTags: ['beta-testers'] },
        { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash' },
        { value: 'openai-gpt-5', label: 'OpenAI GPT-5', requiresTags: ['beta-testers'] },
        { value: 'openai-gpt-5-mini', label: 'OpenAI GPT-5 Mini' },
        { value: 'openai-gpt-5-nano', label: 'OpenAI GPT-5 Nano' },
        { value: 'openai-o3', label: 'OpenAI O3', requiresTags: ['beta-testers'] },
        { value: 'openai-o3-mini', label: 'OpenAI O3 Mini' },
        { value: 'gemini-2.5-flash-thinking', label: 'Gemini 2.5 Flash Thinking', requiresTags: ['beta-testers'] },
        { value: 'none', label: 'None' }
      ]
    },
    enable_anthropic_web_search: {
      type: 'checkbox',
      label: 'Enable Web Search (Anthropic only)'
    }
  }
}

Via Code Execution Tool

For code execution tasks, a simplified model selection is available:

{
  id: 'code_execution',
  configuration: {
    coder_model: {
      type: 'select',
      options: [
        { value: 'gemini', label: 'Gemini' },
        { value: 'anthropic', label: 'Anthropic' }
      ]
    }
  }
}

Backend Configuration

Default Model Selection

The backend uses the following priority for model selection:

  1. Explicit Configuration: toolConfigs.advanced_models.smart_tool
  2. Fallback: Claude 3.7 Sonnet (claude-3-7-sonnet-20250219)
# From vac_service.py
selected_smart_tool = toolConfigs.get("advanced_models", {}).get("smart_tool") or "anthropic"

Model Resolution

The smarts.py module handles model resolution:

def stream_smart(question, chat_history, selected_smart_tool, **kwargs):
    if selected_smart_tool in ["anthropic-3.7-sonnet", "anthropic-3.5-sonnet", "anthropic-4.0-sonnet", "anthropic-4.0-opus"]:
        # Route to Anthropic models
        return stream_smart_anthropic(...)
    elif selected_smart_tool.startswith("gemini-2.5"):
        # Route to Gemini 2.5 models
        return stream_smart_gemini_thinking(...) if "thinking" in selected_smart_tool else stream_smart_gemini(...)
    elif selected_smart_tool == "none":
        return {"error": "No smart tool selected"}
    else:
        raise ValueError(f"Unknown smart_tool: {selected_smart_tool}")

Access Control

Tag-Based Permissions

Model access is controlled through user tags:

  • admin-tools: Required for Claude 4.0 Opus
  • beta-testers: Required for Gemini Thinking models
  • No tags required: All other models (general availability)

Permission Validation

// Frontend validation example
const hasRequiredTags = (requiresTags: string[], userTags: string[]) => {
  return requiresTags.every(tag => userTags.includes(tag));
};

Model-Specific Features

Anthropic Models

Web Search Integration

  • Available for all Anthropic models
  • Configured via enable_anthropic_web_search checkbox
  • Uses built-in web search capabilities
# Backend configuration
if toolConfigs.get("advanced_models", {}).get("enable_anthropic_web_search"):
    # Enable web search tools

Gemini Models

Code Execution

  • Available for all Gemini models
  • Sandboxed Python execution environment
  • File system access within execution context

Thinking Mode

  • Available for -thinking variants
  • Provides step-by-step reasoning
  • Enhanced problem-solving capabilities
# Thinking mode detection
if "thinking" in selected_smart_tool:
    return stream_smart_gemini_thinking(...)

Best Practices

Model Selection Strategy

  1. General Use: Claude 3.7 Sonnet (default)
  2. Fast Responses: Claude 3.5 Sonnet or Gemini 2.5 Flash
  3. Code Tasks: Gemini 2.5 models (code execution support)
  4. Complex Analysis: Claude 4.0 Sonnet or Gemini 2.5 Pro
  5. Most Complex Tasks: Claude 4.0 Opus (admin access)
  6. Enhanced Reasoning: Gemini Thinking models (beta access)

Performance Considerations

  • Token Limits: Each model has different context limits
  • Response Time: Flash models are optimized for speed
  • Cost: Higher-tier models (4.0 Opus) have higher costs
  • Capabilities: Match model to task complexity

Configuration Examples

Basic Assistant Configuration

{
  "tools": ["advanced_models"],
  "toolConfigs": {
    "advanced_models": {
      "smart_tool": "anthropic-3.7-sonnet"
    }
  }
}

Code-Focused Assistant

{
  "tools": ["advanced_models", "code_execution"],
  "toolConfigs": {
    "advanced_models": {
      "smart_tool": "gemini-2.5-pro"
    },
    "code_execution": {
      "coder_model": "gemini"
    }
  }
}

Research Assistant (Admin)

{
  "tools": ["advanced_models"],
  "toolConfigs": {
    "advanced_models": {
      "smart_tool": "anthropic-4.0-opus",
      "enable_anthropic_web_search": true
    }
  }
}

Migration from Previous Versions

From Gemini 1.5 to 2.5

  • Update all gemini-1.5-* references to gemini-2.5-*
  • New thinking variants available for enhanced reasoning
  • Improved code execution capabilities

From Anthropic 3.0 to 3.7/4.0

  • Claude 3.7 is now the default (previously 3.5)
  • Claude 4.0 models available for advanced tasks
  • Consistent web search integration across all versions

Troubleshooting

Common Issues

Invalid Model Selection

Error: Unknown smart_tool: invalid-model

Solution: Use one of the supported smart tool keys listed above.

Permission Denied

Access denied: Model requires admin-tools tag

Solution: Ensure user has required tags or select a generally available model.

Model Not Responding

Model timeout or connection error

Solution: Check model availability and try fallback model selection.

Debug Configuration

Enable debug logging to troubleshoot model selection:

# Backend debug
VAC_DEBUG=true

# Check model resolution
logging.info(f"Selected model: {selected_smart_tool}")
logging.info(f"Resolved to: {actual_model_id}")

API Reference

Model Selection Endpoint

POST /vac/assistant/<assistant_id>
Content-Type: application/json

{
  "user_input": "Your question here",
  "emissaryConfig": {
    "toolConfigs": {
      "advanced_models": {
        "smart_tool": "anthropic-3.7-sonnet"
      }
    }
  }
}

Direct Model Access

POST /vac/streaming/<model_name>
Content-Type: application/json

{
  "user_input": "Your question here",
  "chat_history": []
}

Where <model_name> can be:

  • anthropic (uses default Anthropic model)
  • gemini (uses default Gemini model)
  • Specific smart tool keys for precise control

See Also