Edison/command-assistant
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Heiko Joerg Schick
2025-04-09 09:34:15 +02:00
commit c19fb93ec5
47 changed files with 5174 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/README.md
+49
View File
@@ -0,0 +1,49 @@
# Edison User Documentation
Welcome to the Edison user documentation! This guide will help you understand how to use Edison effectively in your day-to-day terminal usage.
## Table of Contents
1. [Installation](installation.md)
2. [Basic Usage](basic-usage.md)
3. [Advanced Features](advanced-features.md)
4. [Configuration](configuration.md)
5. [Troubleshooting](troubleshooting.md)
## Quick Start
Edison is a command-line tool that translates natural language into shell commands. To use Edison, simply type `edison` followed by your query:
```bash
edison how to compress all jpg files in the current directory
```
Edison will generate the appropriate command and ask for your confirmation before executing it.
## Feature Overview
```mermaid
flowchart TD
A[Edison CLI] --> B[Natural Language Processing]
B --> C{Command Generation}
C --> D[Command Execution]
C --> E[Command Explanation]
C --> F[Interactive Mode]
style A fill:#f9d5e5,stroke:#333,stroke-width:2px
style B fill:#eeeeee,stroke:#333,stroke-width:2px
style C fill:#d3f6db,stroke:#333,stroke-width:2px
style D fill:#d3f6f5,stroke:#333,stroke-width:2px
style E fill:#d3f6f5,stroke:#333,stroke-width:2px
style F fill:#d3f6f5,stroke:#333,stroke-width:2px
```
Edison offers several key features:
- **Natural Language Command Generation**: Describe what you want to do in plain English
- **Command Explanation**: Get explanations for complex commands
- **Interactive Mode**: Use Edison in an interactive shell
- **Shell Integration**: Works with your default shell
- **Configurable**: Adjust settings via `edison.yaml`
Check the individual documentation pages for more detailed information on each feature.
docs/user/advanced-features.md
+190
View File
@@ -0,0 +1,190 @@
# Advanced Features
Edison offers several advanced features to enhance your productivity. This guide explores these capabilities in detail.
## Interactive Mode
Interactive mode provides a dedicated shell for continuous Edison interactions.
```mermaid
stateDiagram-v2
[*] --> Interactive: edison -i
Interactive --> Query: Enter query
Query --> CommandGeneration: Process query
CommandGeneration --> CommandDisplay: Display command
CommandDisplay --> ActionChoice: Prompt for action
ActionChoice --> Execution: y/Enter
ActionChoice --> Modification: m
ActionChoice --> Explanation: x
ActionChoice --> Clipboard: c
ActionChoice --> Query: n/skip
Execution --> Query: Command executed
Modification --> Execution: Execute modified command
Explanation --> ActionChoice: Show explanation
Clipboard --> ActionChoice: Copy to clipboard
Interactive --> [*]: exit/quit/!exit/Ctrl+D
```
To start interactive mode:
```bash
edison -i
```
In interactive mode, you can:
- Enter queries one after another without restarting Edison
- Access command history with up/down arrows
- Use tab completion for Edison commands
- Type `!help` to see available commands
- Type `!exit`, `exit`, `!quit`, `quit` or press `Ctrl+D` to exit
## Command Explanations
Get explanations for complex commands:
```bash
edison -e how to find duplicate files in a directory
```
The `-e` (or `--explain`) flag makes Edison provide an explanation of the generated command, breaking it down part by part. Edison uses terminal-friendly formatting to make explanations more readable:
- **Bold text** for emphasis and headers
- **Green text** for commands and file paths
- **Yellow text** for command parameters and options
- **Cyan text** for section beginnings and important concepts
- **Code formatting** for command snippets and examples
In interactive mode, use the `x` option when prompted for an action to get an explanation.
## Configuration
Edison can be configured through the `edison.yaml` file. This configuration file is located in the Edison installation directory.
Here's an example configuration:
```yaml
# OpenAI API settings
model: gpt-3.5-turbo
temperature: 0
max_tokens: 500
# Safety settings
safety: true
# Shell settings
shell: bash
```
Configuration options:
| Option | Description | Default |
|--------|-------------|---------|
| model | OpenAI model to use | gpt-3.5-turbo |
| temperature | Randomness of completions (0-1) | 0 |
| max_tokens | Maximum response tokens | 500 |
| safety | Require confirmation before execution | true |
| shell | Shell to use for command execution | system default |
| openai_api_key | OpenAI API key (optional) | - |
You can view your current configuration with:
```bash
edison -c
```
## Logging and Debugging
Edison provides verbose logging for troubleshooting:
```bash
edison -v list all processes
```
With the `-v` (or `--verbose`) flag, Edison will output detailed DEBUG level logs.
Log files are stored in the `edison/logs` directory and can be useful for debugging issues.
## Streaming Command Generation
Edison supports streaming command generation, which shows the command being generated in real-time:
```mermaid
sequenceDiagram
participant User
participant Edison
participant API as OpenAI API
User->>Edison: Natural language query
Edison->>API: Request with streaming enabled
Note over Edison,API: Streaming connection established
API-->>Edison: Token: "f"
Edison->>User: Display: "f"
API-->>Edison: Token: "ind"
Edison->>User: Update: "find"
API-->>Edison: Token: " -name"
Edison->>User: Update: "find -name"
API-->>Edison: Token: " \"*.txt\""
Edison->>User: Update: "find -name \"*.txt\""
API-->>Edison: Token: " -type f"
Edison->>User: Final: "find -name \"*.txt\" -type f"
```
This feature:
- Provides immediate feedback during command generation
- Makes Edison feel more responsive, especially for complex commands
- Allows you to see the thought process in real-time
### Hiding the "Generating command:" Prefix
By default, Edison displays "Generating command:" while it's working. You can hide this prefix with the following configuration:
```yaml
# In edison.yaml
show_generating_prefix: false
```
## Direct Command Modification
Edison provides a direct command modification option that allows you to edit the generated command in-place:
1. When prompted for action, press `d` to directly modify the command
2. Edison will present an interactive editor with the current command
3. Edit the command as needed
4. Press Enter to execute the modified command
This feature is especially useful for:
- Making minor adjustments to generated commands
- Adding flags or options that weren't included
- Correcting parts of the command that may not be exactly what you want
## Performance Optimization
For faster response times:
1. Use a faster model like `gpt-3.5-turbo` (default) instead of larger models
2. Keep queries concise and specific
3. Use interactive mode to avoid startup overhead for multiple commands
4. Enable streaming mode for perceived performance improvements
## Safety Features
Edison includes built-in safety measures:
1. **Command confirmation**: By default, Edison asks for confirmation before executing commands
2. **Dangerous command detection**: Edison will warn about potentially dangerous operations
3. **Markdown filtering**: Commands containing markdown formatting are not executed directly
To disable the safety confirmation (not recommended):
```yaml
# In edison.yaml
safety: false
```
## Cross-Platform Considerations
Edison works on Linux, macOS, and Windows, but some commands might be platform-specific. For best results:
1. Mention your operating system in queries for system-specific commands
2. Use the `-e` flag to understand what a command does before executing it
3. Be aware that file paths use different separators (/ vs \\) on different platforms
docs/user/basic-usage.md
+94
View File
@@ -0,0 +1,94 @@
# Basic Usage
Edison is designed to be intuitive and easy to use. This guide covers the fundamental operations and commands.
## Command Structure
```
edison [OPTIONS] <your natural language query>
```
For example:
```bash
edison how to find all png files in the current directory
```
## Basic Workflow
```mermaid
sequenceDiagram
participant User
participant Edison
participant API as OpenAI API
participant Shell
User->>Edison: Natural language query
Edison->>API: Send prompt with query
API-->>Edison: Return command
Edison->>User: Display command & ask for confirmation
User->>Edison: Confirm (Y/n/m)
alt User confirms
Edison->>Shell: Execute command
Shell-->>User: Show command output
else User modifies
User->>Edison: Modified command
Edison->>Shell: Execute modified command
Shell-->>User: Show command output
else User declines
Edison->>User: Command skipped
end
```
1. **Enter your query**: Describe in natural language what you want to do
2. **Review the command**: Edison will display the generated shell command
3. **Choose an action**:
- Press `Enter` or type `y` to execute the command
- Type `n` to skip execution
- Type `m` to modify the command before execution
- Type `d` to directly modify the command (new feature!)
- Type `c` to copy the command to clipboard
## Command Line Options
Edison supports several command-line options:
| Option | Description |
|--------|-------------|
| `-v, --verbose` | Enable verbose logging (DEBUG level) |
| `-i, --interactive` | Start interactive shell mode |
| `-e, --explain` | Explain the generated command |
| `-c, --config` | Print current configuration |
| `-s, --safety` | Enable safety mode (only useful when safety is off) |
## Examples
Here are some example queries you can try:
```bash
# File operations
edison list all files larger than 10MB
edison create a new directory called "project"
edison find files modified in the last 24 hours
# System information
edison check CPU usage
edison show network connections
edison how much disk space do I have left
# Text processing
edison count lines in all python files
edison find lines containing "error" in log files
edison replace "old" with "new" in all text files
```
## Tips for Effective Queries
1. **Be specific**: The more specific your query, the better the generated command
2. **Include parameters**: Mention specific filenames, sizes, or other parameters
3. **Start with verbs**: Commands usually work best when starting with actions like "find", "list", "create"
4. **Use common terminology**: Avoid obscure technical terms when possible
## Next Steps
Once you're comfortable with basic usage, explore [Advanced Features](advanced-features.md) to learn about interactive mode, command explanations, and more.
docs/user/configuration.md
+152
View File
@@ -0,0 +1,152 @@
# Configuration
Edison provides several ways to configure its behavior to suit your needs. This guide explains the available configuration options and how to set them.
## Configuration File
The primary way to configure Edison is through the `edison.yaml` file. This file is located in the Edison installation directory.
```mermaid
flowchart LR
A[edison.yaml] --> B[OpenAI Settings]
A --> C[Safety Settings]
A --> D[Shell Settings]
B --> B1[Model]
B --> B2[Temperature]
B --> B3[Max Tokens]
B --> B4[API Key]
C --> C1[Safety Mode]
D --> D1[Shell Type]
style A fill:#f9d5e5,stroke:#333,stroke-width:2px
style B fill:#eeeeee,stroke:#333,stroke-width:2px
style C fill:#d3f6db,stroke:#333,stroke-width:2px
style D fill:#d3f6f5,stroke:#333,stroke-width:2px
```
### Sample Configuration File
Here's an example `edison.yaml` file with all available options:
```yaml
# OpenAI API settings
model: gpt-4o-mini
temperature: 0
max_tokens: 500
openai_api_key: your_api_key_here # Optional, can be set via environment variable
streaming: true # Enable streaming command generation
# Safety settings
safety: true
# UI settings
show_generating_prefix: true # Show "Generating command:" prefix during generation
# Shell settings
shell: bash # Options: bash, zsh, powershell.exe, cmd.exe, etc.
```
## Configuration Options
### OpenAI API Settings
| Option | Description | Default | Possible Values |
|--------|-------------|---------|----------------|
| model | OpenAI model to use | gpt-4o-mini | gpt-4o-mini, gpt-3.5-turbo, gpt-4, etc. |
| temperature | Randomness of completions | 0 | 0.0 - 1.0 |
| max_tokens | Maximum tokens in response | 500 | 1 - 4096 |
| openai_api_key | Your OpenAI API key | - | Valid API key |
| streaming | Enable streaming command generation | true | true, false |
### Safety Settings
| Option | Description | Default | Possible Values |
|--------|-------------|---------|----------------|
| safety | Require confirmation before execution | true | true, false |
### UI Settings
| Option | Description | Default | Possible Values |
|--------|-------------|---------|----------------|
| show_generating_prefix | Show "Generating command:" prefix during generation | true | true, false |
### Shell Settings
| Option | Description | Default | Possible Values |
|--------|-------------|---------|----------------|
| shell | Shell to use for command execution | (system default) | bash, zsh, powershell.exe, cmd.exe, etc. |
## Setting Your OpenAI API Key
There are several ways to set your OpenAI API key, listed in order of precedence:
1. **Environment variable**:
- Linux/macOS: `export OPENAI_API_KEY=<yourkey>`
- Windows: `$env:OPENAI_API_KEY="<yourkey>"`
2. **API key file**:
Create a file at `~/.openai.apikey` containing only your API key.
3. **Configuration file**:
Add your key to the `edison.yaml` file:
```yaml
openai_api_key: your_api_key_here
```
## Viewing Current Configuration
To view your current configuration:
```bash
edison -c
```
This will display all current settings, including where your OpenAI API key is being loaded from (but will not display the key itself for security reasons).
## Configuration Load Order
Edison loads configuration in this order:
1. Default values
2. Values from `edison.yaml`
3. Environment variables (for API key)
4. Command-line arguments
Later sources override earlier ones.
## Recommended Configurations
### For Beginners
```yaml
model: gpt-4o-mini
temperature: 0
max_tokens: 500
safety: true
```
### For Advanced Users
```yaml
model: gpt-4 # If you have access
temperature: 0.2 # Slightly more creative
max_tokens: 1000 # For more detailed responses
safety: true # Keep safety on unless you really know what you're doing
```
### For Performance
```yaml
model: gpt-3.5-turbo # Fastest option if you need maximum speed
temperature: 0
max_tokens: 300 # Lower limits can be faster
```
## Troubleshooting Configuration Issues
- **Configuration not applying**: Ensure your `edison.yaml` file is in the correct location
- **API key not recognized**: Check for extra whitespace or quotes in your key
- **Model not available**: Verify you have access to the specified model in your OpenAI account
docs/user/installation.md
+109
View File
@@ -0,0 +1,109 @@
# Edison Installation Guide
This guide covers how to install Edison on different operating systems.
## Prerequisites
Before installing Edison, ensure you have:
- Python 3.6 or higher
- pip (Python package manager)
- An OpenAI API key
## Installation Process
```mermaid
flowchart LR
A[Get Repository] --> B[Install Dependencies]
B --> C[Configure API Key]
C --> D[Test Installation]
style A fill:#f9d5e5,stroke:#333,stroke-width:2px
style B fill:#eeeeee,stroke:#333,stroke-width:2px
style C fill:#d3f6db,stroke:#333,stroke-width:2px
style D fill:#d3f6f5,stroke:#333,stroke-width:2px
```
### Linux and macOS
1. Clone the repository:
```bash
git clone https://github.com/user/command-assistant
cd command-assistant
```
2. Run the installation script:
```bash
source install_edison.sh
```
This script will:
- Create a virtual environment
- Install required dependencies
- Set up the Edison command
3. Configure your OpenAI API key using one of these methods:
- Environment variable: `export OPENAI_API_KEY=<yourkey>`
- Create a file at `~/.openai.apikey` with just the key
- Add the key to the `edison.yaml` configuration file
### Windows
1. Clone the repository:
```powershell
git clone https://github.com/user/command-assistant
cd command-assistant
```
2. Run the installation script:
```powershell
.\install_edison.bat
```
3. Configure your OpenAI API key using one of these methods:
- Environment variable: `$env:OPENAI_API_KEY="<yourkey>"`
- Create a file at `~/.openai.apikey` with just the key
- Add the key to the `edison.yaml` configuration file
## Manual Installation
If you prefer to install manually:
1. Clone the repository:
```bash
git clone https://github.com/user/command-assistant
cd command-assistant
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install the package:
```bash
pip install -e .
```
4. Configure your OpenAI API key as described above
## Verifying Installation
To test your installation, run:
```bash
edison what is the current time
```
You should see a command generated that displays the current time.
## Troubleshooting
If you encounter issues during installation:
- Ensure Python 3.6+ is installed and in your PATH
- Check that your OpenAI API key is correctly set
- Verify that all dependencies were installed correctly
See the [Troubleshooting](troubleshooting.md) page for more detailed help.
docs/user/themes.md
+150
View File
@@ -0,0 +1,150 @@
# Edison Themes Guide
Edison supports rich syntax highlighting for commands through its theme system. This guide explains how to use and customize themes in Edison.
## Available Themes
Edison uses the Rich library's syntax highlighting capabilities, which are powered by Pygments. The following themes are available out of the box:
| Theme Name | Description | Style |
|------------|-------------|-------|
| monokai | Default theme with vibrant colors | Dark |
| github-dark | Based on GitHub's dark theme | Dark |
| solarized-dark | Popular dark theme with softer colors | Dark |
| dracula | High contrast dark theme | Dark |
| nord | Bluish dark theme | Dark |
| gruvbox-dark | Retro dark theme with warm colors | Dark |
| one-dark | Based on Atom's One Dark theme | Dark |
| vs | Based on Visual Studio's default theme | Light |
| solarized-light | Light version of the Solarized theme | Light |
| gruvbox-light | Light version of the Gruvbox theme | Light |
## Using Themes
You can specify a theme in three ways:
### 1. In the Configuration File
Edit your `edison.yaml` file to set the default theme:
```yaml
ui:
theme: "github-dark" # Change from the default "monokai"
```
### 2. Via Command-Line Argument
Specify a theme for a single command:
```bash
edison --theme dracula "list all files"
```
### 3. In Interactive Mode
The theme specified in the configuration or command-line will be used in interactive mode as well.
## Theme Elements
Themes apply different colors to various syntax elements:
- **Keywords**: Shell keywords like `if`, `for`, `while`, etc.
- **Strings**: Text enclosed in quotes
- **Comments**: Lines starting with `#` in bash
- **Variables**: Names prefixed with `$` in bash
- **Operators**: Symbols like `=`, `-gt`, `|`, etc.
- **Functions**: Function names and calls
- **Numbers**: Numeric literals
- **Punctuation**: Brackets, parentheses, etc.
## Creating Custom Themes
While Edison doesn't directly support custom themes, you can create your own by extending the Rich library:
1. Create a custom theme file (e.g., `custom_themes.py`):
```python
from pygments.style import Style
from pygments.token import (
Comment, Error, Keyword, Literal, Name, Number, Operator, String, Text
)
class CustomTheme(Style):
"""A custom syntax highlighting theme."""
# Define colors
background_color = "#282c34"
highlight_color = "#3e4451"
# Define token colors
styles = {
Text: "#abb2bf",
Error: "#e06c75",
Comment: "#5c6370",
Keyword: "#c678dd",
Keyword.Reserved: "#c678dd",
Keyword.Namespace: "#c678dd",
Name: "#abb2bf",
Name.Builtin: "#e5c07b",
Name.Function: "#61afef",
Name.Class: "#e5c07b",
Name.Decorator: "#61afef",
Name.Variable: "#e06c75",
Number: "#d19a66",
Operator: "#56b6c2",
String: "#98c379",
}
```
2. Register your theme with Pygments:
```python
from pygments.styles import STYLE_MAP
STYLE_MAP["custom"] = "custom_themes.CustomTheme"
```
3. Use your custom theme:
```python
from edison.utils.markdown_utils import print_command_rich
print_command_rich("ls -la", theme="custom")
```
## Theme Compatibility
Theme appearance may vary depending on:
1. **Terminal Capabilities**: Some terminals have limited color support or override colors with their own theme settings.
2. **Color Schemes**: Your terminal's color scheme may affect how themes appear.
3. **Font Settings**: Certain font features like ligatures can affect the display of syntax-highlighted code.
## Troubleshooting
If you're not seeing theme differences:
1. **Check Terminal Support**: Ensure your terminal supports 256 colors or true color:
```bash
echo $TERM
echo $COLORTERM
```
For best results, use a terminal that supports true color (24-bit color).
2. **Try High-Contrast Themes**: If differences are subtle, try themes with higher contrast like `dracula` vs `solarized-light`.
3. **Use Complex Commands**: Simple commands might not have enough syntax elements to show significant differences between themes.
## Demo Scripts
Edison includes two demonstration scripts to help you visualize theme differences:
1. `theme_demo.py`: Shows the same bash script rendered with different themes
2. `edison_theme_demo.py`: Demonstrates how Edison's theme functionality works with its markdown_utils module
Run these scripts to see the themes in action:
```bash
python theme_demo.py
python edison_theme_demo.py
docs/user/troubleshooting.md
+128
View File
@@ -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