docs: documentazione MkDocs completa + fix build + verifica OpenCV dinamica

- Aggiunti docs/ (9 pagine MkDocs, tema Material) + mkdocs.yml - Fix mkdocs.yml: repo_url -> git.enne2.net, tasklist (era taskbuttons), fence Mermaid via helper locale mermaid_fence.py (def_fence_mermaid rimosso da pymdown-extensions moderne) - Documentate le nuove funzionalità: agy_create_verified (generazione verificata con verifica OpenCV DINAMICA generata dall'LLM), workflow vocale a 2 fasi (vocalPlanningMode), chiavi config context/webSearch - tools.md ora documenta 14 tool; vocal-workflow.md include l'overlay di conferma piano; configuration.md include vocalPlanningMode - .gitignore: esclusi site/ e __pycache__/ - Build MkDocs verificata (site/ generato correttamente)
2026-08-11 00:47:23 +02:00
parent a81000912a
commit 2137150da3
12 changed files with 946 additions and 0 deletions
@@ -0,0 +1,196 @@
+# Strumenti Registrati (Tools)
+
+L'estensione `agy-pi` espone **14 strumenti (tools)** all'agente principale `pi`. Ciascun tool è definito tramite schemi strict `TypeBox` e fornisce istruzioni dettagliate al modello su come e quando utilizzarlo.
+
+---
+
+## Tabella Riassuntiva
+
+| Tool | Scopo Principale | Modalità | Timeout Default |
+|---|---|---|---|
+| [`agy`](#1-agy) | Subagent generico multi-turno (chat, image, analyze) | Dynamic | 180s |
+| [`agy_generate`](#2-agy_generate) | Generazione immagini strutturata | Image | 300s |
+| [`agy_edit`](#3-agy_edit) | Editing immagini controllato (Keep+Change+Add) | Image | 300s |
+| [`agy_inpaint`](#4-agy_inpaint) | Inpainting / In-place editing di zone specifiche | Image | 300s |
+| [`agy_style_transfer`](#5-agy_style_transfer) | Trasferimento di stile artistico | Image | 300s |
+| [`agy_compose`](#6-agy_compose) | Fusione / Composizione di più immagini | Image | 300s |
+| [`agy_character`](#7-agy_character) | Consistenza del personaggio tra generazioni | Image | 300s |
+| [`agy_analyze`](#8-agy_analyze) | Analisi file multimediali (immagini, audio, video) | Analyze | 180s |
+| [`agy_transcribe`](#9-agy_transcribe) | Trascrizione audio nativa via Gemini/enne2 API | API | 120s |
+| [`agy_video`](#10-agy_video) | Analisi e ispezione scene/codec file video | Analyze | 180s |
+| [`agy_tts`](#11-agy_tts) | Sintesi vocale Text-To-Speech nativa Gemini | API | 60s |
+| [`agy_models`](#12-agy_models) | Lista modelli disponibili su agy CLI | CLI | 30s |
+| [`agy_conversation`](#13-agy_conversation) | Ispezione e gestione stato conversazione | System | Instant |
+| [`agy_create_verified`](#14-agy_create_verified) | Generazione immagine iterativa con verifica | Image | 300s |
+
+---
+
+## Dettaglio degli Strumenti
+
+### 1. `agy`
+Tool generico per delegare un task ad `agy`. Mantiene lo stato della conversazione (multi-shot reasoning).
+
+- **Parametri**:
+  - `prompt` (`string`, obbligatorio): Il task da inviare ad agy.
+  - `mode` (`"chat" | "image" | "analyze"`, opzionale): Tipo di operazione (default `"chat"`).
+  - `model` (`string`, opzionale): Modello agy (es. `Gemini 3.1 Pro (High)`).
+  - `effort` (`"low" | "medium" | "high"`, opzionale): Livello di reasoning.
+  - `newConversation` (`boolean`, opzionale): Se `true`, azzera lo stato e parte da zero.
+  - `addDir` (`string`, opzionale): Cartella da aggiungere al contesto di workspace agy.
+  - `filePath` (`string`, opzionale): File da allegare.
+  - `yolo` (`boolean`, opzionale): Abilita `--dangerously-skip-permissions`.
+  - `injectContext` (`boolean`, opzionale): Abilita la context injection (default `true`).
+  - `webSearch` (`boolean`, opzionale): Override ricerca web per questo prompt.
+
+---
+
+### 2. `agy_generate`
+Generazione da zero di immagini basata su formule narrative trasparenti per il modello Gemini Image Generation.
+
+- **Formula costruita**: `[Soggetto] + [Azione] + [Luogo] + [Composizione] + [Stile] + [Illuminazione] + [Aspect Ratio]`
+- **Parametri principali**:
+  - `subject` (`string`, obbligatorio): Descrizione del soggetto primario.
+  - `action`, `location`, `composition`, `style`, `lighting`, `aspectRatio` (`string`, opzionali).
+  - `text` (`string`, opzionale): Testo grafico da incorporare.
+  - `negative` (`string`, opzionale): Elementi da evitare.
+  - `outputDir` (`string`, opzionale): Directory in cui salvare l'immagine generata.
+
+---
+
+### 3. `agy_edit`
+Modifica controllata di un'immagine esistente basata sulla regola **Keep + Change + Add + Render**.
+
+- **Best Practice Gemini**: Viene apportata una sola modifica per turno per evitare degrado dell'immagine base.
+- **Parametri principali**:
+  - `baseImage` (`string`, obbligatorio): Percorso dell'immagine sorgente.
+  - `keep` (`string`, obbligatorio): Elementi da mantenere inalterati (posa, luci, volto, ecc.).
+  - `change` (`string`, obbligatorio): La modifica principale richiesta.
+  - `add` (`string`, opzionale): Nuovi elementi da aggiungere.
+  - `render` (`string`, opzionale): Target estetico di output (es. *"fotorealismo editoriale"*).
+  - `preserveAspectRatio` (`boolean`, opzionale): Preserva la proporzione originale.
+
+---
+
+### 4. `agy_inpaint`
+Inpainting / Semantic Masking: modifica un elemento ben circoscritto senza alterare il contesto circostante.
+
+- **Parametri**:
+  - `baseImage` (`string`, obbligatorio): Percorso immagine di partenza.
+  - `target` (`string`, obbligatorio): Oggetto/area specifica da cambiare (es. *"la giacca del soggetto"*).
+  - `replacement` (`string`, obbligatorio): Nuova descrizione dell'oggetto (es. *"un giubbotto in pelle nera"*).
+  - `keepRest` (`string`, opzionale): Dettagli da preservare (default: *"tutto il resto"*).
+
+---
+
+### 5. `agy_style_transfer`
+Trasferimento di stile artistico preservando la composizione e i volumi dell'immagine base.
+
+- **Parametri**:
+  - `baseImage` (`string`, obbligatorio): Immagine sorgente.
+  - `style` (`string`, obbligatorio): Stile di destinazione (es. *"Acquerello Impressionista"*, *"Cyberpunk Neon"*, *"Disegno Tecnico"*).
+  - `preserve` (`string`, opzionale): Cosa mantenere (default: *"la composizione originale"*).
+
+---
+
+### 6. `agy_compose`
+Combina da 2 a 14 immagini in un unico scatto armonioso.
+
+- **Parametri**:
+  - `images` (`string[]`, obbligatorio): Elenco dei percorsi immagine.
+  - `instruction` (`string`, obbligatorio): Istruzioni su quali elementi prendere da ciascuna immagine e come fonderli.
+
+---
+
+### 7. `agy_character`
+Garantisce la consistenza visiva di un personaggio o oggetto attraverso più scatti.
+
+- **Parametri**:
+  - `referenceImage` (`string`, obbligatorio): Immagine di riferimento con la fisionomia del personaggio.
+  - `name` (`string`, obbligatorio): Nome/Token identificativo (es. *"Avatar-Elena"*).
+  - `features` (`string`, obbligatorio): Tratti somatici/caratteristici immutabili.
+  - `task` (`string`, obbligatorio): Nuova azione o contesto in cui inserire il personaggio.
+
+---
+
+### 8. `agy_analyze`
+Analizza in dettaglio qualsiasi file multimediale supportato (immagini, tracce audio o video).
+
+- **Parametri**:
+  - `filePath` (`string`, obbligatorio): Percorso del file.
+  - `question` (`string`, opzionale): Domanda di analisi specifica.
+  - `yolo` (`boolean`, opzionale): Auto-approvazione permessi CLI (obbligatorio per audio/video).
+
+---
+
+### 9. `agy_transcribe`
+Esegue la trascrizione audio ad alta velocità direttamente tramite le API Gemini (`gemini-3.5-flash`) o il server proxy `enne2`.
+
+- **Parametri**:
+  - `filePath` (`string`, obbligatorio): File audio (WAV, MP3, OGG, M4A).
+  - `language` (`string`, opzionale): Lingua parlata (es. `"italiano"`).
+
+---
+
+### 10. `agy_video`
+Ispezione approfondita di clip video: descrizione delle scene, analisi del movimento, verifica traccia audio, codec e risoluzione.
+
+- **Parametri**:
+  - `filePath` (`string`, obbligatorio): Percorso del file video MP4/MOV/MKV.
+  - `question` (`string`, opzionale): Quesito specifico sulla clip.
+
+---
+
+### 11. `agy_tts`
+Converte un testo in parlato e lo riproduce in locale tramite l'API Gemini TTS (`gemini-2.5-flash-preview-tts`).
+
+- **Parametri**:
+  - `text` (`string`, obbligatorio): Testo da sintetizzare.
+  - `play` (`boolean`, opzionale): Riproduci subito l'audio (default `true`).
+  - `outputDir` (`string`, opzionale): Cartella di salvataggio del file WAV risultante.
+
+---
+
+### 12. `agy_models`
+Elenca i modelli LLM e Vision attualmente disponibili nell'installazione di `agy`.
+
+---
+
+### 13. `agy_conversation`
+Strumento di utilità di sistema per ispezionare o azzerare lo stato della conversazione.
+
+- **Parametri**:
+  - `action` (`"id" | "list" | "reset"`, obbligatorio): Action richiesta.
+
+---
+
+### 14. `agy_create_verified`
+Genera un'immagine **conforme a requisiti specifici** tramite un loop iterativo
+self-contained: genera → analizza con visione → verifica con OpenCV dinamico →
+rigenera se necessario. Ideale quando l'orchestratore di `pi` **non ha visione**.
+
+Il loop (fino a `maxIterations`):
+
+```
+1. Genera immagine con agy (mode image) dai requisiti
+2. Analizza con visione testuale → giudice PASS/FAIL vs requisiti
+3. Verifica con OpenCV DINAMICO → script generato dall'LLM ad hoc
+4. Se FAIL → rigenera con prompt di correzione (ri-attacca immagine base)
+```
+
+La **verifica OpenCV è dinamica**: l'LLM genera a runtime uno script
+Python/OpenCV specifico per i requisiti dell'immagine (non metriche hardcodate),
+che restituisce un JSON standard:
+
+```json
+{"pass": true/false, "score": 0..1, "findings": [...], "errors": [...]}
+```
+
+La decisione di conformità combina visione PASS + OpenCV PASS; le `findings`
+OpenCV vengono iniettate nelle issue per guidare la rigenerazione.
+
+- **Parametri**:
+  - `requirements` (`string`, obbligatorio): Requisiti precisi che l'immagine deve soddisfare.
+  - `outputDir` (`string`, opzionale): Cartella di salvataggio dell'immagine finale.
+  - `maxIterations` (`number`, opzionale): Limite iterazioni (default 3, max 5).
+  - `useOpenCV` (`boolean`, opzionale): Esegue la verifica OpenCV dinamica (default `true`).
+  - `model` (`string`, opzionale): Modello agy.