Nicolas Cantu
0af507143a
- New smart-ide-global-api (127.0.0.1:37149): internal bearer, upstream proxy, X-OIDC forward - SSO gateway calls global API with GLOBAL_API_INTERNAL_TOKEN; logs to .logs/sso-gateway/ - Aggregated config example, docs, VERSION 0.0.2, claw proxy local URL hint
8.8 KiB
8.8 KiB
Périmètre fonctionnel des services — IDE, plateforme et backends applicatifs
Ce document précise ce que fait chaque brique (fonction métier / technique), qui l’utilise (IDE, automation, backend d’un produit), et ce qui est hors périmètre. Il complète services.md, API/README.md et ecosystem-architecture-and-sync.md.
1. Trois contextes de consommation
| Contexte | Acteur typique | Objectif |
|---|---|---|
| IDE / poste développeur | Lapce, Cursor, scripts locaux, extensions | Édition, Git, agents, prévisualisation, découverte des endpoints, tâches documentaires ponctuelles |
| Automation / ia_dev | ia_dev, cron, hooks, CI autorisée |
Déploiement, tickets, synchro RAG, clones sous racine contrôlée |
| Backend applicatif (projet développé) | Serveur docv, API Enso, autres produits 4NK | Fonctionnalités métier exposées aux utilisateurs finaux ; appels serveur à serveur vers la couche IA générique si le produit le prévoit |
Règle de séparation : les micro-services sous services/ du monorepo smart_ide sont une plateforme technique (outillage, IA générique, orchestration). Les API REST métier (gestion documentaire, règles métier, persistance produit) vivent dans les dépôts applicatifs (ex. docv), pas dans smart_ide.
2. Services HTTP du monorepo smart_ide
Tous écoutent en principe sur 127.0.0.1 ; ports par défaut : API/README.md. Configuration agrégée : config/services.local.env.example.
| Service | Périmètre fonctionnel | Rôle pour l’IDE | Rôle pour les backends applicatifs (projets) |
|---|---|---|---|
| smart_ide-orchestrator | Résolution d’intentions en cibles (Ollama, AnythingLLM, micro-services, gateway) sans logique LLM propre | Point d’entrée unique pour l’UI « intentions » ; dryRun pour inspection |
Optionnel : même point d’entrée si le back route par intention ; sinon appels directs aux services cibles pour moins d’indirection |
| ia-dev-gateway | Registre d’agents ia_dev, lancement de runs, flux SSE (spécification) |
Palette / outils « lancer agent », timeline | Possible pour scénarios « agent long » déclenchés depuis un back ; contrat : features/ia-dev-service.md |
| repos-devtools-server | Clone / liste / chargement de dépôts Git sous une racine contrôlée (REPOS_DEVTOOLS_ROOT) |
Rafraîchir l’espace de code sans quitter l’IDE | Rarement côté prod utilisateur ; plutôt outillage et environnements de build / sandbox |
| anythingllm-devtools | Workspaces AnythingLLM, upload documentaire, orchestration avec repos-devtools, RAG initial (.4nkaiignore) |
Aligner workspace / dépôt depuis l’IDE ou un script | Possible pour pipelines « alimenter le RAG » automatisés ; secrets et URL AnythingLLM côté hôte |
| langextract-api | Extraction structurée depuis texte (schéma, exemples, modèle configurable) | Enrichir une feature « extraire des entités » dans l’IDE | Recommandé comme brique générique quand le back a besoin d’extractions typées (voir docv-ai-integration.md) |
| agent-regex-search-api | Recherche regex sur fichiers (ripgrep), périmètre REGEX_SEARCH_ROOT |
Recherche symbolique large dans le workspace | Prudent : exposer seulement si le root est strictement borné ; plutôt poste dev ou job batch |
| claw-harness-api (proxy) | Proxy HTTP vers un exécuteur claw-code amont | Outillage modèles alternatifs en dev | Optionnel si politique projet autorise ce proxy en interne |
| local-office | Manipulation programmatique de fichiers Office (docx, etc.), clé X-API-Key |
Tests / génération de documents depuis l’IDE | Possible pour génération batch ou transformations Office côté serveur applicatif (hors UI ONLYOFFICE) |
| smart-ide-tools-bridge | Registre des URLs locales ; jobs Carbonyl / PageIndex / Chandra (chemins validés sous SMART_IDE_MONOREPO_ROOT) |
Découverte des services ; lancer OCR / index / plan terminal depuis l’IDE | Non prévu pour le trafic utilisateur final : jobs longs, liés au poste / au monorepo ; les backs produit doivent préférer leurs propres pipelines (OCR, index) en prod si besoin |
| smart-ide-sso-gateway | Validation JWT docv / Enso + proxy via smart-ide-global-api vers les micro-services | Alternative au BFF maison pour un front ou un outil qui appelle déjà l’IdP | Possible quand le produit veut un seul point d’entrée HTTP local vers la plateforme IA sous identité utilisateur OIDC ; les appels M2M peuvent rester directs vers un micro-service ou vers l’API globale — features/sso-gateway-service.md, repo/service-smart-ide-global-api.md |
3. Outils CLI et sous-modules (sans listener HTTP dédié)
| Outil | Périmètre fonctionnel | IDE | Backends applicatifs |
|---|---|---|---|
Carbonyl (services/carbonyl/) |
Navigateur terminal (Chromium) pour ouvrir une URL | Prévisualisation test (preview_urls + scripts) ; via bridge open-plan |
Pas d’intégration serveur typique |
PageIndex (services/pageindex/) |
Index arborescent « vectorless » sur PDF / Markdown | Via tools-bridge POST /v1/pageindex/run |
Réutiliser le modèle (amont) dans un pipeline produit si besoin ; pas le bridge comme API publique |
Chandra (services/chandra/) |
OCR structuré PDF / images → MD / HTML / JSON | Via tools-bridge POST /v1/chandra/ocr ou CLI locale |
Même logique : moteur amont réutilisable ; le bridge reste outil poste |
4. Services d’hôte hors code services/ (souvent Docker / systemd)
| Composant | Périmètre | IDE | Backends applicatifs |
|---|---|---|---|
| Ollama | Inférence LLM locale | Chat / complétion via orchestrateur ou URL directe | Appels HTTP /api/... depuis le back si réseau et politique le permettent |
| AnythingLLM | RAG, workspaces, threads | Consultation workspace, synchro via devtools / scripts | API workspace / documents pour QA ou recherche documentaire métier (anythingllm-workspaces.md) |
| ONLYOFFICE | Édition bureautique interactive | Intégration front | Embarqué côté produit pour l’utilisateur final |
| docv (dépôt externe) | Gestion documentaire métier, persistance, règles Enso | Consommation comme produit | C’est l’API métier documentaire ; elle peut appeler orchestrateur / Ollama / AnythingLLM / langextract selon docv-ai-integration.md |
5. API des projets développés (clarification)
- Les backends des projets (ex. docv, API enso-front / BFF, services métier) exposent leurs propres routes (REST, GraphQL, etc.) vers le front et les clients.
- Le monorepo smart_ide ne remplace pas ces API : il fournit des micro-services transverses et de la documentation (
projects/<id>/conf.json, SSH, chemins données). - Intégration type docv → smart_ide : serveur à serveur, tokens dédiés, réseau interne ; orthogonal au SSO utilisateur (sso-docv-enso.md).
6. Rôles respectifs (rappel)
- IDE : orchestrateur (intentions), tools-bridge (registre + jobs outils), devtools AnythingLLM, repos-devtools, regex search, ia-dev-gateway, smart-ide-global-api + smart-ide-sso-gateway (OIDC utilisateur → API globale → micro-services, si activé), accès directs Ollama / AnythingLLM selon l’UX.
- Backends applicatifs : consommer en priorité les services stables et documentés pour l’IA générique (langextract, AnythingLLM, Ollama, éventuellement orchestrateur) ; éviter de dépendre du tools-bridge pour la charge utilisateur ; respecter périmètres fichiers (
REGEX_SEARCH_ROOT, SSH / données déployées — remote-deployed-data-ssh.md).