Development Guide¶

Welcome to the EVOSEAL development guide! This comprehensive document provides all the information you need to get started with development and contribute effectively to the project.

Table of Contents¶

Development Environment Setup
Code Organization
Development Workflow
Testing
Documentation
Code Style
Dependency Management
Debugging
Performance Optimization
Security Considerations
Release Process
Troubleshooting

Development Environment Setup¶

Prerequisites¶

Python 3.10+
Git
(Optional) Docker and Docker Compose
(Optional) Task Master CLI for task management
(Recommended) Pre-commit for code quality checks

Quick Start¶

Fork and Clone the repository:

git clone https://github.com/your-username/EVOSEAL.git
cd EVOSEAL

Set up a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install development dependencies:

pip install -r requirements/dev.txt
pip install -e .  # Install package in development mode

Set up pre-commit hooks:
```
pre-commit install
```

Verify installation:

python -m pytest tests/
python -c "import evoseal; print('Installation successful!')"

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Alternative Setup with Docker¶

# Build development container
docker-compose -f docker-compose.dev.yml build

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Access the container
docker-compose -f docker-compose.dev.yml exec evoseal bash

Code Organization¶

Project Structure¶

evoseal/
├── core/                    # Core framework components
├── integration/            # Integration modules (DGM, OpenEvolve, SEAL (Self-Adapting Language Models))
├── agents/                # Agent implementations
├── providers/             # AI/ML model providers
├── models/                # Data models and schemas
├── storage/               # Data persistence
└── utils/                 # Utility functions

tests/
├── unit/                  # Unit tests
├── integration/           # Integration tests
├── regression/            # Regression tests
└── safety/                # Safety and security tests

docs/
├── api/                   # API documentation
├── guides/                # User and developer guides
├── architecture/          # Architecture documentation
├── safety/                # Safety documentation
└── core/                  # Core system documentation

Coding Conventions¶

Modules: Use snake_case for module names
Classes: Use PascalCase for class names
Functions: Use snake_case for function names
Constants: Use UPPER_CASE for constants
Private members: Prefix with single underscore _
Type hints: Always include type hints for public APIs

Development Workflow¶

1. Planning¶

Check existing issues and discussions
Create or update issue for your feature/fix
Discuss approach with maintainers if needed

2. Development¶

Create feature branch from main
Write code following style guidelines
Add comprehensive tests
Update documentation

3. Testing¶

Run unit tests: pytest tests/unit/
Run integration tests: pytest tests/integration/
Run safety tests: pytest tests/safety/
Check code coverage: pytest --cov=evoseal

4. Quality Checks¶

Format code: black evoseal tests
Sort imports: isort evoseal tests
Lint code: ruff check evoseal tests
Type check: mypy evoseal
Security scan: bandit -r evoseal

5. Documentation¶

Update docstrings for new/modified functions
Update relevant documentation files
Add examples if introducing new features

6. Submission¶

Commit changes with descriptive messages
Push branch to your fork
Create pull request with detailed description
Address review feedback

Testing¶

Test Categories¶

Unit Tests¶

Test individual functions and classes
Mock external dependencies
Fast execution (< 1s per test)
Location: tests/unit/

Integration Tests¶

Test component interactions
Use real dependencies where possible
Moderate execution time
Location: tests/integration/

Safety Tests¶

Test safety mechanisms and rollback
Critical for production readiness
Location: tests/safety/

Regression Tests¶

Test for performance regressions
Benchmark critical paths
Location: tests/regression/

Running Tests¶

# Run all tests
pytest

# Run specific test category
pytest tests/unit/
pytest tests/integration/
pytest tests/safety/

# Run with coverage
pytest --cov=evoseal --cov-report=html

# Run specific test file
pytest tests/unit/test_evolution_pipeline.py

# Run with verbose output
pytest -v

# Run tests matching pattern
pytest -k "test_safety"

Writing Tests¶

import pytest
from unittest.mock import Mock, patch
from evoseal.core import EvolutionPipeline

class TestEvolutionPipeline:
    def test_initialization(self):
        """Test pipeline initialization."""
        pipeline = EvolutionPipeline()
        assert pipeline is not None

    @patch('evoseal.core.evolution_pipeline.SomeExternalService')
    def test_with_mock(self, mock_service):
        """Test with mocked external dependency."""
        mock_service.return_value.process.return_value = "success"
        pipeline = EvolutionPipeline()
        result = pipeline.run()
        assert result == "success"

    def test_error_handling(self):
        """Test error handling."""
        pipeline = EvolutionPipeline()
        with pytest.raises(ValueError):
            pipeline.run(invalid_param=True)

Code Style and Quality¶

Pre-commit Hooks¶

Automatically run on each commit: - Black - Code formatting - isort - Import sorting - Ruff - Linting and style enforcement - Mypy - Static type checking - Bandit - Security scanning - Safety - Dependency vulnerability scanning

Manual Quality Checks¶

# Format code
black evoseal tests

# Sort imports
isort evoseal tests

# Lint code
ruff check evoseal tests

# Type checking
mypy evoseal

# Security scanning
bandit -r evoseal

# Dependency vulnerability check
safety check

Code Style Guidelines¶

Line length: 88 characters (Black default)
Docstrings: Google style docstrings
Type hints: Required for all public APIs
Error handling: Use specific exception types
Logging: Use structured logging with appropriate levels

Dependency Management¶

Requirements Files¶

requirements.txt - Base runtime dependencies
requirements/dev.txt - Development dependencies
requirements/test.txt - Testing dependencies
requirements/docs.txt - Documentation dependencies

Adding Dependencies¶

Add to appropriate requirements file
Pin versions for stability
Update requirements/requirements.txt with pip freeze
Test with new dependencies
Update documentation if needed

Dependency Updates¶

# Check for outdated packages
pip list --outdated

# Update specific package
pip install --upgrade package_name

# Regenerate frozen requirements
pip freeze > requirements/requirements.txt

Debugging¶

Debug Configuration¶

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Use debugger
import pdb; pdb.set_trace()

# Or use ipdb for better experience
import ipdb; ipdb.set_trace()

Common Debugging Scenarios¶

Evolution Pipeline Issues¶

Check component initialization
Verify configuration files
Review event system logs
Validate safety mechanisms

Integration Problems¶

Test components individually
Check API credentials
Verify network connectivity
Review error logs

Performance Issues¶

Profile with cProfile
Monitor memory usage
Check database queries
Review algorithm complexity

Performance Optimization¶

Profiling¶

# Profile with cProfile
python -m cProfile -o profile.stats your_script.py

# Analyze profile
python -c "import pstats; p=pstats.Stats('profile.stats'); p.sort_stats('cumulative').print_stats(20)"

# Memory profiling
pip install memory-profiler
python -m memory_profiler your_script.py

Optimization Guidelines¶

Algorithms: Choose appropriate data structures
Database: Optimize queries and use indexes
Caching: Cache expensive computations
Async: Use async/await for I/O operations
Parallelism: Use multiprocessing for CPU-bound tasks

Security Considerations¶

Code Security¶

Never commit API keys or secrets
Use environment variables for sensitive data
Validate all inputs
Sanitize user-provided data
Use secure random number generation

Dependency Security¶

Regularly update dependencies
Use safety to check for vulnerabilities
Review dependency licenses
Minimize dependency count

Runtime Security¶

Run with minimal privileges
Use sandboxed execution for untrusted code
Implement proper error handling
Log security-relevant events

Release Process¶

Version Numbering¶

Follow Semantic Versioning
Format: MAJOR.MINOR.PATCH
Pre-release: MAJOR.MINOR.PATCH-alpha.N

Release Checklist¶

Pre-release:
[ ] All tests passing
[ ] Documentation updated
[ ] CHANGELOG.md updated
[ ] Version bumped
Release:
[ ] Create release branch
[ ] Final testing
[ ] Create GitHub release
[ ] Deploy to PyPI
[ ] Update documentation
Post-release:
[ ] Merge to main
[ ] Create next development branch
[ ] Announce release

Troubleshooting¶

Common Issues¶

Import Errors¶

# Ensure package is installed in development mode
pip install -e .

# Check Python path
python -c "import sys; print(sys.path)"

Test Failures¶

# Run tests with verbose output
pytest -v --tb=long

# Run specific failing test
pytest tests/path/to/test.py::test_function -v

Pre-commit Hook Failures¶

# Run hooks manually
pre-commit run --all-files

# Skip hooks temporarily (not recommended)
git commit --no-verify

Performance Issues¶

# Profile the application
python -m cProfile -o profile.stats main.py

# Check memory usage
python -m memory_profiler main.py

Getting Help¶

Documentation: Check docs/ directory
Issues: Search existing GitHub issues
Discussions: Use GitHub Discussions
Community: Join our Discord/Slack
Maintainers: Contact project maintainers

Contributing Guidelines¶

Code of Conduct¶

Be respectful and inclusive
Follow our Code of Conduct
Help create a welcoming environment

Contribution Process¶

Fork the repository
Create a feature branch
Make your changes
Add tests and documentation
Submit a pull request
Respond to review feedback

Pull Request Guidelines¶

Clear, descriptive title
Detailed description of changes
Link to related issues
Include tests for new functionality
Update documentation as needed
Ensure all checks pass

Thank you for contributing to EVOSEAL! Your efforts help make this project better for everyone. - Blacken-docs - Format code in documentation

Manual Checks¶

Run these before pushing:

# Format code with Black
black .


# Sort imports
isort .


# Run type checking
mypy .


# Run linter
ruff check .

Pre-commit Installation¶

# Install pre-commit
pip install pre-commit

# Install git hooks
pre-commit install

Project Structure¶

evoseal/
├── core/               # Core framework components
├── integration/        # Integration modules (DGM, OpenEvolve, SEAL (Self-Adapting Language Models))
├── models/            # Data models
├── providers/         # AI/ML model providers
├── storage/           # Data persistence
├── utils/             # Utility functions
└── examples/          # Example scripts and templates

Testing¶

Run the test suite with:

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run integration tests
pytest tests/integration/

# Run tests with coverage
pytest --cov=evoseal tests/

## Documentation

We use MkDocs with the Material theme for documentation. To serve the docs locally:

```bash
mkdocs serve

Development Workflow¶

Using Task Master¶

We use task-master for task management:

# List all tasks
task-master list

# Show details of a task
task-master show <task_id>

# Mark a task as done
task-master set-status --id=<task_id> --status=done

# Generate task files
task-master generate

Pull Request Process¶

Ensure all tests pass
Update documentation as needed
Run pre-commit checks
Create a pull request with:
Clear description of changes
Related issue numbers
Screenshots if applicable
Updated documentation

Versioning¶

We follow Semantic Versioning
Update version in evoseal/__version__.py
Update CHANGELOG.md with release notes

Code Review Process¶

PRs require at least one approval
All CI checks must pass
Code must be well-documented
Follows project coding standards

Release Process¶

Update version in pyproject.toml
Update CHANGELOG.md
Create a release tag
Push the tag to trigger deployment

Last update: 2025-07-20
Created: 2025-06-17