READMECONF.md

ChemLab Virtual (Virtual Labo Chimique)

Application web (Vite/React/TypeScript) de laboratoire de chimie virtuel: tu ajoutes des substances sur un plan de travail (canvas Fabric.js), tu observes le resultat et tu peux sauvegarder/exporter tes experiences. Les observations sont generees par IA via Groq (avec fallback automatique entre plusieurs modeles).

Fonctionnalites

• Page d'accueil + acces au labo (/ et /lab)
• Inventaire de substances (categorie, etat, niveau de danger, recherche)
• Plan de travail interactif (Fabric.js): ajout, deplacement, suppression, reset, plein ecran, export PNG/SVG, notes texte
• Gestion de workspaces: multi-experiences, favoris, renommage, import/export JSON, undo/redo (Ctrl+Z / Ctrl+Y)
• Observations: journal des resultats + export CSV
• Temperature: reglage utilise par l'IA pour contextualiser les resultats
• IA pedagogique: resultat d'experience + Cas d'usage: + suggestions de melanges a explorer (une seule reponse texte, contraintes de forme)

Stack technique

• Vite (serveur dev sur http://localhost:8080)
• React 18 + TypeScript
• TailwindCSS + shadcn-ui (Radix)
• Fabric.js (canvas)
• Groq API (OpenAI-compatible) pour l'IA

Demarrage (local)

Prerequis: Node.js (recommande: >= 18).

npm install
npm run dev

Scripts utiles:

• npm run dev: serveur de dev (Vite)
• npm run build: build de production
• npm run preview: preview du build
• npm run lint: lint ESLint

Configuration IA (Groq)

1. Copier .env.example vers .env
2. Renseigner GROQ_API_KEY
3. (Optionnel) definir GROQ_MODELS (liste ordonnee, separee par des virgules)

Variables:

• GROQ_API_KEY: cle Groq (ne pas committer)
• GROQ_MODELS: liste de modeles a tester dans l'ordre (fallback automatique)

Exemple:

GROQ_API_KEY=...
GROQ_MODELS=llama-3.3-70b-versatile,openai/gpt-oss-120b,openai/gpt-oss-20b,llama-3.1-8b-instant,openai/gpt-oss-safeguard-20b

Notes:

• La cle n'est jamais envoyee au navigateur: le front appelle POST /api/ai/mix, et le serveur Vite effectue l'appel Groq.
• Les modeles contenant safeguard sont automatiquement exclus de la generation (ils renvoient souvent des refus ou du reasoning sans contenu). Ils peuvent rester dans GROQ_MODELS sans bloquer la generation.

Endpoints (dev/preview)

Ces routes existent uniquement via le middleware Vite (pas en hebergement 100% statique):

• GET /api/ai/ping: verifie que le serveur voit la cle et affiche la liste des modeles utilises
• POST /api/ai/mix: genere une observation IA

En production statique, il faut fournir un backend equivalent (Cloudflare Workers, Netlify Functions, serveur Node, etc.) et router /api/ai/* vers ce backend.

Depannage (IA)

Si les observations IA ne se generent pas:

• Verifier GET /api/ai/ping (presence de la cle, liste des modeles utilises)
• Redemarrer le serveur apres changement de .env
• En cas de quota/rate limit, le fallback passe au modele suivant automatiquement (si GROQ_MODELS contient plusieurs modeles)

Structure du code (principaux fichiers)

• src/pages/Index.tsx: landing page
• src/pages/Lab.tsx: orchestration du labo (workspaces, temperature, observations, IA)
• src/components/lab/FabricLabCanvas.tsx: canvas + interactions + detection de melange
• src/data/substances.ts: catalogues de substances
• src/data/experimentTemplates.ts: templates d'experiences
• server/aiMixMiddleware.ts: proxy IA (Groq) + fallback multi-modeles

Stockage / sauvegarde

• Les workspaces sont sauvegardes dans localStorage (navigateur) et peuvent etre exportes/importes en JSON.

Limitations connues

• La “reaction” est une generation textuelle IA (pas un moteur de chimie deterministe).
• L'export video time-lapse depend du support navigateur (MediaRecorder) et reste experimental.