command-assistant/docs/developer/development-setup.md

# 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