Architecture Global Search & Intelligence Artificielle - Phase 1

🎯 Décision d'Architecture

✅ Recommandation : Backend NestJS (implémenté)

Pourquoi NestJS pour la Phase 1 ?

Infrastructure existante :
- LlmService et OpenaiService déjà en place
- Gestion des clés API OpenAI par utilisateur
- Accès direct à la DB via Kysely
- TypeScript partagé avec le frontend
Avantages :
- Pas de communication inter-services (plus simple)
- Déploiement et maintenance plus faciles
- Performance suffisante pour la Phase 1
- Cohérence avec l'architecture existante
Limites acceptables pour Phase 1 :
- Pas besoin de LangChain intensif
- Pas de traitement batch lourd
- Pas de modèles ML complexes

🔄 Évolution future : Service Python séparé (Phase 2/3)

Quand envisager un service Python séparé ?

Si besoin de LangChain de manière intensive
Traitement batch lourd (indexation, analyse massive)
Modèles ML complexes (embedding, classification avancée)
Besoin de bibliothèques Python spécifiques (pandas, scikit-learn, etc.)

Architecture proposée si migration nécessaire :

Frontend → NestJS Backend → Python AI Service (gRPC/REST)
                              ↓
                         OpenAI/LangChain

📁 Structure Actuelle

backend/src/search/
├── search.service.ts          # Recherche classique (DB + Notion)
├── search.controller.ts        # Endpoints REST
├── search.module.ts            # Module NestJS
└── ai-search.service.ts        # ✨ NOUVEAU : Service IA pour Phase 1

🔌 Endpoints API

1. `POST /api/search/ai/process`

Traite une requête en langage naturel et détermine l'intention.

Request:

{
  "query": "sessions de mariage en juillet 2024 avec montant > 2000€"
}

Response:

{
  "intent": "create_view",
  "confidence": 0.95,
  "parsedQuery": {
    "entity": "sessions",
    "filters": [
      {
        "field": "type",
        "operator": "equals",
        "value": "mariage"
      },
      {
        "field": "date",
        "operator": "between",
        "value": ["2024-07-01", "2024-07-31"]
      },
      {
        "field": "amount",
        "operator": "greater_than",
        "value": 2000
      }
    ]
  }
}

2. `POST /api/search/ai/filters`

Génère des filtres structurés à partir d'une requête en langage naturel.

Request:

{
  "query": "contacts actifs avec au moins 2 sessions cette année",
  "entity": "contacts"
}

Response:

{
  "filters": [
    {
      "field": "session_count",
      "operator": "greater_than",
      "value": 2
    },
    {
      "field": "last_session_date",
      "operator": "greater_than",
      "value": "2024-01-01"
    }
  ],
  "entity": "contacts"
}

3. `POST /api/search/ai/answer`

Répond à une question sur les données.

Request:

{
  "question": "Quel est le revenu total du mois dernier ?",
  "context": {
    "invoices": [...]
  }
}

Response:

{
  "answer": "Le revenu total du mois dernier est de 15 450€.",
  "confidence": 0.92,
  "sources": [
    {
      "type": "invoices",
      "id": "invoice-123",
      "snippet": "Facture #2024-001 - 2500€"
    }
  ]
}

🏗️ Architecture du Service IA

`AiSearchService`

Le service AiSearchService fournit trois méthodes principales :

processQuery() : Classification d'intention
- Analyse la requête utilisateur
- Détermine l'intention (search, create_view, execute_action, question)
- Parse la requête pour extraire les paramètres
generateFilters() : Génération de filtres
- Convertit le langage naturel en filtres DB structurés
- Supporte les opérateurs : equals, contains, greater_than, less_than, between, in
- Valide les champs selon l'entité cible
answerQuestion() : Réponse aux questions
- Analyse le contexte fourni
- Génère une réponse naturelle
- Cite les sources utilisées

Prompts System

Les prompts sont construits dynamiquement selon :

L'entité cible (sessions, contacts, quotes, invoices)
Les champs disponibles pour chaque entité
Le type de requête (classification, filtres, question)

Configuration

Modèle par défaut : gpt-4o-mini (configurable par utilisateur)
Temperature :
- 0.2 pour la classification d'intention
- 0.1 pour la génération de filtres (précision maximale)
- 0.3 pour les réponses aux questions
Format de réponse : JSON strict (response_format: { type: "json_object" })

🔄 Flux d'Utilisation

Exemple 1 : Création d'une vue personnalisée

1. User: "Crée une vue des sessions de mariage du mois de juillet"
   ↓
2. Frontend → POST /api/search/ai/process
   ↓
3. AiSearchService.processQuery()
   → Intent: "create_view"
   → Entity: "sessions"
   → Filters: [type="mariage", date="2024-07"]
   ↓
4. Frontend → POST /api/search/ai/filters (si besoin de plus de précision)
   ↓
5. Frontend applique les filtres et affiche la vue

Exemple 2 : Question sur les données

1. User: "Quel est le revenu total du mois dernier ?"
   ↓
2. Frontend → POST /api/search/ai/process
   → Intent: "question"
   ↓
3. Frontend récupère les données nécessaires (invoices du mois dernier)
   ↓
4. Frontend → POST /api/search/ai/answer
   → Answer: "Le revenu total est de 15 450€"
   ↓
5. Frontend affiche la réponse

Exemple 3 : Action complexe

1. User: "Crée une facture pour toutes les sessions payées du mois dernier"
   ↓
2. Frontend → POST /api/search/ai/process
   → Intent: "execute_action"
   → Action: "create_invoice"
   → Parameters: { sessions: "paid", period: "last_month" }
   ↓
3. Frontend exécute l'action via l'API appropriée

🔐 Sécurité

Authentification : JWT + ActiveUserGuard requis
Clés API : Chaque utilisateur utilise sa propre clé OpenAI (stockée chiffrée)
Validation : Tous les filtres générés sont validés avant application
Rate Limiting : À implémenter si nécessaire (via RateLimitingModule)

📊 Performance

Latence attendue : 1-3 secondes par requête IA (selon le modèle)
Cache : À implémenter pour les requêtes fréquentes
Optimisation : Utilisation de gpt-4o-mini par défaut (plus rapide et moins cher)

🚀 Phase 1 - Complétée ✅

✅ Service AiSearchService créé
✅ Endpoints API ajoutés
✅ Intégration frontend (GlobalSearch component)
✅ Application des filtres générés aux requêtes DB
✅ Interface utilisateur pour l'assistant conversationnel
✅ Système d'exécution d'actions complexes

🚀 Phase 2 - Création assistée par IA ✅

Structure

backend/src/ai-assistant/
├── ai-creation.service.ts    # Génération de brouillons d'entités
├── ai-report.service.ts       # Génération de rapports intelligents
├── ai-writing.service.ts      # Rédaction assistée
├── ai-assistant.controller.ts # Endpoints API
├── ai-assistant.module.ts     # Module NestJS
└── README.md                  # Documentation

Services

1. AiCreationService

Génère des brouillons d'entités (sessions, contacts, devis, factures) à partir de prompts en langage naturel.

Endpoint: POST /api/ai-assistant/draft

Exemple:

{
  "prompt": "Crée une nouvelle session photo pour le mariage de Marie et Pierre le 15 juillet 2024 à Paris, avec un devis de 2500€",
  "entityType": "session"
}

2. AiReportService

Génère des rapports personnalisés via prompts, l'IA agrège les données et génère le rapport.

Endpoint: POST /api/ai-assistant/report

Exemple:

{
  "prompt": "Génère un rapport PDF des revenus par type de session pour le dernier trimestre",
  "dataContext": {
    "sessions": [...],
    "invoices": [...],
    "analytics": {...}
  }
}

3. AiWritingService

Utilise l'IA pour générer des ébauches d'emails, de descriptions de sessions, de notes de contact, etc.

Endpoint: POST /api/ai-assistant/writing

Exemple:

{
  "prompt": "Rédige un email de suivi pour le devis #2024-001 en rappelant les avantages de notre offre",
  "type": "email",
  "context": {
    "entityType": "quote",
    "entityData": {...},
    "recipient": { "name": "John Doe", "email": "john@example.com" },
    "tone": "professional",
    "language": "fr"
  }
}

Configuration

Modèle par défaut : gpt-4o-mini (configurable par utilisateur)
Temperature :
- 0.3 pour la génération de brouillons (cohérence)
- 0.4 pour les rapports (créativité modérée)
- 0.7 pour la rédaction (créativité)
Cache :
- 5 minutes pour brouillons et rédaction
- 10 minutes pour rapports (plus coûteux)
Format de réponse : JSON strict (response_format: { type: "json_object" })

📝 Notes

Le service est conçu pour être évolutif : si besoin d'un service Python séparé plus tard, l'interface peut être abstraite
Les prompts peuvent être améliorés itérativement selon les retours utilisateurs
La structure modulaire permet d'ajouter facilement de nouvelles fonctionnalités (Phase 3)
Phase 2 utilise la même infrastructure que Phase 1 (NestJS, OpenAI, cache Redis)

🎯 Décision d'Architecture​

✅ Recommandation : Backend NestJS (implémenté)​

🔄 Évolution future : Service Python séparé (Phase 2/3)​

📁 Structure Actuelle​

🔌 Endpoints API​

1. POST /api/search/ai/process​

2. POST /api/search/ai/filters​

3. POST /api/search/ai/answer​

🏗️ Architecture du Service IA​

AiSearchService​

Prompts System​

Configuration​

🔄 Flux d'Utilisation​

Exemple 1 : Création d'une vue personnalisée​

Exemple 2 : Question sur les données​

Exemple 3 : Action complexe​

🔐 Sécurité​

📊 Performance​

🚀 Phase 1 - Complétée ✅​

🚀 Phase 2 - Création assistée par IA ✅​

Structure​

Services​

1. AiCreationService​

2. AiReportService​

3. AiWritingService​

Configuration​

📝 Notes​

🎯 Décision d'Architecture

✅ Recommandation : Backend NestJS (implémenté)

🔄 Évolution future : Service Python séparé (Phase 2/3)

📁 Structure Actuelle

🔌 Endpoints API

1. `POST /api/search/ai/process`

2. `POST /api/search/ai/filters`

3. `POST /api/search/ai/answer`

🏗️ Architecture du Service IA

`AiSearchService`

Prompts System

Configuration

🔄 Flux d'Utilisation

Exemple 1 : Création d'une vue personnalisée

Exemple 2 : Question sur les données

Exemple 3 : Action complexe

🔐 Sécurité

📊 Performance

🚀 Phase 1 - Complétée ✅

🚀 Phase 2 - Création assistée par IA ✅

Structure

Services

1. AiCreationService

2. AiReportService

3. AiWritingService

Configuration

📝 Notes