TP1 - Cahier des charges et configuration de l'environnement

Lab Pratique 60 min Debutant

---

Objectifs d'apprentissage

A la fin de ce lab, vous serez capable de :

• Creer une structure de repertoires de projet pour le deploiement ML
• Configurer un environnement virtuel Python avec venv
• Installer et gerer les dependances avec pip et requirements.txt
• Rediger un cahier des charges pour un projet ML
• Verifier que l'environnement est fonctionnel avec un script de test

---

Contexte du projet

Tout au long de ce cours, vous construirez un service complet de prediction ML — de l'entrainement du modele au deploiement de l'API. Ce premier lab pose les fondations.

Voir la feuille de route du projet

---

Prerequis

Element	Description
Python 3.10+	Installe et accessible via le terminal (python --version)
pip	Gestionnaire de paquets Python (inclus avec Python)
Git	Pour le versionnement du code
Terminal	PowerShell (Windows) ou bash (macOS/Linux)
Editeur de code	VS Code, Cursor ou PyCharm

Verifiez votre installation Python

Avant de commencer, executez ces commandes dans votre terminal :

python --version    # Devrait afficher Python 3.10+
pip --version       # Devrait afficher pip 23+
git --version       # Devrait afficher git 2+

Si une commande echoue, installez le composant manquant avant de continuer.

---

Etape 1 : Creer la structure du projet

1.1 Creer le repertoire racine

Ouvrez votre terminal et creez le repertoire du projet :

# Creer le repertoire principal
mkdir ml-deployment-project
cd ml-deployment-project

1.2 Creer l'arborescence complete

Creez la structure standard pour un projet ML :

# Creer les repertoires
mkdir -p app
mkdir -p models
mkdir -p data/raw
mkdir -p data/processed
mkdir -p tests
mkdir -p scripts
mkdir -p notebooks
mkdir -p docs

1.3 Creer les fichiers d'initialisation

# Fichiers __init__.py pour les packages Python
touch app/__init__.py
touch tests/__init__.py

Sur Windows (PowerShell)

Remplacez touch par New-Item :

New-Item -ItemType File -Path app/__init__.py
New-Item -ItemType File -Path tests/__init__.py

Ou utilisez simplement votre editeur de code pour creer les fichiers.

1.4 Verifier la structure

Votre projet devrait ressembler a ceci :

ml-deployment-project/
├── app/
│   └── __init__.py
├── models/
├── data/
│   ├── raw/
│   └── processed/
├── tests/
│   └── __init__.py
├── scripts/
├── notebooks/
└── docs/

Verification — Commande pour afficher l'arborescence

# macOS/Linux
find . -type f -o -type d | head -20

# Windows PowerShell
Get-ChildItem -Recurse -Depth 2 | Select-Object FullName

Vous devriez voir tous les repertoires et les fichiers __init__.py.

---

Etape 2 : Configurer l'environnement virtuel

2.1 Creer l'environnement virtuel

# Depuis la racine du projet
python -m venv .venv

2.2 Activer l'environnement

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (CMD)
.venv\Scripts\activate.bat

# macOS / Linux
source .venv/bin/activate

PowerShell — Politique d'execution

Si vous obtenez une erreur sur PowerShell, executez d'abord :

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Puis reessayez l'activation.

2.3 Verifier l'activation

# L'invite devrait afficher (.venv)
(.venv) $ python --version
Python 3.11.x

# Verifier que pip pointe vers l'environnement virtuel
(.venv) $ pip --version
pip 23.x.x from .../ml-deployment-project/.venv/lib/...

Verification — Comment savoir si l'environnement est actif ?

1. Votre invite affiche (.venv) au debut
2. which python (Linux/macOS) ou Get-Command python (PowerShell) pointe vers .venv/
3. pip list affiche tres peu de paquets (seulement pip et setuptools)

2.4 Mettre a jour pip

python -m pip install --upgrade pip

---

Etape 3 : Installer les dependances

3.1 Creer le fichier requirements.txt

Creez un fichier requirements.txt a la racine du projet avec le contenu suivant :

# ===========================================
# ML Deployment Project - Dependencies
# ===========================================

# --- Core ML ---
scikit-learn==1.4.2
pandas==2.2.0
numpy==1.26.4
joblib==1.3.2

# --- API Framework ---
fastapi==0.109.0
uvicorn[standard]==0.27.0
pydantic==2.5.3

# --- Testing ---
pytest==8.0.0
pytest-cov==4.1.0
httpx==0.26.0

# --- Model Explainability ---
shap==0.44.1
lime==0.2.0.1

# --- Utilities ---
python-dotenv==1.0.0
requests==2.31.0

3.2 Installer les dependances

pip install -r requirements.txt

L'installation prend du temps ?

L'installation de SHAP et de ses dependances peut prendre 2 a 5 minutes. C'est normal — SHAP compile des extensions C en arriere-plan.

Si l'installation de SHAP echoue, vous pouvez temporairement le commenter dans requirements.txt et l'installer plus tard.

3.3 Verifier l'installation

# Verifier que les paquets principaux sont installes
pip list | grep -i "scikit-learn\|fastapi\|pandas\|pytest\|shap"

Verification — Sortie attendue

Vous devriez voir quelque chose comme :

fastapi          0.109.0
pandas           2.2.0
pytest           8.0.0
scikit-learn     1.4.2
shap             0.44.1

Si un paquet est manquant, verifiez les erreurs d'installation et reessayez avec :

pip install <nom-du-paquet>

---

Etape 4 : Creer les fichiers de configuration

4.1 Fichier .gitignore

Creez un fichier .gitignore a la racine :

# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
*.egg

# Virtual environment
.venv/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Data files (too large for Git)
data/raw/
*.csv
*.parquet
*.h5

# Model files (too large for Git)
models/*.pkl
models/*.joblib
models/*.onnx

# Environment variables
.env

# Jupyter
.ipynb_checkpoints/

# OS
.DS_Store
Thumbs.db

# Testing
.pytest_cache/
htmlcov/
.coverage

4.2 Fichier README.md

Creez un fichier README.md a la racine :

# ML Deployment Project

A complete machine learning deployment pipeline — from model training to production API.

## Quick Start

```bash
# Clone the repository
git clone <repo-url>
cd ml-deployment-project

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/ -v

# Start the API server
uvicorn app.main:app --reload

Project Structure

ml-deployment-project/
├── app/            # FastAPI application
├── models/         # Serialized ML models
├── data/           # Datasets (raw + processed)
├── tests/          # Unit and integration tests
├── scripts/        # Training and utility scripts
├── notebooks/      # Jupyter notebooks for exploration
└── docs/           # Project documentation

Technology Stack

• ML: scikit-learn, pandas, NumPy
• API: FastAPI, uvicorn
• Testing: pytest, httpx
• Explainability: SHAP, LIME

### 4.3 Fichier pyproject.toml

Creez un fichier `pyproject.toml` a la racine :

```toml
[project]
name = "ml-deployment-project"
version = "0.1.0"
description = "ML model deployment with FastAPI"
requires-python = ">=3.10"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = "-v --tb=short"

[tool.ruff]
line-length = 88
target-version = "py311"

---

Etape 5 : Rediger le cahier des charges

5.1 Creer le document

Creez le fichier docs/project_brief.md avec le contenu suivant. Adaptez-le a votre projet — ce modele est pour un modele de prediction de desabonnement client.

# Cahier des charges — Service de prediction du desabonnement client

## 1. Enonce du probleme

Predire si un client va annuler son abonnement dans les 30 prochains jours,
en se basant sur ses habitudes d'utilisation et les informations de son compte.

## 2. Utilisateurs finaux

- **Primaire** : Equipe de succes client (via tableau de bord web)
- **Secondaire** : Equipe marketing (rapports par lots)

## 3. Exigences en donnees

| Feature | Type | Source |
|---------|------|--------|
| tenure_months | int | Base de donnees CRM |
| monthly_charges | float | Systeme de facturation |
| total_charges | float | Systeme de facturation |
| contract_type | categoriel | Base de donnees CRM |
| internet_service | categoriel | BD Services |
| tech_support_calls | int | Tickets de support |

## 4. Exigences du modele

| Metrique | Cible |
|----------|-------|
| AUC-ROC | > 0.85 |
| Precision | > 0.80 |
| Rappel | > 0.70 |
| Latence d'inference | < 200ms |

## 5. Entree / Sortie

**Entree (requete API) :**
```json
{
  "tenure_months": 24,
  "monthly_charges": 65.5,
  "total_charges": 1572.0,
  "contract_type": "month-to-month",
  "internet_service": "fiber_optic",
  "tech_support_calls": 3
}

Sortie (reponse API) :

{
  "churn_probability": 0.73,
  "risk_level": "high",
  "model_version": "1.0.0"
}

6. Perimetre

Dans le perimetre

• Modele de classification binaire (desabonnement / pas de desabonnement)
• API REST avec FastAPI
• Tests unitaires avec pytest
• Explicabilite du modele (SHAP)
• Documentation de l'API (Swagger)

Hors perimetre

• Predictions en streaming temps reel
• Application mobile
• Architecture multi-tenant
• Inference GPU

7. Calendrier

Semaine	Livrable
1-2	Configuration de l'environnement + cahier des charges
3-5	Entrainement + evaluation du modele
6-8	Developpement de l'API + documentation
9-10	Tests + explicabilite
11-15	Integration + projet final

:::tip[Personnalisez votre cahier des charges]
Vous pouvez choisir un autre probleme ML si vous preferez :
- **Detection de spam** (classification de texte)
- **Prediction du prix des maisons** (regression)
- **Classification d'images** (si vous etes a l'aise avec le deep learning)

L'important est de documenter clairement les entrees, sorties, metriques et le perimetre.
:::

---

## Etape 6 : Script de verification

### 6.1 Creer le script de test

Creez le fichier `scripts/verify_setup.py` :

```python
"""
Verification script for ML Deployment Project setup.
Run this script to confirm your environment is correctly configured.
"""

import sys


def check_python_version():
    version = sys.version_info
    assert version.major == 3 and version.minor >= 10, (
        f"Python 3.10+ required, got {version.major}.{version.minor}"
    )
    print(f"  Python {version.major}.{version.minor}.{version.micro}")


def check_import(module_name, display_name=None):
    display = display_name or module_name
    try:
        mod = __import__(module_name)
        version = getattr(mod, "__version__", "unknown")
        print(f"  {display} {version}")
        return True
    except ImportError:
        print(f"  {display} — NOT INSTALLED")
        return False


def check_project_structure():
    from pathlib import Path

    required_dirs = ["app", "models", "data", "tests", "scripts", "docs"]
    required_files = [
        "requirements.txt",
        "app/__init__.py",
        "tests/__init__.py",
    ]

    project_root = Path(__file__).parent.parent
    missing = []

    for d in required_dirs:
        if not (project_root / d).is_dir():
            missing.append(f"Directory: {d}/")

    for f in required_files:
        if not (project_root / f).is_file():
            missing.append(f"File: {f}")

    if missing:
        print("  MISSING:")
        for m in missing:
            print(f"    - {m}")
        return False

    print(f"  All {len(required_dirs)} directories present")
    print(f"  All {len(required_files)} required files present")
    return True


def main():
    print("=" * 50)
    print("ML Deployment Project — Setup Verification")
    print("=" * 50)
    all_ok = True

    print("\n[1/3] Python Version")
    try:
        check_python_version()
    except AssertionError as e:
        print(f"  FAIL: {e}")
        all_ok = False

    print("\n[2/3] Package Imports")
    packages = [
        ("sklearn", "scikit-learn"),
        ("pandas", None),
        ("numpy", None),
        ("fastapi", None),
        ("uvicorn", None),
        ("pydantic", None),
        ("pytest", None),
        ("httpx", None),
        ("joblib", None),
    ]

    for module_name, display_name in packages:
        if not check_import(module_name, display_name):
            all_ok = False

    # SHAP and LIME are optional (may fail on some systems)
    print("\n  Optional packages:")
    check_import("shap")
    check_import("lime")

    print("\n[3/3] Project Structure")
    if not check_project_structure():
        all_ok = False

    print("\n" + "=" * 50)
    if all_ok:
        print("ALL CHECKS PASSED — Your environment is ready!")
    else:
        print("SOME CHECKS FAILED — Review the errors above.")
    print("=" * 50)

    return 0 if all_ok else 1


if __name__ == "__main__":
    sys.exit(main())

6.2 Executer la verification

python scripts/verify_setup.py

Verification — Sortie attendue

==================================================
ML Deployment Project — Setup Verification
==================================================

[1/3] Python Version
  Python 3.11.5

[2/3] Package Imports
  scikit-learn 1.4.2
  pandas 2.2.0
  numpy 1.26.4
  fastapi 0.109.0
  uvicorn 0.27.0
  pydantic 2.5.3
  pytest 8.0.0
  httpx 0.26.0
  joblib 1.3.2

  Optional packages:
  shap 0.44.1
  lime 0.2.0.1

[3/3] Project Structure
  All 6 directories present
  All 3 required files present

==================================================
ALL CHECKS PASSED — Your environment is ready!
==================================================

---

Etape 7 : Creer un premier test

7.1 Ecrire un test unitaire

Creez le fichier tests/test_setup.py :

"""Basic tests to verify the project environment."""

import importlib


def test_python_version():
    import sys
    assert sys.version_info >= (3, 10), "Python 3.10+ required"


def test_sklearn_import():
    sklearn = importlib.import_module("sklearn")
    assert hasattr(sklearn, "__version__")


def test_fastapi_import():
    fastapi = importlib.import_module("fastapi")
    assert hasattr(fastapi, "FastAPI")


def test_pandas_import():
    pd = importlib.import_module("pandas")
    assert hasattr(pd, "DataFrame")


def test_project_structure():
    from pathlib import Path

    root = Path(__file__).parent.parent
    assert (root / "app").is_dir()
    assert (root / "models").is_dir()
    assert (root / "tests").is_dir()
    assert (root / "requirements.txt").is_file()

7.2 Executer les tests

pytest tests/test_setup.py -v

Verification — Sortie attendue

========================= test session starts =========================
collected 5 items

tests/test_setup.py::test_python_version PASSED          [ 20%]
tests/test_setup.py::test_sklearn_import PASSED           [ 40%]
tests/test_setup.py::test_fastapi_import PASSED           [ 60%]
tests/test_setup.py::test_pandas_import PASSED            [ 80%]
tests/test_setup.py::test_project_structure PASSED        [100%]

========================= 5 passed in 0.42s =========================

Tous les tests doivent passer (5/5). Si un test echoue, verifiez que le paquet correspondant est installe.

---

Etape 8 : Initialiser Git

8.1 Initialiser le depot

git init
git add .
git commit -m "Initial project setup: structure, dependencies, and verification"

8.2 Verifier le statut

git status
git log --oneline

Verification — Ce que Git devrait ignorer

Verifiez que .gitignore fonctionne correctement :

git status

Vous ne devriez PAS voir :

• .venv/ (environnement virtuel)
• __pycache__/ (fichiers compiles)
• data/raw/ (donnees brutes)

Si ces fichiers apparaissent, verifiez votre .gitignore.

---

Resume du lab

Ce que vous avez accompli

Etape	Description	Statut
1	Structure du projet creee	☐
2	Environnement virtuel configure	☐
3	Dependances installees	☐
4	Fichiers de configuration crees (.gitignore, README, pyproject.toml)	☐
5	Cahier des charges redige	☐
6	Script de verification execute avec succes	☐
7	Premier test unitaire ecrit et reussi	☐
8	Depot Git initialise	☐

Structure finale du projet

ml-deployment-project/
├── app/
│   └── __init__.py
├── models/
├── data/
│   ├── raw/
│   └── processed/
├── tests/
│   ├── __init__.py
│   └── test_setup.py
├── scripts/
│   └── verify_setup.py
├── notebooks/
├── docs/
│   └── project_brief.md
├── .gitignore
├── .venv/                  (pas dans Git)
├── pyproject.toml
├── README.md
└── requirements.txt

Commandes essentielles a retenir

Action	Commande
Activer l'environnement	source .venv/bin/activate ou .venv\Scripts\activate
Installer les dependances	pip install -r requirements.txt
Executer les tests	pytest tests/ -v
Verifier l'environnement	python scripts/verify_setup.py
Demarrer l'API (Module 3)	uvicorn app.main:app --reload

Prochain lab

Dans le Lab 2 (Module 2), vous entrainerez un modele de classification avec scikit-learn et le serialiserez pour le deploiement. La structure que vous venez de creer servira de fondation pour le reste du cours.