open-edge-platform/vss-summarize-video

VSS Résumer

Exécuter le pipeline de résumé via le Pipeline Manager. Appelez vous-même l'API documentée et rapporter uniquement les réponses observées. Les points de terminaison utilisent le préfixe nginx /manager. Lorsque les outils MCP vss_* sont connectés, vss_summarize_video couvre le même travail ; cette compétence est la voie REST.

Définir HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}.

Contrat de réponse lorsque VSS n'est pas accessible

L'utilisateur peut être loin du déploiement, $HOST peut refuser les connexions, ou une précondition en direct peut échouer (par exemple, le mode résumé est désactivé ou la vidéo nommée est absente). Dans tous ces cas ne pas bloquer et ne pas inventer de réponses. Signaler le blocage observé, puis répondre avec la séquence d'appels exacte et complète que l'utilisateur peut exécuter après l'avoir corrigée : chemins complets des points de terminaison, corps des requêtes / champs de formulaire, le champ que chaque étape reporte de la réponse précédente, et la condition qui indique qu'une étape est terminée. Ne pas abréger ou omettre le flux de résumé demandé simplement parce qu'il n'a pas pu être exécuté. Indiquer clairement quelles commandes n'ont pas été exécutées. Ne jamais terminer la réponse en demandant s'il faut les exécuter.

Configuration de l'environnement (à exécuter en premier)

Cette compétence pilote l'application Video Search & Summarization via ses fichiers sources réels, donc l'application VSS doit être présente et vous devez exécuter les commandes depuis sa racine. Faites ceci avant toute autre chose, et cela fonctionne que la source VSS soit déjà dans votre espace de travail ou non.

Exécutez le bootstrap fourni. Il résout la racine de l'application dans cet ordre et l'affiche comme seule ligne sur la sortie standard :

1. Remonter le répertoire courant à la recherche d'une racine d'application VSS - un répertoire contenant les trois marqueurs setup.sh, docker/, et pipeline-manager/.
2. Demander à git le dépôt englobant (git rev-parse --show-toplevel) et vérifier s'il contient sample-applications/video-search-and-summarization, ou s'il est lui-même une racine d'application VSS. C'est ce qui permet à votre propre clone - ou à un fork - de fonctionner sans modification.
3. Réutiliser un checkout déjà placé par un bootstrap précédent dans ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries.

Si l'un de ceux-ci fonctionne, ce checkout est réutilisé et AUCUN clone n'est exécuté. Ce n'est que lorsque les trois échouent qu'il clone - et seulement un checkout superficiel (--depth 1), à branche unique, partiel de juste sample-applications/video-search-and-summarization depuis main :

# SKILL_DIR est le répertoire DE CETTE compétence (affiché lors du chargement de la compétence) ;
# dans le dépôt, c'est .github/skills/vss-summarize-video. Fonctionne de même si la compétence est installée seule.
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

Chaque commande ci-dessous suppose que le répertoire de travail est ce APP_ROOT. Pour tirer d'un fork/branche ou réutiliser un répertoire de checkout spécifique, redéfinir VSS_REPO_URL, VSS_REPO_BRANCH, ou VSS_CLONE_DIR avant de l'exécuter. Le bootstrap refuse d'écraser une destination de clone non-VSS existante.

Préconditions

1. Backend sain et résumé activé - sonder d'abord ; si ce n'est pas le cas, utiliser la compétence installée vss-troubleshoot ou vss-deploy par nom :

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
   

2. Un videoId à résumer - en téléverser un avec POST /manager/videos (multipart, champ video), qui retourne { "videoId": "…" }. Ou lister ceux existants - noter que la réponse est un objet { "videos": [...] }, pas un tableau nu, et name est un hachage généré (le vrai nom de fichier est dans url / dataStore.fileName):

   curl -s -X POST "$HOST/manager/videos" -F "video=@/chemin/vers/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. Démarrer le pipeline de résumé

POST /manager/summary. Le corps a des champs obligatoires ; l'absence de title, sampling.*, ou evam.evamPipeline retourne 400. Voir references/summary-request.md pour le schéma complet, les surcharges de prompt, et les options audio.

Requête minimale valide :

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Revue du quai de chargement",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

Contrainte d'échantillonnage : le Pipeline Manager impose multiFrame == frameOverlap + samplingFrame. Avec frameOverlap: 0, définir multiFrame == samplingFrame. Non-concordance → 400 « Multi frame mismatch ». evamPipeline est l'un de object_detection | video_ingestion.

Pour résumer seulement une partie d'un clip, ajouter les options sampling.videoStart et sampling.videoEnd (secondes) - par exemple, les dix premières minutes sont "videoStart": 0, "videoEnd": 600.

2. Interroger jusqu'à la fin

Le summaryPipelineId retourné est le stateId. GET /manager/summary/{stateId} n'a pas de champ status/progress au niveau supérieur (seulement /raw en a) - la progression se trouve dans les champs par étape :

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # chaîne, "complete" quand segmenté
  frames:   .frameSummaryStatus,     # objet COUNTS : {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # chaîne : "na" → "inProgress" → "complete"  ← vrai signal de fin
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ L'achèvement est videoSummaryStatus == "complete", PAS summary étant non vide. Le texte final du summary est diffusé en continu de façon incrémentale alors que videoSummaryStatus est encore "inProgress", donc interroger sur "longueur du résumé > 0" retourne un résultat tronqué, en milieu de phrase. Toujours se baser sur videoSummaryStatus. Avec produceFinalSummary: false il n'y a pas d'étape finale - se baser sur frameSummaryStatus.inProgress == 0 à la place.

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

La résumation est lente (VLM par segment + LLM map-reduce) - minutes, pas secondes.

3. Récupérer le résumé

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # résumé final map-reduce
# Les légendes par segment se trouvent dans .frameSummaries[] (chacun : frameKey, status, summary).
# PAS dans .chunks[] - ceux-ci ne portent que {chunkId, duration, audioTranscripts} :
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # tout (audio, frames, status, …)

Présenter le texte final du résumé ; proposer le détail par segment si utile. L'audio sans parole donne un audioTranscriptSummary qui le dit - pas une erreur.

Piste d'audit de la réponse finale

Les arguments des outils peuvent ne pas être visibles pour l'utilisateur ou l'évaluateur. La réponse finale doit donc rapporter le résultat du bootstrap : le APP_ROOT résolu, si un checkout existant a été réutilisé sans clonage, et que les commandes ont été exécutées après être allé dans cette racine d'application. Indiquer également qu'un échec total du bootstrap retombe sur un checkout superficiel (--depth 1), à branche unique, partiel de seulement l'application VSS depuis main. Rapporter les valeurs observées de /manager/health et de la fonctionnalité de résumé.

Pour le workflow de résumé, nommer chaque opération publique du Manager utilisée (méthode et chemin /manager/...), les champs importants de la requête, la réponse observée, et le report de summaryPipelineId à STATE_ID. Lorsqu'une précondition bloque l'exécution, séparer clairement les sondes observées des commandes non exécutées et montrer quand même la requête valide exacte, la condition d'achèvement et l'étape de récupération sans inventer d'identifiants ou de contenu de résumé.

Gestion

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # lister tout
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # supprimer un