Objectif

Exploiter le pipeline d'alertes VSS (détection de mode, abonnements Alert-Bridge, notifications Slack, requêtes, intégration de caméras, personnalisation des prompts de vérification).

Prérequis

• Déploiement VSS actif accessible sur $HOST_IP (voir vss-deploy-profile et references/).
• Identifiants NGC dans $NGC_CLI_API_KEY et $NVIDIA_API_KEY pour les extractions d'images.
• curl, jq et Docker disponibles sur le système appelant.

Instructions

Suivez les tableaux de routage et les workflows étape par étape ci-dessous. Chaque section se terminant par workflow, quick start ou flow est destinée à être exécutée du haut au bas. La documentation de référence se trouve dans references/ et les scripts d'aide dans scripts/ — appelez-les via run_script quand le skill pointe vers un script par nom.

Exemples

Les scénarios exécutables de bout en bout se trouvent sous evals/ (chaque manifeste *.json) ; les blocs curl en ligne apparaissent dans chaque workflow ci-dessous. Relancez avec nv-base validate <this-skill-dir> --agent-eval.

Limitations

Nécessite le profil VSS / microservice correspondant déployé et accessible. Les modèles/NIMs hébergés par NGC sont soumis à des limites de débit, des besoins en mémoire GPU et des conditions de licence ; les limites de concurrence et de stockage dépendent du matériel hôte et du fichier compose du profil.

Dépannage

• Connexion refusée → microservice non actif : sondez /docs ou /health, redéployez via vss-deploy-profile.
• HTTP 401/403 sur extractions NGC → NGC_CLI_API_KEY manquante/expirée : docker login nvcr.io et réexportez la clé.
• OOM / échec de chargement de modèle → mémoire GPU insuffisante : utilisez une variante plus petite ou docker compose down pour libérer les GPUs.

Gestion des alertes VSS

Le profil d'alertes fonctionne dans l'un des deux modes (choisi via /vss-deploy-profile -p alerts -m {verification,real-time}) — voir le tableau The Two Modes ci-dessous. Ce skill route en fonction du mode déployé + intention utilisateur (surveillance vs gestion CRUD d'abonnements vs webhook Slack).

Cas d'utilisation

• Démarrer/arrêter une alerte en temps réel sur un capteur (« Démarrer une alerte en temps réel pour les boîtes déposées sur warehouse_sample »)
• Créer/lister/arrêter les règles d'abonnement en temps réel sur Alert Bridge
• Configurer ou gérer les notifications d'incident Slack
• Lister ou requêter les incidents / alertes détectés ; vérifier les verdicts (confirmé/rejeté/non vérifié)
• Ajouter une nouvelle caméra au pipeline d'alertes ; personnaliser les prompts du vérificateur VLM (mode CV)

Prérequis de déploiement

Nécessite le profil VSS alerts sur $HOST_IP en mode verification (CV) ou real-time (VLM).

# Soit vss-rtvi-cv (mode CV) SOIT vss-rtvi-vlm (mode VLM) doit être présent.
curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && docker ps --format '{{.Names}}' \
     | grep -qE '^(vss-rtvi-cv|vss-rtvi-vlm)$'

Si le sondage échoue, demandez quel mode déployer et passez à /vss-deploy-profile -p alerts -m <mode> (refuser → arrêter ; déploiement autonome pré-autorisé → exécuter directement avec verification par défaut). S'il réussit, détectez le mode selon l'étape 1.

Les deux modes (choix au moment du déploiement)

Changer de mode utilise le flux de destruction + déploiement vss-deploy-profile avec l'autre flag -m (VLM → CV ajoute le pipeline CV ; CV → VLM le déchire). rtvi-vlm s'exécute dans les deux modes.

Étape 1 — Détecter le mode actuellement déployé

Avant d'exécuter un workflow d'alerte, vérifiez quel mode est actif. Utilisez les conteneurs CV uniquement comme signal — vss-rtvi-vlm n'est pas un signal de mode fiable car il s'exécute dans les deux modes.

# Mode CV verification (vss-behavior-analytics + vss-rtvi-cv sont CV uniquement)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics && echo "mode=CV"

# Mode VLM real-time (pas de pipeline CV ; vss-rtvi-vlm s'exécute toujours)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics || \
  docker ps --format '{{.Names}}' | grep -qx vss-rtvi-vlm && echo "mode=VLM"

Si vss-behavior-analytics est présent → mode CV (qui a aussi vss-rtvi-vlm). Si seul vss-rtvi-vlm est présent (et pas de pipeline CV) → mode VLM. Si aucun ne correspond, le profil d'alertes n'est pas déployé — dirigez l'utilisateur vers le skill vss-deploy-profile.

Signal alternatif (préféré quand docker ps n'est pas accessible) : vérifiez le generated.env du profil :

grep -E '^MODE=' deploy/docker/developer-profiles/dev-profile-alerts/generated.env
# MODE=2d_cv   → mode CV (surensemble complet)
# MODE=2d_vlm  → mode VLM real-time (vss-rtvi-vlm uniquement ; pas de vss-rtvi-cv)

Étape 2 — Router selon le mode déployé

Confirmez toujours avant de déclencher un redéploiement. Un changement de mode arrête toute surveillance en cours et redémarre les services.

Précédence d'intention (première correspondance gagne)

1. Workflow E (Slack) — mots-clés spécifiques à Slack (slack, webhook + slack, bot token, slack channel). notify seul n'est pas suffisant.
2. Workflow D (Abonnements) — capteur plus condition de détection, mots-clés CRUD de règle (rule, subscription, ID de règle), ou arrêt/suppression d'une alerte nommée par type/condition (« arrêter l'alerte PPE », « supprimer la règle de collision »). Un alert_type/condition nommé = une règle existante → protocole d'arrêt en deux étapes de D (GET /api/v1/realtime → oui/non confirmer → supprimer), jamais Workflow B.
3. Workflow B (surveillance VLM) — start/stop générique sur un capteur sans condition de détection et sans qualificatif de type d'alerte (« démarrer/arrêter alerte en temps réel pour capteur X »). Un arrêt qui nomme un type (« arrêter l'alerte PPE ») est un arrêt de règle → Workflow D.
4. Workflow C (Query) — recherche d'incident / que s'est-il passé (show/list incidents, recent alerts, requêtes de plage horaire, et formulations informelles « des alertes…? » / « des alertes aujourd'hui ? » / « quoi de déclenché ? »). Un alerts nu (sans rule/subscription/active rules) signifie incidents → Workflow C, jamais Workflow D.
5. Workflow A (CV) — gestion de déploiement CV pour tout ce qui ne correspond pas ci-dessus.

alerts vs alert rules (C vs D) — choisir exactement un, jamais les deux : que s'est-il passé / quoi de déclenché (incidents) → Workflow C (POST /generate). Quelles règles/abonnements sont configurés ou actifs → Workflow D (GET /api/v1/realtime nu, pas /incidents). Un alerts nu = incidents (C) ; alert rules / subscriptions / active rules = inventaire (D). Ne jamais répondre de mémoire ; exécuter l'appel unique correct — détail complet du endpoint dans Workflow C ci-dessous.

Désambiguation (B vs D) : si un capteur est nommé avec langage start/monitor mais la condition de détection est floue, demandez :

« Voulez-vous que je (a) crée une règle d'alerte persistante sur Alert Bridge qui s'exécute jusqu'à ce que vous la supprimiez, ou (b) démarre une session de surveillance unique via l'Agent VSS ? »

Routage d'arrêt (B vs D) : « Arrêter l'alerte <type> » (nomme un alert_type/condition comme PPE, collision, feu) = arrêter une règle d'abonnement → Workflow D (rechercher via GET /api/v1/realtime, puis protocole d'arrêt/confirmation en deux étapes dans references/alert-subscriptions.md ; ne pas appeler POST /generate). Un « arrêter alerte en temps réel / arrêter surveillance sur <capteur> » nu sans qualificatif de type = Workflow B.

Si un prompt mélange les workflows (« démarrer surveillance et envoyer à Slack »), posez une question de clarification pour diviser l'ordre d'exécution.

Texte de refus mode CV pour intentions D et E

Quand le mode déployé est CV verification et l'utilisateur demande une intention d'alerte-abonnement ou Slack/notification, refusez avec ce message textuellement :

« Les abonnements d'alertes et les notifications Slack ne sont pris en charge qu'en mode VLM real-time. Votre déploiement actuel est <CV verification | non déployé>. Pour utiliser ces fonctionnalités, redéployez avec /vss-deploy-profile -p alerts -m real-time (note : basculer détruit la surveillance CV actuelle). »

Pas de redéploiement automatique. L'utilisateur décide s'il faut basculer les modes.

Prérequis pour l'un ou l'autre mode : le capteur doit être dans VIOS

Les deux modes nécessitent que la caméra soit d'abord enregistrée dans VIOS (via le skill vss-manage-video-io-storage) :

• URL RTSP / caméra IP → l'ajouter avec POST /sensor/add (section 6 de ce skill) ; enregistrez le sensorId / nom.
• Capteur existant nommé → confirmez qu'il apparaît dans GET /sensor/list avant de continuer.

Sur CV, l'ajout du RTSP est l'étape d'intégration entière (le pipeline la reprend automatiquement). Sur VLM, c'est un prérequis au Workflow B.

Le endpoint /generate de l'Agent

Toutes les actions de flux VLM et toutes les actions de requête passent par le endpoint de langage naturel de l'Agent VSS :

AGENT="http://<AGENT_ENDPOINT>"   # par défaut http://localhost:8000 sur le profil d'alertes

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "<requête en langage naturel>"}' | jq .

Résolution du endpoint : utilisez le endpoint de l'agent du contexte de déploiement VSS actif. S'il est indisponible, demandez à l'utilisateur. Ne découvrez pas via le système de fichiers.

Vérification de disponibilité : curl -sf --connect-timeout 5 "$AGENT/docs".

N'appelez pas directement les endpoints du microservice rtvi-vlm — passez toujours par l'agent. L'agent dispatch en interne vers rtvi_vlm_alert, rtvi_prompt_gen et video_analytics_mcp.get_incidents.

Workflow A — Mode CV (-m verification / MODE=2d_cv)

Les alertes CV sont pilotées par le déploiement, non par la demande — il n'y a pas d'appel d'agent pour « créer » une.

1. Vérifiez si le capteur est dans VIOS via GET /sensor/list du skill vss-manage-video-io-storage (idempotent — ne faites pas aveuglément POST /sensor/add).
2. S'il manque, intégrez via POST /sensor/add de ce skill. Le pipeline CV reprend automatiquement le flux une fois enregistré et en ligne.
3. Confirmez en ligne : curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/status" | jq .
4. Les alertes arrivent dans Elasticsearch (Behavior Analytics → vérification alert-bridge par alert_type_config.json). Requêtez avec Workflow C.

Une alerte de pipeline CV statique sur un déploiement VLM uniquement est une inadéquation de mode — voir le tableau de routage ci-dessus.

Workflow B — Surveillance VLM en temps réel (mode CV ou VLM)

Intentions start / stop génériques via l'Agent VSS pour un capteur nommé sans condition de détection (si une condition est présente, routez vers Workflow D). rtvi-vlm s'exécute dans les deux modes.

# start: input_message = "Start real-time alert for sensor <id>"
# stop:  input_message = "Stop real-time alert for sensor <id>"
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "<start|stop> real-time alert for sensor <id>"}' | jq .

Coulisse : rtvi_prompt_gen → rtvi_vlm_alert action="start". Chaque chunk est captionné ; un chunk dont la réponse VLM contient yes/true (insensible à la casse) publie un incident sur mdx-vlm-incidents. Les prompts doivent forcer une réponse Oui/Non. Une demande de pipeline CV statique sur un déploiement VLM uniquement est une inadéquation de mode — voir le tableau de routage.

Workflow D — Abonnements aux alertes (mode VLM real-time uniquement)

Créer / lister / supprimer des règles d'alerte en temps réel persistantes sur Alert Bridge. Routez ici quand le prompt a des mots-clés de règle (rule, subscription, un ID de règle) ou quand il apparie un capteur spécifique à une condition de détection spécifique (ex. « Configurer une alerte en temps réel sur warehouse-dock-1 pour violations PPE », « Surveiller capteur entrance-1 pour tailgating », « Arrêter règle 496aebd1-… »).

Pas ici : start/stop générique sans condition (→ Workflow B) ou opérations Slack (→ Workflow E).

Chargez et suivez references/alert-subscriptions.md comme playbook faisant autorité pour CRUD d'abonnements. Mode VLM real-time uniquement ; refusez avec le texte de refus canonique sur CV.

Workflow E — Notifications Slack (mode VLM real-time uniquement)

Utilisez quand l'utilisateur mentionne explicitement Slack ou le relais webhook (démarrer/arrêter serveur webhook, vérifier statut/santé, envoyer message test, définir canal/token Slack). Le mot notify seul n'est pas suffisant.

alert-notify (port 9090) ≠ vss-alert-bridge (/api/v1/realtime). Ne touchez PAS à vss-alert-bridge pour opérations Slack.

Routes ici : « Configurer notifications Slack », « Vérifier si alert-notify s'exécute », « Envoyer alerte test à Slack ». Ne route PAS ici : « Me notifier quand quelqu'un entre la zone » (→ D/B), « Alerter et notifier sur mon téléphone » (ambigu — demandez).

Chargez et suivez references/alert-notify.md. Code dans scripts/alert-notify/. Mode VLM real-time uniquement.

Workflow C — Requête / Liste d'alertes (fonctionne dans l'un ou l'autre mode)

Les alertes générées CV et VLM arrivent dans Elasticsearch et sont requêtables via l'outil video_analytics_mcp.get_incidents de l'agent. Postez les demandes en langage naturel à $AGENT/generate — « Montrez-moi les alertes récentes pour le capteur X », « Lister les alertes confirmées de la dernière heure », « Montrer les incidents de collision de Camera_02 entre <ISO> et <ISO> ».

Les formulations informelles routent aussi ici. Les questions comme « Des alertes aujourd'hui ? », « Quoi de détecté ? » ou « Quelque chose de détecté récemment ? » sont des requêtes d'incident — émettez un POST /generate (ex. {"input_message": "List alerts from today"}) et résumez le résultat. Ne jamais répondre ces questions de mémoire et ne jamais répondre « pas d'alertes » sans exécuter la requête. Une question « alerts » nue est toujours une recherche d'incident (Workflow C), pas une liste de règles d'abonnement (Workflow D).

Ne PAS lister règles d'abonnement pour requête d'incident. Le GET /api/v1/realtime nu (pas /incidents) liste des règles (Workflow D) et est mauvais pour « que s'est-il passé » — ne l'appelez/sondez jamais ou ne chargez le playbook Workflow D pour requête d'incident.

Résultat vide est réponse valide. Si aucun incident ne correspond (ex. système fraîchement déployé sans activité), rapportez qu'aucun n'a été trouvé / le compte est 0 pour la période demandée et ARRÊTEZ — ne tombez pas sur listing de règles ou chasse à d'autres endpoints.

Pour filtrage plus riche / non-langage-naturel (niveau capteur, séries temporelles, comptages) utilisez le skill vss-query-analytics (VA-MCP sur port 9901).

Interprétation de verdict & prompts de vérificateur CV (mode CV uniquement)

Les alertes CV portent un verdict de vérification VLM (confirmed / rejected / unverified) ; les incidents VLM real-time n'ont pas de verdict séparé (le déclenchement est lui-même une réponse Oui/Non VLM). Les prompts de vérificateur de chemin CV sont personnalisables via alert_type_config.json (redémarrez alert-bridge pour appliquer). Voir references/cv-verifier-prompts.md pour tableau de verdicts, significations de champs et règles de personnalisation de prompt.

Liens entre skills

Pièges

• alert-notify (port 9090) ≠ vss-alert-bridge. Opérations Slack → Workflow E (alert-notify) ; ne routez jamais Slack vers /api/v1/realtime de vss-alert-bridge.
• Périmètre workflow par mode : A est CV uniquement ; B et C fonctionnent dans l'un ou l'autre mode ; D et E sont VLM real-time uniquement (refusez sur CV avec texte canonique).
• N'utilisez pas vss-rtvi-vlm comme signal de mode — s'exécute dans les deux modes. Utilisez vss-behavior-analytics (CV uniquement) ou var env MODE.
• Un changement de mode déchire le déploiement actuel — les flux VLM en cours et l'état d'alerte CV non persisté sont perdus.
• Passez toujours par $AGENT/generate — n'appelez jamais rtvi-vlm directement. Le déclencheur VLM est un match de token "yes"/"true" (insensible à casse) ; rtvi_prompt_gen applique le motif Oui/Non, donc ne bricolez pas des prompts qui le cassent.
• Le capteur doit déjà être dans VIOS pour l'un ou l'autre mode (utilisez vss-manage-video-io-storage pour entrées RTSP uniquement).

bump:1