enne2/agy-pi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
agy-pi/docs/tools.md
T
enne2 2137150da3 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

197 lines
8.8 KiB
Markdown
Raw Permalink Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink