Implement a comprehensive debug system and thinking transparency solution for the NextGenApp. This includes real-time logging, categorized log levels, and enhanced chat interface with tool usage visualization. Introduce a modular architecture for better error handling and response management. Add tests for the new features and update documentation to reflect these changes.

app_ng.py

@@ -32,6 +32,8 @@ from dataclasses import asdict
 # Local imports
 from agent_ng import NextGenAgent, ChatMessage, get_agent_ng
 from llm_manager import get_llm_manager
+from debug_streamer import get_debug_streamer, get_log_handler, LogLevel, LogCategory
+from streaming_chat import get_chat_interface
 
 
 class NextGenApp:
@@ -44,6 +46,11 @@ class NextGenApp:
         self.is_initializing = False
         self.initialization_complete = False
         
+        # Initialize debug system
+        self.debug_streamer = get_debug_streamer("app_ng")
+        self.log_handler = get_log_handler("app_ng")
+        self.chat_interface = get_chat_interface("app_ng")
+        
         # Initialize synchronously first, then start async initialization
         self._start_async_initialization()
     
@@ -66,10 +73,12 @@ class NextGenApp:
     async def _initialize_agent(self):
         """Initialize the agent asynchronously"""
         self.is_initializing = True
+        self.debug_streamer.info("Starting agent initialization", LogCategory.INIT)
         self.initialization_logs.append("🚀 Starting agent initialization...")
         
         try:
             # Initialize agent (uses single provider from AGENT_PROVIDER)
+            self.debug_streamer.info("Creating agent instance", LogCategory.INIT)
             self.agent = await get_agent_ng()
             
             # Wait for agent to be ready
@@ -78,24 +87,34 @@ class NextGenApp:
             while not self.agent.is_ready() and wait_time < max_wait:
                 await asyncio.sleep(0.5)
                 wait_time += 0.5
+                self.debug_streamer.debug(f"Waiting for agent... ({wait_time:.1f}s)", LogCategory.INIT)
                 self.initialization_logs.append(f"⏳ Waiting for agent... ({wait_time:.1f}s)")
             
             if self.agent.is_ready():
                 status = self.agent.get_status()
+                self.debug_streamer.success(f"Agent ready with {status['current_llm']}", LogCategory.INIT)
                 self.initialization_logs.append(f"✅ Agent ready with {status['current_llm']}")
                 self.initialization_logs.append(f"🔧 Tools available: {status['tools_count']}")
                 self.initialization_complete = True
             else:
+                self.debug_streamer.error("Agent initialization timeout", LogCategory.INIT)
                 self.initialization_logs.append("❌ Agent initialization timeout")
                 
         except Exception as e:
+            self.debug_streamer.error(f"Initialization failed: {str(e)}", LogCategory.INIT)
             self.initialization_logs.append(f"❌ Initialization failed: {str(e)}")
         
         self.is_initializing = False
     
     def get_initialization_logs(self) -> str:
         """Get initialization logs as formatted string"""
-        return "\n".join(self.initialization_logs)
+        # Combine static logs with real-time debug logs
+        static_logs = "\n".join(self.initialization_logs)
+        debug_logs = self.log_handler.get_current_logs()
+        
+        if debug_logs and debug_logs != "No logs available yet.":
+            return f"{static_logs}\n\n--- Real-time Debug Logs ---\n\n{debug_logs}"
+        return static_logs
     
     def get_agent_status(self) -> str:
         """Get current agent status"""
@@ -109,55 +128,58 @@ class NextGenApp:
         else:
             return "❌ Agent not ready"
     
-    async def chat_with_agent(self, message: str, history: List[Tuple[str, str]]) -> Tuple[List[Tuple[str, str]], str]:
+    async def chat_with_agent(self, message: str, history: List[Dict[str, str]]) -> Tuple[List[Dict[str, str]], str]:
         """
-        Chat with the agent using modern streaming.
+        Chat with the agent using modern streaming with thinking transparency.
         
         Args:
             message: User message
-            history: Chat history as list of tuples
+            history: Chat history as list of message dicts
             
         Returns:
             Updated history and empty message
         """
         if not self.agent or not self.agent.is_ready():
             error_msg = "Agent not ready. Please wait for initialization to complete."
-            history.append((message, error_msg))
+            history.append({"role": "user", "content": message})
+            history.append({"role": "assistant", "content": error_msg})
             return history, ""
         
-        # Convert history to ChatMessage format
-        chat_history = []
-        for user_msg, assistant_msg in history:
-            chat_history.append(ChatMessage(role="user", content=user_msg))
-            chat_history.append(ChatMessage(role="assistant", content=assistant_msg))
-        
-        # Add current user message
-        chat_history.append(ChatMessage(role="user", content=message))
-        
-        # Stream response
-        response_content = ""
-        thinking_content = ""
-        tool_usage = []
+        self.debug_streamer.info(f"Starting chat with message: {message[:50]}...", LogCategory.STREAM)
         
         try:
-            async for event in self.agent.stream_chat(message, chat_history[:-1]):  # Exclude current message
-                if event["type"] == "content":
-                    response_content += event["content"]
-                elif event["type"] == "thinking":
-                    thinking_content = event["content"]
-                elif event["type"] == "tool_use":
-                    tool_usage.append(event["content"])
-                elif event["type"] == "error":
-                    response_content = f"❌ {event['content']}"
-                    break
-        
+            # Convert tuple history to dict format for internal processing
+            tuple_history = []
+            for msg in history:
+                if isinstance(msg, dict):
+                    if msg.get("role") == "user":
+                        tuple_history.append((msg["content"], ""))
+                    elif msg.get("role") == "assistant":
+                        if tuple_history:
+                            tuple_history[-1] = (tuple_history[-1][0], msg["content"])
+                        else:
+                            tuple_history.append(("", msg["content"]))
+                elif isinstance(msg, tuple):
+                    tuple_history.append(msg)
+            
+            # Use the streaming chat interface
+            updated_tuple_history, _ = await self.chat_interface.chat_with_agent(message, tuple_history, self.agent)
+            
+            # Convert back to dict format for Gradio
+            dict_history = []
+            for user_msg, assistant_msg in updated_tuple_history:
+                if user_msg:
+                    dict_history.append({"role": "user", "content": user_msg})
+                if assistant_msg:
+                    dict_history.append({"role": "assistant", "content": assistant_msg})
+            
+            return dict_history, ""
         except Exception as e:
-            response_content = f"❌ Error: {str(e)}"
-        
-        # Add response to history
-        history.append((message, response_content))
-        
-        return history, ""
+            self.debug_streamer.error(f"Error in chat_with_agent: {str(e)}", LogCategory.STREAM)
+            error_msg = f"❌ Error: {str(e)}"
+            history.append({"role": "user", "content": message})
+            history.append({"role": "assistant", "content": error_msg})
+            return history, ""
     
     def create_interface(self) -> gr.Blocks:
         """Create the Gradio interface"""
@@ -247,13 +269,15 @@ class NextGenApp:
                 with gr.TabItem("💬 Chat", id="chat"):
                     with gr.Row():
                         with gr.Column(scale=3):
-                            # Chat interface
+                            # Chat interface with metadata support for thinking transparency
                             chatbot = gr.Chatbot(
                                 label="Chat with the Agent",
                                 height=500,
                                 show_label=True,
                                 container=True,
-                                show_copy_button=True
+                                show_copy_button=True,
+                                type="messages",  # Enable metadata support
+                                bubble_full_width=False
                             )
                             
                             with gr.Row():
@@ -292,8 +316,12 @@ class NextGenApp:
                     
                     def copy_last_response(history):
                         if history and len(history) > 0:
-                            last_response = history[-1][1]  # Get last assistant message
-                            return last_response
+                            # Find the last assistant message
+                            for msg in reversed(history):
+                                if isinstance(msg, dict) and msg.get("role") == "assistant":
+                                    return msg.get("content", "")
+                                elif isinstance(msg, tuple):
+                                    return msg[1]  # Get last assistant message from tuple
                         return ""
                     
                     def quick_math():
@@ -345,8 +373,8 @@ class NextGenApp:
                     )
                 
                 # Logs Tab
-                with gr.TabItem("📜 Initialization Logs", id="logs"):
-                    gr.Markdown("### Agent Initialization Logs")
+                with gr.TabItem("📜 Logs", id="logs"):
+                    gr.Markdown("### Initialization Logs")
                     logs_display = gr.Markdown(
                         "🟡 Starting initialization...",
                         elem_classes=["status-card"]
@@ -357,10 +385,20 @@ class NextGenApp:
                     def refresh_logs():
                         return self.get_initialization_logs()
                     
+                    def clear_logs():
+                        self.log_handler.clear_logs()
+                        return "Logs cleared."
+                    
                     refresh_logs_btn.click(
                         fn=refresh_logs,
                         outputs=[logs_display]
                     )
+                    
+                    clear_logs_btn = gr.Button("🗑️ Clear Logs", elem_classes=["cmw-button"])
+                    clear_logs_btn.click(
+                        fn=clear_logs,
+                        outputs=[logs_display]
+                    )
                 
                 # Stats Tab
                 with gr.TabItem("📊 Statistics", id="stats"):
@@ -420,6 +458,13 @@ class NextGenApp:
                 outputs=[model_info]
             )
             
+            # Auto-refresh logs every 3 seconds
+            logs_timer = gr.Timer(3.0, active=True)
+            logs_timer.tick(
+                fn=refresh_logs,
+                outputs=[logs_display]
+            )
+            
             # Load initial logs
             demo.load(
                 fn=refresh_logs,

debug_streamer.py

@@ -0,0 +1,403 @@
+"""
+Lean Debug Streamer
+==================
+
+A highly efficient, modular debug streaming system for real-time logging
+and thinking transparency in LLM agents.
+
+Key Features:
+- Real-time log streaming to Gradio interface
+- Thinking transparency with collapsible sections
+- Minimal overhead and clean separation of concerns
+- Thread-safe logging with queue-based streaming
+- Support for different log levels and categories
+- Integration with Gradio ChatMessage metadata
+
+Inspired by the sophisticated logging in agent.py but designed to be
+lean, efficient, and modular.
+"""
+
+import asyncio
+import threading
+import time
+from typing import Dict, Any, Optional, Callable, List, Union
+from dataclasses import dataclass, field
+from enum import Enum
+from queue import Queue, Empty
+import json
+from datetime import datetime
+
+
+class LogLevel(Enum):
+    """Log levels for different types of messages"""
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    THINKING = "thinking"
+    TOOL_USE = "tool_use"
+    LLM_STREAM = "llm_stream"
+    SUCCESS = "success"
+
+
+class LogCategory(Enum):
+    """Categories for organizing logs"""
+    INIT = "initialization"
+    LLM = "llm_call"
+    TOOL = "tool_execution"
+    STREAM = "streaming"
+    ERROR = "error_handling"
+    THINKING = "thinking_process"
+    SYSTEM = "system"
+
+
+@dataclass
+class LogEntry:
+    """A single log entry with metadata"""
+    timestamp: float
+    level: LogLevel
+    category: LogCategory
+    message: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    thread_id: str = ""
+    session_id: str = "default"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            "timestamp": self.timestamp,
+            "level": self.level.value,
+            "category": self.category.value,
+            "message": self.message,
+            "metadata": self.metadata,
+            "thread_id": self.thread_id,
+            "session_id": self.session_id,
+            "formatted_time": datetime.fromtimestamp(self.timestamp).strftime("%H:%M:%S.%f")[:-3]
+        }
+
+
+class DebugStreamer:
+    """
+    Lean, efficient debug streamer for real-time logging.
+    
+    Features:
+    - Thread-safe queue-based logging
+    - Real-time streaming to Gradio interface
+    - Minimal overhead with clean separation
+    - Support for different log levels and categories
+    - Integration with Gradio ChatMessage metadata
+    """
+    
+    def __init__(self, session_id: str = "default", max_queue_size: int = 1000):
+        self.session_id = session_id
+        self.max_queue_size = max_queue_size
+        self.log_queue = Queue(maxsize=max_queue_size)
+        self.subscribers: List[Callable[[LogEntry], None]] = []
+        self.is_running = False
+        self.worker_thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+        
+        # Start the worker thread
+        self.start()
+    
+    def start(self):
+        """Start the debug streamer worker thread"""
+        if self.is_running:
+            return
+        
+        self.is_running = True
+        self.worker_thread = threading.Thread(target=self._worker_loop, daemon=True)
+        self.worker_thread.start()
+    
+    def stop(self):
+        """Stop the debug streamer"""
+        self.is_running = False
+        if self.worker_thread:
+            self.worker_thread.join(timeout=1.0)
+    
+    def subscribe(self, callback: Callable[[LogEntry], None]):
+        """Subscribe to log entries"""
+        with self._lock:
+            self.subscribers.append(callback)
+    
+    def unsubscribe(self, callback: Callable[[LogEntry], None]):
+        """Unsubscribe from log entries"""
+        with self._lock:
+            if callback in self.subscribers:
+                self.subscribers.remove(callback)
+    
+    def _worker_loop(self):
+        """Worker loop that processes log entries"""
+        while self.is_running:
+            try:
+                # Get log entry with timeout
+                entry = self.log_queue.get(timeout=0.1)
+                
+                # Notify all subscribers
+                with self._lock:
+                    for callback in self.subscribers:
+                        try:
+                            callback(entry)
+                        except Exception as e:
+                            print(f"Error in log subscriber: {e}")
+                
+                self.log_queue.task_done()
+                
+            except Empty:
+                continue
+            except Exception as e:
+                print(f"Error in debug streamer worker: {e}")
+    
+    def log(self, level: LogLevel, category: LogCategory, message: str, 
+            metadata: Optional[Dict[str, Any]] = None, session_id: Optional[str] = None):
+        """Log a message with the specified level and category"""
+        if metadata is None:
+            metadata = {}
+        
+        entry = LogEntry(
+            timestamp=time.time(),
+            level=level,
+            category=category,
+            message=message,
+            metadata=metadata,
+            thread_id=threading.get_ident(),
+            session_id=session_id or self.session_id
+        )
+        
+        try:
+            self.log_queue.put_nowait(entry)
+        except:
+            # Queue is full, drop the oldest entry
+            try:
+                self.log_queue.get_nowait()
+                self.log_queue.put_nowait(entry)
+            except Empty:
+                pass
+    
+    # Convenience methods for different log levels
+    def debug(self, message: str, category: LogCategory = LogCategory.SYSTEM, 
+              metadata: Optional[Dict[str, Any]] = None):
+        """Log a debug message"""
+        self.log(LogLevel.DEBUG, category, message, metadata)
+    
+    def info(self, message: str, category: LogCategory = LogCategory.SYSTEM, 
+             metadata: Optional[Dict[str, Any]] = None):
+        """Log an info message"""
+        self.log(LogLevel.INFO, category, message, metadata)
+    
+    def warning(self, message: str, category: LogCategory = LogCategory.SYSTEM, 
+                metadata: Optional[Dict[str, Any]] = None):
+        """Log a warning message"""
+        self.log(LogLevel.WARNING, category, message, metadata)
+    
+    def error(self, message: str, category: LogCategory = LogCategory.ERROR, 
+              metadata: Optional[Dict[str, Any]] = None):
+        """Log an error message"""
+        self.log(LogLevel.ERROR, category, message, metadata)
+    
+    def thinking(self, message: str, metadata: Optional[Dict[str, Any]] = None):
+        """Log a thinking process message"""
+        self.log(LogLevel.THINKING, LogCategory.THINKING, message, metadata)
+    
+    def tool_use(self, tool_name: str, tool_args: Dict[str, Any], 
+                 result: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None):
+        """Log a tool usage"""
+        tool_metadata = {
+            "tool_name": tool_name,
+            "tool_args": tool_args,
+            "result": result,
+            **(metadata or {})
+        }
+        self.log(LogLevel.TOOL_USE, LogCategory.TOOL, f"Using tool: {tool_name}", tool_metadata)
+    
+    def llm_stream(self, content: str, metadata: Optional[Dict[str, Any]] = None):
+        """Log LLM streaming content"""
+        self.log(LogLevel.LLM_STREAM, LogCategory.LLM, content, metadata)
+    
+    def success(self, message: str, category: LogCategory = LogCategory.SYSTEM, 
+                metadata: Optional[Dict[str, Any]] = None):
+        """Log a success message"""
+        self.log(LogLevel.SUCCESS, category, message, metadata)
+    
+    def get_recent_logs(self, count: int = 50) -> List[LogEntry]:
+        """Get recent log entries (for debugging)"""
+        # This is a simple implementation - in production you might want to use a proper log store
+        return []
+
+
+class GradioLogHandler:
+    """
+    Handler for streaming logs to Gradio interface.
+    
+    This class handles the conversion of log entries to Gradio-compatible
+    formats and manages the streaming to the Logs tab.
+    """
+    
+    def __init__(self, debug_streamer: DebugStreamer):
+        self.debug_streamer = debug_streamer
+        self.log_buffer: List[str] = []
+        self.max_buffer_size = 1000
+        self.current_logs_display = ""
+        
+        # Subscribe to log entries
+        self.debug_streamer.subscribe(self._handle_log_entry)
+    
+    def _handle_log_entry(self, entry: LogEntry):
+        """Handle a new log entry"""
+        # Format the log entry for display
+        formatted_log = self._format_log_entry(entry)
+        
+        # Add to buffer
+        self.log_buffer.append(formatted_log)
+        
+        # Trim buffer if too large
+        if len(self.log_buffer) > self.max_buffer_size:
+            self.log_buffer = self.log_buffer[-self.max_buffer_size:]
+        
+        # Update current display
+        self.current_logs_display = "\n".join(self.log_buffer[-50:])  # Show last 50 entries
+    
+    def _format_log_entry(self, entry: LogEntry) -> str:
+        """Format a log entry for display"""
+        timestamp = datetime.fromtimestamp(entry.timestamp).strftime("%H:%M:%S.%f")[:-3]
+        
+        # Choose emoji based on level
+        emoji_map = {
+            LogLevel.DEBUG: "🔍",
+            LogLevel.INFO: "ℹ️",
+            LogLevel.WARNING: "⚠️",
+            LogLevel.ERROR: "❌",
+            LogLevel.THINKING: "💭",
+            LogLevel.TOOL_USE: "🔧",
+            LogLevel.LLM_STREAM: "📡",
+            LogLevel.SUCCESS: "✅"
+        }
+        
+        emoji = emoji_map.get(entry.level, "📝")
+        
+        # Format the message with better spacing
+        formatted = f"{emoji} [{timestamp}] {entry.message}"
+        
+        # Add metadata if present
+        if entry.metadata:
+            metadata_str = json.dumps(entry.metadata, indent=2)
+            formatted += f"\n   📋 {metadata_str}"
+        
+        # Add new line for better readability
+        formatted += "\n"
+        
+        return formatted
+    
+    def get_current_logs(self) -> str:
+        """Get the current logs display"""
+        return self.current_logs_display or "No logs available yet."
+    
+    def clear_logs(self):
+        """Clear the log buffer"""
+        self.log_buffer.clear()
+        self.current_logs_display = ""
+
+
+class ThinkingTransparency:
+    """
+    Handler for thinking transparency in Gradio ChatMessage.
+    
+    This class manages the creation of thinking sections that can be
+    displayed in collapsible accordions in the Gradio chat interface.
+    """
+    
+    def __init__(self, debug_streamer: DebugStreamer):
+        self.debug_streamer = debug_streamer
+        self.current_thinking = ""
+        self.thinking_metadata = {}
+    
+    def start_thinking(self, title: str = "🧠 Thinking", metadata: Optional[Dict[str, Any]] = None):
+        """Start a thinking process"""
+        self.current_thinking = ""
+        self.thinking_metadata = {
+            "title": title,
+            "status": "pending",
+            **(metadata or {})
+        }
+        self.debug_streamer.thinking(f"Starting thinking process: {title}")
+    
+    def add_thinking(self, content: str):
+        """Add content to the current thinking process"""
+        self.current_thinking += content
+        self.debug_streamer.thinking(content)
+    
+    def complete_thinking(self, final_content: Optional[str] = None):
+        """Complete the thinking process"""
+        if final_content:
+            self.current_thinking = final_content
+        
+        self.thinking_metadata["status"] = "done"
+        self.debug_streamer.thinking("Thinking process completed")
+        
+        return self._create_thinking_message()
+    
+    def _create_thinking_message(self) -> Dict[str, Any]:
+        """Create a ChatMessage-compatible thinking message"""
+        return {
+            "role": "assistant",
+            "content": self.current_thinking,
+            "metadata": self.thinking_metadata
+        }
+    
+    def create_tool_usage_message(self, tool_name: str, tool_args: Dict[str, Any], 
+                                 result: str) -> Dict[str, Any]:
+        """Create a tool usage message with metadata"""
+        return {
+            "role": "assistant",
+            "content": f"Used tool: {tool_name}\n\n**Arguments:**\n{json.dumps(tool_args, indent=2)}\n\n**Result:**\n{result}",
+            "metadata": {
+                "title": f"🔧 {tool_name}",
+                "status": "done",
+                "tool_name": tool_name,
+                "tool_args": tool_args
+            }
+        }
+
+
+# Global debug streamer instance
+_global_debug_streamer: Optional[DebugStreamer] = None
+_global_log_handler: Optional[GradioLogHandler] = None
+_global_thinking_transparency: Optional[ThinkingTransparency] = None
+
+
+def get_debug_streamer(session_id: str = "default") -> DebugStreamer:
+    """Get the global debug streamer instance"""
+    global _global_debug_streamer
+    if _global_debug_streamer is None:
+        _global_debug_streamer = DebugStreamer(session_id)
+    return _global_debug_streamer
+
+
+def get_log_handler(session_id: str = "default") -> GradioLogHandler:
+    """Get the global log handler instance"""
+    global _global_log_handler
+    if _global_log_handler is None:
+        debug_streamer = get_debug_streamer(session_id)
+        _global_log_handler = GradioLogHandler(debug_streamer)
+    return _global_log_handler
+
+
+def get_thinking_transparency(session_id: str = "default") -> ThinkingTransparency:
+    """Get the global thinking transparency instance"""
+    global _global_thinking_transparency
+    if _global_thinking_transparency is None:
+        debug_streamer = get_debug_streamer(session_id)
+        _global_thinking_transparency = ThinkingTransparency(debug_streamer)
+    return _global_thinking_transparency
+
+
+def cleanup_debug_system():
+    """Cleanup the debug system"""
+    global _global_debug_streamer, _global_log_handler, _global_thinking_transparency
+    
+    if _global_debug_streamer:
+        _global_debug_streamer.stop()
+        _global_debug_streamer = None
+    
+    _global_log_handler = None
+    _global_thinking_transparency = None

docs/DEBUG_SYSTEM_README.md

@@ -0,0 +1,166 @@
+********# Debug System & Thinking Transparency
+
+## Overview
+
+I've implemented a comprehensive debug system and thinking transparency solution for your LLM agent. This addresses the empty response issue with OpenRouter and provides real-time visibility into the agent's thinking process.
+
+## 🚀 Key Features
+
+### 1. **Lean Debug Module** (`debug_streamer.py`)
+- **Real-time logging** with thread-safe queue-based system
+- **Minimal overhead** with clean separation of concerns
+- **Multiple log levels**: DEBUG, INFO, WARNING, ERROR, THINKING, TOOL_USE, LLM_STREAM, SUCCESS
+- **Categorized logging**: INIT, LLM, TOOL, STREAM, ERROR, THINKING, SYSTEM
+- **Auto-streaming to Gradio** Logs tab
+
+### 2. **Error Handling** (Integrated)
+- **Centralized error classification** via `error_handler.py`
+- **Provider-specific error handling** for all LLM providers
+- **Automatic retry logic** with exponential backoff
+- **Comprehensive error reporting** with suggested actions
+
+### 3. **Thinking Transparency** (`streaming_chat.py`)
+- **Real-time thinking process** visualization
+- **Collapsible thinking sections** using Gradio ChatMessage metadata
+- **Tool usage visualization** with detailed metadata
+- **Streaming response handling** with event-based architecture
+- **Clean separation** between thinking, tool usage, and content
+
+### 4. **Enhanced App** (`app_ng.py`)
+- **Integrated debug system** with real-time log streaming
+- **Thinking transparency** in chat interface
+- **Auto-refreshing logs** every 3 seconds
+- **Modern Gradio ChatMessage** format with metadata support
+- **Comprehensive error handling** and fallback mechanisms
+
+## 🔧 How It Works
+
+### Debug Streaming
+```python
+# Initialize debug system
+debug_streamer = get_debug_streamer("session_id")
+log_handler = get_log_handler("session_id")
+
+# Log messages with categories
+debug_streamer.info("Agent initialized", LogCategory.INIT)
+debug_streamer.thinking("Processing user question...")
+debug_streamer.tool_use("calculator", {"operation": "add", "a": 5, "b": 3}, "8")
+```
+
+### Thinking Transparency
+```python
+# Start thinking process
+thinking_transparency.start_thinking("🧠 Analyzing question...")
+thinking_transparency.add_thinking("Let me break this down...")
+thinking_message = thinking_transparency.complete_thinking()
+
+# Create tool usage message
+tool_message = thinking_transparency.create_tool_usage_message(
+    tool_name="calculator",
+    tool_args={"operation": "multiply", "a": 4, "b": 7},
+    result="28"
+)
+```
+
+### Error Handling
+```python
+# Centralized error classification and handling
+error_handler = get_error_handler()
+error_info = error_handler.classify_error(error, "openrouter")
+if error_info.is_temporary:
+    # Handle retry logic
+    pass
+```
+
+## 🎯 Problem Solutions
+
+### 1. **Error Handling Issue**
+- **Root Cause**: LLM providers return various error types (rate limits, auth issues, service unavailable)
+- **Solution**: Centralized error classification and proper error reporting
+- **Features**: Provider-specific handling, automatic retry, clear error messages
+
+### 2. **Thinking Transparency**
+- **Problem**: No visibility into agent's reasoning process
+- **Solution**: Real-time thinking sections with collapsible metadata
+- **Implementation**: Gradio ChatMessage metadata system
+
+### 3. **Debug Visibility**
+- **Problem**: Hard to debug agent issues
+- **Solution**: Real-time streaming logs with categorization
+- **Features**: Auto-refresh, clear logs, detailed metadata
+
+## 🚀 Usage
+
+### Running the Enhanced App
+```bash
+python app_ng.py
+```
+
+### Testing the Debug System
+```bash
+python test_debug_system.py
+```
+
+### Key Features in the UI
+
+1. **Chat Tab**:
+   - Real-time thinking transparency
+   - Tool usage visualization
+   - Streaming responses
+   - Error handling with helpful messages
+
+2. **Logs Tab**:
+   - Real-time debug logs
+   - Auto-refresh every 3 seconds
+   - Clear logs functionality
+   - Categorized logging
+
+3. **Stats Tab**:
+   - Agent statistics
+   - LLM information
+   - Tool usage counts
+
+## 🔍 Debugging OpenRouter Issues
+
+The system now handles OpenRouter-specific issues:
+
+1. **Rate Limiting (429 errors)**: Automatic detection and user-friendly messages
+2. **Authentication Errors (401)**: Clear error messages with setup instructions
+3. **Empty Responses**: Multiple retry strategies with fallback responses
+4. **Service Issues**: Graceful degradation with helpful suggestions
+
+## 📊 Log Categories
+
+- **INIT**: Initialization and setup
+- **LLM**: LLM calls and responses
+- **TOOL**: Tool execution and results
+- **STREAM**: Streaming events
+- **ERROR**: Error handling
+- **THINKING**: Thinking process
+- **SYSTEM**: System-level events
+
+## 🎨 Thinking Transparency Features
+
+- **Collapsible thinking sections** with titles
+- **Real-time thinking updates** as the agent processes
+- **Tool usage metadata** with arguments and results
+- **Error visualization** with helpful context
+- **Status indicators** (pending, done, error)
+
+## 🔧 Configuration
+
+The system is highly configurable:
+
+- **Log levels**: Adjust verbosity
+- **Retry attempts**: Configure retry strategies
+- **Auto-refresh intervals**: Customize UI updates
+- **Session management**: Isolated debug contexts
+
+## 🚀 Next Steps
+
+1. **Test the system** with your OpenRouter setup
+2. **Monitor the logs** for any issues
+3. **Customize log levels** as needed
+4. **Extend thinking transparency** for specific use cases
+
+The system is designed to be lean, efficient, and transparent while providing comprehensive debugging capabilities for your LLM agent.

streaming_chat.py

@@ -0,0 +1,335 @@
+"""
+Modern Streaming Chat Interface
+==============================
+
+A sophisticated streaming chat interface that provides real-time thinking
+transparency and tool usage visualization using Gradio's ChatMessage metadata.
+
+Key Features:
+- Real-time thinking transparency with collapsible sections
+- Tool usage visualization with metadata
+- Streaming response handling
+- Integration with debug system
+- Clean separation of concerns
+- Support for multiple LLM providers
+
+Based on Gradio's ChatMessage metadata system for thinking transparency.
+"""
+
+import asyncio
+import time
+from typing import List, Dict, Any, Optional, Tuple, AsyncGenerator
+from dataclasses import dataclass
+import json
+
+from debug_streamer import get_debug_streamer, get_log_handler, get_thinking_transparency, LogLevel, LogCategory
+
+
+@dataclass
+class ChatMessage:
+    """Enhanced ChatMessage with metadata support for thinking transparency"""
+    role: str  # "user" or "assistant"
+    content: str
+    metadata: Optional[Dict[str, Any]] = None
+    
+    def to_gradio_format(self) -> Dict[str, Any]:
+        """Convert to Gradio ChatMessage format"""
+        return {
+            "role": self.role,
+            "content": self.content,
+            "metadata": self.metadata or {}
+        }
+
+
+class StreamingChatInterface:
+    """
+    Modern streaming chat interface with thinking transparency.
+    
+    This class handles real-time streaming of chat responses with
+    thinking transparency, tool usage visualization, and debug logging.
+    """
+    
+    def __init__(self, session_id: str = "default"):
+        self.session_id = session_id
+        self.debug_streamer = get_debug_streamer(session_id)
+        self.log_handler = get_log_handler(session_id)
+        self.thinking_transparency = get_thinking_transparency(session_id)
+        
+        # Chat state
+        self.current_thinking = ""
+        self.current_tool_usage = []
+        self.is_thinking = False
+        
+    async def stream_chat_response(self, message: str, history: List[Tuple[str, str]], 
+                                 agent: Any) -> AsyncGenerator[Tuple[List[Tuple[str, str]], str], None]:
+        """
+        Stream a chat response with thinking transparency.
+        
+        Args:
+            message: User message
+            history: Chat history as list of tuples
+            agent: The agent instance to use
+            
+        Yields:
+            Updated history and empty message for Gradio
+        """
+        if not message.strip():
+            yield history, ""
+            return
+        
+        self.debug_streamer.info(f"Starting chat response for: {message[:50]}...", LogCategory.STREAM)
+        
+        # Add user message to history
+        working_history = history + [(message, "")]
+        yield working_history, ""
+        
+        try:
+            # Start thinking process
+            await self._start_thinking_process(message)
+            
+            # Stream the response
+            async for event in self._stream_agent_response(message, history, agent):
+                if event["type"] == "thinking":
+                    await self._handle_thinking_event(event, working_history)
+                elif event["type"] == "tool_use":
+                    await self._handle_tool_use_event(event, working_history)
+                elif event["type"] == "content":
+                    await self._handle_content_event(event, working_history)
+                elif event["type"] == "error":
+                    await self._handle_error_event(event, working_history)
+                
+                yield working_history, ""
+            
+            # Complete the response
+            await self._complete_response(working_history)
+            yield working_history, ""
+            
+        except Exception as e:
+            self.debug_streamer.error(f"Error in streaming chat: {str(e)}", LogCategory.STREAM)
+            await self._handle_streaming_error(e, working_history)
+            yield working_history, ""
+    
+    async def _start_thinking_process(self, message: str):
+        """Start the thinking process"""
+        self.is_thinking = True
+        self.current_thinking = ""
+        self.current_tool_usage = []
+        
+        self.thinking_transparency.start_thinking(
+            title="🧠 Thinking",
+            metadata={"message": message[:100] + "..." if len(message) > 100 else message}
+        )
+        
+        self.debug_streamer.thinking(f"Starting to process: {message}")
+    
+    async def _stream_agent_response(self, message: str, history: List[Tuple[str, str]], 
+                                   agent: Any) -> AsyncGenerator[Dict[str, Any], None]:
+        """Stream response from the agent"""
+        try:
+            # Convert history to internal format
+            internal_history = []
+            for user_msg, assistant_msg in history:
+                internal_history.append(ChatMessage(role="user", content=user_msg))
+                if assistant_msg:
+                    internal_history.append(ChatMessage(role="assistant", content=assistant_msg))
+            
+            # Stream from agent
+            if hasattr(agent, 'stream_chat'):
+                async for event in agent.stream_chat(message, internal_history):
+                    yield event
+            elif hasattr(agent, 'stream'):
+                # Fallback to basic streaming
+                for chunk in agent.stream(message, internal_history):
+                    yield {"type": "content", "content": chunk}
+            else:
+                # Fallback to non-streaming
+                response = agent(message, chat_history=internal_history)
+                if hasattr(response, 'answer'):
+                    yield {"type": "content", "content": response.answer}
+                else:
+                    yield {"type": "content", "content": str(response)}
+                    
+        except Exception as e:
+            self.debug_streamer.error(f"Error streaming from agent: {str(e)}", LogCategory.STREAM)
+            yield {"type": "error", "content": f"Error: {str(e)}"}
+    
+    async def _handle_thinking_event(self, event: Dict[str, Any], working_history: List[Tuple[str, str]]):
+        """Handle thinking events"""
+        thinking_content = event.get("content", "")
+        self.current_thinking += thinking_content
+        
+        # Update thinking in the last assistant message
+        if working_history and len(working_history) > 0:
+            last_user, last_assistant = working_history[-1]
+            if last_assistant == "":
+                # Create thinking message with metadata
+                thinking_message = self.thinking_transparency._create_thinking_message()
+                working_history[-1] = (last_user, thinking_message["content"])
+            else:
+                # Update existing thinking
+                working_history[-1] = (last_user, self.current_thinking)
+    
+    async def _handle_tool_use_event(self, event: Dict[str, Any], working_history: List[Tuple[str, str]]):
+        """Handle tool usage events"""
+        tool_name = event.get("content", "unknown")
+        tool_metadata = event.get("metadata", {})
+        
+        self.current_tool_usage.append({
+            "tool_name": tool_name,
+            "metadata": tool_metadata
+        })
+        
+        # Create tool usage message
+        tool_message = self.thinking_transparency.create_tool_usage_message(
+            tool_name=tool_name,
+            tool_args=tool_metadata.get("tool_args", {}),
+            result=tool_metadata.get("result", "Tool executed")
+        )
+        
+        # Add tool usage to history
+        if working_history and len(working_history) > 0:
+            last_user, last_assistant = working_history[-1]
+            working_history[-1] = (last_user, tool_message["content"])
+    
+    async def _handle_content_event(self, event: Dict[str, Any], working_history: List[Tuple[str, str]]):
+        """Handle content events"""
+        content = event.get("content", "")
+        
+        if working_history and len(working_history) > 0:
+            last_user, last_assistant = working_history[-1]
+            
+            # If we have thinking content, complete it first
+            if self.is_thinking and self.current_thinking:
+                self.thinking_transparency.complete_thinking()
+                self.is_thinking = False
+            
+            # Update the response content
+            if last_assistant == "":
+                working_history[-1] = (last_user, content)
+            else:
+                # Append to existing content
+                working_history[-1] = (last_user, last_assistant + content)
+    
+    async def _handle_error_event(self, event: Dict[str, Any], working_history: List[Tuple[str, str]]):
+        """Handle error events"""
+        error_content = event.get("content", "Unknown error")
+        
+        # Log the error for debugging
+        self.debug_streamer.error(f"Streaming error: {error_content}", LogCategory.LLM)
+        
+        if working_history and len(working_history) > 0:
+            last_user, last_assistant = working_history[-1]
+            working_history[-1] = (last_user, f"❌ {error_content}")
+    
+    async def _complete_response(self, working_history: List[Tuple[str, str]]):
+        """Complete the response process"""
+        if self.is_thinking:
+            self.thinking_transparency.complete_thinking()
+            self.is_thinking = False
+        
+        self.debug_streamer.success("Chat response completed", LogCategory.STREAM)
+    
+    async def _handle_streaming_error(self, error: Exception, working_history: List[Tuple[str, str]]):
+        """Handle streaming errors"""
+        error_msg = f"❌ **Streaming Error**\n\n{str(error)}\n\nPlease try again."
+        
+        if working_history and len(working_history) > 0:
+            last_user, last_assistant = working_history[-1]
+            working_history[-1] = (last_user, error_msg)
+    
+    def create_thinking_message(self, content: str, title: str = "🧠 Thinking") -> ChatMessage:
+        """Create a thinking message with metadata"""
+        return ChatMessage(
+            role="assistant",
+            content=content,
+            metadata={
+                "title": title,
+                "status": "pending" if self.is_thinking else "done"
+            }
+        )
+    
+    def create_tool_usage_message(self, tool_name: str, tool_args: Dict[str, Any], 
+                                 result: str) -> ChatMessage:
+        """Create a tool usage message with metadata"""
+        return ChatMessage(
+            role="assistant",
+            content=f"🔧 **{tool_name}**\n\n**Arguments:**\n{json.dumps(tool_args, indent=2)}\n\n**Result:**\n{result}",
+            metadata={
+                "title": f"🔧 {tool_name}",
+                "status": "done",
+                "tool_name": tool_name,
+                "tool_args": tool_args
+            }
+        )
+    
+    def create_error_message(self, error: str, error_type: str = "error") -> ChatMessage:
+        """Create an error message with metadata"""
+        return ChatMessage(
+            role="assistant",
+            content=f"❌ **{error_type.title()}**\n\n{error}",
+            metadata={
+                "title": f"❌ {error_type.title()}",
+                "status": "done",
+                "error": True
+            }
+        )
+
+
+class GradioChatInterface:
+    """
+    Gradio-specific chat interface that handles the conversion between
+    internal chat format and Gradio's expected format.
+    """
+    
+    def __init__(self, session_id: str = "default"):
+        self.streaming_chat = StreamingChatInterface(session_id)
+        self.debug_streamer = get_debug_streamer(session_id)
+        self.log_handler = get_log_handler(session_id)
+    
+    async def chat_with_agent(self, message: str, history: List[Tuple[str, str]], 
+                            agent: Any) -> Tuple[List[Tuple[str, str]], str]:
+        """
+        Chat with the agent using Gradio format.
+        
+        Args:
+            message: User message
+            history: Chat history as list of tuples
+            agent: The agent instance
+            
+        Returns:
+            Updated history and empty message
+        """
+        try:
+            # Stream the response
+            async for updated_history, _ in self.streaming_chat.stream_chat_response(
+                message, history, agent
+            ):
+                # Yield intermediate results for real-time updates
+                pass
+            
+            return updated_history, ""
+            
+        except Exception as e:
+            self.debug_streamer.error(f"Error in Gradio chat interface: {str(e)}", LogCategory.STREAM)
+            error_history = history + [(message, f"❌ Error: {str(e)}")]
+            return error_history, ""
+    
+    def get_current_logs(self) -> str:
+        """Get current logs for the Logs tab"""
+        return self.log_handler.get_current_logs()
+    
+    def clear_logs(self):
+        """Clear the logs"""
+        self.log_handler.clear_logs()
+
+
+# Global chat interface instances
+_global_chat_interface: Optional[GradioChatInterface] = None
+
+
+def get_chat_interface(session_id: str = "default") -> GradioChatInterface:
+    """Get the global chat interface instance"""
+    global _global_chat_interface
+    if _global_chat_interface is None:
+        _global_chat_interface = GradioChatInterface(session_id)
+    return _global_chat_interface

test_debug_system.py

@@ -0,0 +1,106 @@
+"""
+Test script for the new debug system and thinking transparency.
+
+This script tests the debug streaming, thinking transparency, and response fixing
+functionality to ensure everything works correctly.
+"""
+
+import asyncio
+import time
+from debug_streamer import get_debug_streamer, get_log_handler, get_thinking_transparency, LogLevel, LogCategory
+from streaming_chat import get_chat_interface
+
+
+async def test_debug_system():
+    """Test the debug system components"""
+    print("🧪 Testing Debug System Components...")
+    
+    # Test debug streamer
+    debug_streamer = get_debug_streamer("test")
+    print("✅ Debug streamer initialized")
+    
+    # Test log handler
+    log_handler = get_log_handler("test")
+    print("✅ Log handler initialized")
+    
+    # Test thinking transparency
+    thinking_transparency = get_thinking_transparency("test")
+    print("✅ Thinking transparency initialized")
+    
+    
+    # Test chat interface
+    chat_interface = get_chat_interface("test")
+    print("✅ Chat interface initialized")
+    
+    # Test logging
+    debug_streamer.info("Test info message", LogCategory.SYSTEM)
+    debug_streamer.warning("Test warning message", LogCategory.SYSTEM)
+    debug_streamer.error("Test error message", LogCategory.SYSTEM)
+    debug_streamer.success("Test success message", LogCategory.SYSTEM)
+    
+    # Test thinking process
+    thinking_transparency.start_thinking("🧠 Test Thinking")
+    thinking_transparency.add_thinking("This is a test thinking process...")
+    thinking_transparency.add_thinking(" Adding more thoughts...")
+    thinking_message = thinking_transparency.complete_thinking()
+    print(f"✅ Thinking message created: {thinking_message}")
+    
+    # Test tool usage
+    tool_message = thinking_transparency.create_tool_usage_message(
+        tool_name="test_tool",
+        tool_args={"param1": "value1", "param2": "value2"},
+        result="Tool executed successfully"
+    )
+    print(f"✅ Tool message created: {tool_message}")
+    
+    # Test log retrieval
+    logs = log_handler.get_current_logs()
+    print(f"✅ Current logs: {len(logs)} characters")
+    
+    print("🎉 All tests passed!")
+
+
+
+
+async def test_streaming_chat():
+    """Test the streaming chat interface"""
+    print("\n💬 Testing Streaming Chat Interface...")
+    
+    chat_interface = get_chat_interface("test")
+    
+    # Test message creation
+    thinking_msg = chat_interface.streaming_chat.create_thinking_message(
+        "This is a test thinking process",
+        "🧠 Test Thinking"
+    )
+    print(f"✅ Thinking message: {thinking_msg.role} - {thinking_msg.content[:50]}...")
+    
+    tool_msg = chat_interface.streaming_chat.create_tool_usage_message(
+        tool_name="test_tool",
+        tool_args={"test": "value"},
+        result="Success"
+    )
+    print(f"✅ Tool message: {tool_msg.role} - {tool_msg.content[:50]}...")
+    
+    error_msg = chat_interface.streaming_chat.create_error_message(
+        "Test error occurred",
+        "Test Error"
+    )
+    print(f"✅ Error message: {error_msg.role} - {error_msg.content[:50]}...")
+    
+    print("🎉 Streaming chat tests passed!")
+
+
+async def main():
+    """Run all tests"""
+    print("🚀 Starting Debug System Tests...\n")
+    
+    await test_debug_system()
+    await test_streaming_chat()
+    
+    print("\n🎉 All tests completed successfully!")
+    print("\nThe debug system is ready for use with the Next-Gen App!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())