Initial commit

2025-04-09 09:34:15 +02:00
commit c19fb93ec5
47 changed files with 5174 additions and 0 deletions
@@ -0,0 +1,177 @@
+# Architecture Overview
+
+This document provides a comprehensive overview of Edison's architecture, components, and their interactions.
+
+## System Architecture
+
+```mermaid
+graph TD
+    subgraph User Interaction
+        CLI[CLI Module]
+        Interactive[Interactive Mode]
+        Console[Console UI]
+    end
+    
+    subgraph Core Components
+        APIClient[API Client]
+        PromptManager[Prompt Manager]
+        CommandExecutor[Command Executor]
+    end
+    
+    subgraph Configuration
+        ConfigManager[Config Manager]
+        Validation[Validation]
+    end
+    
+    subgraph Utilities
+        Logging[Logging Utils]
+        OSUtils[OS Utils]
+    end
+    
+    CLI --> APIClient
+    CLI --> CommandExecutor
+    CLI --> Console
+    CLI --> Interactive
+    Interactive --> APIClient
+    Interactive --> CommandExecutor
+    
+    APIClient --> PromptManager
+    APIClient --> ConfigManager
+    CommandExecutor --> Validation
+    CommandExecutor --> OSUtils
+    
+    ConfigManager --> Logging
+    
+    style User Interaction fill:#f9d5e5,stroke:#333,stroke-width:2px
+    style Core Components fill:#d3f6db,stroke:#333,stroke-width:2px
+    style Configuration fill:#d3f6f5,stroke:#333,stroke-width:2px
+    style Utilities fill:#eeeeee,stroke:#333,stroke-width:2px
+```
+
+## Component Breakdown
+
+### User Interaction Layer
+
+The user interaction layer handles all user-facing functionality:
+
+1. **CLI Module** (`edison/cli.py`):
+   - Entry point for the application
+   - Parses command-line arguments
+   - Initializes logging and configuration
+   - Coordinates between components
+
+2. **Interactive Mode** (`edison/ui/interactive.py`):
+   - Provides a dedicated shell for continuous interaction
+   - Manages command history and user input
+   - Handles special commands and actions
+
+3. **Console UI** (`edison/ui/console.py`):
+   - Formats and displays text output
+   - Presents commands and prompt options
+   - Manages colored output with termcolor
+
+### Core Components
+
+The core components handle the main business logic:
+
+1. **API Client** (`edison/core/api_client.py`):
+   - Manages communication with the OpenAI API
+   - Handles API key management and retry logic
+   - Processes responses from the API
+
+2. **Prompt Manager** (`edison/core/prompt_manager.py`):
+   - Constructs effective prompts for the AI model
+   - Formats user queries for optimal command generation
+   - Adapts prompts based on shell and OS
+
+3. **Command Executor** (`edison/core/command_executor.py`):
+   - Safely executes generated commands
+   - Handles command output and errors
+   - Adapts execution for different shells and platforms
+
+### Configuration Layer
+
+The configuration layer manages settings and validation:
+
+1. **Config Manager** (`edison/config/config_manager.py`):
+   - Loads and validates configuration from edison.yaml
+   - Provides default settings
+   - Handles environment variables for API keys
+
+2. **Validation** (`edison/utils/validation.py`):
+   - Validates commands for safety
+   - Detects potentially dangerous operations
+   - Checks for invalid syntax or formatting
+
+### Utilities
+
+Utility modules provide support functions:
+
+1. **Logging Utils** (`edison/utils/logging_utils.py`):
+   - Configures logging for the application
+   - Manages log files and levels
+   - Provides logger access
+
+2. **OS Utils** (`edison/utils/os_utils.py`):
+   - Provides OS-specific functionality
+   - Detects platform and shell information
+   - Manages environment variables
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant Config
+    participant APIClient
+    participant CommandExecutor
+    participant Shell
+    
+    User->>CLI: Input query
+    CLI->>Config: Load configuration
+    CLI->>APIClient: Send query
+    APIClient->>APIClient: Format prompt
+    APIClient->>OpenAI: API request
+    OpenAI-->>APIClient: Command response
+    APIClient-->>CLI: Return command
+    CLI->>User: Display command
+    User->>CLI: Confirm execution
+    CLI->>CommandExecutor: Execute command
+    CommandExecutor->>Shell: Run in shell
+    Shell-->>CommandExecutor: Command output
+    CommandExecutor-->>CLI: Execution result
+    CLI->>User: Display output
+```
+
+1. User inputs a natural language query
+2. CLI loads configuration and processes arguments
+3. Query is sent to the API client
+4. API client formats the prompt and sends it to OpenAI
+5. Response is received and processed
+6. Command is displayed to the user
+7. User confirms, modifies, or cancels execution
+8. If confirmed, command is sent to the command executor
+9. Command executor runs the command in the appropriate shell
+10. Output is returned to the CLI and displayed to the user
+
+## Extension Points
+
+Edison is designed to be extensible in several ways:
+
+1. **New UI Components**: Add new UI modes by extending the UI components
+2. **Alternative AI Providers**: The API client can be extended to support other AI providers
+3. **Custom Prompt Templates**: The prompt manager can be enhanced with specialized prompts
+4. **Additional Command Validation**: Add custom validation rules in the validation module
+5. **Platform-Specific Features**: Extend OS utils for additional platform support
+
+## Technologies Used
+
+Edison is built using:
+
+- **Python**: Core programming language
+- **OpenAI API**: For natural language processing and command generation
+- **prompt_toolkit**: For interactive shell functionality
+- **termcolor**: For colored terminal output
+- **pyyaml**: For configuration file parsing
+- **pyperclip**: For clipboard integration