Initial commit

2025-04-09 09:34:15 +02:00
commit c19fb93ec5
47 changed files with 5174 additions and 0 deletions
@@ -0,0 +1,128 @@
+# Troubleshooting
+
+This guide helps you diagnose and resolve common issues with Edison.
+
+## Common Issues and Solutions
+
+```mermaid
+flowchart TB
+    Start[Issue Detected] --> A{API Related?}
+    A -->|Yes| B[API Issues]
+    A -->|No| C{Installation Related?}
+    C -->|Yes| D[Installation Issues]
+    C -->|No| E{Command Related?}
+    E -->|Yes| F[Command Issues]
+    E -->|No| G[Other Issues]
+    
+    B --> B1[Check API Key]
+    B --> B2[Check Network]
+    B --> B3[Check Model Access]
+    
+    D --> D1[Check Python Version]
+    D --> D2[Check Dependencies]
+    D --> D3[Check PATH]
+    
+    F --> F1[Check Command Syntax]
+    F --> F2[Check Shell Compatibility]
+    
+    style Start fill:#f9d5e5,stroke:#333,stroke-width:2px
+    style B fill:#eeeeee,stroke:#333,stroke-width:2px
+    style D fill:#d3f6db,stroke:#333,stroke-width:2px
+    style F fill:#d3f6f5,stroke:#333,stroke-width:2px
+    style G fill:#f5d3d3,stroke:#333,stroke-width:2px
+```
+
+### API Issues
+
+| Issue | Solution |
+|-------|----------|
+| `No OpenAI API key found` | Set your API key using one of the [configuration methods](configuration.md#setting-your-openai-api-key) |
+| `Rate limit exceeded` | Wait a minute before trying again, or check your OpenAI rate limits |
+| `Invalid API key` | Verify your API key is correct and has not expired |
+| `Model not available` | Ensure you have access to the requested model, or change to `gpt-3.5-turbo` |
+
+### Installation Issues
+
+| Issue | Solution |
+|-------|----------|
+| `Command not found: edison` | Ensure Edison is installed and in your PATH |
+| `No module named 'openai'` | Reinstall Edison or run `pip install -r requirements.txt` |
+| `ModuleNotFoundError` | Ensure all dependencies are installed correctly |
+| `Python version error` | Ensure you're using Python 3.6+ |
+
+### Command Execution Issues
+
+| Issue | Solution |
+|-------|----------|
+| `Command contains markdown` | Edison detected markdown in the response; rerun the query |
+| `Command execution failed` | The generated command has syntax errors; try modifying it |
+| `Permission denied` | The command requires higher permissions; prefix with sudo if appropriate |
+| `Command not found` | The generated command uses a program not installed on your system |
+
+### Other Issues
+
+| Issue | Solution |
+|-------|----------|
+| `Slow response times` | Try a faster model or check your internet connection |
+| `Inaccurate commands` | Be more specific in your query or add more context |
+| `Unexpected behavior` | Check the logs for detailed error information |
+
+## Enabling Verbose Mode
+
+For more detailed troubleshooting, use verbose mode:
+
+```bash
+edison -v your query here
+```
+
+This will print detailed logs that can help identify issues.
+
+## Checking Logs
+
+Log files are stored in the `edison/logs` directory. The main log file is `edison.log`. Check this file for detailed error messages and API interactions.
+
+```bash
+cat edison/logs/edison.log | tail -n 50
+```
+
+## Resetting Configuration
+
+If you suspect a configuration issue, you can reset to defaults by removing or renaming your `edison.yaml` file:
+
+```bash
+mv edison.yaml edison.yaml.bak
+```
+
+Edison will create a new configuration file with default settings on the next run.
+
+## Common Error Messages and Meanings
+
+### "No OpenAI API key found"
+
+You need to set your OpenAI API key. See [configuration options](configuration.md).
+
+### "Error calling OpenAI API"
+
+There was an issue communicating with the OpenAI API. Check:
+1. Your internet connection
+2. API key validity
+3. OpenAI service status
+
+### "Response does not contain a valid command"
+
+The AI generated a response that Edison couldn't interpret as a command. Try:
+1. Rephrasing your query to be more specific
+2. Checking logs for the full response
+3. Using a different model
+
+## Getting Help
+
+If you continue to experience issues:
+
+1. Check the full documentation
+2. Look for similar issues in the GitHub repository
+3. Open a new issue with:
+   - A clear description of the problem
+   - Steps to reproduce
+   - Any error messages (with sensitive information redacted)
+   - Your OS and Python version