# 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