Brief de lancement — microservice d'embeddings (tlr-embeddings)

Destiné à l'instance qui codera le microservice Python d'embeddings. À utiliser comme message d'ouverture (ou à lire en premier) dans le dépôt du microservice. Nom de dépôt : tlr-embeddings (ex-telaria-embeddings, renommé en Batch 1 ; convention tlr-*). Statut : brief de coordination.

Rôle

Coder un microservice Python d'embeddings, composant du socle IA de Codexia. Dépôt Python autonome (aucun PHP ici), déployable séparément.

Docs de référence (lecture seule, dans telaria-doc)

• specs/ia-coeur.md — §3.3 (embeddings) et §4.1 (contrat HTTP = source de vérité).
• tutos/ia/microservice-embeddings-python.md — pas-à-pas + squelette FastAPI.
• specs/ia-vitrine.md §3 — décisions actées (ne pas re-débattre).

Décisions actées (ne pas re-litiger)

• Stack : FastAPI + sentence-transformers + uvicorn.
• Modèle : intfloat/multilingual-e5-base (multilingue FR, léger CPU).
• Endpoints :
  • GET /health → { "status":"ok", "model":…, "dim":768 }
  • POST /embed → req { "type":"query"|"passage", "texts":[…] } ; res { "model":…, "dim":768, "vectors":[[…]] }
• Préfixes e5 (query: / passage: ) gérés côté service selon type. normalize_embeddings=True (cosinus).
• Service stateless, bind 127.0.0.1 (pas d'exposition publique), modèle chargé une seule fois au démarrage.
• Déployable séparément (systemd). Versions figées (requirements.txt).

Périmètre V1 (uniquement)

Le microservice (/health, /embed) + tests + requirements.txt + README. Hors périmètre : le côté Symfony, l'index sqlite-vec (autres lots).

Contraintes

• VPS CPU-only : l'embedding d'une requête doit rester rapide ; l'indexation en batch est gérée par l'appelant.
• Le service est consommé en HTTP par le bundle « cœur RAG » Symfony → le contrat doit matcher ia-coeur.md §4.1 au caractère près.

Économie de quota

• Travailler en Sonnet (tout est déjà cadré par la spec/tuto) — ou sur une clé API dédiée. Itérations serrées, pas de sur-exploration.

Coordination

• Lecture seule sur telaria-doc.
• Question / évolution du contrat destinée à l'équipe doc → déposer une note dans …/.claude/projects/C--src-telaria-doc/memory/inbox-from-embeddings.md.

Première action

Lire les 3 docs ci-dessus, puis proposer l'arborescence du dépôt + app.py conforme au contrat §4.1, et valider avant d'aller plus loin.

Implémentation

Historique des décisions