Vitrine IA — cadre et architecture

Expression de besoin et cadrage de l'initiative « IA » de Codexia : exploiter la base documentaire par l'IA, l'interroger, et automatiser la veille. Statut : brouillon de cadrage (doc-design). Document vivant.

1. Contexte et objectif

Codexia est une vitrine de savoir-faire. Le sujet du moment étant l'IA, cette initiative vise à démontrer la maîtrise professionnelle de l'IA : non pas un produit marchand, mais la preuve qu'on sait concevoir, mettre en œuvre et encadrer des outils IA de bout en bout.

Besoin métier : faire de la documentation Markdown de Codexia une base de connaissance exploitée par l'IA, selon trois usages :

1. Interroger la doc via un standard agentique (MCP) — exposer la doc comme des outils utilisables par un client IA (Claude Desktop, Cursor…).
2. Un chatbot RAG — poser des questions en langage naturel sur la doc, réutilisable d'un projet à l'autre.
3. Une veille automatisée — agents planifiés qui suivent l'actualité (IA, dev web, qualité, juridique) et alimentent pilotage/veille/.

Cadre d'usage initial : démos réalisées par l'auteur lui-même, pas d'accès public au démarrage. La latence est donc justifiable en démo, et le volume de requêtes reste faible.

Hors périmètre (mis en pause) : recherche site / CRUD / fonctionnalités web « classiques ». Les fondations existantes (i18n, compte utilisateur) sont jugées suffisantes pour l'instant.

2. Principes directeurs

• Capitaliser l'existant : cette initiative consolide des specs déjà avancées plutôt que de repartir de zéro (voir §8).
• Un cœur, trois surfaces : une seule pile de connaissance réutilisée par les trois usages (pas trois piles séparées).
• KISS et pérennité : périmètre petit assumé ; un composant propre et sûr vaut mieux qu'une usine.
• Cohérence vitrine : Symfony-natif autant que possible (montrer qu'on construit, pas seulement qu'on câble du SaaS).
• Garde-fous IA de série : citations systématiques des sources, jamais de sortie présentée comme faisant autorité (surtout juridique). Voir §7.
• Accessibilité RGAA AA et conventions du dépôt (AGENTS.md) appliquées aux interfaces produites.
• Doc qui s'enrichit par la pratique : tout concept technique introduit ici doit être expliqué par ailleurs — tuto (pas-à-pas) ou fiche (synthèse) dédiée. La doc-design alimente la base de connaissance. Voir §11.

3. Décisions actées

• Génération LLM : Claude via API (qualité, on-brand pour la vitrine), avec prompt caching pour maîtriser le coût.
• Embeddings : locaux et multilingues — intfloat/multilingual-e5-base retenu pour le MVP (bon FR, léger sur CPU) ; BAAI/bge-m3 gardé en option « retrieval hybride dense + lexical » pour une démo plus poussée. Gratuit, indépendant d'un second fournisseur, calculés à l'indexation (hors-ligne).
• Retrieval léger : stockage vectoriel SQLite + sqlite-vec (ou équivalent embarqué). Pas d'OpenSearch / telaria-search (mis en pause).
• Stratégie « hybride » (embeddings locaux + génération API) retenue : meilleur compromis coût/qualité et meilleure démonstration (toute la pile RAG, pas seulement l'appel d'API).
• Exécution des embeddings : microservice Python (FastAPI + sentence-transformers), appelé en HTTP par Symfony. Choix assumé d'introduire Python à côté de PHP (montée en compétence et valeur CV, écosystème IA).
• Forme du code : bundle(s) Symfony réutilisable(s) — la réutilisabilité multi-projets est déjà une exigence (spec MCP multi-tenant) et le surcoût est faible si fait dès le départ. telaria reste l'application hôte/consommatrice.
• Topologie des dépôts : le microservice d'embeddings = dépôt Python distinct tlr-embeddings (déployable indépendamment) ; les composants Symfony (cœur RAG, serveur MCP tlr-mcp) sont des bundles dédiés, consommés par l'application telaria.
• Nommage : umbrella tlr-mcp (produit multi-tenant, mcp.telaria.dev), Codexia = tenant/consommateur.
• Ordre des lots : L0 (cœur) → L1 (MCP V1 lecture seule) confirmé.
• Premier livrable : ce document cadre, avant le détail de chaque surface.

Contrainte structurante : le VPS est CPU-only (6 vCPU, 12 Go RAM, pas de GPU — cf. pilotage/veille/). D'où le choix d'externaliser la génération et de garder le local pour l'indexation/retrieval.

4. Architecture cible : un cœur, trois surfaces

                         ┌───────────────────────────────────────┐
                         │            SURFACES (usages)            │
                         │                                         │
   Client agent  ───────▶│  1. MCP server      (outils sur la doc) │
   (Claude/Cursor)       │                                         │
   Navigateur    ───────▶│  2. Chatbot RAG     (Q/R web)           │
   (démo perso)          │                                         │
   Planificateur ───────▶│  3. Veille agentique (pipeline auto)    │
   (cron/scheduler)      └───────────────────┬─────────────────────┘
                                             │
                         ┌───────────────────▼─────────────────────┐
                         │                 CŒUR                     │
                         │  Ingestion .md → découpage (chunks)      │
                         │  → embeddings (local, multilingue)       │
                         │  → index vectoriel (sqlite-vec)          │
                         │  → service de récupération (retrieval)   │
                         │  → port LLM (génération via Claude)      │
                         └──────────────────────────────────────────┘

4.1 Le cœur (socle commun)

• Ingestion : parcours des .md (doc Codexia, et plus tard sources externes), découpage en chunks avec métadonnées (chemin, titre, section, date).
• Embeddings : vectorisation locale des chunks (batch, à l'indexation).
• Index : stockage vectoriel embarqué + recherche par similarité (k plus proches voisins), éventuellement hybride lexical + vectoriel.
• Retrieval : service qui, pour une requête, renvoie les passages pertinents + leurs sources.
• Port LLM : abstraction d'appel au modèle de génération (Claude), avec injection du contexte récupéré et prompt caching.

4.2 Surface 1 — MCP (différenciateur)

Expose la doc comme outils à un client agentique, via le standard MCP d'Anthropic.

• V1 lecture seule : search_docs, read_doc, list_docs (et plus tard validate_markdown, check_links, draft_*).
• Réutilise le retrieval du cœur.
• Valeur : interopérabilité agentique, doc actionnable, réutilisable multi-projets (specs déjà multi-tenant).

4.3 Surface 2 — Chatbot RAG (démo visible)

Interface web de questions/réponses sur la doc.

• Flux : question → retrieval (cœur) → prompt + contexte → génération Claude → réponse avec citations des sources.
• Réutilisable pour de futurs projets (modèle multi-projets).
• Front : Symfony/Twig ; amélioration progressive côté JS pour le confort de chat (streaming) sans casser l'accessibilité.

4.4 Surface 3 — Veille agentique

Pipeline planifié qui alimente pilotage/veille/.

• Flux : sources (RSS / sites officiels) → récupération → résumé LLM → déduplication / classification par thème → écriture (proposition) dans la veille.
• Thèmes : IA, dev web, qualité, juridique (RGPD/CNIL, AI Act/EUR-Lex).
• Implémentation Symfony-native (Scheduler + Messenger) plutôt que SaaS no-code.

5. Périmètre V1 (MVP) et hors-périmètre

6. Contraintes

• Infra : VPS CPU-only → génération externalisée, indexation locale acceptable (batch).
• Coût : minimisé par embeddings locaux + prompt caching ; quotas à définir.
• Accessibilité : interfaces produites conformes RGAA 4.1 AA.
• RGPD : la doc ne contient pas de données personnelles de tiers ; risque faible. À surveiller si des sources externes en introduisent.
• Sources : toute réponse/synthèse cite ses sources avec liens valides (règle AGENTS.md).

7. Garde-fous IA (obligatoires)

• Hallucinations : réponses ancrées sur le contexte récupéré ; afficher les passages sources ; signaler quand la doc ne couvre pas la question. Voir fiche 6.1.
• Autorité juridique : la veille juridique ne fait jamais autorité — elle pointe vers les textes officiels (CNIL, EUR-Lex).
• RAG bien fait : cf. fiche 4.3 (RAG, méta-prompts).
• Agents et automatisation : cadrage des actions autonomes, cf. fiche 4.5.
• Déploiement : arbitrages cloud/API/local, cf. fiche 2.5.

8. Consolidation documentaire requise

Cette initiative a remis de l'ordre dans des docs IA dispersées :

• La spec MCP de référence est désormais ia-mcp.md (L1), qui a absorbé les anciennes specs source (gouvernance, multi-tenant).
• Le détail technique du serveur reste dans bundles/tlr-mcp.md + bundles/tlr-mcp/*.

Nommage (validé) : umbrella tlr-mcp (produit multi-tenant, mcp.telaria.dev), Codexia étant consommateur/tenant. Le cœur RAG et le chatbot sont des composants Telaria réutilisables (bundles), configurés côté Codexia. La fusion en une spec MCP unique est réalisée : ia-mcp.md (L1).

9. Découpage en lots (proposition)

• L0 — Cœur : ingestion + embeddings locaux + index + retrieval (testable en CLI).
• L1 — MCP V1 : 3 outils lecture seule au-dessus du cœur, branchés sur un client agent.
• L2 — Chatbot RAG : UI web + génération Claude + citations.
• L3 — Veille V1 : pipeline 1 thème (IA) bout-en-bout.

Chaque lot fait l'objet d'une spec dédiée (specs/ia-*.md). Rédigés : Lot 0 — Cœur : ia-coeur.md ; Lot 1 — MCP : ia-mcp.md ; Lot 2 — Chatbot : ia-chatbot.md ; Lot 3 — Veille : ia-veille.md. Les 4 lots sont spécifiés.

10. État des décisions

État d'implémentation (2026-06-04) : les 4 lots sont livrés et en prod (telaria.dev).

• L0 — Cœur RAG : validé en prod (telaria/rag-bundle v0.1.3, microservice tlr-embeddings).
• L1 — MCP V1 : telaria/mcp-bundle v0.1.3 (3 outils lecture seule), intégré à telaria v0.5.0 (Phase 7).
• L2 — Chatbot RAG : livré sous deux surfaces — page démo /assistant et « le chat » embarqué dans le viewer /docs (cf. ia-chatbot.md).
• L3 — Veille agentique : pipeline en prod (telaria v0.5.0 : diagnostic, standby, import CSV).
• + Surface documentaire /docs livrée (viewer + rendu accessible, cf. docs-web.md).

Décisions cadre tranchées (voir §3) : stratégie LLM hybride, modèle d'embeddings (multilingual-e5-base, bge-m3 en option), microservice Python, forme bundle, nommage tlr-mcp, ordre L0 → L1.

Points fins à préciser dans la spec du lot concerné (pas avant) :

• Cœur (L0) : taille des chunks et chevauchement, sqlite-vec vs alternative, contrat HTTP du microservice d'embeddings, schéma d'index.
• MCP (L1) : liste exacte des outils V1 et schémas JSON, transport (stdio vs HTTP), client de démo.
• Chatbot (L2) : politique de prompt caching, format des citations, amélioration progressive du front.
• Veille (L3) : sources du thème pilote (catalogue figé dans ia-veille-sources.md), cadence, format d'écriture dans pilotage/veille/, monitoring des flux communautaires, filtrage arXiv, calibrage seuil Hacker News.

11. Production documentaire d'accompagnement

Principe (cf. §2) : chaque concept technique introduit donne lieu à un tuto et/ou une fiche, produits avec la spec du lot correspondant. À constituer au fil des lots :

Documents liés

• Spec MCP de référence : ia-mcp.md
• Détail technique du serveur : bundles/tlr-mcp.md
• Guide IA (concepts, Ollama, MCP, VRAM) : guides/ia.md
• Veille « IA dans Codexia » : pilotage/veille/README.md
• Base de connaissance IA (59 fiches) : agents/toc.md

Implémentation

Historique des décisions