- ROADMAP: ne garde que le travail a venir + index compact du complete (995 -> ~155 lignes); detail deplace vers docs/features/ et docs/archive/

- docs/features/: fiches detaillees #74, #75, #76, #77, #78, #79

- docs/archive/COMPLETED_v1-v2.md: detail des items courts livres

- CHANGELOG: alignement sur les tags (2.0.0 date, 2.2.0/2.2.1 ajoutes, Unreleased = travail #79 post-2.2.1)

- AGENTS.md + docs/DELIVERY_WORKFLOW.md: methode de livraison unique (Definition of Done) referencee par ROADMAP, CONTRIBUTING, ISSUES_TODOLIST

2026-09-11 14:07:56 -04:00

5.8 KiB

Raw Blame History

#79 — Assistant IA — Outils (function calling) & serveur MCP

Statut : 🔵 En cours — Phase 0 + B1/B2/B3/B7 + G livrés (2026-09-11) Effort : 10-15 jours | Impact : 🟡 Références : Roadmap · Guide d'architecture IA

Description : Transformer l'assistant BooksLM (protocole texte obsigate-action limité à create_file/create_directory) en un agent capable de lire, chercher, lister, ouvrir et modifier, via function calling natif, puis exposer ObsiGate à des clients MCP externes (Claude Desktop, Cursor…). Les deux fronts consomment une couche d'outils partagée — source unique de vérité.
Documentation : AI_ARCHITECTURE_GUIDE.md (architecture, catalogue d'outils, sécurité, phases).

A. Fondations — couche d'outils partagée (2-3 jours) — ✅ livré (2026-09-11)

A1. Créer backend/tools/ : context.py (ToolContext : user, allowed_vaults, mode, confirmed), registry.py (décorateur @tool + schéma JSON), schemas.py, service.py, audit.py
A2. Extraire la logique métier des routes de backend/main.py en fonctions de service réutilisables (les routes deviennent des wrappers) — partiel : services lecture/recherche livrés (list_vaults, list_directory, read_file, search_fulltext, list_tags) ; refactor des routes main.py à suivre
A3. Contexte de permissions : chaque outil applique check_vault_access + resolve_safe_path
A4. Audit : journalisation JSONL de chaque appel d'outil (qui, quoi, vault, résultat) — action ai_tool_call, arguments sensibles résumés
A5. Tests unitaires du registry + services (sans IA) — tests/test_tools.py (30 tests)

B. Function calling in-app (3-4 jours) — 🔵 partiel (B1/B2/B3/B7 livrés 2026-09-11)

B1. Abstraction tool-calling provider-agnostique : backend/ai_chat.py (chat_completion, ToolCall, LLMResponse) — OpenAI-compat (tools/tool_choice, parsing tool_calls) + Gemini (functionDeclarations/functionCall)
B2. Agent loop backend/agent/loop.py : boucle tool→résultat→tool, limite d'itérations (10), truncation des résultats ; endpoint opt-in POST /api/ai/bookslm/agent (events SSE tool/message/confirmation)
B3. Fallback : retry sans tools si le provider rejette les tools (400/404/422) → chat simple ; protocole texte obsigate-action conservé côté frontend
B4. SSE réellement streaming (corriger bookslm_routes.py — le message final reste envoyé en un seul événement)
B5. Confirmations UI : outils read auto, outils write via carte Apply (bookslm.js:515), aperçu diff pour edit_file
B6. Outils de navigation in-app : open_file, reveal_in_tree (événement obsigate:open-file)
B7. Tests : agent loop LLM mocké (tests/test_agent_loop.py), providers (tests/test_ai_chat.py), endpoint (tests/test_bookslm.py)

C. Catalogue d'outils — lecture & recherche (1-2 jours)

C1. Vaults/navigation : list_vaults, list_directory, list_all_files
C2. Lecture : read_file, read_file_raw, get_backlinks, list_backups, diff_backup, get_graph
C3. Recherche : search_fulltext, search_advanced, search_paths, list_tags, suggest_tags, list_recent

D. Catalogue d'outils — mutations (2 jours)

D1. create_file, create_directory (migration du protocole texte existant)
D2. edit_file, append_to_file, rename_file, rename_directory, move_path
D3. replace_in_files (⚠️ confirmation two-step + backup auto)
D4. delete_file, delete_directory, restore_backup (⚠️ confirmation two-step + backup auto, toggle par vault)

E. Serveur MCP (2-3 jours)

E1. backend/mcp/server.py (SDK MCP Python) enregistrant les outils depuis le registry
E2. Mapping des primitives : Tools (mutations + recherche), Resources (vaults/fichiers en lecture vault://), Prompts (templates)
E3. Transport Streamable HTTP : endpoint /mcp dans FastAPI, auth Authorization: Bearer <JWT> → get_current_user (décision 2026-09-11). stdio optionnel plus tard
E4. Confirmations : two-step propose_*/apply_* avec token signé (usage unique, TTL) ; élicitation optionnelle si le client l'annonce (décision 2026-09-11)
E5. Toggle par vault pour désactiver les outils destructifs (défaut : activés)
E6. Tests : handshake MCP, permissions par vault, mapping des ressources, anti-rejeu du token

F. Durcissement & documentation (1 jour)

F1. Rate limiting par token/outil + quotas (BOOKSLM_MAX_*)
F2. Redaction des secrets avant retour au LLM
F3. Documentation OpenAPI (backend/openapi_docs.py) + guide MCP
F4. Tests E2E de bout en bout

G. Sélection fournisseur/modèle par défaut — ✅ livré

G1. Persistance ai_default_provider + ai_default_models dans data/config.json (_DEFAULT_CONFIG)
G2. Lecture + rechargement à chaud dans backend/ai.py (get_default_provider, reload_ai_config)
G3. UI : sélecteurs « Fournisseur par défaut » + « Modèle par défaut » dans #cfg-ai (frontend/index.html, frontend/js/config.js)
G4. i18n FR/EN

Décisions

✅ Transport MCP : Streamable HTTP (2026-09-11)
✅ Confirmation MCP : two-step propose/apply (2026-09-11)
✅ Périmètre des mutations externes : toutes autorisées (create/edit/rename/move/delete) — encadrées par confirmation + backup auto + audit + toggle par vault (2026-09-11)
Détail et justification dans le guide §8.

Reference in New Issue View Git Blame Copy Permalink

5.8 KiB Raw Blame History

#79 — Assistant IA — Outils (function calling) & serveur MCP

A. Fondations — couche d'outils partagée (2-3 jours) — ✅ livré (2026-09-11)

B. Function calling in-app (3-4 jours) — 🔵 partiel (B1/B2/B3/B7 livrés 2026-09-11)

C. Catalogue d'outils — lecture & recherche (1-2 jours)

D. Catalogue d'outils — mutations (2 jours)

E. Serveur MCP (2-3 jours)

F. Durcissement & documentation (1 jour)

G. Sélection fournisseur/modèle par défaut — ✅ livré

Décisions

5.8 KiB

Raw Blame History