Troubleshooting Guide

This guide covers common issues you might encounter when working with Airtrain and how to resolve them.

API Connectivity Issues

API Key Authentication Errors

Symptoms:

• Error messages like "Authentication failed" or "Invalid API key"
• Status codes 401 or 403 from provider APIs

Solutions:

1. Verify your API key is correct and not expired
2. Ensure you're loading credentials correctly:

from airtrain.integrations.openai.credentials import OpenAICredentials
import os

# Create credentials
creds = OpenAICredentials(
    openai_api_key=os.getenv("OPENAI_API_KEY"),
    organization_id=os.getenv("OPENAI_ORG_ID"),  # Optional
)

# Validate credentials
try:
    creds.validate_credentials()
    print("Credentials are valid")
except Exception as e:
    print(f"Credential error: {e}")

3. Check if you need organization IDs (for OpenAI) or other provider-specific details
4. For OpenAI, verify you're using the correct key type (production vs test)

Rate Limiting Issues

Symptoms:

• Error messages mentioning "rate limit exceeded"
• Status code 429 from provider APIs

Solutions:

1. Implement rate limiting in your Airtrain setup:

from airtrain.utils.rate_limiters import ExponentialBackoffLimiter
from airtrain.models import OpenAIModel

# Set up rate limiting
limiter = ExponentialBackoffLimiter(
    initial_delay=1, 
    max_delay=60,
    max_retries=5
)

# Use with model
model = OpenAIModel(
    model_name="gpt-4-turbo",
    rate_limiter=limiter
)

2. Batch your requests when processing multiple items
3. Consider using a model with lower usage costs
4. Review your account limits with the provider and request increases if needed

Schema and Validation Errors

Input Schema Validation Failures

Symptoms:

• Errors like "Validation error for model..."
• Pydantic validation exceptions

Solutions:

1. Check your input data against your schema requirements:

from airtrain.core.schemas import InputSchema
from pydantic import Field, ValidationError

class UserQuery(InputSchema):
    query: str
    max_results: int = Field(ge=1, le=50)

# Debug validation issues
try:
    input_data = UserQuery(query="Search term", max_results=100)  # Will fail validation
except ValidationError as e:
    print(f"Validation error: {e}")
    # Fix: Set value within allowed range
    input_data = UserQuery(query="Search term", max_results=50)

2. Add explicit type conversions if needed
3. Use Pydantic's model_validate method to validate data:

try:
    # Validate from dict
    data_dict = {"query": "test", "max_results": "10"}  # Note: string instead of int
    input_data = UserQuery.model_validate(data_dict)  # Pydantic will convert to int
    print(f"Validated successfully: {input_data}")
except ValidationError as e:
    print(f"Validation failed: {e}")

Tool Output Parsing Errors

Symptoms:

• Error messages about tools returning unexpected formats
• Issues with nested objects in tool responses

Solutions:

1. Ensure your tools return objects that match the output schema:

from airtrain.core.schemas import OutputSchema

class SearchResult(OutputSchema):
    results: list[dict]
    total: int

# Correct
def search_function(query):
    # ... search logic ...
    return SearchResult(results=[{"title": "Result"}], total=1)

# Incorrect - will cause errors
def bad_search_function(query):
    # Returns dict instead of SearchResult object
    return {"results": [{"title": "Result"}], "total": 1}

2. Use explicit schema validation in your tool implementations:

def search_function(query):
    # ... search logic ...
    results = get_search_results(query)
    
    # Validate before returning
    try:
        return SearchResult(results=results, total=len(results))
    except ValidationError:
        # Fallback to empty results on validation error
        return SearchResult(results=[], total=0)

Agent Behavior Issues

Agent Not Using Tools Correctly

Symptoms:

• Agent doesn't use available tools when expected
• Tools are called with incorrect parameters

Solutions:

1. Ensure you're registering tools correctly with the agent:

from airtrain.core import Agent, Tool

# Create tools
calculator_tool = Tool(
    name="calculator",
    function=calculate,
    input_schema=CalculatorInput,
    output_schema=CalculatorOutput,
    description="Calculate mathematical expressions (add, subtract, multiply, divide)"
)

# Register properly
agent = Agent(
    name="math_helper",
    model=model,
    tools=[calculator_tool]  # Add tools here
)

# Or add later
agent.add_tool(calculator_tool)

2. Check your tool descriptions - they should clearly explain:

   • What the tool does
   • When to use it
   • Required parameters
   • Example usage

3. Verify model capabilities (some models support tool calling better than others)

Memory Persistence Issues

Symptoms:

• Agent "forgets" information between sessions
• Context is lost between interactions

Solutions:

1. Set up persistent memory:

from airtrain.core.memory import FileMemory

# Create persistent memory
memory = FileMemory(file_path="agent_memory.json")

# Store data
memory.store("user_preferences", {"theme": "dark"})

# Create agent with persistent memory
agent = Agent(name="assistant", model=model, memory=memory)

2. Explicitly save memory after updates if using custom storage:

# After processing
response = agent.process("Remember I prefer dark mode")
agent.memory.save()  # Explicitly save if needed

3. Check file permissions if using file-based storage

Integration-Specific Issues

OpenAI Integration Issues

Common issues:

• "context_length_exceeded" errors
• Function/tool calling format errors

Solutions:

1. Monitor and manage token usage:

from airtrain.models import OpenAIModel

model = OpenAIModel(
    model_name="gpt-4-turbo",
    max_tokens=1000  # Limit response tokens
)

# Track usage
response = agent.process("Long query...")
print(f"Tokens used: {response.usage.total_tokens}")

2. For tool calling issues, ensure your schemas match OpenAI's expected format
3. Check OpenAI model versions - some features might not be available in all models

Anthropic Integration Issues

Common issues:

• Messages exceeding Claude's context window
• Multi-modal content formatting errors

Solutions:

1. Check compatible model versions for features you're using
2. For multi-modal content, ensure images are properly encoded:

import base64

# Correctly encode images for Claude
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

# Use in multi-modal content
image_data = encode_image("image.jpg")

Performance Optimization

Slow Response Times

Symptoms:

• Responses from agents take longer than expected
• System feels unresponsive

Solutions:

1. Use faster models for time-sensitive tasks:

# Slower but more capable
opus_model = AnthropicModel("claude-3-opus-20240229")

# Faster for simple tasks
haiku_model = AnthropicModel("claude-3-haiku-20240307")

2. Implement request batching for multiple items
3. Use caching for common queries:

from airtrain.utils.caching import ResponseCache

# Create cache
cache = ResponseCache(ttl=3600)  # 1 hour TTL

# Use in processing
query = "What is Airtrain?"
cached_response = cache.get(query)

if cached_response:
    return cached_response
else:
    response = agent.process(query)
    cache.set(query, response)
    return response

4. Consider asynchronous processing for non-blocking operations

Getting More Help

If you're still experiencing issues:

1. Check the GitHub repository for known issues
2. Join the GitHub Discussions to ask questions
3. Review detailed error logs (enable DEBUG level logging)

from airtrain.utils.logging import configure_logging

# Enable detailed logging
configure_logging(
    level="DEBUG",
    file_path="airtrain_debug.log"
)

4. Include relevant details when asking for help:
   • Airtrain version
   • Python version
   • Error messages and stack traces
   • Code snippets demonstrating the issue
   • Steps to reproduce the problem