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

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

# 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

# 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

# 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:

# 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

# 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:

# Lint the entire package
pylint edison

# Lint a specific file
pylint edison/cli.py

Testing

In the future, Edison will use pytest for testing:

# 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:

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:

import pdb; pdb.set_trace()  # Add this line where you want to break

# Or with Python 3.7+
breakpoint()

Development Workflow

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:

{
    "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