Product — Use Cases¶

Périmètre¶

API v1 : endpoints canoniques /v1/generate/reply et /v1/search/query
Canaux : webchat, Facebook Messenger, WhatsApp
RAG : citations obligatoires, datasets v1.x indexés
Hypothèses : datasets v1.x publiés (Data Cards), IAM opérationnel, observabilité OTLP accessible

Vue d'ensemble¶

Définitions KPI¶

Taux d'auto-résolution = (# convos résolues sans agent) / (# convos totales).
CSAT post-réponse = moyenne des notes post-réponse (échantillon ≥ 100).
Taux d'hallucination (QA) = (# réponses factuellement incorrectes) / (# réponses évaluées).
TTR (Time To Resolution) = médiane du temps entre 1er message et résolution/handover clos.

Use case	Persona principal	Priorité (MoSCoW)	KPI clé	Dépendances
FAQ RAG sourcée	Client final	MUST	MRR@5, Taux d'auto-résolution	KB v1.x, Vector DB
Suivi de commande	Client final	MUST	CSAT, Latence E2E	Intégration order API (mock MVP)
Politique remboursement	Client final	MUST	Taux d'hallucination, Citations %	KB policy
Handover agent	Agent Support	SHOULD	Taux transfert, TTR	Bridge agent

Use Case 1 : FAQ RAG sourcée¶

Acteurs¶

Client final
SalamBot

Préconditions¶

Dataset salambot-faq-fr v1.x indexé
Canal actif (webchat/FB/WA)
SLO latence configurés

Flux nominal¶

User pose une question
RAG récupère top_k passages pertinents
LLM génère réponse avec citations[] obligatoires
Réponse renvoyée avec confidence et métriques

Diagramme de flux FAQ RAG¶

sequenceDiagram
    participant U as Utilisateur
    participant API as API Gateway
    participant RAG as Service RAG
    participant VDB as Vector DB
    participant LLM as LLM Router
    participant KB as Knowledge Base

    U->>API: POST /v1/generate/reply<br/>{"prompt": "politique remboursement?"}
    API->>API: Validation tenant/schema
    API->>RAG: Recherche passages
    RAG->>VDB: Query embedding + top_k=5
    VDB->>KB: Récupération documents
    KB-->>VDB: Passages + métadonnées
    VDB-->>RAG: Résultats scorés

    alt Passages pertinents trouvés
        RAG->>LLM: Génération avec contexte
        LLM->>LLM: Vérification citations
        LLM-->>RAG: Réponse + citations[]
        RAG->>RAG: Calcul confidence

        alt Confidence >= 0.60
            RAG-->>API: Réponse avec citations
            API-->>U: 200 OK + réponse sourcée
        else Confidence < 0.60 et >= 0.40
            RAG-->>API: Réponse + suggestion reformulation
            API-->>U: 200 OK + demande clarification
        else Confidence < 0.40
            RAG->>API: Déclenchement handover
            API-->>U: Transfert vers agent
        end
    else Aucun passage pertinent
        RAG->>API: Échec recherche
        API-->>U: Message d'excuse + handover
    end

Cas limites¶

Pas de document pertinent ⇒ message d'excuse + handover
Confiance < 0.40 ⇒ handover automatique
Citations vides ⇒ bloquer réponse + handover

Critères d'acceptation¶

Given FAQ v1.x, When question 'retours', Then citations[].url contient la page policy et confidence >= 0.60
Performance : TTFB p95 ≤ 600ms, E2E p95 ≤ 2.5s sur 7j

API Examples¶

# Génération de réponse (exemple minimal)
curl -X POST http://localhost:8080/v1/generate/reply \\
  -H 'Content-Type: application/json' \\
  -H 'X-SalamBot-Tenant: demo' \\
  -d '{
    "schema_version":"1.0",
    "tenant":"demo",
    "channel":"webchat",
    "message_id":"msg_123",
    "correlation_id":"corr_123",
    "timestamp":"2025-08-14T10:00:00Z",
    "locale":"fr-MA",
    "data":{
      "prompt":"Quelle est la politique de remboursement ?",
      "context":[]
    }
  }'

Réponse attendue (extrait)

{
  "answer": "...",
  "citations": [
    {
      "source_id": "kb:policy#refunds",
      "url": "https://kb.example/policy#refunds",
      "page": 2,
      "section": "remboursements",
      "score": 0.84
    }
  ],
  "latency_ms": 850,
  "confidence": 0.72,
  "trace_id": "...",
  "correlation_id": "corr_123"
}

# Recherche directe (RAG)
curl -X POST http://localhost:8080/v1/search/query \\
  -H 'Content-Type: application/json' \\
  -d '{
    "query":"remboursement",
    "tenant":"demo",
    "top_k":3
  }'

Règle : citations[] ne doit jamais être vide pour une réponse basée RAG (sinon handover).

KPI¶

MRR@5 ≥ 0.80
Taux d'auto-résolution ≥ 60%
Taux d'hallucination ≤ 3%

Use Case 2 : Suivi de commande (MVP: mock)¶

Acteurs¶

Client final
SalamBot

Préconditions¶

Endpoint mock order API disponible
Mapping intents minimal configuré

Flux nominal¶

User fournit numéro de commande
Vérification format, appel API (mock)
Réponse avec statut + éventuelle action suivante

Diagramme de flux Suivi de commande¶

sequenceDiagram
    participant U as Utilisateur
    participant API as API Gateway
    participant NLU as Service NLU
    participant ORDER as Order API (Mock)
    participant LLM as LLM Router

    U->>API: "Où en est ma commande CMD123?"
    API->>NLU: Extraction intent + entités
    NLU->>NLU: Détection intent: order_tracking
    NLU->>NLU: Extraction: order_id="CMD123"
    NLU-->>API: Intent + entités structurées

    API->>API: Validation format order_id

    alt Format valide
        API->>ORDER: GET /orders/CMD123

        alt Commande trouvée
            ORDER-->>API: {"status": "shipped", "tracking": "TRK456"}
            API->>LLM: Génération réponse contextuelle
            LLM-->>API: Réponse formatée
            API-->>U: "Votre commande CMD123 est expédiée.<br/>Suivi: TRK456"
        else Commande non trouvée
            ORDER-->>API: 404 Not Found
            API->>LLM: Génération message d'erreur
            LLM-->>API: Message d'excuse
            API-->>U: "Commande introuvable.<br/>Vérifiez le numéro."
        end

    else Format invalide
        API->>LLM: Demande reformulation
        LLM-->>API: Message de clarification
        API-->>U: "Format invalide.<br/>Ex: CMD123 ou ORD456"
    end

    alt API Order indisponible
        ORDER-->>API: Timeout/Error
        API->>API: Fallback vers handover
        API-->>U: "Service temporairement indisponible.<br/>Transfert vers agent..."
    end

Cas limites¶

Numéro invalide ⇒ demande de reformulation
API indisponible ⇒ fallback RAG + handover si nécessaire

Critères d'acceptation¶

Given numéro valide, Then retour statut en < 2.5s
Logs et trace_id présents pour chaque requête

KPI¶

CSAT ≥ 4.2/5
E2E p95 ≤ 2.5s

Use Case 3 : Politique de remboursement¶

Acteurs¶

Client final
SalamBot

Préconditions¶

KB policy indexée et à jour
Garde-fous ton/risques configurés

Flux nominal¶

User demande informations sur 'remboursement'
RAG retrouve la section policy pertinente
Réponse avec citations + éventuels liens UI

Cas limites¶

Policy absente ⇒ message neutre + handover
Conflit de versions KB ⇒ utiliser dernière version publiée

Critères d'acceptation¶

Réponse contient au moins 1 citation exacte (page/section/url)
Taux d'hallucination ≤ 3%

KPI¶

Citations présentes ≥ 95% des réponses RAG

Use Case 4 : Handover agent¶

Acteurs¶

Client final
Agent Support
SalamBot

Préconditions¶

Bridge agent opérationnel
Règles de transfert définies

Flux nominal¶

Détection seuils (confiance basse/intent critique)
Création ticket/session agent avec contexte complet
Notification agent et prise en charge

Diagramme de flux Handover agent¶

sequenceDiagram
    participant U as Utilisateur
    participant API as API Gateway
    participant EVAL as Évaluateur
    participant PII as Masquage PII
    participant BRIDGE as Bridge Agent
    participant AGENT as Agent Support
    participant TICKET as Système Tickets

    U->>API: Question complexe/sensible
    API->>EVAL: Évaluation confidence + intent

    alt Déclenchement handover
        EVAL->>EVAL: Confidence < 0.40 OU<br/>Intent critique détecté
        EVAL->>PII: Masquage données sensibles
        PII->>PII: Anonymisation PII<br/>Préservation contexte
        PII-->>BRIDGE: Contexte sécurisé

        BRIDGE->>TICKET: Création ticket<br/>+ métadonnées (tenant, canal, trace_id)
        TICKET-->>BRIDGE: ticket_id généré

        BRIDGE->>BRIDGE: Recherche agent disponible

        alt Agent disponible
            BRIDGE->>AGENT: Notification + contexte complet
            AGENT-->>BRIDGE: Prise en charge confirmée
            BRIDGE-->>API: Session agent établie
            API-->>U: "Transfert vers agent...<br/>Référence: #TKT123"

            Note over AGENT,U: Conversation directe agent-utilisateur
            AGENT->>U: "Bonjour, je prends le relais..."

        else Aucun agent disponible
            BRIDGE->>TICKET: Mise en file d'attente
            BRIDGE-->>API: Position dans la file
            API-->>U: "Tous nos agents sont occupés.<br/>Position: 3 (≈5min)"

            Note over TICKET: Notification automatique<br/>dès qu'un agent se libère
        end

    else Pas de handover nécessaire
        EVAL-->>API: Traitement normal
        API-->>U: Réponse automatique
    end

Cas limites¶

Aucun agent disponible ⇒ file d'attente
Données sensibles ⇒ masquage avant transfert

Critères d'acceptation¶

Contexte complet transmis (question, passages, trace_id)
Temps de transfert ≤ 5s

KPI¶

Taux de transfert ≤ 30%
TTR médian ≤ 5 min

Conformité & ton¶

Masquage systématique des PII avant transfert agent.
Réponses conformes au style guide (ne pas promettre d'actions non supportées).
Voir Security/pii.md et Security/audit.md pour la traçabilité.

Exigences non-fonctionnelles¶

Disponibilité : 99.9% (SLA)
Latence : ≤ 2s (P95) pour génération
Débit : 1000 req/min par tenant
Sécurité : chiffrement bout-en-bout, audit complet
Endpoints canoniques uniquement (/v1/generate/reply, /v1/search/query) — voir API/reference.md.
Observabilité OTLP (port 4318), corrélation trace_id/correlation_id
Sécurité : no-PII logs, signatures webhooks

Horodatage¶

Toutes les réponses/événements utilisent des timestamps ISO 8601 UTC (Z). L'heure locale n'est qu'un rendu UI.

Erreurs & fallbacks globaux¶

Codes : INVALID_REQUEST, RATE_LIMIT, UPSTREAM_TIMEOUT, INSUFFICIENT_CONFIDENCE.
Confiance : si < 0.40 ⇒ handover auto ; 0.40–0.60 ⇒ proposer reformulation + augmenter top_k.
Idempotence : POST /v1/generate/reply sans Idempotency-Key ⇒ 400 INVALID_REQUEST.
Webhooks : retries exponentiels (2s, 4s, 8s, 16s, 32s, max 5).

Instrumentation & analytics¶

Événements : msg_received, rag_retrieved, reply_generated, handover_triggered.
Propriétés : tenant, channel, latency_ms, top_k, confidence, trace_id, correlation_id.
Objectif : tableaux de bord MRR@k, latence (TTFB/E2E), taux de handover (cf. PRD Lite).

Dépendances¶

Quality/datasets.md (Data Cards, MRR)
Security/iam.md, Security/pii.md, Security/audit.md
Deployment/local.md, Deployment/cloud-local.md, Deployment/on-prem.md pour environnements

Feature flags & rollout (réf. PRD Lite)¶

Flags : rag_enabled, handover_enabled, wa_channel_enabled, fb_channel_enabled, analytics_basic.
Rollout progressif par pourcentage de tenants (5% → 25% → 100%) avec rollback.

Roadmap produit¶

La timeline suivante présente l'évolution prévue des fonctionnalités SalamBot :

timeline
    title Roadmap SalamBot 2025-2026

    section Q1 2025
        MVP Core : FAQ RAG sourcée
                 : Webchat + FB Messenger
                 : Handover basique
                 : Dataset v1.0 (FR)

        Observabilité : Métriques OTLP
                      : Dashboards Grafana
                      : Alerting P0/P1

        Sécurité : IAM multi-tenant
                 : Audit logs
                 : PII detection

    section Q2 2025
        Canaux : WhatsApp Business
               : Webchat avancé
               : API webhooks

        RAG v2 : Citations enrichies
               : Confidence adaptative
               : Multi-langue (AR)

        Analytics : CSAT tracking
                  : A/B testing
                  : Usage analytics

    section Q3 2025
        IA Avancée : Fine-tuning local
                   : Prompt engineering
                   : Context window 32k

        Intégrations : CRM connectors
                     : Order tracking API
                     : Payment status

        Performance : Edge caching
                    : Response streaming
                    : Auto-scaling

    section Q4 2025
        Enterprise : SSO/SAML
                   : Advanced RBAC
                   : Custom branding

        Intelligence : Sentiment analysis
                     : Intent prediction
                     : Proactive suggestions

        Global : Multi-région
               : Compliance GDPR+
               : 99.9% SLA

    section Q1 2026
        Innovation : Voice integration
                   : Video support
                   : AR/VR ready

        Ecosystem : Partner APIs
                  : Marketplace
                  : Third-party plugins

        AI Ethics : Bias detection
                  : Explainable AI
                  : Responsible AI

Jalons critiques¶

Milestone	Date cible	Critères de succès	Risques
MVP Production	Mars 2025	CSAT ≥ 4.0, Auto-résolution ≥ 60%	Qualité dataset, Performance
Multi-canal	Juin 2025	3 canaux actifs, Handover ≤ 30%	Intégrations WhatsApp
IA Avancée	Sept 2025	Confidence ≥ 0.70, Latence ≤ 1.5s	Coûts compute, Fine-tuning
Enterprise Ready	Déc 2025	10+ tenants, SLA 99.9%	Scalabilité, Sécurité
Innovation	Mars 2026	Voice/Video POC, API ecosystem	R&D, Adoption marché

Métriques de succès par phase¶

Q1 2025 : Taux d'auto-résolution ≥ 60%, CSAT ≥ 4.0, Latence E2E ≤ 2.5s
Q2 2025 : 3 canaux actifs, MRR@5 ≥ 0.85, Handover ≤ 30%
Q3 2025 : Multi-langue (FR+AR), Confidence ≥ 0.70, Intégrations CRM
Q4 2025 : 10+ tenants enterprise, SLA 99.9%, Compliance GDPR
Q1 2026 : Voice/Video POC, API ecosystem, Responsible AI