Development Setup¶

Guide for setting up a ModelForge development environment.

Overview¶

This guide helps you set up a local development environment for contributing to ModelForge.

Prerequisites¶

Required Software¶

Python 3.11.x (Python 3.12 not yet supported)
Git for version control
NVIDIA GPU with CUDA support (for testing)
CUDA Toolkit 11.8 or 12.x
Node.js 18+ and npm (for frontend development)

Recommended Tools¶

VS Code or PyCharm for IDE
Docker (optional, for isolated testing)
WSL 2 (Windows users)

Initial Setup¶

1. Fork and Clone Repository¶

# Fork the repository on GitHub first

# Clone your fork
git clone https://github.com/YOUR-USERNAME/ModelForge.git
cd ModelForge

# Add upstream remote
git remote add upstream https://github.com/ForgeOpus/ModelForge.git

2. Create Virtual Environment¶

# Create virtual environment
python3.11 -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate

# Windows:
venv\Scripts\activate

3. Install Dependencies¶

# Upgrade pip
pip install --upgrade pip

# Install ModelForge in editable mode
pip install -e .

# Install PyTorch with CUDA support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

# Install development dependencies
pip install pytest pytest-cov black flake8 mypy pre-commit

4. Install Unsloth (Optional, Linux/WSL only)¶

pip install unsloth

5. Set Up Pre-commit Hooks¶

# Install pre-commit hooks
pre-commit install

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

Frontend Development Setup¶

ModelForge has a React frontend in the Frontend directory.

1. Navigate to Frontend Directory¶

cd Frontend

2. Install Dependencies¶

npm install

3. Run Development Server¶

npm run dev

The frontend will be available at http://localhost:5173.

4. Build for Production¶

npm run build

Running ModelForge in Development¶

Start Backend Server¶

# From repository root
modelforge run

Or run directly with Python:

python -m ModelForge.cli run

Start Frontend Development Server¶

cd Frontend
npm run dev

Access Application¶

Backend API: http://localhost:8000
Frontend Dev Server: http://localhost:5173
API Documentation: http://localhost:8000/docs

Project Structure¶

ModelForge/
├── ModelForge/                 # Backend Python package
│   ├── __init__.py
│   ├── app.py                  # FastAPI application
│   ├── cli.py                  # CLI entry point
│   ├── providers/              # Model providers
│   │   ├── huggingface_provider.py
│   │   ├── unsloth_provider.py
│   │   └── provider_factory.py
│   ├── strategies/             # Training strategies
│   │   ├── sft_strategy.py
│   │   ├── qlora_strategy.py
│   │   ├── rlhf_strategy.py
│   │   ├── dpo_strategy.py
│   │   └── strategy_factory.py
│   ├── routers/                # API routers
│   │   ├── finetuning_router.py
│   │   ├── models_router.py
│   │   ├── playground_router.py
│   │   └── hub_management_router.py
│   ├── services/               # Business logic
│   │   ├── training_service.py
│   │   ├── model_service.py
│   │   └── hardware_service.py
│   ├── schemas/                # Pydantic schemas
│   │   └── training_schemas.py
│   ├── utilities/              # Utility functions
│   │   ├── hardware_detection/
│   │   └── configs/
│   ├── formatters/             # Dataset formatters
│   ├── evaluation/             # Evaluation metrics
│   └── model_configs/          # Hardware profile configs
├── Frontend/                   # React frontend
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── utils/
│   ├── public/
│   └── package.json
├── docs/                       # Documentation
├── tests/                      # Test suite
├── pyproject.toml              # Python project config
├── README.md
└── requirements.txt

Development Workflow¶

1. Create Feature Branch¶

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Changes¶

Edit code following the coding standards (see below).

3. Run Tests¶

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_providers.py

# Run specific test
pytest tests/test_providers.py::test_huggingface_provider

4. Format Code¶

# Format with black
black ModelForge/ tests/

# Check with flake8
flake8 ModelForge/ tests/

# Type check with mypy
mypy ModelForge/

5. Commit Changes¶

git add .
git commit -m "feat: add new feature"

Commit Message Format: - feat: New feature - fix: Bug fix - docs: Documentation - refactor: Code refactoring - test: Tests - chore: Maintenance

6. Push and Create Pull Request¶

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Coding Standards¶

Python Style¶

Follow PEP 8 style guide
Use type hints for function signatures
Max line length: 88 characters (Black default)
Use docstrings for all public functions and classes

Example¶

from typing import Dict, Any

def load_model(
    model_id: str,
    device_map: str = "auto",
    **kwargs: Dict[str, Any]
) -> Any:
    """
    Load a model from HuggingFace Hub.

    Args:
        model_id: HuggingFace model ID
        device_map: Device mapping strategy
        **kwargs: Additional arguments

    Returns:
        Loaded model instance

    Raises:
        ModelAccessError: If model cannot be accessed
    """
    # Implementation
    pass

JavaScript/React Style¶

Use ESLint and Prettier
Use functional components and hooks
Use TypeScript for new components (preferred)

Testing¶

Write tests for new features
Maintain >80% code coverage
Use descriptive test names

def test_huggingface_provider_loads_model_successfully():
    """Test that HuggingFace provider can load a model."""
    provider = HuggingFaceProvider()
    model = provider.load_model("meta-llama/Llama-3.2-3B")
    assert model is not None

Testing¶

Unit Tests¶

# Run unit tests
pytest tests/unit/

# Run with verbose output
pytest -v tests/unit/

Integration Tests¶

# Run integration tests
pytest tests/integration/

# Skip slow tests
pytest -m "not slow" tests/

End-to-End Tests¶

# Run E2E tests
pytest tests/e2e/

Coverage Report¶

pytest --cov=ModelForge --cov-report=html
open htmlcov/index.html  # View coverage report

Debugging¶

Backend Debugging¶

VS Code¶

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: ModelForge",
      "type": "python",
      "request": "launch",
      "module": "ModelForge.cli",
      "args": ["run"],
      "console": "integratedTerminal"
    }
  ]
}

PyCharm¶

Right-click ModelForge/cli.py
Select "Debug 'cli'"
Add breakpoints as needed

Frontend Debugging¶

Browser DevTools¶

Open application in browser
Press F12 to open DevTools
Use Console, Network, and React DevTools

VS Code¶

Install "Debugger for Chrome" extension and configure.

Environment Variables¶

Create a .env file in the repository root:

# HuggingFace token
HUGGINGFACE_TOKEN=your_token_here

# Optional: Custom paths
MODELFORGE_DATA_DIR=/path/to/data
MODELFORGE_MODELS_DIR=/path/to/models

# Development settings
DEBUG=true
LOG_LEVEL=DEBUG

Common Development Tasks¶

Adding a New Provider¶

Create ModelForge/providers/your_provider.py
Implement provider interface
Register in provider_factory.py
Add to VALID_PROVIDERS in training_schemas.py
Write tests
Update documentation

See Custom Providers Guide.

Adding a New Strategy¶

Create ModelForge/strategies/your_strategy.py
Implement strategy interface
Register in strategy_factory.py
Add to VALID_STRATEGIES in training_schemas.py
Write tests
Update documentation

See Custom Strategies Guide.

Adding a New API Endpoint¶

Add endpoint in appropriate router (e.g., routers/finetuning_router.py)
Create/update Pydantic schemas in schemas/
Implement business logic in services/
Write tests
Update API documentation

Adding a Frontend Component¶

Create component in Frontend/src/components/
Add to relevant page in Frontend/src/pages/
Update routing if needed
Style with Tailwind CSS
Test in browser

Documentation¶

Build Documentation (If Using MkDocs)¶

# Install MkDocs
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Documentation Standards¶

Use Markdown format
Include code examples
Add screenshots for UI features
Keep docs in sync with code

Continuous Integration¶

GitHub Actions¶

ModelForge uses GitHub Actions for CI/CD.

Workflow runs on: - Pull requests - Pushes to main branch

Checks: - Linting (black, flake8) - Type checking (mypy) - Tests (pytest) - Coverage

Local CI Simulation¶

# Run all CI checks locally
black --check ModelForge/ tests/
flake8 ModelForge/ tests/
mypy ModelForge/
pytest --cov=ModelForge

Release Process¶

Version Bumping¶

Update version in pyproject.toml
Update CHANGELOG.md
Create git tag: git tag v2.1.0
Push tag: git push --tags

Publishing to PyPI¶

# Build distribution
python -m build

# Upload to PyPI
python -m twine upload dist/*

Getting Help¶

Resources¶

GitHub Discussions: Ask questions
GitHub Issues: Report bugs or request features
Discord/Slack: Real-time chat (if available)
Documentation: Comprehensive guides

Before Asking for Help¶

Check existing documentation
Search existing issues
Try to reproduce the issue
Gather relevant information (logs, error messages)

Contributing Guidelines¶

Pull Request Process¶

Ensure all tests pass
Update documentation
Add entry to CHANGELOG.md
Request review from maintainers
Address review feedback
Squash commits if requested

Code Review Checklist¶

[ ] Code follows style guide
[ ] Tests are included and passing
[ ] Documentation is updated
[ ] No breaking changes (or documented)
[ ] Performance considerations addressed
[ ] Security implications reviewed

Troubleshooting Development Issues¶

Import Errors¶

Problem: Cannot import ModelForge modules

Solution:

# Reinstall in editable mode
pip install -e .

CUDA Errors¶

Problem: CUDA not available

Solution:

# Check CUDA installation
nvidia-smi

# Reinstall PyTorch with correct CUDA version
pip install torch --index-url https://download.pytorch.org/whl/cu126

Frontend Build Errors¶

Problem: npm build fails

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Test Failures¶

Problem: Tests fail locally

Solution:

# Clear pytest cache
pytest --cache-clear

# Run with verbose output
pytest -vv

Best Practices¶

Code Quality¶

✅ Write self-documenting code
✅ Use meaningful variable names
✅ Keep functions small and focused
✅ Add comments for complex logic
✅ Handle errors gracefully

Performance¶

✅ Profile before optimizing
✅ Use appropriate data structures
✅ Avoid premature optimization
✅ Cache expensive computations
✅ Test with realistic data sizes

Security¶

✅ Never commit secrets
✅ Validate all inputs
✅ Use environment variables for config
✅ Keep dependencies updated
✅ Follow security best practices

Next Steps¶

Contributing Guide - Contribution guidelines
Architecture Overview - System architecture
Model Configurations - Adding model configs

Happy coding! Thanks for contributing to ModelForge! 🚀