# CLAUDE.md — UQO-Chat (copie de travail)

La spécification d'origine (28 sections) est la référence produit ; ce fichier résume ce qui est implémenté, les écarts assumés et les règles à respecter en travaillant dans ce dépôt. Voir README.md pour le démarrage et le déploiement.

# Règles d'or (inchangées)

1. Aucun code étudiant/LLM ne s'exécute dans le processus API : toujours sandbox-runner (app/sandbox/client.py).
2. Un seul point d'entrée LLM : app/llm/openrouter.py → LLMClient.
3. Slugs de modèles = config (app/core/config.py, env). Vérifier https://openrouter.ai/models avant d'en changer (vérifiés 2026-09-05 : anthropic/claude-sonnet-4.6, openai/gpt-5.5, anthropic/claude-opus-4.6, openai/gpt-5.4-nano).
4. Chaque outil = app/tools/<nom>.py + app/tools/schemas/<nom>.json + test + carte frontend/src/components/tools/<nom>-card.tsx.
5. Streaming SSE partout (app/api/v1/chat.py), français dans l'UI/prompts, anglais dans le code.
6. Jamais de contenu de message dans les logs (app/core/logging.py masque content, text, email…).
7. Mobile-first (375 px) ; QA Playwright : python3 /tmp/uqo-qa/qa.py (captures 375/1440, détection d'overflow).

# État (v0.1.0, 2026-09-06)

• Backend FastAPI 3.12 : auth (lien magique ou code d'accès), conversations, chat SSE avec boucle agentique (8 itérations, outils en parallèle), 7 outils, RAG BM25 sur les sites de notes (rag/ingest.py lit le HTML généré dist/<cours>/seance/NN), quiz, fichiers (TTL), tableau de bord prof (analytics anonymisées, ingestion, réglages, annonces), coûts admin, purge/anonymisation horaire.
• Frontend React 18 + Vite + Tailwind : chat mobile/desktop, cartes d'outils, quiz interactif, panneau fichiers/sources, préférences, Loi 25 (consentement, suppression), PWA (précache ≈ 2 Mo).
• Sandbox : sandbox-runner/ (FastAPI) exécute python -I -B sous sandbox-exec (macOS) : réseau interdit, écriture confinée, rlimits, timeout, figures matplotlib capturées.
• Déploiement : mld (PM2 uqo-chat-api :8190 + uqo-chat-sandbox :8191 + uqo-chat-ngrok www.uqo-chat.app). Secrets dans M1M32:~/dispatch/apps/uqo-chat.json.

# Écarts assumés

SQLite au lieu de Postgres/pgvector (Postgres accepté via DATABASE_URL) ; cache/limiteur mémoire au lieu de Redis ; fichiers sur disque au lieu de MinIO ; BM25 au lieu d'embeddings (OpenRouter n'en propose pas ; EMBEDDINGS_BASE_URL optionnel) ; create_all au lieu d'Alembic ; code d'accès en plus du lien magique (pas de SMTP). k8s/ + docker-compose.yml décrivent la cible complète de la spec.

# À faire (roadmap spec)

Export PDF de conversation ; file d'attente hors-ligne (Background Sync) ; évaluation pédagogique automatique en CI (40 questions/cours, juge MODEL_FAST) ; tests adverses sandbox complets ; Alembic ; migration éventuelle Postgres/pgvector ; autorisation du logo officiel UQO (VITE_USE_OFFICIAL_LOGO).