🔍 Add environment debug script

Helps diagnose 'str expected, not NoneType' startup error:
• Checks all required environment variables
• Tests critical module imports
• Identifies missing OPENAI_API_KEY as root cause
• Provides specific HF Spaces setup instructions

Usage: python debug_env.py

debug_env.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+Environment Variables Debug Script for HF Spaces
+Helps diagnose the 'str expected, not NoneType' error
+"""
+
+import os
+import sys
+from pathlib import Path
+
+def check_environment():
+    """Check all required environment variables and configurations"""
+    print("🔍 AgentGraph Environment Debug Report")
+    print("=" * 50)
+    print()
+    
+    # Critical environment variables
+    env_vars = {
+        "OPENAI_API_KEY": "❌ REQUIRED - OpenAI API access",
+        "LANGFUSE_PUBLIC_KEY": "🟡 Optional - AI monitoring",
+        "LANGFUSE_SECRET_KEY": "🟡 Optional - AI monitoring", 
+        "LANGFUSE_HOST": "🟡 Optional - AI monitoring",
+        "OPENAI_MODEL_NAME": "🟡 Optional - defaults to gpt-4o-mini",
+        "DB_URI": "🟡 Optional - defaults to SQLite",
+        "PYTHONPATH": "🔧 System variable",
+        "HOME": "🔧 System variable",
+        "PATH": "🔧 System variable"
+    }
+    
+    print("📋 Environment Variables Check:")
+    print("-" * 30)
+    missing_critical = []
+    
+    for var, description in env_vars.items():
+        value = os.getenv(var)
+        if value is None:
+            status = "❌ NOT SET"
+            if "REQUIRED" in description:
+                missing_critical.append(var)
+        elif value == "":
+            status = "⚠️ EMPTY"
+            if "REQUIRED" in description:
+                missing_critical.append(var)
+        else:
+            # Mask sensitive values
+            if "KEY" in var or "SECRET" in var:
+                masked_value = f"{value[:8]}..." if len(value) > 8 else "***"
+                status = f"✅ SET ({masked_value})"
+            else:
+                status = f"✅ SET ({value[:50]}...)" if len(value) > 50 else f"✅ SET ({value})"
+        
+        print(f"  {var:20} | {status:25} | {description}")
+    
+    print()
+    
+    # Check critical paths and files
+    print("📁 Critical Paths Check:")
+    print("-" * 25)
+    
+    paths_to_check = [
+        ("Current directory", Path.cwd()),
+        ("utils/config.py", Path("utils/config.py")),
+        ("backend/app.py", Path("backend/app.py")),
+        ("main.py", Path("main.py")),
+        ("pyproject.toml", Path("pyproject.toml"))
+    ]
+    
+    for name, path in paths_to_check:
+        if path.exists():
+            status = "✅ EXISTS"
+        else:
+            status = "❌ MISSING"
+        print(f"  {name:20} | {status:15} | {path}")
+    
+    print()
+    
+    # Python path check
+    print("🐍 Python Environment:")
+    print("-" * 20)
+    print(f"  Python version: {sys.version}")
+    print(f"  Python path: {sys.executable}")
+    print(f"  Working directory: {os.getcwd()}")
+    print(f"  PYTHONPATH: {os.getenv('PYTHONPATH', 'NOT SET')}")
+    
+    print()
+    
+    # Try importing critical modules
+    print("📦 Import Test:")
+    print("-" * 15)
+    
+    modules_to_test = [
+        "utils.config",
+        "backend.app", 
+        "fastapi",
+        "uvicorn",
+        "pydantic",
+        "sqlalchemy"
+    ]
+    
+    for module in modules_to_test:
+        try:
+            __import__(module)
+            print(f"  {module:20} | ✅ OK")
+        except ImportError as e:
+            print(f"  {module:20} | ❌ FAILED: {str(e)}")
+        except Exception as e:
+            print(f"  {module:20} | ⚠️ ERROR: {str(e)}")
+    
+    print()
+    
+    # Summary
+    print("📊 Summary:")
+    print("-" * 10)
+    
+    if missing_critical:
+        print(f"❌ CRITICAL: Missing required environment variables: {', '.join(missing_critical)}")
+        print("🔧 Fix: Set these variables in HF Spaces Settings > Environment variables")
+        return False
+    else:
+        print("✅ All critical environment variables are set")
+        
+        # Try to identify the specific error
+        print()
+        print("🔍 Specific Error Analysis:")
+        print("The 'str expected, not NoneType' error suggests:")
+        print("1. A string parameter is being passed None instead of a string")
+        print("2. Most likely in configuration or initialization code")
+        print("3. Check Pydantic model validation or string concatenation")
+        
+        return True
+
+def test_config_import():
+    """Test importing and using the config module"""
+    print()
+    print("🧪 Config Module Test:")
+    print("-" * 20)
+    
+    try:
+        from utils.config import OPENAI_API_KEY, validate_config
+        
+        print(f"OPENAI_API_KEY loaded: {'✅ YES' if OPENAI_API_KEY else '❌ NO'}")
+        
+        # Test validation
+        is_valid = validate_config()
+        print(f"Config validation: {'✅ PASSED' if is_valid else '❌ FAILED'}")
+        
+        return is_valid
+        
+    except Exception as e:
+        print(f"❌ Config import failed: {str(e)}")
+        return False
+
+if __name__ == "__main__":
+    print("Starting environment debug check...")
+    print()
+    
+    # Basic environment check
+    env_ok = check_environment()
+    
+    # Config test
+    config_ok = test_config_import()
+    
+    print()
+    print("🎯 RECOMMENDATIONS:")
+    print("=" * 20)
+    
+    if not env_ok:
+        print("1. ❌ Set missing OPENAI_API_KEY in HF Spaces environment variables")
+        print("2. 🔗 Go to: https://huggingface.co/spaces/holistic-ai/AgentGraph/settings")
+        print("3. 📝 Add: OPENAI_API_KEY = your_openai_api_key")
+    
+    if not config_ok:
+        print("4. 🔧 Check utils/config.py for import issues")
+        print("5. 🐍 Verify Python dependencies are installed correctly")
+    
+    if env_ok and config_ok:
+        print("✅ Environment looks good!")
+        print("🔍 The 'str expected, not NoneType' error may be in:")
+        print("   • Pydantic model validation")
+        print("   • String formatting/concatenation")
+        print("   • Database connection string")
+        print("   • FastAPI configuration")
+        
+    print()
+    print("📊 Run this script in HF Spaces to get the exact error location!")