324 lines
8.4 KiB
Markdown
324 lines
8.4 KiB
Markdown
# Code Structure
|
|
|
|
This document provides a detailed overview of Edison's code organization and file structure.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
edison/
|
|
├── __init__.py # Package initialization
|
|
├── __main__.py # Entry point for module execution
|
|
├── cli.py # Command-line interface
|
|
├── edison.prompt # Prompt template for command generation
|
|
├── edison.yaml # Default configuration file
|
|
├── config/ # Configuration management
|
|
│ ├── __init__.py
|
|
│ └── config_manager.py
|
|
├── core/ # Core business logic
|
|
│ ├── __init__.py
|
|
│ ├── api_client.py # OpenAI API integration
|
|
│ ├── command_executor.py # Command execution
|
|
│ └── prompt_manager.py # Prompt handling
|
|
├── logs/ # Log files directory
|
|
├── ui/ # User interface components
|
|
│ ├── __init__.py
|
|
│ ├── console.py # Console output formatting
|
|
│ └── interactive.py # Interactive shell mode
|
|
└── utils/ # Utility functions
|
|
├── __init__.py
|
|
├── logging_utils.py # Logging configuration
|
|
├── os_utils.py # OS-specific utilities
|
|
└── validation.py # Command validation
|
|
```
|
|
|
|
## Key Files and Their Functions
|
|
|
|
```mermaid
|
|
classDiagram
|
|
cli <|-- config_manager
|
|
cli <|-- api_client
|
|
cli <|-- console
|
|
cli <|-- interactive
|
|
api_client <|-- prompt_manager
|
|
interactive <|-- api_client
|
|
interactive <|-- command_executor
|
|
|
|
class cli {
|
|
+main()
|
|
+parse_arguments()
|
|
}
|
|
|
|
class config_manager {
|
|
+load_config()
|
|
+print_config()
|
|
}
|
|
|
|
class api_client {
|
|
+create_client()
|
|
+generate_command()
|
|
+call_api()
|
|
+get_api_key()
|
|
}
|
|
|
|
class prompt_manager {
|
|
+get_full_prompt()
|
|
+load_prompt_template()
|
|
}
|
|
|
|
class command_executor {
|
|
+execute_command()
|
|
}
|
|
|
|
class console {
|
|
+print_command()
|
|
+prompt_user_input()
|
|
+handle_command_execution()
|
|
+handle_user_input()
|
|
}
|
|
|
|
class interactive {
|
|
+interactive_mode()
|
|
+get_command_explanation()
|
|
+show_help()
|
|
}
|
|
|
|
class logging_utils {
|
|
+setup_logging()
|
|
+get_logger()
|
|
}
|
|
|
|
class os_utils {
|
|
+get_default_shell()
|
|
+missing_posix_display()
|
|
}
|
|
|
|
class validation {
|
|
+check_for_issue()
|
|
+check_for_markdown()
|
|
+is_dangerous_command()
|
|
}
|
|
```
|
|
|
|
### Core Modules
|
|
|
|
#### cli.py
|
|
|
|
The main entry point and command-line interface for Edison:
|
|
- Parses command-line arguments
|
|
- Initializes logging
|
|
- Loads configuration
|
|
- Handles user interaction flow
|
|
- Manages error handling
|
|
|
|
```python
|
|
def main():
|
|
"""Main entry point for the application."""
|
|
# Parse arguments, set up logging, load config, etc.
|
|
|
|
def parse_arguments():
|
|
"""Parse command line arguments."""
|
|
# Define and parse command-line arguments
|
|
```
|
|
|
|
#### config/config_manager.py
|
|
|
|
Handles configuration loading and management:
|
|
- Loads settings from edison.yaml
|
|
- Provides default values
|
|
- Validates configuration
|
|
|
|
```python
|
|
def load_config():
|
|
"""Load configuration from the YAML file."""
|
|
# Find and load the configuration file
|
|
|
|
def print_config(config):
|
|
"""Print the current configuration."""
|
|
# Display configuration settings
|
|
```
|
|
|
|
#### core/api_client.py
|
|
|
|
Manages interaction with the OpenAI API:
|
|
- Creates and initializes the API client
|
|
- Handles API key management
|
|
- Formats queries and processes responses
|
|
- Implements retry logic
|
|
- Supports both streaming and non-streaming command generation
|
|
|
|
```python
|
|
def create_client(config):
|
|
"""Create and initialize an OpenAI client."""
|
|
# Initialize API client with key
|
|
|
|
def generate_command(client, config, query, max_retries=3):
|
|
"""Generate a command using the OpenAI API with retry logic."""
|
|
# Send query to API and handle response
|
|
|
|
def generate_command_streaming(client, config, query, callback):
|
|
"""Generate a command using the OpenAI API with streaming output.
|
|
|
|
Args:
|
|
client: The OpenAI client
|
|
config: The configuration dictionary
|
|
query: The user query
|
|
callback: Function to call with each token
|
|
"""
|
|
# Stream response tokens and call the callback for each one
|
|
```
|
|
|
|
#### core/command_executor.py
|
|
|
|
Executes shell commands:
|
|
- Runs commands in the appropriate shell
|
|
- Handles command output and errors
|
|
- Implements safety checks
|
|
|
|
```python
|
|
def execute_command(shell, command):
|
|
"""Execute a shell command."""
|
|
# Run command and handle result
|
|
```
|
|
|
|
#### core/prompt_manager.py
|
|
|
|
Manages prompt templates and formatting:
|
|
- Loads prompt templates
|
|
- Formats user queries for optimal results
|
|
- Adapts prompts based on shell and OS
|
|
|
|
```python
|
|
def get_full_prompt(query, shell="bash"):
|
|
"""Get the full prompt for the given query and shell."""
|
|
# Format prompt with query and shell info
|
|
```
|
|
|
|
### UI Modules
|
|
|
|
#### ui/console.py
|
|
|
|
Handles console output and user interaction:
|
|
- Formats and displays text
|
|
- Presents command options
|
|
- Handles user input
|
|
- Supports direct command modification
|
|
- Controls display of generating prefix
|
|
|
|
```python
|
|
def print_command(command, show_generating_prefix=True):
|
|
"""Print a command to the console."""
|
|
# Display command with formatting, optionally showing the generating prefix
|
|
|
|
def handle_command_execution(client, config, command, explain=False):
|
|
"""Handle the execution of a command."""
|
|
# Manage command execution flow
|
|
|
|
def handle_direct_modification(command):
|
|
"""Handle direct modification of a command.
|
|
|
|
Args:
|
|
command: The command to modify
|
|
|
|
Returns:
|
|
The modified command
|
|
"""
|
|
# Present interactive editor for direct command modification
|
|
```
|
|
|
|
#### ui/interactive.py
|
|
|
|
Provides an interactive shell mode:
|
|
- Manages continuous interaction
|
|
- Handles command history
|
|
- Processes special commands
|
|
|
|
```python
|
|
def interactive_mode(client, config):
|
|
"""Start an interactive shell."""
|
|
# Run interactive loop
|
|
|
|
def get_command_explanation(client, command):
|
|
"""Get an explanation for a command."""
|
|
# Generate explanation
|
|
```
|
|
|
|
### Utility Modules
|
|
|
|
#### utils/logging_utils.py
|
|
|
|
Configures and manages logging:
|
|
- Sets up log files and formats
|
|
- Controls log levels
|
|
- Provides access to loggers
|
|
|
|
```python
|
|
def setup_logging(verbose=False):
|
|
"""Configure logging for the application."""
|
|
# Set up logging with appropriate levels
|
|
```
|
|
|
|
#### utils/os_utils.py
|
|
|
|
Provides OS-specific functionality:
|
|
- Detects platform information
|
|
- Manages environment-specific behavior
|
|
- Determines default shell
|
|
|
|
```python
|
|
def get_default_shell():
|
|
"""Get the default shell for the current OS."""
|
|
# Determine system shell
|
|
```
|
|
|
|
#### utils/validation.py
|
|
|
|
Validates and checks commands:
|
|
- Detects potentially dangerous commands
|
|
- Checks for markdown formatting
|
|
- Identifies command issues
|
|
|
|
```python
|
|
def is_dangerous_command(command):
|
|
"""Check if a command is potentially dangerous."""
|
|
# Analyze command for dangerous patterns
|
|
```
|
|
|
|
## Static Files
|
|
|
|
- **edison.prompt**: Template for generating prompts sent to the OpenAI API
|
|
- **edison.yaml**: Default configuration file with settings
|
|
|
|
## Dependencies and Imports
|
|
|
|
The project uses these key dependencies:
|
|
|
|
1. **Core Python Libraries**:
|
|
- `argparse`: For command-line argument parsing
|
|
- `logging`: For log management
|
|
- `subprocess`: For command execution
|
|
- `os`, `sys`: For system interaction
|
|
|
|
2. **External Libraries**:
|
|
- `openai`: For API interaction
|
|
- `termcolor`: For colored terminal output
|
|
- `python-dotenv`: For environment variable loading
|
|
- `pyyaml`: For configuration parsing
|
|
- `pyperclip`: For clipboard operations
|
|
- `prompt_toolkit`: For interactive shell functionality
|
|
- `colorama`: For cross-platform color support
|
|
|
|
## Code Style and Conventions
|
|
|
|
Edison follows these coding conventions:
|
|
|
|
1. **PEP 8**: Standard Python style guide
|
|
2. **Docstrings**: All functions and classes have docstrings in the Google style
|
|
3. **Error Handling**: Comprehensive try/except blocks with detailed logging
|
|
4. **Modularity**: Functions and classes have single responsibilities
|
|
5. **Type Hints**: Not currently used but planned for future versions
|
|
|
|
## Special Considerations
|
|
|
|
1. **Cross-Platform Support**: Code includes handling for different operating systems
|
|
2. **API Key Security**: Multiple secure methods for handling API keys
|
|
3. **Command Safety**: Validation to prevent dangerous command execution |