Initialize repository and commit S1_skeleton changes

s1_skeleton/.env.example

@@ -0,0 +1,30 @@
+# ──────────────────────────────────────────────────────────────────
+# Configuration de l'agent — copier en .env et adapter les valeurs
+# NE JAMAIS committer le fichier .env (il est dans .gitignore)
+# ──────────────────────────────────────────────────────────────────
+
+# ── LLM (Séance 1 : Ollama local) ─────────────────────────────────
+LLM_BASE_URL=http://localhost:11434/v1
+MODEL_NAME=llama3.1:8b
+
+# Séance 3 : routing multi-modèle (laisser vide pour S1)
+# MODEL_LIGHT=gemma3:4b
+# MODEL_HEAVY=qwen2.5:72b
+# LLM_PROVIDER=ollama   # ollama | vllm | litellm
+
+# ── Mémoire (Séance 2 : Redis) ─────────────────────────────────────
+# REDIS_URL=redis://localhost:6379
+# Laisser vide en S1 → MemorySaver (en mémoire, perdu au restart)
+
+# ── Base vectorielle (Séance 2 : Qdrant) ──────────────────────────
+# QDRANT_URL=http://localhost:6333
+# QDRANT_COLLECTION=formation-docs
+
+# ── API ────────────────────────────────────────────────────────────
+API_HOST=0.0.0.0
+API_PORT=8000
+LOG_LEVEL=INFO
+
+# ── Agent ──────────────────────────────────────────────────────────
+AGENT_MAX_ITERATIONS=20
+AGENT_MAX_TOKENS=4096

s1_skeleton/.gitignore

@@ -0,0 +1,36 @@
+# Environnement Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+
+# Variables d'environnement — NE JAMAIS committer
+.env
+
+# Mypy
+.mypy_cache/
+*.pyi
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+reports/
+
+# IDE
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.log

s1_skeleton/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - langgraph
+          - langchain-core
+          - pydantic
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: no-commit-to-branch
+        args: [--branch, main]

s1_skeleton/README.md

@@ -0,0 +1,145 @@
+# Agent Catalogue — Séance 1 · Squelette TP
+
+> Formation Agents IA · LangGraph · Projet fil rouge
+
+---
+
+## Objectif
+
+Implémenter un agent ReAct capable de répondre à des questions sur
+un catalogue produit, en utilisant des outils LangGraph.
+
+Les tests vous disent si votre implémentation est correcte.
+Le formateur a la correction en cas de blocage.
+
+---
+
+## Installation (5 min)
+
+```bash
+# 1. Installer les dépendances
+uv sync --extra dev
+
+# 2. Copier la configuration
+cp .env.example .env
+# Vérifier que MODEL_NAME correspond au modèle téléchargé
+
+# 3. Démarrer Ollama
+ollama serve &
+
+# 4. Vérifier qu'Ollama répond
+curl http://localhost:11434/v1/models
+```
+
+---
+
+## Ce que vous devez implémenter
+
+### Étape 1 — `src/tools/catalogue.py`
+
+4 fonctions marquées `TODO` (dans l'ordre recommandé) :
+
+| Fonction | Difficulté | Tests |
+|---|---|---|
+| `search_product()` | ⭐ | `TestSearchProduct` (5 tests) |
+| `calculate_price()` | ⭐⭐ | `TestCalculatePrice` (7 tests) |
+| `list_products()` | ⭐⭐ | `TestListProducts` (6 tests) |
+| `check_stock()` | ⭐ bonus | `TestCheckStock` (5 tests) |
+
+### Étape 2 — `src/models/provider.py`
+
+1 fonction `get_llm()` : lire les variables d'env et retourner un `ChatOpenAI`.
+
+### Étape 3 — `src/agents/react_agent.py`
+
+3 fonctions dans l'ordre :
+
+| Fonction | Ce qu'elle fait |
+|---|---|
+| `should_continue()` | Décide si l'agent utilise un outil ou s'arrête |
+| `agent_node()` | Appelle le LLM et retourne sa décision |
+| `build_agent()` | Assemble le graphe (noeuds + edges + compilation) |
+
+---
+
+## Lancer les tests
+
+```bash
+# Tous les tests unitaires (Ollama non requis)
+uv run pytest tests/unit/ -v
+
+# Un module à la fois
+uv run pytest tests/unit/test_tools.py -v
+uv run pytest tests/unit/test_agent.py -v
+
+# Un test précis
+uv run pytest tests/unit/test_tools.py::TestSearchProduct::test_found_by_partial_name -v
+```
+
+---
+
+## Tester l'agent manuellement
+
+```bash
+# Mode interactif (une fois react_agent.py implémenté)
+uv run python main.py
+
+# Question directe
+uv run python main.py --ask "Quel est le prix d'une souris ?"
+
+# Avec traces des outils appelés
+uv run python main.py --verbose
+
+# Visualiser le graphe LangGraph
+uv run python main.py --visualize
+```
+
+**Questions de test suggérées :**
+```
+Quel est le prix d'un laptop pro ?
+Je veux 3 souris avec une remise de 15%, combien ça coûte ?
+Quels produits audio avez-vous ?
+Puis-je commander 10 écrans 4K ?
+Avez-vous des produits en rupture de stock ?
+```
+
+---
+
+## Vérification qualité
+
+```bash
+# Linting
+uv run ruff check src/
+
+# Typage strict
+uv run mypy src/
+```
+
+---
+
+## Progression attendue
+
+```
+⬜ Étape 1a : search_product() → TestSearchProduct passe (5 tests)
+⬜ Étape 1b : calculate_price() → TestCalculatePrice passe (7 tests)
+⬜ Étape 1c : list_products() → TestListProducts passe (6 tests)
+⬜ Étape 2  : get_llm() → provider.py implémenté
+⬜ Étape 3a : should_continue() → TestShouldContinue passe (4 tests)
+⬜ Étape 3b : agent_node() → TestAgentNode passe (4 tests)
+⬜ Étape 3c : build_agent() → TestBuildAgent passe (3 tests)
+⬜ Bonus     : check_stock() → TestCheckStock passe (5 tests)
+⬜ Livrable  : premier commit poussé sur Git
+```
+
+---
+
+## Fichiers fournis (ne pas modifier)
+
+| Fichier | Rôle |
+|---|---|
+| `src/tools/catalogue.py` | `CATALOGUE` dict + squelettes |
+| `tests/unit/test_tools.py` | Spécification des outils |
+| `tests/unit/test_agent.py` | Spécification du graphe |
+| `main.py` | CLI interactif complet |
+| `pyproject.toml` | Dépendances + config |
+| `.env.example` | Variables d'environnement |

s1_skeleton/docs/graphs/agent_react.md

@@ -0,0 +1,26 @@
+# Graphe Agent ReAct
+
+```mermaid
+---
+---
+config:
+  flowchart:
+    curve: linear
+---
+graph TD;
+        __start__([<p>__start__</p>]):::first
+        agent(agent)
+        tools(tools)
+        __end__([<p>__end__</p>]):::last
+        __start__ --> agent;
+        agent -. &nbsp;end&nbsp; .-> __end__;
+        agent -.-> tools;
+        tools --> agent;
+        classDef default fill:#f2f0ff,line-height:1.2
+        classDef first fill-opacity:0
+        classDef last fill:#bfb6fc
+
+
+✅ Sauvegardé dans docs\graphs\agent_react.md
+   → Visualiser sur https://mermaid.live
+```

s1_skeleton/main.py

@@ -0,0 +1,148 @@
+"""Point d'entrée principal — CLI interactif et visualisation du graphe.
+
+Ce fichier est FOURNI COMPLET — ce n'est pas un exercice.
+Il fonctionnera dès que react_agent.py sera implémenté.
+
+Usage :
+    uv run python main.py                          # mode interactif
+    uv run python main.py --verbose                # avec traces des outils
+    uv run python main.py --ask "Prix d'un laptop ?"
+    uv run python main.py --visualize              # diagramme Mermaid
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+import uuid
+from pathlib import Path
+
+from dotenv import load_dotenv
+from langchain_core.messages import HumanMessage
+
+load_dotenv()
+
+
+async def chat(question: str, thread_id: str, verbose: bool = False) -> str:
+    """Envoie une question à l'agent et retourne la réponse finale."""
+    # Import ici pour éviter l'import au démarrage si --visualize
+    from src.agents.react_agent import agent
+
+    config = {"configurable": {"thread_id": thread_id}}
+    initial_state = {"messages": [HumanMessage(content=question)], "iterations": 0}
+
+    if verbose:
+        step_num = 0
+        async for event in agent.astream_events(initial_state, config=config, version="v2"):
+            kind = event.get("event", "")
+            if kind == "on_tool_start":
+                step_num += 1
+                print(f"\n  🔧 [{step_num}] {event.get('name', '?')} "
+                      f"← {event.get('data', {}).get('input', {})}")
+            elif kind == "on_tool_end":
+                out = str(event.get("data", {}).get("output", ""))
+                print(f"       → {out[:100]}{'...' if len(out) > 100 else ''}")
+
+        final = await agent.aget_state(config)
+        msgs = final.values.get("messages", [])
+        return str(msgs[-1].content) if msgs else "(aucune réponse)"
+    else:
+        result = await agent.ainvoke(initial_state, config=config)
+        msgs = result.get("messages", [])
+        return str(msgs[-1].content) if msgs else "(aucune réponse)"
+
+
+async def interactive_loop(verbose: bool = False) -> None:
+    """Boucle interactive. Commandes : exit | reset | verbose"""
+    thread_id = f"session-{uuid.uuid4().hex[:8]}"
+    show_verbose = verbose
+
+    print(f"\n{'═'*55}")
+    print("  Agent Catalogue — Formation Agents IA S1")
+    print(f"{'═'*55}")
+    print(f"  Modèle  : {os.getenv('MODEL_NAME', 'llama3.1:8b')}")
+    print(f"  Session : {thread_id}")
+    print(f"  Aide    : exit | reset | verbose")
+    print(f"{'═'*55}\n")
+
+    while True:
+        try:
+            question = input("Vous : ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nAu revoir !")
+            break
+
+        if not question:
+            continue
+        if question.lower() in ("exit", "quit", "q"):
+            print("Au revoir !")
+            break
+        if question.lower() == "reset":
+            thread_id = f"session-{uuid.uuid4().hex[:8]}"
+            print(f"Nouvelle session : {thread_id}\n")
+            continue
+        if question.lower() == "verbose":
+            show_verbose = not show_verbose
+            print(f"Verbose {'activé' if show_verbose else 'désactivé'}\n")
+            continue
+
+        print("\nAgent : ", end="", flush=True)
+        try:
+            response = await chat(question, thread_id, verbose=show_verbose)
+            print(response)
+        except NotImplementedError as e:
+            print(f"\n[TODO] {e}")
+            print("→ Implémentez les fonctions marquées TODO dans src/")
+        except Exception as e:
+            print(f"\n[Erreur] {e}")
+            print("→ Vérifiez qu'Ollama tourne : ollama serve")
+        print()
+
+
+async def ask_once(question: str, verbose: bool = False) -> None:
+    """Pose une question unique."""
+    thread_id = f"cli-{uuid.uuid4().hex[:8]}"
+    print(f"\nQuestion : {question}\n{'─'*50}")
+    try:
+        response = await chat(question, thread_id, verbose=verbose)
+        print(f"\n{response}\n")
+    except NotImplementedError as e:
+        print(f"\n[TODO] {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n[Erreur] {e}")
+        sys.exit(1)
+
+
+def visualize_graph() -> None:
+    """Génère le diagramme Mermaid et le sauvegarde dans docs/graphs/."""
+    from src.agents.react_agent import agent
+
+    mermaid = agent.get_graph().draw_mermaid()
+    print(f"\n{'═'*50}\n  Graphe LangGraph — Mermaid\n{'═'*50}")
+    print(mermaid)
+
+    path = Path("docs/graphs/agent_react.md")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(f"# Graphe Agent ReAct\n\n```mermaid\n{mermaid}```\n", encoding="utf-8")
+    print(f"\n✅ Sauvegardé dans {path}")
+    print("   → Visualiser sur https://mermaid.live\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Agent Catalogue — S1")
+    parser.add_argument("--visualize", action="store_true")
+    parser.add_argument("--ask", type=str, metavar="QUESTION")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    if args.visualize:
+        visualize_graph()
+    elif args.ask:
+        asyncio.run(ask_once(args.ask, verbose=args.verbose))
+    else:
+        asyncio.run(interactive_loop(verbose=args.verbose))
+
+
+if __name__ == "__main__":
+    main()

s1_skeleton/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "agent-project"
+version = "0.1.0"
+description = "Formation Agents IA — Projet fil rouge LangGraph + MCP"
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=0.2.0",
+    "langchain-core>=0.3.0",
+    "langchain-openai>=0.2.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.9.0",
+    "python-dotenv>=1.0.0",
+    "redis>=5.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "mypy>=1.11.0",
+    "ruff>=0.6.0",
+    "pre-commit>=3.8.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+select = ["E", "F", "I", "N", "W", "UP", "ANN"]
+ignore = ["ANN101", "ANN102"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "unit: tests unitaires (rapides, sans dépendances externes)",
+    "integration: tests d'intégration (nécessitent Ollama + services)",
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*", "**/__init__.py"]

s1_skeleton/src/agents/react_agent.py

@@ -0,0 +1,193 @@
+"""Agent ReAct pour le catalogue produit — graphe LangGraph.
+
+SÉANCE 1 — TP : Implémenter les fonctions marquées TODO.
+
+Architecture cible :
+    ┌─────────┐   tool_calls    ┌───────┐
+    │  agent  │ ──────────────► │ tools │
+    │ (LLM)   │ ◄────────────── │       │
+    └─────────┘  tool results   └───────┘
+         │
+         │ no tool_calls  ou  iterations >= MAX
+         ▼
+       [END]
+
+Ordre recommandé :
+    1. Lire AgentState et SYSTEM_PROMPT — comprendre la structure
+    2. Implémenter should_continue()
+    3. Implémenter agent_node()
+    4. Compléter build_agent() en ajoutant noeuds et edges
+    5. Tester avec : uv run python main.py --ask "Prix d'un laptop ?"
+"""
+
+import operator
+import os
+from typing import Annotated, Sequence
+
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+)
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, StateGraph
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.prebuilt import ToolNode
+from typing_extensions import TypedDict
+
+from src.models.provider import get_llm
+from src.tools.catalogue import CATALOGUE_TOOLS
+
+
+# ── État du graphe (FOURNI — ne pas modifier) ─────────────────────────────────
+
+class AgentState(TypedDict):
+    """État partagé entre tous les noeuds du graphe.
+
+    Attributes:
+        messages: Historique de la conversation.
+                  operator.add → les nouveaux messages s'AJOUTENT à la liste.
+        iterations: Compteur d'itérations (protection anti-boucle).
+                    Pas d'Annotated → la valeur est REMPLACÉE à chaque update.
+    """
+    messages: Annotated[Sequence[BaseMessage], operator.add]
+    iterations: int
+
+
+# ── Prompt système (FOURNI — vous pouvez l'améliorer) ────────────────────────
+
+SYSTEM_PROMPT = """Tu es un assistant spécialisé dans la consultation du catalogue produit.
+
+Tu as accès aux outils suivants :
+- search_product    : rechercher un produit par nom ou mot-clé
+- calculate_price   : calculer le prix total avec remise optionnelle
+- list_products     : lister les produits par catégorie
+- check_stock       : vérifier la disponibilité d'un produit
+
+Règles :
+1. Utilise TOUJOURS un outil pour obtenir des informations sur les produits.
+2. Ne jamais inventer des prix, stocks ou descriptions.
+3. Réponds en français, de manière concise et professionnelle."""
+
+
+# ── TODO 1 — Implémenter should_continue ─────────────────────────────────────
+
+def should_continue(state: AgentState) -> str:
+    """Décide si l'agent doit utiliser des outils ou terminer.
+
+    Args:
+        state: État courant du graphe.
+
+    Returns:
+        "tools" si le dernier message contient des tool_calls,
+        END sinon (réponse finale ou limite d'itérations atteinte).
+    """
+    # TODO étape 1 : lire la limite depuis os.getenv("AGENT_MAX_ITERATIONS", "20")
+    #               retourner END si state["iterations"] >= limite
+    #
+    # TODO étape 2 : récupérer le dernier message de state["messages"]
+    #               si c'est un AIMessage avec des tool_calls → retourner "tools"
+    #               sinon → retourner END
+    #
+    # Indice : hasattr(last_message, "tool_calls") and last_message.tool_calls
+    max_iter = int(os.getenv('AGENT_MAX_ITERATIONS', '20'))
+    if state.get('iterations', 0) >= max_iter:
+        return "end" # stop : trop d'itér
+    last_message = state['messages'][-1]
+    if isinstance(last_message, AIMessage):
+        if hasattr(last_message, 'tool_calls') and last_message.tool_calls:
+            return 'tools' # le LLM veut utiliser un outil
+    return "end" # pas de tool_calls = réponse finale
+
+# ── TODO 2 — Implémenter agent_node ──────────────────────────────────────────
+
+def agent_node(state: AgentState) -> dict[str, object]:
+    """Noeud agent : appelle le LLM pour décider de l'action suivante.
+
+    Args:
+        state: État courant du graphe.
+
+    Returns:
+        Dictionnaire avec :
+          - "messages"   : liste contenant le nouveau message AI
+          - "iterations" : compteur incrémenté de 1
+    """
+    # TODO étape 1 : obtenir le LLM via get_llm() et le lier aux outils
+    #               avec llm.bind_tools(CATALOGUE_TOOLS)
+    #
+    # TODO étape 2 : construire la liste de messages à envoyer au LLM
+    #               = [SystemMessage(SYSTEM_PROMPT)] + list(state["messages"])
+    #
+    # TODO étape 3 : appeler llm_with_tools.invoke(messages)
+    #
+    # TODO étape 4 : retourner le dict avec messages et iterations + 1
+    #               Attention : state.get("iterations", 0) + 1
+
+    # Étape 1
+    llm = get_llm(task = "default")
+    llm_with_tools = llm.bind_tools(CATALOGUE_TOOLS)
+
+    # Étape 2
+    messages: list[BaseMessage] = [
+        SystemMessage(content=SYSTEM_PROMPT), # contexte et règles
+        * list(state['messages']), # historique complet
+]
+
+    # Étape 3
+    ai_message = llm_with_tools.invoke(messages)
+
+    # Étape 4
+    return {
+        "messages": [ai_message],
+        "iterations": state.get("iterations", 0) + 1,
+    }
+
+# ── TODO 3 — Compléter build_agent ───────────────────────────────────────────
+
+def build_agent(use_memory: bool = True) -> CompiledStateGraph:
+    """Construit et compile le graphe LangGraph.
+
+    Args:
+        use_memory: Si True, utilise MemorySaver (persistance en RAM).
+
+    Returns:
+        Graphe compilé prêt à être invoqué.
+    """
+    graph: StateGraph = StateGraph(AgentState)
+
+    # TODO étape 1 : ajouter le noeud "agent" avec agent_node
+    #               graph.add_node("agent", agent_node)
+    graph.add_node("agent", agent_node)
+
+    # TODO étape 2 : ajouter le noeud "tools" avec ToolNode(CATALOGUE_TOOLS)
+    #               graph.add_node("tools", ToolNode(CATALOGUE_TOOLS))
+    graph.add_node("tools", ToolNode(CATALOGUE_TOOLS))
+
+    # TODO étape 3 : définir le point d'entrée
+    #               graph.set_entry_point("agent")
+    graph.set_entry_point("agent")
+    # TODO étape 4 : ajouter l'edge conditionnel depuis "agent"
+    #               graph.add_conditional_edges("agent", should_continue, {...})
+    graph.add_conditional_edges(
+        "agent",
+        should_continue,
+        {
+            "tools": "tools",
+            "end": END,
+        },
+    )
+    # TODO étape 5 : ajouter l'edge de retour "tools" → "agent"
+    #               graph.add_edge("tools", "agent")
+    graph.add_edge("tools", "agent")
+    # TODO étape 6 : compiler avec ou sans checkpointer selon use_memory
+    if use_memory:
+        checkpointer = MemorySaver()
+        return graph.compile(checkpointer=checkpointer)
+    else:
+        return graph.compile()
+
+
+# ── Instance globale (décommentez quand build_agent() est implémenté) ─────────
+
+agent: CompiledStateGraph = build_agent(use_memory=True)

s1_skeleton/src/models/provider.py

@@ -0,0 +1,51 @@
+"""Abstraction du fournisseur LLM.
+
+SÉANCE 1 — TP : Implémenter get_llm().
+
+Objectif : cette fonction doit retourner un LLM configuré depuis les
+variables d'environnement, sans que le reste du code connaisse le
+fournisseur (Ollama, vLLM, LiteLLM...).
+
+En séance 3, le routing multi-modèle sera ajouté ici.
+"""
+
+import os
+
+from langchain_core.language_models import BaseChatModel
+from langchain_openai import ChatOpenAI
+from openai import base_url
+
+
+def get_llm(task: str = "default") -> BaseChatModel:
+    """Retourne un LLM configuré depuis les variables d'environnement.
+
+    Variables d'environnement :
+        LLM_BASE_URL : URL de base de l'API.  Ex : http://localhost:11434/v1
+        MODEL_NAME   : Nom du modèle.          Ex : llama3.1:8b
+
+    Args:
+        task: Type de tâche (ignoré en S1, utilisé en S3 pour le routing).
+              Valeurs possibles : "default", "reasoning", "classification".
+
+    Returns:
+        Instance BaseChatModel configurée et prête à l'emploi.
+
+    Example:
+        >>> llm = get_llm()
+        >>> response = llm.invoke([HumanMessage("Bonjour")])
+    """
+    # TODO : lire LLM_BASE_URL et MODEL_NAME depuis os.getenv()
+    #        avec des valeurs par défaut raisonnables
+    # TODO : instancier et retourner un ChatOpenAI avec ces paramètres
+    # Indice : api_key="local" (ignoré par Ollama mais requis par l'interface)
+    #          temperature=0 (déterministe, meilleur pour les agents)
+    base_url: str = os.getenv('LLM_BASE_URL', 'http://localhost:11434/v1')
+    model_name: str = os.getenv('MODEL_NAME', 'llama3.1:8b')
+
+    return ChatOpenAI(
+        base_url=base_url,
+        model=model_name,
+        api_key='local', # ignoré par Ollama mais requis
+        temperature=0, # 0 = déterministe, essentiel pour les agents
+        timeout=120,
+    )

s1_skeleton/src/tools/catalogue.py

@@ -0,0 +1,247 @@
+"""Outils de consultation du catalogue produit.
+
+SÉANCE 1 — TP : Implémenter les 4 outils ci-dessous.
+
+Chaque outil est décoré avec @tool.
+La docstring est lue par le LLM pour décider quand et comment l'utiliser :
+  - soyez précis dans la description
+  - documentez bien les arguments
+  - indiquez ce que retourne la fonction
+
+En séance 2, ces outils seront remplacés par des appels MCP.
+"""
+
+from langchain_core.tools import tool
+
+# ── Catalogue produit (FOURNI — ne pas modifier) ──────────────────────────────
+
+CATALOGUE: dict[str, dict[str, object]] = {
+    "laptop-pro-15": {
+        "name": "Laptop Pro 15",
+        "price": 1299.0,
+        "stock": 5,
+        "category": "informatique",
+        "description": "Laptop haute performance, écran 15 pouces, 32 GB RAM, SSD 1 TB.",
+    },
+    "souris-ergonomique": {
+        "name": "Souris Ergonomique",
+        "price": 49.90,
+        "stock": 23,
+        "category": "accessoires",
+        "description": "Souris verticale ergonomique, sans fil, autonomie 6 mois.",
+    },
+    "clavier-mecanique": {
+        "name": "Clavier Mécanique",
+        "price": 129.0,
+        "stock": 12,
+        "category": "accessoires",
+        "description": "Clavier mécanique Cherry MX Red, rétroéclairé, AZERTY.",
+    },
+    "ecran-4k-27": {
+        "name": 'Écran 4K 27"',
+        "price": 549.0,
+        "stock": 3,
+        "category": "informatique",
+        "description": "Écran 4K UHD 27 pouces, 144 Hz, temps de réponse 1 ms.",
+    },
+    "casque-audio-pro": {
+        "name": "Casque Audio Pro",
+        "price": 199.0,
+        "stock": 8,
+        "category": "audio",
+        "description": "Casque circum-aural, réduction de bruit active, autonomie 30 h.",
+    },
+    "webcam-4k": {
+        "name": "Webcam 4K",
+        "price": 89.0,
+        "stock": 15,
+        "category": "accessoires",
+        "description": "Webcam 4K 30fps, autofocus, micro stéréo intégré.",
+    },
+    "hub-usb-c": {
+        "name": "Hub USB-C 7 ports",
+        "price": 59.90,
+        "stock": 30,
+        "category": "accessoires",
+        "description": "Hub USB-C 7 en 1 : HDMI 4K, USB-A ×3, SD, microSD, USB-C PD.",
+    },
+    "enceinte-bluetooth": {
+        "name": "Enceinte Bluetooth",
+        "price": 79.0,
+        "stock": 0,
+        "category": "audio",
+        "description": "Enceinte portative 20W, waterproof IPX5, autonomie 12 h.",
+    },
+}
+
+
+# ── TODO 1 — Implémenter search_product ───────────────────────────────────────
+
+@tool
+def search_product(name: str) -> str:
+    """Recherche un ou plusieurs produits dans le catalogue par nom ou mot-clé.
+
+    Args:
+        name: Terme de recherche partiel ou complet pour le nom du produit.
+
+    Returns:
+        Une description lisible des produits correspondants si trouvés,
+        ou un message clair indiquant qu'aucun produit ne correspond.
+    """
+    name_lower = name.strip().lower()
+    results: list[dict[str, object]] = []
+
+    for product_id, product in CATALOGUE.items():
+        product_name = str(product["name"]).lower()
+        description = str(product["description"]).lower()
+
+        if name_lower in product_id or name_lower in product_name or name_lower in description:
+            results.append(product)
+
+    if not results:
+        return f"Aucun produit trouvé pour '{name}'."
+
+    lines: list[str] = []
+    for product in results:
+        stock = int(product.get("stock", 0))
+        stock_info = f"{stock} en stock" if stock > 0 else "RUPTURE"
+        lines.append(f"- {product['name']} : {float(product['price']):.2f}€ ({stock_info})")
+    return f"Produits trouvés ({len(results)}) :\n" + "\n".join(lines)
+
+# ── TODO 2 — Implémenter calculate_price ──────────────────────────────────────
+
+@tool
+def calculate_price(
+    product_name: str,
+    quantity: int,
+    discount_percent: float = 0.0,
+) -> str:
+    """Calcule le prix total pour une quantité donnée, avec remise optionnelle.
+
+    Args:
+        product_name: Nom complet ou partiel du produit.
+        quantity: Quantité souhaitée.
+        discount_percent: Remise en pourcentage (0 à 100).
+
+    Returns:
+        Un récapitulatif du calcul ou un message d'erreur.
+    """
+
+    if quantity <= 0:
+        return "La quantité doit être un entier positif."
+
+    if not (0.0 <= discount_percent <= 100.0):
+        return "La remise doit être comprise entre 0 et 100%."
+
+    search = product_name.strip().lower()
+    product = None
+
+    for product_id, p in CATALOGUE.items():
+        if search in str(p['name']).lower() or search in product_id:
+            product = p
+            break
+
+    if product is None:
+        return f"Produit '{product_name}' introuvable dans le catalogue."
+
+    stock = int(str(product['stock']))
+    if stock <= 0:
+        return f"RUPTURE DE STOCK : {product['name']}"
+
+    unit_price = float(str(product['price']))
+    subtotal = unit_price * quantity
+    total = subtotal * (1 - discount_percent / 100)
+
+    return (
+        f"Produit : {product['name']}\n"
+        f"Prix unitaire : {unit_price:.2f}€\n"
+        f"Quantité : {quantity}\n"
+        f"Sous-total : {subtotal:.2f}€\n"
+        f"Remise : {discount_percent:.1f}%\n"
+        f"Total : {total:.2f}€"
+    )
+
+
+# ── TODO 3 — Implémenter list_products ────────────────────────────────────────
+
+@tool
+def list_products(category: str | None = None) -> str:
+    """Liste les produits disponibles, avec filtre optionnel par catégorie.
+
+    Args:
+        category: Nom de la catégorie à filtrer (informatique, accessoires, audio).
+                  Si None, tous les produits sont retournés.
+
+    Returns:
+        Une liste lisible des produits correspondant au filtre, avec l'indication
+        du stock ou de la rupture de stock. Si la catégorie est inconnue,
+        retourne un message clair.
+    """
+    category_search = category.strip().lower() if category else None
+    results: list[str] = []
+
+    for product_id, product in CATALOGUE.items():
+        product_category = str(product.get("category", "")).lower()
+        if category_search is None or category_search == product_category:
+            stock = int(str(product.get("stock", 0)))
+            stock_info = "RUPTURE" if stock <= 0 else f"{stock} en stock"
+            results.append(
+                f"- {product['name']} : {product['price']:.2f}€ ({stock_info})"
+            )
+
+    if category_search is not None and not results:
+        return f"Catégorie inconnue ou aucun produit trouvé pour '{category}'."
+
+    header = "Produits disponibles"
+    if category_search is not None:
+        header += f" dans la catégorie '{category}'"
+    return header + ":\n" + "\n".join(results)
+
+
+# ── TODO 4 (exercice bonus) — Implémenter check_stock ─────────────────────────
+
+@tool
+def check_stock(product_name: str, required_quantity: int) -> str:
+    """Vérifie si le stock est suffisant pour une quantité demandée.
+
+    Args:
+        product_name: Nom complet ou partiel du produit.
+        required_quantity: Quantité demandée.
+
+    Returns:
+        Un message indiquant si la commande est possible, insuffisante,
+        rupture de stock, ou si le produit est introuvable.
+    """
+    if required_quantity <= 0:
+        return "La quantité requise doit être un entier positif."
+
+    search = product_name.strip().lower()
+    product = None
+
+    for product_id, p in CATALOGUE.items():
+        if search in str(p['name']).lower() or search in product_id:
+            product = p
+            break
+
+    if product is None:
+        return f"Produit '{product_name}' introuvable."
+
+    stock = int(str(product.get('stock', 0)))
+    if stock <= 0:
+        return f"RUPTURE DE STOCK : {product['name']}"
+
+    if stock >= required_quantity:
+        return f"Commande possible : {required_quantity} × {product['name']} (stock disponible : {stock}) ✅"
+
+    return f"Stock insuffisant pour {product['name']} : {stock} disponible(s), {required_quantity} demandé(s) ⚠"
+
+
+# ── Liste des outils (FOURNI — compléter au fur et à mesure) ──────────────────
+
+# Commencer avec search_product uniquement, ajouter les autres au fil du TP
+CATALOGUE_TOOLS = [
+    search_product,
+    calculate_price,
+    list_products,
+    check_stock,
+]

s1_skeleton/tests/unit/test_agent.py

@@ -0,0 +1,108 @@
+"""Tests unitaires du graphe LangGraph.
+
+Ces tests sont FOURNIS COMPLETS — ils servent de spécification.
+Ils doivent tous passer une fois react_agent.py implémenté.
+Le LLM est entièrement mocké : Ollama n'est pas nécessaire.
+
+Lancer : uv run pytest tests/unit/test_agent.py -v
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage
+
+from src.agents.react_agent import AgentState, agent_node, should_continue
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def make_state(messages: list, iterations: int = 0) -> AgentState:
+    return AgentState(messages=messages, iterations=iterations)
+
+def ai_with_tools() -> AIMessage:
+    return AIMessage(content="", tool_calls=[
+        {"name": "search_product", "args": {"name": "laptop"}, "id": "c1", "type": "tool_call"}
+    ])
+
+def ai_final(content: str = "Voici la réponse.") -> AIMessage:
+    return AIMessage(content=content)
+
+
+# ── Tests should_continue ─────────────────────────────────────────────────────
+
+class TestShouldContinue:
+
+    def test_returns_tools_when_tool_calls_present(self) -> None:
+        state = make_state([HumanMessage("test"), ai_with_tools()])
+        assert should_continue(state) == "tools"
+
+    def test_returns_end_when_no_tool_calls(self) -> None:
+        from langgraph.graph import END
+        state = make_state([HumanMessage("test"), ai_final()])
+        assert should_continue(state) == END
+
+    def test_returns_end_at_max_iterations(self) -> None:
+        from langgraph.graph import END
+        state = make_state([HumanMessage("test"), ai_with_tools()], iterations=20)
+        assert should_continue(state) == END
+
+    def test_continues_below_max_iterations(self) -> None:
+        state = make_state([HumanMessage("test"), ai_with_tools()], iterations=5)
+        assert should_continue(state) == "tools"
+
+
+# ── Tests agent_node ──────────────────────────────────────────────────────────
+
+class TestAgentNode:
+
+    def test_increments_iterations(self) -> None:
+        with patch("src.agents.react_agent.get_llm") as mock:
+            mock.return_value.bind_tools.return_value.invoke.return_value = ai_final()
+            result = agent_node(make_state([HumanMessage("test")], iterations=2))
+        assert result["iterations"] == 3
+
+    def test_appends_response_to_messages(self) -> None:
+        response = ai_final("Réponse test")
+        with patch("src.agents.react_agent.get_llm") as mock:
+            mock.return_value.bind_tools.return_value.invoke.return_value = response
+            result = agent_node(make_state([HumanMessage("test")]))
+        assert response in result["messages"]
+
+    def test_returns_messages_and_iterations_keys(self) -> None:
+        with patch("src.agents.react_agent.get_llm") as mock:
+            mock.return_value.bind_tools.return_value.invoke.return_value = ai_final()
+            result = agent_node(make_state([HumanMessage("test")]))
+        assert "messages" in result
+        assert "iterations" in result
+
+    def test_binds_tools_to_llm(self) -> None:
+        with patch("src.agents.react_agent.get_llm") as mock:
+            mock_llm = MagicMock()
+            mock_llm.bind_tools.return_value.invoke.return_value = ai_final()
+            mock.return_value = mock_llm
+            agent_node(make_state([HumanMessage("test")]))
+        mock_llm.bind_tools.assert_called_once()
+        assert len(mock_llm.bind_tools.call_args[0][0]) > 0
+
+
+# ── Tests build_agent ─────────────────────────────────────────────────────────
+
+class TestBuildAgent:
+
+    def test_graph_compiles(self) -> None:
+        from src.agents.react_agent import build_agent
+        assert build_agent(use_memory=False) is not None
+
+    def test_graph_has_agent_and_tools_nodes(self) -> None:
+        from src.agents.react_agent import build_agent
+        app = build_agent(use_memory=False)
+        ids = list(app.get_graph().nodes.keys())
+        assert "agent" in ids
+        assert "tools" in ids
+
+    def test_mermaid_is_generated(self) -> None:
+        from src.agents.react_agent import build_agent
+        mermaid = build_agent(use_memory=False).get_graph().draw_mermaid()
+        assert "agent" in mermaid
+        assert "tools" in mermaid

s1_skeleton/tests/unit/test_tools.py

@@ -0,0 +1,144 @@
+"""Tests unitaires des outils du catalogue.
+
+Ces tests sont FOURNIS COMPLETS — ils servent de spécification.
+Ils doivent tous passer une fois vos outils implémentés.
+
+Lancer : uv run pytest tests/unit/test_tools.py -v
+
+Progression recommandée :
+    1. Implémenter search_product → faire passer TestSearchProduct
+    2. Implémenter calculate_price → faire passer TestCalculatePrice
+    3. Implémenter list_products → faire passer TestListProducts
+    4. Implémenter check_stock (bonus) → faire passer TestCheckStock
+"""
+
+import pytest
+
+from src.tools.catalogue import (
+    calculate_price,
+    check_stock,
+    list_products,
+    search_product,
+)
+
+
+# ── search_product ────────────────────────────────────────────────────────────
+
+class TestSearchProduct:
+
+    def test_found_by_partial_name(self) -> None:
+        result = search_product.invoke({"name": "laptop"})
+        assert "Laptop Pro 15" in result
+        assert "1299" in result
+
+    def test_found_case_insensitive(self) -> None:
+        assert "Souris Ergonomique" in search_product.invoke({"name": "SOURIS"})
+        assert "Souris Ergonomique" in search_product.invoke({"name": "souris"})
+
+    def test_not_found_returns_message(self) -> None:
+        result = search_product.invoke({"name": "produit-xyz-inexistant"})
+        assert "Aucun produit" in result
+
+    def test_search_by_description_word(self) -> None:
+        result = search_product.invoke({"name": "ergonomique"})
+        assert "Souris Ergonomique" in result
+
+    def test_multiple_results(self) -> None:
+        # "casque" doit trouver au moins le casque audio
+        result = search_product.invoke({"name": "casque"})
+        assert "Casque Audio Pro" in result
+
+
+# ── calculate_price ───────────────────────────────────────────────────────────
+
+class TestCalculatePrice:
+
+    def test_price_no_discount(self) -> None:
+        result = calculate_price.invoke({"product_name": "souris", "quantity": 2})
+        assert "99.80" in result   # 2 × 49.90
+
+    def test_price_with_discount(self) -> None:
+        result = calculate_price.invoke({
+            "product_name": "souris", "quantity": 2, "discount_percent": 10.0
+        })
+        assert "89.82" in result   # 99.80 - 10%
+
+    def test_quantity_one(self) -> None:
+        result = calculate_price.invoke({"product_name": "clavier", "quantity": 1})
+        assert "129" in result
+
+    def test_invalid_quantity_zero(self) -> None:
+        result = calculate_price.invoke({"product_name": "souris", "quantity": 0})
+        assert "positif" in result.lower()
+
+    def test_invalid_discount_over_100(self) -> None:
+        result = calculate_price.invoke({
+            "product_name": "souris", "quantity": 1, "discount_percent": 150.0
+        })
+        assert "100" in result
+
+    def test_product_not_found(self) -> None:
+        result = calculate_price.invoke({"product_name": "inexistant", "quantity": 1})
+        assert "introuvable" in result.lower()
+
+    def test_out_of_stock_warning(self) -> None:
+        # enceinte-bluetooth est en stock=0
+        result = calculate_price.invoke({"product_name": "enceinte", "quantity": 1})
+        assert "rupture" in result.lower() or "RUPTURE" in result
+
+
+# ── list_products ─────────────────────────────────────────────────────────────
+
+class TestListProducts:
+
+    def test_list_all(self) -> None:
+        result = list_products.invoke({})
+        assert "Laptop Pro 15" in result
+        assert "Casque Audio Pro" in result
+
+    def test_filter_informatique(self) -> None:
+        result = list_products.invoke({"category": "informatique"})
+        assert "Laptop Pro 15" in result
+        assert "Souris" not in result
+
+    def test_filter_audio(self) -> None:
+        result = list_products.invoke({"category": "audio"})
+        assert "Casque Audio Pro" in result
+        assert "Laptop" not in result
+
+    def test_filter_case_insensitive(self) -> None:
+        assert "Casque" in list_products.invoke({"category": "AUDIO"})
+
+    def test_unknown_category(self) -> None:
+        result = list_products.invoke({"category": "meuble"})
+        assert "meuble" in result.lower()
+
+    def test_out_of_stock_shown(self) -> None:
+        result = list_products.invoke({})
+        assert "RUPTURE" in result   # enceinte-bluetooth stock=0
+
+
+# ── check_stock (bonus) ────────────────────────────────────────────────────────
+
+class TestCheckStock:
+
+    def test_sufficient_stock(self) -> None:
+        result = check_stock.invoke({"product_name": "souris", "required_quantity": 5})
+        assert "possible" in result.lower() or "✅" in result
+
+    def test_insufficient_stock(self) -> None:
+        # écran-4k a stock=3, on en demande 10
+        result = check_stock.invoke({"product_name": "ecran", "required_quantity": 10})
+        assert "insuffisant" in result.lower() or "⚠" in result
+
+    def test_out_of_stock(self) -> None:
+        result = check_stock.invoke({"product_name": "enceinte", "required_quantity": 1})
+        assert "RUPTURE" in result or "impossible" in result.lower()
+
+    def test_invalid_quantity(self) -> None:
+        result = check_stock.invoke({"product_name": "souris", "required_quantity": -1})
+        assert "positif" in result.lower()
+
+    def test_product_not_found(self) -> None:
+        result = check_stock.invoke({"product_name": "xyz", "required_quantity": 1})
+        assert "introuvable" in result.lower()