📄 Spec Technique : Module Circuy AI "Page-Skill" & Dynamic Agent

1. Vision & Architecture Globale

Le module Page-Skill permet à l'agent Circuy d'apprendre la structure fonctionnelle d'une page à partir du DOM rendu (Accessibility Tree) pour générer instantanément des visites guidées (Shepherd.js) en réponse aux questions en langage naturel des utilisateurs.

┌─────────────────────────────────────────────────────────────────────────────┐
│ PAGE WEB CLIENT (DOM Rendu)                                                │
│                                                                             │
│  [ Input Client ]    [ Select Pays ]    [ Btn Valider ]                     │
└──────┬──────────────────────────────────────────────────────────────────────┘
       │
       │ 1. Scan DOM / A11y Tree Extraction (SDK JS)
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CIRCUY OVERLAY / CONTENT SCRIPT                                             │
│                                                                             │
│  - Masquage PII / Anonymisation                                             │
│  - Simplification : Balises interactives + aria-* + data-*                  │
└──────┬──────────────────────────────────────────────────────────────────────┘
       │
       │ 2. Payload Anonymisé (JSON A11y)
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CIRCUY BACKEND (Hono / Node.js + LLM Engine)                                │
│                                                                             │
│  ┌──────────────────────────────┐     ┌──────────────────────────────────┐  │
│  │ A. Mode Recording            │     │ B. Mode Runtime Question         │  │
│  │  Generates Page-Skill JSON   │  OR │  Maps Intent -> Shepherd.js JSON │  │
│  └──────────────┬───────────────┘     └────────────────┬─────────────────┘  │
└─────────────────┼──────────────────────────────────────┼────────────────────┘
                  │                                      │
                  ▼                                      ▼
┌──────────────────────────────────┐   ┌──────────────────────────────────────┐
│ DB / Vector Store (Scaleway/OVH) │   │ SDK Client (Exécute le Tour)         │
│ Table: `page_skills`             │   │ `shepherd.addSteps().start()`        │
└──────────────────────────────────┘   └──────────────────────────────────────┘

2. Étape 1 : Le Moteur d'Extraction & Anonymisation (SDK JS)

Le SDK extrait un sous-ensemble minimal du DOM pour ne pas surcharger la fenêtre de context du LLM (token-efficiency) et protéger la vie privée (RGPD).

2.1 Algorithme de Filtrage (A11y Tree Builder)

Le script parcourt le DOM et filtre uniquement les éléments possédant une sémantique d'interaction :

• Éléments conservés : a, button, input, select, textarea, [role="button"], [role="checkbox"], [role="menuitem"], [data-testid], headings (h1-h3), et conteneurs de formulaire (form).
• Propriétés extraites : tagName, id, name, type, aria-label, placeholder, innerText (écourté à 30 chars), data-attributes, et un Sélecteur CSS Résilient .

2.2 Anonymisation des Données Sensibles (PII Masking)

Avant tout envoi au serveur, le SDK applique un masque d'expressions régulières (Regex) sur le texte et les valeurs des inputs :

• Adresses e-mail $\rightarrow$ [EMAIL]
• Numéros de téléphone / CB $\rightarrow$ [SENSITIVE_NUMERIC]
• Valeurs des champs texte saisis par l'utilisateur (input.value) $\rightarrow$ Jamais extraites, seul le placeholder ou le associé est envoyé.

2.3 Structure de données envoyée au Backend (A11yNode[])

// types/ai.ts
export interface A11yNode {
  id: string;
  tag: string;
  type?: string;
  label?: string;
  placeholder?: string;
  role?: string;
  selector: string; // Sélecteur résilient généré par le SDK
  isInteractive: boolean;
}

export interface PageScanPayload {
  urlPattern: string; // Ex: /finance/invoices/*
  pageTitle: string;
  nodes: A11yNode[];
}

3. Étape 2 : Le Modèle de Données "Page-Skill"

Lorsqu'un créateur/admin enregistre une page, le backend passe le PageScanPayload au LLM pour générer un Page-Skill JSON structuré.

3.1 Schéma de la table PostgreSQL (page_skills)

CREATE TABLE page_skills (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  organization_id UUID NOT NULL REFERENCES organizations(id),
  name VARCHAR(255) NOT NULL, -- ex: "Création de Facture"
  route_pattern VARCHAR(512) NOT NULL, -- ex: "/app/invoices/new"
  summary TEXT NOT NULL, -- Description globale par le LLM
  actions_json JSONB NOT NULL, -- Liste des intents et sélecteurs
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_page_skills_org_route ON page_skills(organization_id, route_pattern);

3.2 Structure du JSON de Skill (actions_json)

{
  "summary": "Formulaire de création de facture client avec sélection d'articles et tva.",
  "intents": [
    {
      "intent_id": "select_client",
      "user_goal": "Choisir ou changer de client",
      "selector": "#client-select-dropdown",
      "fallback_selector": "select[name='clientId']",
      "action_type": "click"
    },
    {
      "intent_id": "add_discount",
      "user_goal": "Appliquer une remise ou un pourcentage de réduction",
      "selector": "[data-testid='invoice-discount-input']",
      "fallback_selector": "input[name='discount']",
      "action_type": "input"
    }
  ]
}

4. Étape 3 : Execution Runtime (Question $\rightarrow$ Tour Shepherd.js)

Quand l'utilisateur pose une question dans le widget flottant Circuy ( "Comment ajouter une remise ?" ) :

4.1 Prompt Système LLM (Hono Backend)

Le backend récupère le Page-Skill associé à l'URL courante et envoie la requête suivante au LLM (ex: Claude 3.5 Sonnet ou GPT-4o) avec Structured Outputs (JSON Schema) :

Tu es l'agent d'exécution UI de Circuy.
A partir de la question de l'utilisateur et du "Page-Skill" fourni, génère les étapes d'un tour Shepherd.js.

RÈGLES STRICTES :
1. N'utilise QUE les sélecteurs CSS fournis dans le Page-Skill.
2. Chaque étape doit comporter un titre court et un texte explicatif concis.
3. Retourne un tableau d'étapes au format JSON strict.

[PAGE SKILL]
{actions_json}

[QUESTION UTILISATEUR]
"{user_query}"

4.2 Reponse JSON générée par le LLM

{
  "tour_id": "dynamic_ai_tour",
  "steps": [
    {
      "attachTo": {
        "element": "[data-testid='invoice-discount-input']",
        "on": "bottom"
      },
      "title": "Saisir la remise",
      "text": "Entrez ici le pourcentage de réduction à appliquer à la facture.",
      "buttons": [
        {
          "text": "Terminé",
          "action": "next"
        }
      ]
    }
  ]
}

5. Étape 4 : Intégration SDK Client & Shepherd.js

Le SDK réagit à la réponse de l'API et démarre le guide interactif dans la page hôte.

// sdk/src/ai-agent.ts
import Shepherd from 'shepherd.js';

export async function handleUserQuestion(question: string) {
  const currentPath = window.location.pathname;

  // 1. Appel API au backend Circuy
  const response = await fetch('https://api.circuy.com/v1/ai/ask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ question, route: currentPath })
  });

  const { steps } = await response.json();

  if (!steps || steps.length === 0) {
    showFallbackMessage("Désolé, je n'ai pas trouvé l'élément correspondant sur cette page.");
    return;
  }

  // 2. Instanciation dynamique du tour Shepherd.js
  const tour = new Shepherd.Tour({
    defaultStepOptions: {
      cancelIcon: { enabled: true },
      classes: 'circuy-shepherd-theme',
      scrollTo: { behavior: 'smooth', block: 'center' }
    }
  });

  // 3. Injection des étapes générées par l'IA
  steps.forEach((step: any) => {
    tour.addStep({
      id: step.attachTo.element,
      text: step.text,
      title: step.title,
      attachTo: step.attachTo,
      buttons: [
        {
          text: 'Compris',
          action: tour.next
        }
      ]
    });
  });

  // 4. Lancement du parcours
  tour.start();
}

6. Sécurité & Robustesse

1. Sélecteurs de secours (Fallback Selectors) : Si le sélecteur principal n'est pas trouvé dans le DOM au moment du tour.start(), le SDK tente automatiquement d'utiliser le fallback_selector généré lors de l'apprentissage du Page-Skill.
2. Isolation CSS de l'Infobulle : Les styles Shepherd.js de Circuy sont appliqués avec une classe préfixée (.circuy-shepherd-theme) et encapsulés pour ne pas impacter le CSS du site client.
3. Budget Tokens / Latence : En stockant les Page-Skills pré-calculés en BDD, la requête runtime de l'utilisateur n'envoie que la question + le JSON du skill (environ 500 tokens), garantissant une réponse sous < 800ms .

7. Gouvernance & Workflow de Validation (Human-in-the-Loop)

Afin de garantir la qualité et la pertinence des guides sur les environnements de production, tout parcours généré dynamiquement par le LLM est soumis à un statut de modération strict. Lorsqu'une question d'un utilisateur déclenche la création d'un nouveau guide, celui-ci est exécuté uniquement pour l'utilisateur demandeur en mode éphémère et simultanément enregistré dans la base de données avec le statut pending_review. Une notification est envoyée dans l'espace d'administration (ou sur Slack/Teams) de l'équipe Produit/Admin. Tant que le parcours n'a pas été relu, éventuellement ajusté et explicitement approuvé par un administrateur (status: 'published'), il reste invisible pour l'ensemble des autres utilisateurs de la plateforme. Cela permet de bénéficier de la réactivité de l'IA tout en maintenant un contrôle qualité total sur la documentation et l'UX globale.