Initial commit

2025-04-09 09:34:15 +02:00
commit c19fb93ec5
47 changed files with 5174 additions and 0 deletions
@@ -0,0 +1,247 @@
+# Development Environment Setup
+
+This guide explains how to set up your development environment for Edison.
+
+## Prerequisites
+
+Before beginning development on Edison, ensure you have:
+
+- **Python 3.6+**: Required for core development
+- **Git**: For version control
+- **OpenAI API Key**: For testing API integration
+- **pip**: For package management
+
+## Setting Up Your Development Environment
+
+```mermaid
+flowchart TD
+    A[Clone Repository] --> B[Set Up Virtual Environment]
+    B --> C[Install Dependencies]
+    C --> D[Configure API Key]
+    D --> E[Run Tests]
+    E --> F[Start Development]
+    
+    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:#f5d5f5,stroke:#333,stroke-width:2px
+    style F fill:#f5f5d5,stroke:#333,stroke-width:2px
+```
+
+### Step 1: Clone the Repository
+
+```bash
+# If you're a contributor, fork the repository first, then:
+git clone https://github.com/YOUR_USERNAME/command-assistant.git
+
+# If you're a maintainer:
+git clone https://github.com/user/command-assistant.git
+
+# Navigate to the directory
+cd command-assistant
+```
+
+### Step 2: Create a Virtual Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On macOS/Linux:
+source venv/bin/activate
+
+# On Windows:
+venv\Scripts\activate
+```
+
+### Step 3: Install in Development Mode
+
+```bash
+# Install Edison in development mode
+pip install -e .
+
+# Install development dependencies
+pip install pylint pytest
+```
+
+### Step 4: Configure OpenAI API Key
+
+For development, it's best to use environment variables:
+
+```bash
+# On macOS/Linux:
+export OPENAI_API_KEY="your-api-key-here"
+
+# On Windows:
+set OPENAI_API_KEY=your-api-key-here
+```
+
+Or create a `.env` file in the project root:
+
+```
+OPENAI_API_KEY="your-api-key-here"
+```
+
+## Directory Structure Setup
+
+The development environment should match this structure:
+
+```
+command-assistant/         # Root directory
+├── docs/                 # Documentation
+├── edison/               # Main package
+├── tests/                # Test directory (future addition)
+├── venv/                 # Virtual environment (generated)
+├── .gitignore            # Git ignore file
+├── LICENSE               # License file
+├── README.md             # Project readme
+├── install_edison.sh     # Installation script for Linux/macOS
+├── install_edison.bat    # Installation script for Windows
+├── requirements.txt      # Package dependencies
+└── setup.py              # Package setup file
+```
+
+## Running Edison in Development Mode
+
+```bash
+# Run Edison from the command line
+edison your query here
+
+# Run Edison as a module
+python -m edison your query here
+
+# Run with verbose logging
+edison -v your query here
+```
+
+## Development Tools
+
+### Code Linting
+
+Edison uses `pylint` for code linting:
+
+```bash
+# Lint the entire package
+pylint edison
+
+# Lint a specific file
+pylint edison/cli.py
+```
+
+### Testing
+
+In the future, Edison will use `pytest` for testing:
+
+```bash
+# Run all tests
+pytest
+
+# Run specific tests
+pytest tests/test_api_client.py
+
+# Run with coverage
+pytest --cov=edison
+```
+
+## Debugging
+
+### Logging
+
+Enable verbose logging for debugging:
+
+```bash
+edison -v your query here
+```
+
+Logs are stored in `edison/logs/edison.log`.
+
+### Using a Debugger
+
+For detailed debugging, you can use Python's built-in debugger or an IDE:
+
+```python
+import pdb; pdb.set_trace()  # Add this line where you want to break
+
+# Or with Python 3.7+
+breakpoint()
+```
+
+## Development Workflow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Feature
+    Feature --> Development
+    Development --> Testing
+    Testing --> Refinement
+    Refinement --> Testing: Issues found
+    Testing --> PullRequest: Tests pass
+    PullRequest --> Review
+    Review --> Refinement: Changes requested
+    Review --> Merge: Approved
+    Merge --> [*]
+```
+
+1. **Pick a Feature/Issue**: Select something to work on
+2. **Create a Branch**: Make a new branch for your work
+3. **Development**: Write code, docstrings, and comments
+4. **Testing**: Test your changes thoroughly
+5. **Pull Request**: Submit your changes for review
+6. **Review**: Address any feedback
+7. **Merge**: Changes are merged into main branch
+
+## IDE Setup
+
+### VS Code
+
+Recommended settings for `settings.json`:
+
+```json
+{
+    "python.linting.pylintEnabled": true,
+    "python.linting.enabled": true,
+    "python.formatting.provider": "black",
+    "python.formatting.blackArgs": ["--line-length", "100"],
+    "editor.formatOnSave": true,
+    "python.testing.pytestEnabled": true,
+    "python.testing.unittestEnabled": false,
+    "python.testing.nosetestsEnabled": false,
+    "python.testing.pytestArgs": ["tests"]
+}
+```
+
+### PyCharm
+
+Recommended settings:
+- Enable pylint integration
+- Set code style to PEP 8
+- Configure pytest as the test runner
+
+## Pre-Commit Hooks (Future Addition)
+
+In the future, we'll add pre-commit hooks for:
+- Code formatting with `black`
+- Import sorting with `isort`
+- Linting with `pylint`
+- Type checking with `mypy`
+
+## Troubleshooting Development Issues
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| `ModuleNotFoundError` | Ensure your virtual environment is activated and package is installed with `pip install -e .` |
+| Import errors | Check your PYTHONPATH and package structure |
+| API errors | Verify your API key is set correctly |
+| Permission denied | Check file permissions, especially for executable scripts |
+
+### Getting Help
+
+If you encounter issues during development:
+- Check the documentation
+- Search for similar issues on GitHub
+- Ask for help in your pull request
+- Open a new issue describing your problem