Add comprehensive logging and debugging utilities

Enhanced debugging capabilities for SSH Dev Mode:
- Dual logging (stdout + file) to /tmp/app.log
- DEBUG level logging with detailed component tracking
- Interactive debugging with breakpoints (debug_breakpoint)
- Chat flow debugging script with step-by-step analysis
- Reduced uvicorn/health check noise in logs
- Always-visible debug_print for critical debugging

SSH Debug Tools:
- python3 scripts/debug_chat.py (interactive debugging)
- debug_breakpoint(message, locals()) in code
- Enhanced startup diagnostics

v1.0.5 - Production debugging ready

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

LinkedIn.md

@@ -0,0 +1,95 @@
+# 🚀 VoiceCal.ai v1.0.0 - Clean Architecture Migration
+
+## Migration Success: From Nested Chaos to Clean Deployment
+
+Today I successfully migrated **ChatCal.ai to VoiceCal.ai v1.0.0** with a completely clean repository structure for HuggingFace Spaces deployment.
+
+### The Problem We Solved
+- **Nested directory confusion**: `/chatcal-ai/chatcal-ai/app/` causing path issues
+- **Git workflow inconsistencies**: File upload vs. proper version control
+- **Docker caching issues**: HuggingFace showing stale Dockerfiles
+- **Deployment complexity**: Multiple path adjustments breaking deployments
+
+### The Solution: Fresh Start Architecture
+
+#### Before (Problematic):
+```
+/chatCal.ai/chatcal-ai/  (repo root)
+├── chatcal-ai/          (actual app nested)
+├── speech2text/         (unrelated)
+├── CLAUDE.md           (unrelated)
+└── legacy files...
+```
+
+#### After (Clean):
+```
+/voiceCal-ai-v1/        (repo root = HF Space name)
+├── app/                (FastAPI directly at root)
+├── Dockerfile          (standard deployment)
+├── app.py             (simple entry point)
+├── requirements.txt
+└── pyproject.toml
+```
+
+### Technical Improvements
+
+#### 🏗️ **Architecture**
+- **Standard Docker structure**: No more nested path confusion
+- **Direct file access**: All imports work without path manipulation
+- **Clean git workflow**: Proper semantic versioning (v1.0.0)
+
+#### 🔧 **Development**
+- **Debugging tools**: wget, git, curl, procps, htop, nano, vim, net-tools, lsof, strace
+- **Clean Dockerfile**: No more tee command causing container exit
+- **Proper logging**: Both stdout and `/tmp/app.log` for SSH debugging
+
+#### 🎯 **Deployment**
+- **Fresh HuggingFace Space**: `pgits/voiceCal-ai-v1`
+- **No legacy caching**: Clean start eliminates previous issues
+- **Consistent versioning**: Semantic version matches deployment
+
+### Migration Process
+
+1. ✅ **Created clean directory structure** matching HF Space name
+2. ✅ **Copied essential files** (app/, Dockerfile, requirements.txt, etc.)
+3. ✅ **Updated all path references** for standard deployment
+4. ✅ **Initialized fresh git repo** with proper main branch
+5. ✅ **Ready for fresh HF Space** deployment
+
+### Key Lessons Learned
+
+#### 🎯 **Project Structure Matters**
+- Directory naming should match deployment target
+- Avoid nested structures that complicate Docker deployments
+- Keep unrelated files separate from deployment artifacts
+
+#### 🔄 **Git Workflow Discipline**
+- Always use proper git workflow vs. ad-hoc file uploads
+- Semantic versioning prevents deployment confusion
+- Clean commit history aids debugging
+
+#### 🐳 **Docker Best Practices**
+- Standard WORKDIR structure
+- Include debugging tools for production troubleshooting
+- Avoid complex shell commands in CMD that can cause exit issues
+
+### Next Steps
+
+Now ready to create fresh HuggingFace Space `pgits/voiceCal-ai-v1` with:
+- ✅ Clean repository structure
+- ✅ Standard Docker deployment
+- ✅ All debugging tools included
+- ✅ Proper git workflow established
+- ✅ Semantic versioning (v1.0.0)
+
+**Migration Summary:**
+- **Old**: Nested complexity, path confusion, deployment issues
+- **New**: Clean structure, standard paths, reliable deployment
+
+This migration eliminates the file inconsistencies and deployment issues we were experiencing, setting up a professional foundation for future development.
+
+---
+
+#VoiceAI #HuggingFace #Docker #SoftwareEngineering #CleanArchitecture #FastAPI #Deployment #GitWorkflow
+
+**VoiceCal.ai v1.0.0** - Professional voice-first calendar booking with Google Calendar integration, STT/TTS, and Groq LLM backend.

app.py

@@ -19,25 +19,41 @@ os.environ.setdefault("APP_PORT", "7860")  # HF Spaces default port
 from app.api.main import app
 
 if __name__ == "__main__":
-    import logging
+    # Setup enhanced dual logging (stdout + file)
+    from app.core.logging_config import setup_enhanced_logging, setup_breakpoint_debugging
+
+    # Enable DEBUG level for comprehensive logging
+    log_level = os.environ.get("LOG_LEVEL", "DEBUG")
+    log_file = setup_enhanced_logging(log_level=log_level, log_file="/tmp/app.log")
+    setup_breakpoint_debugging()
 
-    # Configure logging
-    logging.basicConfig(
-        level=logging.INFO,
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-        handlers=[
-            logging.FileHandler('/tmp/app.log'),
-            logging.StreamHandler()
-        ]
-    )
+    import logging
+    logger = logging.getLogger("app.startup")
 
     port = int(os.environ.get("PORT", os.environ.get("APP_PORT", 7860)))
-    print(f"===== Application Startup at {datetime.now()} =====")
-    print(f"🚀 Starting ChatCal.ai on port {port}")
-
-    uvicorn.run(
-        app,
-        host="0.0.0.0",
-        port=port,
-        log_level="info"
-    )
+
+    logger.info(f"🚀 Starting ChatCal.ai VoiceCal-ai-v1 on port {port}")
+    logger.info(f"🔧 Session Backend: {os.environ.get('SESSION_BACKEND', 'unknown')}")
+    logger.info(f"🌍 Environment: {os.environ.get('APP_ENV', 'unknown')}")
+    logger.info(f"📁 Log file: {log_file}")
+    logger.info(f"🐛 SSH debugging available via Dev Mode")
+
+    # Additional startup diagnostics
+    logger.debug("🔍 Environment check:")
+    required_vars = ["GROQ_API_KEY", "GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET", "SECRET_KEY"]
+    for var in required_vars:
+        value = os.environ.get(var, "NOT_SET")
+        masked = value[:10] + "..." if len(value) > 10 and value != "NOT_SET" else value
+        logger.debug(f"   {var}: {masked}")
+
+    try:
+        uvicorn.run(
+            app,
+            host="0.0.0.0",
+            port=port,
+            log_level="warning",  # Reduce uvicorn noise, our dual logger handles app logs
+            access_log=False      # Reduce access log spam
+        )
+    except Exception as e:
+        logger.critical(f"💥 Application startup failed: {e}")
+        raise

app/api/main.py

@@ -306,22 +306,41 @@ async def get_conversation_history(session_id: str):
 @app.post("/chat", response_model=ChatResponse)
 async def chat(request: ChatRequest):
     """Chat with the AI assistant."""
+    from app.core.logging_config import log_chat_request, log_chat_response, debug_print
+
+    # Enhanced logging for chat requests
+    session_id = request.session_id or "new_session"
+    log_chat_request(session_id, request.message)
+    debug_print(f"CHAT START - Session: {session_id[:8]}...", {"message_length": len(request.message)})
+
     try:
         # Create session if not provided
         if not request.session_id:
+            debug_print("Creating new session")
             request.session_id = session_manager.create_session()
-        
+            debug_print(f"New session created: {request.session_id}")
+
         # Get or create conversation
+        debug_print("Getting conversation manager")
         conversation = session_manager.get_or_create_conversation(request.session_id)
         if not conversation:
+            debug_print("ERROR: Conversation not found", {"session_id": request.session_id})
             raise HTTPException(status_code=404, detail="Session not found")
-        
+
+        debug_print("Conversation found, getting response from agent")
+
         # Get response from agent
         response = conversation.get_response(request.message)
-        
+        debug_print("Agent response received", {"response_length": len(response)})
+
         # Store conversation history
+        debug_print("Storing conversation history")
         session_manager.store_conversation_history(request.session_id)
-        
+
+        # Log successful response
+        log_chat_response(request.session_id, response)
+        debug_print("CHAT SUCCESS - Response ready")
+
         return ChatResponse(
             response=response,
             session_id=request.session_id,

app/core/logging_config.py

@@ -0,0 +1,212 @@
+"""
+Enhanced logging configuration for VoiceCal.ai debugging
+
+Provides dual logging to both stdout and file with detailed formatting.
+Includes debugging utilities for SSH breakpoint sessions.
+"""
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+class DualOutputHandler(logging.Handler):
+    """Custom handler that writes to both stdout and file simultaneously."""
+
+    def __init__(self, log_file_path: str):
+        super().__init__()
+        self.log_file_path = log_file_path
+
+        # Ensure log directory exists
+        Path(log_file_path).parent.mkdir(parents=True, exist_ok=True)
+
+        # Create formatter
+        formatter = logging.Formatter(
+            '%(asctime)s | %(levelname)-8s | %(name)-20s | %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        self.setFormatter(formatter)
+
+    def emit(self, record):
+        """Emit log record to both stdout and file."""
+        try:
+            msg = self.format(record)
+
+            # Write to stdout
+            print(msg, flush=True)
+
+            # Write to file
+            with open(self.log_file_path, 'a', encoding='utf-8') as f:
+                f.write(msg + '\n')
+                f.flush()
+
+        except Exception:
+            self.handleError(record)
+
+
+def setup_enhanced_logging(log_level: str = "INFO", log_file: str = "/tmp/app.log"):
+    """
+    Setup enhanced dual logging for VoiceCal.ai
+
+    Args:
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        log_file: Path to log file (default: /tmp/app.log)
+    """
+
+    # Clear any existing handlers
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+
+    # Set log level
+    level = getattr(logging, log_level.upper(), logging.INFO)
+    root_logger.setLevel(level)
+
+    # Add dual output handler
+    dual_handler = DualOutputHandler(log_file)
+    dual_handler.setLevel(level)
+    root_logger.addHandler(dual_handler)
+
+    # Log startup message
+    startup_msg = f"""
+{'='*80}
+🚀 VoiceCal.ai Enhanced Logging Started
+📅 Timestamp: {datetime.now().isoformat()}
+📋 Log Level: {log_level.upper()}
+📁 Log File: {log_file}
+🔧 SSH Debug Mode: Available via Dev Mode
+{'='*80}
+"""
+
+    logging.info(startup_msg)
+
+    # Configure specific loggers for detailed debugging
+    configure_detailed_loggers()
+
+    return log_file
+
+
+def configure_detailed_loggers():
+    """Configure specific loggers for detailed debugging."""
+
+    # Enhanced logging for critical components
+    loggers_config = {
+        'app.core.agent': logging.DEBUG,
+        'app.calendar.auth': logging.DEBUG,
+        'app.core.session_factory': logging.DEBUG,
+        'app.api.main': logging.DEBUG,
+        'google.auth': logging.INFO,
+        'google_auth_httplib2': logging.INFO,
+        'googleapiclient.discovery': logging.INFO,
+        'httpx': logging.WARNING,  # Reduce Groq API noise
+        'llama_index': logging.WARNING,  # Reduce LlamaIndex noise
+    }
+
+    for logger_name, level in loggers_config.items():
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(level)
+
+    logging.info("📊 Detailed logging configured for key components")
+
+
+def log_function_entry(func_name: str, **kwargs):
+    """Log function entry with parameters."""
+    logger = logging.getLogger(f"app.debug.{func_name}")
+    params = ", ".join(f"{k}={v}" for k, v in kwargs.items())
+    logger.debug(f"🔵 ENTER {func_name}({params})")
+
+
+def log_function_exit(func_name: str, result=None, error=None):
+    """Log function exit with result or error."""
+    logger = logging.getLogger(f"app.debug.{func_name}")
+    if error:
+        logger.error(f"🔴 EXIT {func_name} - ERROR: {error}")
+    else:
+        logger.debug(f"🟢 EXIT {func_name} - SUCCESS: {str(result)[:100]}...")
+
+
+def setup_breakpoint_debugging():
+    """
+    Setup debugging utilities for SSH breakpoint sessions.
+
+    Usage in code:
+        from app.core.logging_config import debug_breakpoint
+        debug_breakpoint("Checking calendar auth", locals())
+    """
+    logging.info("🐛 SSH Breakpoint debugging utilities loaded")
+    logging.info("   Use debug_breakpoint(message, locals()) in code for interactive debugging")
+
+
+def debug_breakpoint(message: str, local_vars: dict = None):
+    """
+    Interactive debugging breakpoint for SSH sessions.
+
+    Args:
+        message: Description of breakpoint location
+        local_vars: Local variables to inspect (pass locals())
+    """
+    import pdb
+    import json
+
+    logger = logging.getLogger("app.debug.breakpoint")
+    logger.critical(f"🛑 BREAKPOINT: {message}")
+
+    if local_vars:
+        # Log key variables
+        for key, value in local_vars.items():
+            if not key.startswith('_'):
+                try:
+                    # Try to serialize value for logging
+                    str_val = str(value)[:200]
+                    logger.debug(f"   {key}: {str_val}")
+                except:
+                    logger.debug(f"   {key}: <non-serializable>")
+
+    logger.critical("🔧 Starting interactive debugger (use 'c' to continue)")
+    pdb.set_trace()
+
+
+def log_chat_request(session_id: str, message: str):
+    """Log incoming chat requests with details."""
+    logger = logging.getLogger("app.chat.request")
+    logger.info(f"💬 CHAT REQUEST | Session: {session_id[:8]}... | Message: {message[:100]}...")
+
+
+def log_chat_response(session_id: str, response: str, tools_used: list = None):
+    """Log chat responses with details."""
+    logger = logging.getLogger("app.chat.response")
+    tools_str = f" | Tools: {tools_used}" if tools_used else ""
+    logger.info(f"🤖 CHAT RESPONSE | Session: {session_id[:8]}... | Response: {response[:100]}...{tools_str}")
+
+
+def log_calendar_operation(operation: str, details: dict):
+    """Log calendar operations with details."""
+    logger = logging.getLogger("app.calendar.operation")
+    details_str = ", ".join(f"{k}={v}" for k, v in details.items())
+    logger.info(f"📅 CALENDAR {operation.upper()} | {details_str}")
+
+
+def log_session_operation(operation: str, session_id: str, details: dict = None):
+    """Log session operations with details."""
+    logger = logging.getLogger("app.session.operation")
+    details_str = f" | {details}" if details else ""
+    logger.info(f"🔑 SESSION {operation.upper()} | ID: {session_id[:8]}...{details_str}")
+
+
+# Utility for quick debugging prints that always show
+def debug_print(message: str, data=None):
+    """Always-visible debug print for critical debugging."""
+    timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+    print(f"🚨 DEBUG [{timestamp}] {message}", flush=True)
+    if data:
+        print(f"   Data: {data}", flush=True)
+
+    # Also log to file if possible
+    try:
+        with open("/tmp/debug.log", "a") as f:
+            f.write(f"[{timestamp}] {message}\n")
+            if data:
+                f.write(f"   Data: {data}\n")
+            f.flush()
+    except:
+        pass

scripts/debug_chat.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Interactive debugging script for VoiceCal.ai chat functionality
+
+This script allows you to test and debug chat functionality step by step
+with detailed logging and breakpoints for SSH Dev Mode sessions.
+
+Usage:
+    cd /app && python3 scripts/debug_chat.py
+"""
+
+import sys
+import os
+import uuid
+from datetime import datetime
+
+# Add app to path
+sys.path.insert(0, '/app')
+
+from app.core.logging_config import (
+    setup_enhanced_logging, debug_breakpoint, debug_print,
+    log_chat_request, log_function_entry, log_function_exit
+)
+
+
+def debug_session_manager():
+    """Debug session manager initialization."""
+    debug_print("=== DEBUGGING SESSION MANAGER ===")
+
+    try:
+        from app.core.session_factory import session_manager
+        debug_print("Session manager imported successfully")
+        debug_print(f"Session manager type: {type(session_manager).__name__}")
+
+        # Test session creation
+        session_id = str(uuid.uuid4())
+        debug_print(f"Testing session creation with ID: {session_id}")
+
+        # You can add a breakpoint here for interactive debugging
+        # debug_breakpoint("Session manager ready", locals())
+
+        return session_manager, session_id
+
+    except Exception as e:
+        debug_print(f"Session manager error: {e}")
+        import traceback
+        debug_print(f"Traceback: {traceback.format_exc()}")
+        return None, None
+
+
+def debug_agent_creation(session_id):
+    """Debug agent creation process."""
+    debug_print("=== DEBUGGING AGENT CREATION ===")
+
+    try:
+        from app.core.agent import ChatCalAgent
+        debug_print("ChatCalAgent imported successfully")
+
+        debug_print(f"Creating agent for session: {session_id}")
+        agent = ChatCalAgent(session_id)
+        debug_print("Agent created successfully")
+
+        # Check agent properties
+        debug_print(f"Agent system prompt preview: {agent.base_system_prompt[:100]}...")
+        debug_print(f"Agent user info: {agent.user_info}")
+
+        # Breakpoint for agent inspection
+        # debug_breakpoint("Agent created", locals())
+
+        return agent
+
+    except Exception as e:
+        debug_print(f"Agent creation error: {e}")
+        import traceback
+        debug_print(f"Traceback: {traceback.format_exc()}")
+        return None
+
+
+def debug_calendar_auth():
+    """Debug calendar authentication."""
+    debug_print("=== DEBUGGING CALENDAR AUTH ===")
+
+    try:
+        from app.calendar.auth import CalendarAuth
+        debug_print("CalendarAuth imported successfully")
+
+        auth = CalendarAuth()
+        debug_print(f"CalendarAuth created, redirect URI: {auth.redirect_uri}")
+
+        # Test credential loading
+        from app.config import settings
+        debug_print("Environment variables:")
+        debug_print(f"  GOOGLE_CLIENT_ID: {settings.google_client_id[:10]}...")
+        debug_print(f"  APP_ENV: {settings.app_env}")
+
+        # Test calendar service
+        service = auth.get_calendar_service()
+        debug_print("Calendar service created successfully")
+
+        return True
+
+    except Exception as e:
+        debug_print(f"Calendar auth error: {e}")
+        import traceback
+        debug_print(f"Traceback: {traceback.format_exc()}")
+        return False
+
+
+def debug_chat_flow(message="Hello, I need to book an appointment with Peter"):
+    """Debug the complete chat flow."""
+    debug_print("=== DEBUGGING COMPLETE CHAT FLOW ===")
+
+    # Step 1: Session manager
+    session_manager, session_id = debug_session_manager()
+    if not session_manager:
+        return False
+
+    # Step 2: Agent creation
+    agent = debug_agent_creation(session_id)
+    if not agent:
+        return False
+
+    # Step 3: Calendar auth
+    calendar_ok = debug_calendar_auth()
+    if not calendar_ok:
+        debug_print("⚠️ Calendar auth failed, but continuing with chat test")
+
+    # Step 4: Test conversation
+    debug_print("=== TESTING CONVERSATION ===")
+    try:
+        conversation = session_manager.get_or_create_conversation(session_id)
+        debug_print("Conversation manager created")
+
+        debug_print(f"Sending message: {message}")
+
+        # Add breakpoint before getting response for interactive debugging
+        # debug_breakpoint("About to get agent response", locals())
+
+        response = conversation.get_response(message)
+        debug_print(f"Response received: {response[:200]}...")
+
+        return True
+
+    except Exception as e:
+        debug_print(f"Chat flow error: {e}")
+        import traceback
+        debug_print(f"Traceback: {traceback.format_exc()}")
+        return False
+
+
+def main():
+    """Main debugging session."""
+    print("🐛 VoiceCal.ai Interactive Debugging Session")
+    print("=" * 60)
+
+    # Setup enhanced logging
+    setup_enhanced_logging(log_level="DEBUG", log_file="/tmp/debug_chat.log")
+
+    print("\n📋 Available debugging functions:")
+    print("1. debug_session_manager() - Test session management")
+    print("2. debug_agent_creation(session_id) - Test agent creation")
+    print("3. debug_calendar_auth() - Test calendar authentication")
+    print("4. debug_chat_flow() - Test complete chat flow")
+    print("5. debug_breakpoint(msg, locals()) - Interactive breakpoint")
+
+    print("\n🔧 Starting automated debug flow...")
+    success = debug_chat_flow()
+
+    if success:
+        print("\n✅ All debugging tests passed!")
+    else:
+        print("\n❌ Some debugging tests failed - check logs for details")
+
+    print(f"\n📁 Debug logs saved to: /tmp/debug_chat.log")
+    print("💡 For interactive debugging, uncomment debug_breakpoint() calls in this script")
+
+    # Interactive mode
+    print("\n🎮 Entering interactive mode...")
+    print("Available variables: session_manager, agent, conversation")
+    print("Type 'exit()' to quit")
+
+    import code
+    code.interact(local=locals())
+
+
+if __name__ == "__main__":
+    main()