File size: 7,226 Bytes
22087d0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
"""
LLM Debug Logger - Logs INPUT/OUTPUT/DB_WRITE with date-first sorted filenames.

Usage:
    from core.utils.llm_debugger import llm_debug
    
    # Log LLM input
    correlation_id = llm_debug.log_input(model="gpt-4", messages=[...])
    
    # Log LLM output
    llm_debug.log_output(model="gpt-4", content="...", correlation_id=correlation_id)
    
    # Log DB write
    llm_debug.log_db_write(operation="INSERT", table="messages", record_id="...")

Files are saved to debug_streams/ with date-first filenames for proper sorting:
    - 20260122_103045_123456_INPUT.json
    - 20260122_103045_234567_OUTPUT.json
    - 20260122_103045_345678_DB_WRITE.json

Enable with DEBUG_SAVE_LLM_IO=true in config.
"""

import json
import uuid
from pathlib import Path
from datetime import datetime, timezone
from typing import Dict, Any, List, Optional

from core.utils.logger import logger


class LLMDebugLogger:
    """
    Centralized debug logger for LLM operations.
    
    Logs are saved to debug_streams/ with date-first filenames for proper sorting.
    Each log includes a correlation_id to track related operations.
    """
    
    _instance = None
    _debug_dir: Path = None
    
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._debug_dir = Path("debug_streams")
        return cls._instance
    
    def _is_enabled(self) -> bool:
        """Check if debug logging is enabled (lazy check for config availability)."""
        try:
            from core.utils.config import config
            return config and getattr(config, 'DEBUG_SAVE_LLM_IO', False)
        except ImportError:
            return False
    
    def _get_filename(self, event_type: str) -> str:
        """Generate date-first filename: YYYYMMDD_HHMMSS_microseconds_TYPE.json"""
        now = datetime.now(timezone.utc)
        timestamp = now.strftime("%Y%m%d_%H%M%S")
        micros = now.strftime("%f")[:6]
        return f"{timestamp}_{micros}_{event_type}.json"
    
    def _ensure_dir(self) -> bool:
        """Ensure debug directory exists."""
        try:
            self._debug_dir.mkdir(exist_ok=True)
            return True
        except Exception as e:
            logger.warning(f"[LLM_DEBUG] Failed to create debug dir: {e}")
            return False
    
    def _write_log(self, event_type: str, data: Dict[str, Any]) -> Optional[str]:
        """Write a debug log file. Returns filepath on success."""
        if not self._is_enabled():
            return None
        
        if not self._ensure_dir():
            return None
        
        try:
            filename = self._get_filename(event_type)
            filepath = self._debug_dir / filename
            
            # Add metadata
            data["_event_type"] = event_type
            data["_timestamp"] = datetime.now(timezone.utc).isoformat()
            
            with open(filepath, 'w', encoding='utf-8') as f:
                json.dump(data, f, indent=2, ensure_ascii=False, default=str)
            
            logger.debug(f"[LLM_DEBUG] Saved {event_type} to: {filename}")
            return str(filepath)
        except Exception as e:
            logger.warning(f"[LLM_DEBUG] Error saving {event_type}: {e}")
            return None
    
    def log_input(
        self,
        model: str,
        messages: List[Dict[str, Any]],
        correlation_id: Optional[str] = None,
        **kwargs
    ) -> Optional[str]:
        """
        Log LLM API call INPUT.
        
        Returns correlation_id for tracking related OUTPUT log.
        """
        corr_id = correlation_id or str(uuid.uuid4())[:8]
        
        if not self._is_enabled():
            return corr_id
        
        data = {
            "correlation_id": corr_id,
            "model": model,
            "messages": messages,
            "message_count": len(messages),
            "parameters": {
                k: v for k, v in kwargs.items() 
                if k in ["temperature", "max_tokens", "stop", "stream", "tools", 
                        "tool_choice", "frequency_penalty", "top_p", "response_format"]
            }
        }
        
        # Add tool names if present
        if kwargs.get("tools"):
            data["tool_names"] = [t.get("function", {}).get("name", "unknown") 
                                  for t in kwargs.get("tools", [])]
        
        self._write_log("INPUT", data)
        return corr_id
    
    def log_output(
        self,
        model: str,
        content: str,
        tool_calls: Optional[List[Dict[str, Any]]] = None,
        finish_reason: Optional[str] = None,
        chunk_count: int = 0,
        duration_seconds: float = 0,
        correlation_id: Optional[str] = None,
        **kwargs
    ) -> None:
        """Log LLM API call OUTPUT (streaming response accumulated)."""
        if not self._is_enabled():
            return
        
        data = {
            "correlation_id": correlation_id or "unknown",
            "model": model,
            "duration_seconds": round(duration_seconds, 2),
            "chunk_count": chunk_count,
            "finish_reason": finish_reason,
            "content": content,
            "content_length": len(content) if content else 0,
        }
        
        if tool_calls:
            data["tool_calls"] = tool_calls
            data["tool_call_count"] = len(tool_calls)
        
        # Add any extra kwargs
        data.update(kwargs)
        
        self._write_log("OUTPUT", data)
    
    def log_db_write(
        self,
        operation: str,
        table: str,
        record_id: Optional[str] = None,
        thread_id: Optional[str] = None,
        message_type: Optional[str] = None,
        content_preview: Optional[str] = None,
        correlation_id: Optional[str] = None,
        **kwargs
    ) -> None:
        """
        Log database write operation.
        
        Args:
            operation: Type of operation (INSERT, UPDATE, DELETE)
            table: Table name (messages, threads, etc.)
            record_id: Primary key of the record
            thread_id: Associated thread ID
            message_type: For messages table - type of message
            content_preview: Truncated preview of content (first 500 chars)
            correlation_id: For linking to LLM INPUT/OUTPUT
        """
        if not self._is_enabled():
            return
        
        data = {
            "correlation_id": correlation_id or "unknown",
            "operation": operation,
            "table": table,
        }
        
        if record_id:
            data["record_id"] = record_id
        if thread_id:
            data["thread_id"] = thread_id
        if message_type:
            data["message_type"] = message_type
        if content_preview:
            # Truncate content preview
            preview = str(content_preview)[:500]
            if len(str(content_preview)) > 500:
                preview += "... [truncated]"
            data["content_preview"] = preview
        
        # Add any extra kwargs
        data.update(kwargs)
        
        self._write_log("DB_WRITE", data)


# Singleton instance
llm_debug = LLMDebugLogger()