Quick Start for Developers

Get started with development in 5 minutes using our modern Python 3.13 + UV setup.

Prerequisites

Git
Python 3.13 (uv can install it for you if needed)
Basic knowledge of Python and machine learning

Step 1: Install UV (30 seconds)

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Verify installation
uv --version

Step 2: Clone and Setup (2 minutes)

# Clone the repository
git clone <repository-url>
cd mlops-with-mlflow

# One command to set up everything!
uv sync

# This automatically:
# - Creates a virtual environment (.venv)
# - Installs Python 3.13 if needed
# - Installs all dependencies
# - Installs all packages in development mode

Step 3: Build and Test (2 minutes)

# Build all packages
make build

# Run all tests
make test

# Or do both
make all

Step 4: Start Developing! 🚀

# Run Python scripts (no activation needed!)
uv run python your_script.py

# Run tests for a specific package
cd src/doe-library
uv run pytest tests/

# Run Jupyter notebook
uv run jupyter notebook

# Start MLflow UI
uv run mlflow ui

Common Tasks

Adding a Dependency

# Add to root project
uv add package-name

# Add to specific package
cd src/my-package
uv add package-name

Running Tests

# All tests
uv run pytest

# Specific test file
uv run pytest tests/test_feature.py

# With coverage
uv run pytest --cov=src

Code Quality

# Format code
uv run ruff format .

# Check code
uv run ruff check .

# Fix issues
uv run ruff check --fix .

Working with MLflow

# Start MLflow UI
uv run mlflow ui

# Open http://localhost:5000 in your browser

# Run a training script
uv run python src/mlflow-sklearn/train.py

Project Structure

mlops-with-mlflow/
├── .venv/                  # Virtual environment (auto-generated)
├── pyproject.toml          # Root configuration
├── uv.lock                 # Locked dependencies
├── src/                    # Source packages
│   ├── doe-library/        # Design of experiments
│   ├── io-library/         # I/O utilities
│   ├── feature-library/    # Feature engineering
│   ├── metrics-library/    # ML metrics
│   ├── plot-library/       # Plotting
│   ├── mlflow-sklearn/     # Scikit-learn + MLflow
│   ├── mlflow-tf/          # TensorFlow + MLflow
│   ├── mlflow-torch/       # PyTorch + MLflow
│   └── hurricane-landfall/ # Hurricane prediction
├── docs/                   # Documentation (you're here!)
├── tests/                  # Integration tests
└── deploy/                 # Deployment configs

Next Steps

Read the UV Guide - Learn uv in depth
Review Architecture - Understand the system design
Check Contributing Guidelines - Learn best practices
Explore Shared Libraries - Understand available utilities
Run a Hurricane Pipeline - Try a real example

Helpful Resources

Documentation

UV Package Manager Guide - Complete uv documentation
UV Quick Reference - Command cheat sheet
Testing Guide - Writing and running tests
Quality Gates - Keeping builds green

External Links

Troubleshooting

UV not found

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Add to shell config
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Python 3.13 not available

# UV can install it for you
uv python install 3.13

Build fails

# Clean and rebuild
make clean
uv sync
make build

Tests fail

# Make sure you built first
make build
make test

# Run with verbose output
uv run pytest -v

Getting Help

Internal: Check the /developers/ documentation
UV Issues: https://github.com/astral-sh/uv/issues
MLflow: https://github.com/mlflow/mlflow/issues
Project: Open an issue in the repository

Welcome to the team! Happy coding! 🎉