AI Agent Troubleshooting Guide¶

This guide helps resolve common issues with the PyFIA AI Agent.

Quick Diagnostics¶

Run this command to check your setup:

# Check all dependencies and connections
pyfia-ai --diagnose

This will verify: - ✓ Python version (3.11+) - ✓ Required packages installed - ✓ OpenAI API key configured - ✓ Database connection - ✓ Memory/cache directories

Common Issues¶

1. OpenAI API Key Issues¶

Problem: "OpenAI API key not found"¶

Solution:

# Set the API key
export OPENAI_API_KEY="sk-..."

# Or add to your shell profile
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

Problem: "Invalid API key"¶

Check: - Key starts with sk- - No extra spaces or quotes - Key hasn't been revoked

Test:

import openai
openai.api_key = "your-key"
openai.models.list()  # Should work

2. Database Connection Issues¶

Problem: "Database not found"¶

Solutions:

1. Check file path:

   # Verify file exists
   ls -la /path/to/database.duckdb
   
   # Use absolute path
   pyfia-ai /absolute/path/to/database.duckdb
   

2. Check permissions:

   # Ensure read access
   chmod 644 database.duckdb
   

Problem: "Cannot open database"¶

Possible causes: - Database is corrupted - Wrong DuckDB version - File is locked by another process

Fix:

import duckdb
# Test connection
conn = duckdb.connect("database.duckdb", read_only=True)
conn.execute("SELECT 1").fetchall()

3. Import and Dependency Issues¶

Problem: "ModuleNotFoundError: langchain"¶

Solution:

# Install with AI dependencies
pip install pyfia[langchain]

# Or install all
pip install pyfia[all]

Problem: "ImportError: cannot import name 'create_react_agent'"¶

Fix - Update LangGraph:

pip install --upgrade langgraph langchain-core

4. Query Processing Issues¶

Problem: "No results found"¶

Common causes and fixes:

1. Wrong EVALID:

   # Find available EVALIDs
   fia-ai> evalid
   
   # Use correct EVALID
   fia-ai> Using evalid 372301, count trees
   

2. Too restrictive filters:

   # Start broad
   fia-ai> How many trees total?
   
   # Then narrow down
   fia-ai> How many oak trees?
   fia-ai> How many large oak trees?
   

3. Species name issues:

   # Use partial names
   fia-ai> species pine  # Finds all pines
   
   # Or use scientific names
   fia-ai> Find Quercus alba
   

Problem: "Query timeout"¶

Solutions:

1. Simplify query:

   # Instead of
   fia-ai> Show all tree measurements
   
   # Use
   fia-ai> Show tree counts by species
   

2. Add limits:

   fia-ai> Show top 100 plots by biomass
   

3. Use specific filters:

   fia-ai> Show data for North Carolina only
   

5. Memory and Performance Issues¶

Problem: "Conversation not persisting"¶

Check checkpoint directory:

# Default location
ls ~/.pyfia/checkpoints/

# Set custom location
pyfia-ai database.duckdb --checkpoint-dir ./my_checkpoints

Fix permissions:

mkdir -p ~/.pyfia/checkpoints
chmod 755 ~/.pyfia/checkpoints

Problem: "Slow responses"¶

Optimizations:

1. Enable caching:

   agent = FIAAgent("db.duckdb", enable_cache=True)
   

2. Reduce token usage:

   agent = FIAAgent("db.duckdb", max_tokens=1000)
   

3. Use faster model:

   agent = FIAAgent("db.duckdb", model_name="gpt-3.5-turbo")
   

6. Formatting and Display Issues¶

Problem: "No colors or formatting in terminal"¶

Solutions:

1. Check terminal support:

   # Test Rich support
   python -c "from rich import print; print('[bold green]Test[/bold green]')"
   

2. Force color output:

   export FORCE_COLOR=1
   pyfia-ai database.duckdb
   

3. Disable Rich if needed:

   agent = FIAAgent("db.duckdb", use_rich=False)
   

Problem: "Tables not displaying correctly"¶

Fix terminal width:

# Check terminal size
echo $COLUMNS

# Set minimum width
export COLUMNS=120

Error Messages Reference¶

API Errors¶

Database Errors¶

Agent Errors¶

Debugging Techniques¶

1. Enable Verbose Mode¶

# See detailed processing
pyfia-ai database.duckdb --verbose

# Or in Python
agent = FIAAgent("db.duckdb", verbose=True)

2. Check Logs¶

# View agent logs
tail -f ~/.pyfia/logs/agent.log

# Enable debug logging
export PYFIA_LOG_LEVEL=DEBUG

3. Test Individual Components¶

# Test database connection
from pyfia.database.query_interface import DuckDBQueryInterface
qi = DuckDBQueryInterface("database.duckdb")
qi.test_connection()

# Test tools directly
from pyfia.ai.agent import find_species_codes
result = find_species_codes("oak")
print(result)

4. Trace LangChain Execution¶

# Enable LangChain tracing
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="your-langsmith-key"

Performance Optimization¶

Query Optimization¶

1. Use EVALIDs:

   # Slow - scans all data
   fia-ai> Count all trees
   
   # Fast - uses EVALID index
   fia-ai> Count trees in evalid 372301
   

2. Filter early:

   # Efficient
   fia-ai> Show pine volume in California
   
   # Inefficient  
   fia-ai> Show all volume, then filter for pine in California
   

Resource Management¶

1. Limit memory usage:

   # Set max result size
   agent = FIAAgent("db.duckdb", max_result_mb=100)
   

2. Clear cache periodically:

   fia-ai> clear cache
   

3. Close unused connections:

   agent.close()  # When done
   

Getting Help¶

Self-Help Resources¶

1. Built-in help:

   fia-ai> help
   fia-ai> help export
   

2. Examples:

   fia-ai> show examples
   

3. Documentation:

4. User Guide
5. Examples
6. Tools Reference

Community Support¶

1. GitHub Issues: Report bugs and request features
2. Discussions: Ask questions and share tips
3. Wiki: Community-contributed guides

Debug Information¶

When reporting issues, include:

# System info
python --version
pip show pyfia

# Error details
pyfia-ai --diagnose > debug_info.txt

# Sample query that fails
echo "Your problematic query"

Recovery Procedures¶

Reset Agent State¶

# Clear all caches and checkpoints
rm -rf ~/.pyfia/checkpoints/*
rm -rf ~/.pyfia/cache/*

# Restart fresh
pyfia-ai database.duckdb

Reinstall Package¶

# Complete reinstall
pip uninstall pyfia
pip install pyfia[all] --force-reinstall

Database Repair¶

import duckdb

# Verify database integrity
conn = duckdb.connect("database.duckdb")
conn.execute("PRAGMA integrity_check").fetchall()

# Export and reimport if needed
conn.execute("EXPORT DATABASE 'backup' (FORMAT PARQUET)")

Preventive Measures¶

1. Regular Updates:

   pip install --upgrade pyfia[all]
   

2. Monitor Resources:

   # Check disk space
   df -h ~/.pyfia
   
   # Monitor memory
   htop  # While running agent
   

3. Backup Conversations:

   # Backup checkpoints
   cp -r ~/.pyfia/checkpoints ~/.pyfia/checkpoints.backup
   

4. Test After Updates:

   pyfia-ai --diagnose
   

Remember: Most issues can be resolved by checking the basics - API key, database path, and dependencies. When in doubt, start with pyfia-ai --diagnose.