contaigents

# Debug Logging for Chat Command The Contaigents CLI chat command now includes comprehensive debug logging capabilities to help you understand and troubleshoot LLM interactions, tool calls, and internal operations. ## Usage ### Enable Debug Logging ```bash # Enable debug logging to console contaigents chat --debug # Enable debug logging with file output contaigents chat --debug --debug-file my-debug.log # Debug with specific provider and model contaigents chat --debug --provider openai --model gpt-4 ``` ### Debug Options - `--debug` - Enable debug logging to console - `--debug-file <file>` - Save debug logs to specified file (default: `chat-debug.log`) ## What Gets Logged ### 1. LLM Prompts Shows the exact prompts sent to the LLM provider, including: - Full conversation context - System prompts - Tool instructions - Prompt options (temperature, max tokens, etc.) ### 2. LLM Responses Displays the raw responses from the LLM, including: - Response content - Provider and model information - Response metadata ### 3. Tool Calls Logs all tool execution details: - Tool name and parameters - Tool execution results - Success/failure status - Error messages ### 4. Internal Operations Tracks internal chat service operations: - Turn tracking in tool call loops - Session management - Error handling ## Debug Output Format ### Console Output Debug information is displayed in the console with color-coded sections: ``` 🔍 [14:30:25] PROMPT [a1b2c3d4] (openai/gpt-4) ──────────────────────────────────────────────────────────────────────────────── You are a helpful AI assistant with access to tools... ## Available Tools ### read_file Read the contents of a file... ──────────────────────────────────────────────────────────────────────────────── 📊 Options: { "temperature": 0.7, "maxTokens": 2000 } 💬 [14:30:27] RESPONSE [a1b2c3d4] (openai/gpt-4) ──────────────────────────────────────────────────────────────────────────────── I'll help you read that file. Let me use the read_file tool: <tool_call name="read_file" id="1"> <file_path>README.md</file_path> </tool_call> ──────────────────────────────────────────────────────────────────────────────── 🔧 [14:30:27] TOOL CALL [a1b2c3d4] Tool: read_file Args: { "file_path": "README.md" } ⚙️ [14:30:27] TOOL RESPONSE [a1b2c3d4] Tool: read_file Success: true Result: # Project Title This is the README content... ``` ### File Output When `--debug-file` is specified, logs are also saved to a JSON Lines file: ```json {"timestamp":"2024-01-15T14:30:25.123Z","type":"prompt","sessionId":"a1b2c3d4","provider":"openai","model":"gpt-4","data":{"prompt":"You are a helpful...","options":{"temperature":0.7}}} {"timestamp":"2024-01-15T14:30:27.456Z","type":"response","sessionId":"a1b2c3d4","provider":"openai","model":"gpt-4","data":{"content":"I'll help you..."}} {"timestamp":"2024-01-15T14:30:27.789Z","type":"tool_call","sessionId":"a1b2c3d4","data":{"name":"read_file","parameters":{"file_path":"README.md"}}} ``` ## Debug Session Dump When you exit a debug session, a comprehensive dump is automatically saved: ``` 👋 Chat session ended. 📁 Debug logs saved to: chat-debug-dump-1705329025123.json 🔍 Debug session saved to: chat-debug-dump-1705329025123.json Goodbye! ``` ### Dump File Structure ```json { "generatedAt": "2024-01-15T14:30:25.123Z", "totalEntries": 15, "logs": [ { "timestamp": "2024-01-15T14:30:25.123Z", "type": "prompt", "sessionId": "a1b2c3d4", "provider": "openai", "model": "gpt-4", "data": { "prompt": "Full prompt content...", "options": { "temperature": 0.7, "maxTokens": 2000 } } } ] } ``` ## Log Types ### Prompt Logs - **Type**: `prompt` - **Contains**: Full prompt text, options, provider info - **When**: Before each LLM API call ### Response Logs - **Type**: `response` - **Contains**: Response content, provider info - **When**: After each LLM API response ### Tool Call Logs - **Type**: `tool_call` - **Contains**: Tool name, parameters - **When**: When tool calls are parsed from LLM response ### Tool Response Logs - **Type**: `tool_response` - **Contains**: Tool results, success status, errors - **When**: After tool execution completes ### Error Logs - **Type**: `error` - **Contains**: Error messages, stack traces - **When**: When errors occur during processing ### Info Logs - **Type**: `info` - **Contains**: General information messages - **When**: For important operational events ## Use Cases ### 1. Debugging LLM Behavior ```bash contaigents chat --debug --provider openai ``` - See exact prompts sent to the LLM - Understand how conversation context is built - Analyze response patterns ### 2. Tool Call Troubleshooting ```bash contaigents chat --debug --debug-file tool-debug.log ``` - Track tool call parsing - Debug tool parameter issues - Analyze tool execution results ### 3. Performance Analysis ```bash contaigents chat --debug --debug-file performance.log ``` - Monitor turn counts in tool loops - Track response times - Identify bottlenecks ### 4. Provider Comparison ```bash # Test with OpenAI contaigents chat --debug --provider openai --debug-file openai-test.log # Test with Anthropic contaigents chat --debug --provider anthropic --debug-file anthropic-test.log ``` ## Tips for Effective Debugging ### 1. Use Descriptive Debug Files ```bash contaigents chat --debug --debug-file "issue-reproduction-$(date +%Y%m%d).log" ``` ### 2. Focus on Specific Issues - Use `--temperature 0` for consistent responses during debugging - Test with simple prompts first - Isolate tool-related issues ### 3. Analyze Patterns - Look for repeated tool call failures - Check prompt length and complexity - Monitor conversation context growth ### 4. Share Debug Information - Debug dumps are perfect for bug reports - Remove sensitive information before sharing - Include relevant portions of logs in issues ## Privacy and Security ### Sensitive Information Debug logs may contain: - API keys (if logged in prompts) - File contents - User input - System information ### Best Practices - Review debug files before sharing - Use environment variables for API keys - Avoid logging sensitive file contents - Clean up debug files regularly ## Integration with Development ### CI/CD Testing ```bash # Automated testing with debug output echo "Test prompt" | contaigents chat --non-interactive --debug --debug-file ci-test.log ``` ### Development Workflow 1. Enable debug logging during development 2. Test specific scenarios 3. Analyze logs for improvements 4. Share debug dumps for collaboration