From 666abe765bb477536ffee924e8ccc813a5306a45 Mon Sep 17 00:00:00 2001 From: ALI YESILKAYA Date: Mon, 22 Jun 2026 23:34:38 +0200 Subject: [PATCH] =?UTF-8?q?docs(stt):=20catalogue=20des=20demandes=20possi?= =?UTF-8?q?bles=20=C3=A0=20Asa=20(#54)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ajoute docs/asa-commandes.md : liste complète, classée par capacité, des demandes que l'on peut faire à Asa (avec exemples de phrases FR), bâtie sur l'implémentation réelle (intents client + outils serveur + services du portail) : réveil/veille, santé homelab (host_health/cluster_status), métriques (PromQL), doc Funk (RAG), recherche web, actions admin (confirmation), ouvrir un service, portefeuille, mémoire, contextes. Liée depuis README.md et docs/stt-presentation.md. Co-authored-by: Claude Opus 4.8 --- README.md | 1 + docs/asa-commandes.md | 140 +++++++++++++++++++++++++++++++++++++++ docs/stt-presentation.md | 2 + 3 files changed, 143 insertions(+) create mode 100644 docs/asa-commandes.md diff --git a/README.md b/README.md index fe522d7..aadcc92 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,7 @@ calling) pour répondre à partir de données réelles. | 🗣️ **Veille/réveil** | « Asa » réveille · « Asa stop » endort | 📖 **Présentation complète (schémas de la chaîne + captures)** : [`docs/stt-presentation.md`](docs/stt-presentation.md) +· 🗣️ **Ce que tu peux lui demander** : [`docs/asa-commandes.md`](docs/asa-commandes.md) · Détails techniques : [`admin/ia/stt.md`](admin/ia/stt.md) --- diff --git a/docs/asa-commandes.md b/docs/asa-commandes.md new file mode 100644 index 0000000..e1cfdf8 --- /dev/null +++ b/docs/asa-commandes.md @@ -0,0 +1,140 @@ +# Ce que tu peux demander à Asa + +Catalogue des demandes possibles à l'assistant vocal **Asa** (par la voix ou en tapant dans le +HUD). La plupart passent par le contexte agentique **`asa`** (par défaut) : Asa **choisit seule** +le bon outil. Quelques demandes sont des **intents déterministes** traités côté client (avant +même d'appeler le modèle) — signalés par 🎯. + +> Tu n'as pas besoin de dire le mot « outil » ni de choisir un contexte : formule naturellement. +> Astuce : commence par « Asa, … » pour la réveiller si elle est en veille. + +--- + +## 🗣️ Réveil / veille + +| Demande | Effet | +|---|---| +| « **Asa** » | Réveille l'assistante (sort de veille) | +| « Asa, » | Réveille **et** exécute la question | +| « **Asa stop** », « dors », « au revoir », « bonne nuit », « silence » | La remet en **veille** (n'écoute plus que le mot de réveil) | + +--- + +## 🩺 État & santé du homelab *(outils `host_health`, `cluster_status`)* + +Données **live** (Prometheus) — Asa va chercher l'info réelle, pas la doc. + +- « Est-ce que **gpu-01** tourne bien ? » +- « Et **storage-01** ? » +- « Donne-moi la **température**, la **VRAM** et la **puissance** du GPU » +- « Quelle est l'**utilisation CPU** de gpu-01 ? » · « Combien de **RAM libre** sur storage-01 ? » +- « Quel est l'**uptime** de storage-01 ? » · « L'espace **disque** est‑il ok ? » +- « Est-ce que le **cluster** va bien ? » · « Combien de **pods** tournent ? » +- « Y a-t-il des **pods en erreur** / en CrashLoop ? » · « Les **nœuds Kubernetes** sont‑ils prêts ? » +- « Est-ce que **llama-server** est en ligne ? » + +## 📈 Métriques précises *(outil `prometheus_query`)* + +Pour une métrique pointue non couverte ci-dessus, Asa peut écrire une requête PromQL : + +- « Combien de **cibles Prometheus** sont up ? » +- « Quelle est la **charge** des nœuds du cluster ? » +- « Montre-moi la **consommation mémoire** des pods du namespace ai. » + +## 🚨 Alertes *(contexte alerting / Alertmanager)* + +- « Y a-t-il des **alertes** actives ? » · « Qu'est-ce qui **ne va pas** en ce moment ? » + +--- + +## 📚 Documentation Funk *(outil `search_docs` — RAG)* + +Questions sur la **conception / la config** du homelab (répond depuis la doc `admin/`) : + +- « Comment **relancer dnsmasq** ? » +- « Quelle est la config **nftables** pour le cluster ? » +- « Quels **profils Hermes** existent et quels modèles utilisent-ils ? » +- « Comment fonctionne le **RAG** / l'ingestion de la doc ? » +- « Quelle est l'architecture **réseau / VLAN** de Funk ? » +- « C'est quoi le **watchdog** de llama-server ? » + +--- + +## 🌐 Recherche web *(outil `web_search` — SearXNG privé)* + +Pour tout ce qui est **hors homelab** ou **récent** : + +- « **Cherche sur le web** la dernière version de Kubernetes. » +- « Quelles sont les **nouveautés** de ROCm 7 ? » +- « Trouve la **doc officielle** de SearXNG. » +- « C'est quoi le **CVE** récent sur … ? » + +--- + +## 🤖 Actions d'administration *(outil `admin_action` — confirmation requise)* + +Asa **propose** l'action puis attend ton **« confirme »** avant d'exécuter (via Hermes). Dis +« annule » pour abandonner. + +- « **Redémarre** le déploiement open-webui. » → *« Tu veux que j'exécute : … ? »* → « **confirme** » +- « **Relance** le pod n8n. » · « **Redémarre** litellm sur storage-01. » +- « **Ré-ingère** la doc dans le RAG. » + +> ⚠️ Réservé aux demandes explicites d'agir, toujours derrière confirmation + jeton. Pour de la +> simple lecture, Asa n'utilise jamais cet outil. + +--- + +## 🧭 Ouvrir un service 🎯 *(intent client : « ouvre / lance / montre »)* + +Ouvre la page du service dans le navigateur. Le `` accepte plusieurs **alias** : + +| Service | Dis par ex. | +|---|---| +| **Ghostfolio** | « ouvre le **portefeuille** », « ouvre **ghosto** », « montre la **bourse** » | +| **Grafana** | « ouvre **grafana** », « affiche le **monitoring** / **dashboard** » | +| **ArgoCD** | « ouvre **argo** », « montre les **déploiements** / **gitops** » | +| **n8n** | « ouvre **n8n** », « lance les **workflows** / l'**automatisation** » | +| **Open WebUI** | « ouvre le **chat** / **webui** / l'**interface IA** » | +| **Prometheus** | « ouvre **prometheus** / les **métriques brutes** » | +| **Alertmanager** | « ouvre les **alertes** / **alarmes** » | + +## 🟢 Santé du portail 🎯 *(intent : « état du cluster / des services »)* + +- « **État du cluster** » · « État des **services** » · « Comment va l'**infra** ? » → résumé santé live des tuiles du portail. + +--- + +## 💰 Portefeuille Ghostfolio 🎯 *(intent : « combien sur mon ghostfolio »)* + +- « **Combien** sur mon **ghostfolio** ? » · « Quelle est la **valeur** de mon **portefeuille** ? » +- « Combien je **vaux** en bourse ? » + +--- + +## 🧠 Mémoire & conversation + +Asa garde le **fil** de la session et une **mémoire long terme** (Qdrant). Tu peux donc enchaîner : + +- « Et **storage-01** ? » (après avoir parlé de gpu-01) +- « **Rappelle-toi** que je préfère les réponses courtes. » +- Pour repartir de zéro : bouton **reset** du HUD (ou « **réinitialise** la conversation »). + +--- + +## 🧩 Contextes (avancé) + +Par défaut Asa est en contexte **`asa`** (outils). Le HUD permet d'en présélectionner d'autres +(sélecteur en haut à droite) pour cadrer la réponse : + +| Contexte | Pour | +|---|---| +| **asa** | Tout — Asa choisit ses outils *(défaut)* | +| **funk** | Q&A strict sur la **doc** uniquement (grounding strict) | +| **ghostfolio** / **grafana** / **alerting** / **cluster** | Réponses cadrées sur une source live précise | + +--- + +> Catalogue lié à l'implémentation réelle (`stt/client/stt/portal/intents.py`, +> `stt/server/stt_server/tools.py`, `contexts.py`). Vue d'ensemble : +> [`docs/stt-presentation.md`](stt-presentation.md) · détails : [`admin/ia/stt.md`](../admin/ia/stt.md). diff --git a/docs/stt-presentation.md b/docs/stt-presentation.md index ca8c77e..8df941d 100644 --- a/docs/stt-presentation.md +++ b/docs/stt-presentation.md @@ -100,6 +100,8 @@ Si Asa veut **agir** (`admin_action`), la boucle s'arrête et elle **propose** ; ## Ce qu'Asa sait faire +> 🗣️ **Liste complète des demandes possibles (exemples de phrases)** : [`asa-commandes.md`](asa-commandes.md). + | Capacité | Comment | Outils / sources | |---|---|---| | 🔎 **Savoir** | Doc Funk + **état live** du homelab, l'outil est choisi par le modèle | `search_docs` (RAG), `host_health`, `cluster_status`, `prometheus_query` |