enne2/agy-pi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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)
This commit is contained in:
Matteo Benedetto
2026-08-11 00:47:23 +02:00
parent a81000912a
commit 2137150da3
12 changed files with 946 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+97
View File
@@ -0,0 +1,97 @@
# Architettura di agy-pi
Questo documento descrive la struttura interna e il ciclo di vita dell'estensione `agy-pi`, spiegando l'interazione tra l'agente host (`pi`), l'estensione Node.js/TypeScript e il subagent CLI (`agy`).
---
## Architettura dei Componenti
L'estensione `agy-pi` fa da ponte tra l'ambiente di esecuzione di `pi` e la CLI `agy` / API Google Gemini:
```mermaid
sequenceDiagram
autonumber
actor User as Utente / Tastiera (F12)
participant PI as pi Agent Core
participant EXT as agy-pi (extensions/index.ts)
participant FFMPEG as ffmpeg & Audio Subsystem
participant AGY as agy CLI (Antigravity)
participant GEMINI as Google Gemini API
rect rgb(30, 40, 60)
note over User, EXT: Workflow Vocale F12
User->>EXT: Pressione F12 (Start Record)
EXT->>FFMPEG: Spawn ffmpeg (pulse -> wav 16kHz)
EXT->>User: Audio sound "start" (aevalsrc)
User->>EXT: Pressione F12 (Stop Record)
EXT->>FFMPEG: SIGINT & optimizeAudio (silenceremove)
EXT->>GEMINI: POST generateContent (Audio Opus/OGG + STT)
GEMINI-->>EXT: Trascrizione testuale
EXT->>EXT: Legge editorText & unisce contesto sessione
EXT->>AGY: Interpretation prompt via executeAgy()
AGY-->>EXT: Testo interpretato finale
EXT->>PI: sendUserMessage(finalText)
end
rect rgb(40, 50, 30)
note over PI, AGY: Tool Execution Workflow
PI->>EXT: Execute Tool (es. agy_generate)
EXT->>EXT: buildContextBlock() [Env + Memory + Web]
EXT->>AGY: execFileAsync(agy -p prompt --output-format json)
AGY-->>EXT: JSON Output & IMAGE_PATH
EXT-->>PI: ToolResult { content, details }
end
```
---
## Moduli Funzionali
### 1. Engine di Gestione dello Stato e Persistenza
L'estensione mantiene lo stato sia in memoria sia su disco attraverso diverse strutture dati:
- **Conversazione agy Multi-Turno**:
- `~/.agy-chat/conversation_id`: File di testo contenente l'ID dell'ultima conversazione attiva.
- `~/.gemini/antigravity-cli/conversations/`: Cartella gestita dalla CLI `agy` contenente i file SQLite `.db` con la cronologia dei turni.
- **Configurazione Persistente (`AgyConfig`)**:
- `~/.config/agy-pi/config.json`: File protetto (permessi `0600`) che mantiene le preferenze di sistema (modello di default, backend STT/TTS, token budget, ecc.).
- **Memoria Durevole (`DurableMemory`)**:
- `~/.config/agy-pi/memory.json`: Archivio dei fatti rilevanti (obiettivi, decisioni, convenzioni, questioni aperte) aggiornato in modo automatico.
### 2. Wrapper di Esecuzione `executeAgy()`
Tutte le interazioni con il binario `agy` passano attraverso la funzione asincrona `executeAgy()`:
```typescript
interface AgyExecOptions {
prompt: string;
mode?: "chat" | "image" | "analyze";
model?: string;
effort?: "low" | "medium" | "high";
newConversation?: boolean;
stateless?: boolean;
addDirs?: string[];
filePaths?: string[];
yolo?: boolean;
timeoutMs?: number;
outputDir?: string;
signal?: AbortSignal;
contextBlock?: string;
}
```
#### Risoluzione Bug Output Format (`--output-format json`)
Quando `agy` viene eseguito in modalità non interattiva (piped/redirected), la CLI non scrive su `stdout` grezzo. Per superare questo limite, `executeAgy` aggiunge automaticamente il flag `--output-format json`, parsando la proprietà `.response` dell'oggetto ritornato.
---
## Ciclo di Vita di una Chiamata Tool
1. **Invocazione del Tool**: `pi` seleziona uno dei 13 tool registrati ed esegue il metodo `execute()`.
2. **Costruzione del Prompt**: Il tool trasforma i parametri strutturati in un prompt narrativo (es. aggiungendo `IMAGE_PATH` o clausole `Keep+Change+Add+Render`).
3. **Context Injection**: Se abilitato (`contextInject = true`), viene inserito il blocco `<CONTEXT_AGENTE>` preparato da `buildContextBlock()`.
4. **Esecuzione CLI / API**: Invocazione del binario `agy` con gestione dei timeout (3 min per chat/analisi, 5 min per immagini).
5. **Post-Processing Asset**: Se viene generata un'immagine, la funzione `extractImagePath()` rileva il percorso dall'output e `copyImage()` lo duplica eventualmente nella cartella di destinazione `outputDir`.
6. **Aggiornamento Stato**: Se la chiamata è stateful, l'ID della conversazione viene aggiornato in `~/.agy-chat/conversation_id`.
7. **Ritorno a pi**: Restituzione del risultato formattato secondo la specifica di `pi` (`{ content, details }`).
docs/cli-wrapper.md
+70
View File
@@ -0,0 +1,70 @@
# Wrapper Script CLI (`bin/agy-chat.sh`)
Oltre all'estensione TypeScript per `pi`, il repository include lo script di utilità Bash standalone **`bin/agy-chat.sh`**.
---
## Scopo dello Script
Lo script permette di eseguire conversazioni multi-turno con `agy` direttamente dal terminale shell, mantenendo la persistenza dell'ID conversazione in `~/.agy-chat/conversation_id` esattamente come fa l'estensione Node.js.
---
## Sintassi & Parametri
```bash
./bin/agy-chat.sh [OPZIONI] "PROMPT"
```
### Tabella dei Parametri
| Opzione | Descrizione |
|---|---|
| `"prompt"` | Il prompt o task da inviare ad `agy` |
| `--new` | Forza l'avvio di una nuova conversazione (ignora l'ID salvato) |
| `--reset` | Elimina il file di stato `conversation_id` ed esce |
| `--id` | Stampa l'ID della conversazione attualmente attiva ed esce |
| `--list` | Elenca le conversazioni recenti salvate nel database SQLite di `agy` |
| `--resume <id>` | Riprende una conversazione specifica indicando il suo ID |
| `--model <nome>` | Specifica il modello LLM (es. `--model "Gemini 3.1 Pro (High)"`) |
| `--effort <livello>` | Livello di reasoning: `low` \| `medium` \| `high` |
| `--add-dir <path>` | Aggiunge una directory al contesto di lavoro di `agy` |
| `--yolo` | Passa il flag `--dangerously-skip-permissions` ad `agy` |
---
## Esempi d'Uso
### 1. Avviare o Continuare una Conversazione
```bash
./bin/agy-chat.sh "Spiegami la differenza tra REST e GraphQL"
```
### 2. Continuare la Conversazione (Multi-Turno)
```bash
./bin/agy-chat.sh "Puoi fare un esempio in TypeScript per la risposta precedente?"
```
### 3. Forzare una Nuova Conversazione con Modello Specifico
```bash
./bin/agy-chat.sh --new --model "Gemini 3.1 Pro (High)" --effort high "Disegna l'architettura di un sistema a microservizi"
```
### 4. Gestione dello Stato
```bash
# Mostra l'ID attivo
./bin/agy-chat.sh --id
# Elenca tutte le conversazioni salvate
./bin/agy-chat.sh --list
# Ripristina lo stato
./bin/agy-chat.sh --reset
```
---
## Variabili d'Ambiente Supportate
- **`AGY_CHAT_STATE`**: Directory del file di stato (default: `~/.agy-chat`).
- **`AGY_BIN`**: Percorso dell'eseguibile `agy` (default: `agy` presente nel `PATH`).
docs/commands-keybindings.md
+88
View File
@@ -0,0 +1,88 @@
# Comandi Slash & Scorciatoie da Tastiera
`agy-pi` mette a disposizione un ricco set di comandi slash interattivi e scorciatoie globali per interagire con l'estensione direttamente dal terminale di `pi`.
---
## Comandi Slash (Slash Commands)
### Gestione Conversazione agy
| Comando | Descrizione | Sintassi / Esempio |
|---|---|---|
| `/agy` | Invia un prompt diretto al subagent `agy` | `/agy Spiega la teoria della relatività` |
| `/agy:new` | Forza la creazione di una nuova conversazione pulita | `/agy:new` |
| `/agy:list` | Mostra l'ID della conversazione agy attiva | `/agy:list` |
| `/agy:reset` | Azzera l'ID conversazione salvato in locale | `/agy:reset` |
---
### Configurazione & Diagnostica TUI
#### `/agy:config`
Gestisce le opzioni di configurazione salvate in `~/.config/agy-pi/config.json`.
- `/agy:config`: Mostra l'elenco completo di tutte le opzioni con i valori attuali e le descrizioni.
- `/agy:config get <chiave>`: Stampa il valore di una singola chiave.
- `/agy:config set <chiave> <valore>`: Modifica il valore di una chiave e salva su disco.
- `/agy:config reset`: Ripristina le impostazioni predefinite di fabbrica.
#### `/agy:key` (Dialog TUI Overlay)
Apre una finestra di dialogo grafica in sovrimpressione nel terminale (`pi-tui` overlay) per inserire o modificare la chiave API Gemini:
```
┌────────────────────────────────────────────────────────┐
│ 🔑 Chiave API Gemini │
│ Attuale: AIza...yfDY │
│ │
│ Nuova chiave: ••••••••••••••••••••••••••••••••••••• │
│ │
│ Digita la chiave • Enter conferma • Esc annulla │
└────────────────────────────────────────────────────────┘
```
- Input mascherato per prevenire il leak della chiave sul terminale o nella cronologia.
- Salva contemporaneamente la chiave in `~/.config/agy-pi/config.json` e in `~/.agy-chat/gemini-key` (permessi `0600`).
#### `/agy:status` (Diagnostica TUI Overlay)
Mostra una dashboard grafica centrata con lo stato di salute dell'estensione:
```
┌────────────────────────────────────────────────────────┐
│ 📊 Stato agy-pi │
│ │
│ Binario agy: trovato /home/enne2/.local/bin/agy │
│ Versione: agy version 1.4.2 │
│ Chiave Gemini: ✅ valida │
│ Chiave (mask): AIza...yfDY │
│ Modello attivo: Gemini 3.1 Pro (High) │
│ Backend STT: gemini │
│ Notifiche TTS: true │
│ │
│ Ultimo errore: (nessuno) │
│ │
│ Enter o Esc per chiudere │
└────────────────────────────────────────────────────────┘
```
---
### Registrazione Vocale & TTS
| Comando | Descrizione |
|---|---|
| `/agy:record` | Avvia o ferma la registrazione vocale (equivalente al tasto **F12**). |
| `/agy:record:stop` | Ferma la registrazione attiva ed elabora l'audio. |
| `/agy:record:cancel` | Annulla la registrazione corrente senza inviare prompt. |
| `/agy:speak <testo>` | Sintetizza ed esegue l'audio del testo specificato via Gemini TTS. |
| `/agy:vocal [on\|off\|status]` | Attiva (`on`), disattiva (`off`) o mostra lo stato (`status`) del feedback vocale automatico TTS. |
---
## Scorciatoie da Tastiera (Keybindings)
### Tasto `F12` — Registrazione Vocale Toggle
- **Primo tocco (`F12`)**: Avvia la registrazione audio tramite `ffmpeg`, riproduce il suono sci-fi *Power Up* e mostra la barra di stato live `🔴 REGISTRAZIONE... MM:SS / MM:SS`.
- **Secondo tocco (`F12`)**: Interrompe la registrazione, riproduce il suono *Deactivate*, ottimizza l'audio (soppressione silenzio), invia la traccia a Gemini per la trascrizione e trasmette il prompt risultante a `pi`.
### Tasto `Esc` / `Escape` — Annullamento Registrazione
- Durante una registrazione audio attiva, premere `Esc` o `Escape` abortisce immediatamente il processo `ffmpeg`, rimuove il file temporaneo, riproduce il tono acustico di cancellazione e cancella l'indicatore di stato.
docs/configuration.md
+87
View File
@@ -0,0 +1,87 @@
# Sistema di Configurazione
L'estensione `agy-pi` implementa un sistema di configurazione gerarchico e persistente, progettato per garantire massima sicurezza ed elasticità sia in ambienti locali che server.
---
## File di Configurazione (`config.json`)
Le impostazioni vengono memorizzate nel file JSON:
`~/.config/agy-pi/config.json`
!!! security "Sicurezza e Permessi"
Il file `config.json` viene creato con permessi restrittivi `0600` (leggibile e modificabile unicamente dall'utente proprietario del processo) per prevenire l'accesso non autorizzato alle chiavi API memorizzate.
---
## Gerarchia delle Risoluzione Chiavi
Quando un modulo o un tool dell'estensione richiede un valore di configurazione (es. `geminiApiKey`), l'estensione segue questa priorità:
```mermaid
graph TD
ENV[1. Variabili d'Ambiente System/Shell] -->|Se assente| CONFIG[2. File ~/.config/agy-pi/config.json]
CONFIG -->|Se assente| SECRET[3. File ~/.agy-chat/gemini-key]
SECRET -->|Se assente| DEFAULT[4. Valore Default di Fabbrica CONFIG_DEFAULTS]
```
---
## Tabella delle Opzioni di Configurazione
| Chiave | Tipo | Default | Descrizione |
|---|---|---|---|
| `geminiApiKey` | `string` | `undefined` | Chiave API Google Gemini (usata per STT, TTS e Web Search grounding). |
| `enne2ApiKey` | `string` | `undefined` | Bearer token opzionale per l'autenticazione verso il proxy `ai.enne2.net`. |
| `sttBackend` | `string` | `"gemini"` | Backend per la trascrizione vocale: `"gemini"` \| `"enne2"`. |
| `sttUrl` | `string` | `"https://ai.enne2.net"` | URL endpoint base per il backend STT enne2. |
| `sttModel` | `string` | `"gemma4:E4B"` | Identificativo modello per il backend STT enne2. |
| `sttMaxDuration` | `number` | `120` | Durata massima della registrazione audio in secondi. |
| `ttsBackend` | `string` | `"gemini"` | Backend per la sintesi vocale: `"gemini"` \| `"enne2"`. |
| `ttsNotify` | `boolean` | `true` | Abilita o disabilita le notifiche acustiche/vocali automatiche a fine trascrizione. |
| `ttsModel` | `string` | `"gemini-2.5-flash-preview-tts"` | Modello Gemini dedicato al Text-To-Speech. |
| `agyBin` | `string` | `"agy"` | Percorso assoluto o nome del binario eseguibile `agy`. |
| `agyDefaultModel` | `string` | `undefined` | Modello predefinito per le chiamate ad `agy` (es. `Gemini 3.1 Pro (High)`). |
| `agyTimeoutMs` | `number` | `180000` | Timeout generale in millisecondi per l'esecuzione di `agy` (3 minuti). |
| `contextInject` | `boolean` | `true` | Iniezione automatica del contesto dell'agente nel prompt `agy`. |
| `contextTokens` | `number` | `1500` | Budget massimo di token allocato per il blocco di contesto iniettato. |
| `webSearch` | `string` | `"auto"` | Modalità ricerca web (Strada A): `"auto"` \| `"on"` \| `"off"`. |
| `vocalPlanningMode` | `boolean` | `true` | Workflow vocale a 2 fasi: piano + conferma in overlay prima di eseguire. |
---
## Esempio di File `config.json`
```json
{
"sttBackend": "gemini",
"sttUrl": "https://ai.enne2.net",
"sttModel": "gemma4:E4B",
"sttMaxDuration": 120,
"ttsBackend": "gemini",
"ttsNotify": true,
"ttsModel": "gemini-2.5-flash-preview-tts",
"agyTimeoutMs": 180000,
"contextInject": true,
"contextTokens": 1500,
"webSearch": "auto",
"vocalPlanningMode": true,
"geminiApiKey": "AIzaSyD-EXAMPLE_KEY_STRING_HERE"
}
```
---
## Variabili d'Ambiente Mappate
Le seguenti variabili di ambiente sovrascrivono la configurazione quando presenti:
```bash
export GEMINI_API_KEY="AIzaSy..."
export ENNE2_API_KEY="sk-..."
export AGY_STT_BACKEND="enne2" # oppure "gemini"
export AGY_STT_URL="https://ai.enne2.net"
export AGY_STT_MODEL="gemma4:E4B"
export AGY_BIN="/home/utente/.local/bin/agy"
export AGY_TTS_NOTIFY="0" # disabilita notifiche TTS
```
docs/context-injection.md
+89
View File
@@ -0,0 +1,89 @@
# Context Injection Engine (Fase 2)
L'estensione `agy-pi` include un motore avanzato di **Context Injection** che costruisce in tempo reale un blocco strutturato di contesto prima di ogni prompt inviato ad `agy`.
---
## Architettura del Blocco di Contesto
Il blocco di contesto rispetta le best practice di **Context Engineering** per i modelli di grandi dimensioni (LLM):
- Utilizzo di tag XML semantici.
- Posizionamento della richiesta utente **sempre alla fine** del prompt per contrastare l'effetto *"Lost in the Middle"* (Liu et al., TACL 2024).
- Gestione rigida del token budget (default 1500 token).
```xml
[CONTEXT_AGENTE] Contesto ambiente e stato corrente per la risposta. Usa solo se pertinente; la richiesta dell'utente è sotto.
<environment_snapshot>
cwd: /home/utente/progetto
os: linux x64
time: 2026-08-10T17:15:00.000Z
git_branch: main (dirty)
modified: src/index.ts | package.json
</environment_snapshot>
<session_state>
Utente: Analizza la struttura di questo componente...
Assistente: Ho controllato i file...
</session_state>
<durable_memory>
goal: Implementare il nuovo modulo di autenticazione
decisions: Usare token JWT con scadenza 1h | Database Postgres
conventions: TypeScript strict mode
</durable_memory>
<web_context>
[Risultati ricerca web Gemini grounding su topic pertinente]
</web_context>
--------------------------------
[ RICHIESTA UTENTE ]
```
---
## I 4 Moduli di Contesto
### 1. `<environment_snapshot>`
Estrae le informazioni dell'ambiente di lavoro corrente:
- Directory di lavoro attiva (`cwd`).
- Sistema operativo e architettura.
- Data e ora correnti (ISO 8601).
- Stato Git: branch corrente, indicatore `dirty` e lista fino agli ultimi 8 file modificati.
### 2. `<session_state>`
Recupera gli ultimi 3 messaggi dell'utente dalla sessione di `pi`. Il testo viene compresso e sanitizzato per evitare il bloat di token senza perdere il filo della conversazione.
### 3. `<durable_memory>` (Memoria Persistente Automatica)
Gestita tramite il file `~/.config/agy-pi/memory.json`:
- Registra l'obiettivo primario del progetto (`goal`), le decisioni prese (`decisions`), le convenzioni di codice (`conventions`) e le questioni aperte (`openQuestions`).
- **Auto-Update**: Quando la conversazione in `pi` supera i 24 turni, l'estensione estrae automaticamente i punti chiave e aggiorna `memory.json` per mantenere il contesto senza dover riinviare l'intero transcript.
### 4. `<web_context>` (Strada A: Ricerca Web Integrata)
Quando `webSearch` è impostato su `"auto"` o `"on"`, l'estensione valuta il prompt con la funzione euristica `needsWebSearch()`:
#### Filtri Negativi (Non effettuano ricerca web):
- Generazione ed editing di immagini (`agy_generate`, `agy_edit`, ecc.).
- Task di codice locale o refactoring.
- Comandi di gestione della conversazione o sintesi locale.
#### Trigger Positivi (Attivano la ricerca web):
- Riferimenti alla data/ora corrente (*"oggi"*, *"ultime notizie"*, *"2026"*).
- Domande su versioni di pacchetti, dipendenze o release note.
- Confronti tra tecnologie (*"differenza tra X e Y"*, *"migliore alternativa"*).
- Notizie o fatti di attualità.
La ricerca viene effettuata via API Gemini sfruttando la funzionalità di **Google Search Grounding**, ed i risultati vengono inseriti nel tag `<web_context>`.
Un sistema di cache temporale evita ricerche identiche ripetute entro 60 secondi.
---
## Gestione del Token Budget (Token Cap)
Il budget predefinito è di **1500 token**, suddiviso tra i diversi moduli:
- `environment_snapshot`: max ~300 token.
- `session_state`: max ~500 token.
- `durable_memory`: max ~400 token.
- `web_context`: max ~300 token.
docs/index.md
+77
View File
@@ -0,0 +1,77 @@
# Panoramica di agy-pi
<p align="center">
<img src="../assets/agy-pi-logo.jpg" alt="agy-pi logo" width="220"/>
</p>
**`agy-pi`** è un'estensione avanzata per **pi** (`@earendil-works/pi-coding-agent`) che integra **Google Antigravity CLI (`agy`)** e le API di **Gemini multimodale** come subagent autonomo e assistente multimodale dentro l'ambiente di pi.
---
## Il Problema & La Soluzione
| Sfida | Soluzione offertata da `agy-pi` |
|---|---|
| **Limitazione Text-Only di pi** | `agy-pi` agisce da ponte multimodale: pi delega ad `agy` l'elaborazione di immagini, audio, video e compiti di ragionamento profondo. |
| **Generazione & Editing Immagini** | Implementa formule narrative strutturate ([Soggetto]+[Azione]+[Stile], Keep+Change+Add+Render, Inpainting, Style Transfer, Composizione Multi-Immagine, Character Consistency). |
| **Input Vocale Senza Mani** | Scorciatoia **F12** con registrazione microfono, indicatore TUI live, soppressione silenzio, feedback sonori sci-fi e trascrizione nativa via Gemini/enne2. |
| **Multimodalità Ibrida (Voce + Tastiera)** | Integra automaticamente il testo presente nel campo editor di pi con il messaggio vocale registrato. |
| **Context Lost in the Middle** | Sistema di Context Injection in 4 fasi (`<environment_snapshot>`, `<session_state>`, `<durable_memory>`, `<web_context>`) con token cap ed euristiche anti-ridondanza. |
---
## Caratteristiche Principali
```mermaid
graph TD
PI[pi Coding Agent] -->|Tool Call / Slash Command| EXT[agy-pi Extension]
subgraph Core Features
EXT --> TOOLS[14 Specialized Tools]
EXT --> VOCAL[Workflow Vocale F12]
EXT --> CTX[Context Injection Engine]
EXT --> TUI[TUI Overlays /agy:key & /agy:status]
end
TOOLS --> AGY_CLI[Google Antigravity CLI agy]
VOCAL --> GEMINI_STT[Gemini STT / enne2 STT]
VOCAL --> GEMINI_TTS[Gemini TTS / Feedbacks Sonori]
CTX --> MEMORY[Memory JSON & Web Search Grounding]
```
1. **Subagent Multimodale Avanzato**: Espone 14 strumenti specializzati riconosciuti dall'LLM di pi per generare, modificare ed analizzare asset multimediali, inclusa la **generazione verificata iterativa** (`agy_create_verified`) con verifica visione + OpenCV dinamico.
2. **Sistema di Configurazione Persistente**: Configurazione via `/agy:config` salvata con permessi restrittivi `0600` in `~/.config/agy-pi/config.json`.
3. **Interfaccia Grafica TUI**: Dialoghi interattivi in sovrimpressione (`/agy:key` per mascherare e gestire la chiave API Gemini e `/agy:status` per la diagnostica di sistema).
4. **Modulo Vocale Sci-Fi Integrato**: Registrazione ad alte prestazioni via `ffmpeg`, rilevamento automatico del parlato (`volumedetect`), compressione `libopus`/`libmp3lame` e feedback acustici sintetizzati proceduralmente.
---
## Requisiti e Dipendenze
- **Node.js**: >= 18.x / v22.x
- **pi-coding-agent**: `@earendil-works/pi-coding-agent`
- **Google Antigravity CLI (`agy`)**: Installato e autenticato in locale (es. `~/.local/bin/agy`).
- **ffmpeg**: Necessario per il recording del microfono, la rimozione del silenzio e i feedback sonori procedurali.
- **Utilità Audio System**: `paplay` (PulseAudio), `aplay` (ALSA) o `ffplay`.
---
## Installazione Rapida
```bash
# Installazione da repository locale
pi install /percorso/a/agy-pi
# Oppure test dinamico senza installazione permanente
pi -e /percorso/a/agy-pi
```
Configura la chiave API Gemini per la trascrizione vocale e la ricerca web:
```bash
# Tramite overlay grafico dentro pi:
/agy:key
# Oppure via linea di comando:
/agy:config set geminiApiKey AIzaSy...
```
docs/tools.md
+196
View File
@@ -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.
docs/troubleshooting.md
+67
View File
@@ -0,0 +1,67 @@
# Troubleshooting & Diagnostica
Guida alla risoluzione dei problemi comuni durante l'utilizzo dell'estensione `agy-pi`.
---
## 1. Strumento Diagnostico Integrato (`/agy:status`)
Prima di procedere con la ricerca manuale dei guasti, esegui il comando slash dentro `pi`:
```
/agy:status
```
L'overlay TUI diagnostico verificherà automaticamente:
- Esistenza e versione dell'eseguibile `agy`.
- Presenza e validità della chiave API Gemini.
- Backend STT e stato notifiche TTS attivi.
- Ultimo messaggio di errore registrato nei log di `agy`.
---
## 2. Problemi Frequenti e Soluzioni
### A. Binario `agy` non trovato (`bash: agy: command not found`)
- **Causa**: Il binario `agy` non si trova nel `PATH` di sistema o nell'ubicazione standard `~/.local/bin/agy`.
- **Soluzione**: Imposta il percorso esplicito dell'eseguibile:
```
/agy:config set agyBin /percorso/assoluto/a/agy
```
### B. Registrazione vocale F12 fallita o senza audio
- **Causa 1**: `ffmpeg` non è installato nel sistema.
- **Soluzione**: Installa `ffmpeg` tramite il package manager della tua distribuzione (es. `sudo apt install ffmpeg`).
- **Causa 2**: Nessun parlato rilevato (`audioHasSpeech` ritorna errore).
- **Soluzione**: Verifica il microfono e alza il livello di guadagno di PulseAudio/ALSA.
- **Causa 3**: Mancanza dell'utility di riproduzione audio PulseAudio (`paplay`).
- **Soluzione**: Installa `pulseaudio-utils` oppure lascia che il sistema usi il fallback automatico `aplay` / `ffplay`.
### C. Errore API Gemini o Key Mancante (`HTTP 401` / `HTTP 403`)
- **Causa**: La chiave API Gemini non è stata inserita o è scaduta.
- **Soluzione**: Apri l'overlay grafico per configurare la chiave in modo sicuro:
```
/agy:key
```
### D. Immagine generata non trovata (`IMAGE_PATH` assente)
- **Causa**: `agy` ha completato l'operazione ma non ha restituito il pattern `IMAGE_PATH` o il modello non ha generato un file su disco.
- **Soluzione**: Aumenta il timeout di generazione portando `agyTimeoutMs` a 300000 (5 minuti) o imposta `stateless: true`.
### E. Errore HTTP 413 (`Payload Too Large`) durante la trascrizione audio
- **Causa**: File audio di grandi dimensioni inviato in formato WAV grezzo.
- **Soluzione**: L'estensione converte automaticamente i WAV in formato **Opus/OGG** (`libopus` a 16kbps). Assicurati che `ffmpeg` sia compilato con supporto a `libopus` o `libmp3lame`.
---
## 3. Ispezione dei Log
I log dettagliati delle interazioni della CLI `agy` sono memorizzati in:
`~/.gemini/antigravity-cli/log/`
Per visualizzare l'ultimo errore di sistema:
```bash
ls -t ~/.gemini/antigravity-cli/log/* | head -1 | xargs tail -n 50
```
docs/vocal-workflow.md
+101
View File
@@ -0,0 +1,101 @@
# Workflow Vocale (Registrazione F12)
L'estensione `agy-pi` trasforma `pi` in un assistente multimodale completo grazie all'integrazione di un workflow di input vocale nativo attivabile con il tasto **F12** o tramite il comando `/agy:record`.
---
## Diagramma di Flusso della Registrazione Vocale
```mermaid
flowchart TD
A[Pressione F12] --> B{Recording in corso?}
B -- No --> C[startRecording: Spawn ffmpeg]
C --> D[Play Sound: Start PowerUp]
C --> E[Avvia Timer TUI Status]
B -- Yes --> F[stopRecording: Send SIGINT]
F --> G[Play Sound: Stop Deactivate]
F --> H[optimizeAudio: silenceremove ffmpeg]
H --> I[audioHasSpeech: volumedetect check]
I -- Parlato Assente --> J[Errore: Silenzio o volume basso]
I -- Parlato Presente --> K[transcribeAudio: API Gemini / enne2]
K --> L[Legge editorText da TUI]
L --> M[Unisce Voce + Testo Editor + Contesto]
M --> N[executeAgy: plan-first, genera PIANO]
N --> N1{vocalPlanningMode?}
N1 -- true --> N2[Overlay TUI: trascrizione + piano]
N2 --> N3[Enter=Esegui | Esc=Annulla | E=Modifica | F12=Registra]
N3 -- Enter --> O[Svuota editorText TUI]
N3 -- Esc --> X[Annulla: playSound cancel]
N1 -- false --> O
O --> P[sendUserMessage prompt a pi]
P --> Q[Play Sound: Done Chime & TTS Notify]
```
---
## Fasi del Workflow Vocale
### 1. Avvio & Cattura dell'Audio (`startRecording`)
Alla pressione del tasto **F12**:
- Viene avviato un sottoprocesso `ffmpeg` che cattura dal dispositivo PulseAudio predefinito (`-f pulse -i default`).
- L'audio viene campionato a 16.000 Hz in mono (`-ac 1 -ar 16000`).
- Viene attivato un timer TUI che aggiorna dinamicamente lo stato di `pi`:
`🔴 REGISTRAZIONE... 00:14 / 02:00 (Esc per annullare)`
### 2. Feedback Acustici Sci-Fi Procedurali (`playSound`)
Per non dipendere da file audio esterni, i suoni di feedback vengono generati proceduralmente usando il filtro `aevalsrc` di `ffmpeg` e riprodotti tramite `paplay` (fallback su `aplay` o `ffplay`):
- **`start`**: Sweep di frequenza ascendente ($440 \text{ Hz} \to 1760 \text{ Hz}$).
- **`stop`**: Sweep di frequenza discendente ($1200 \text{ Hz} \to 300 \text{ Hz}$).
- **`cancel`**: Suono modulato a bassa frequenza ($350 \text{ Hz} \to 200 \text{ Hz}$).
- **`timeout`**: Pulsazione bi-tono di avviso radar.
- **`done`**: Arpeggio scintillante acuto ($C_5 - E_5 - G_5$).
### 3. Ottimizzazione & Rilevamento del Parlato
Prima della trascrizione:
- **`optimizeAudio()`**: Utilizza il filtro `silenceremove` di `ffmpeg` per eliminare il silenzio iniziale e finale con soglia a `-50dB`.
- **`audioHasSpeech()`**: Esegue una passata `volumedetect`. Se `max_volume` è inferiore a `-35dB` o `mean_volume` è sotto a `-45dB`, la registrazione viene classificata come silenzio, evitando di effettuare chiamate API inutili ed evitando allucinazioni da parte del modello STT.
### 4. Compressione & Inizio Trascrizione
- L'audio ottimizzato WAV viene convertito al volo in formato **Opus/OGG** (`libopus` a 16kbps). Questo riduce il payload di oltre il 60%, evitando errori `HTTP 413 Payload Too Large`.
- Invio della richiesta alle API Gemini (`gemini-3.5-flash`) o al server `enne2`.
### 5. Multimodalità Ibrida (Voce + Testo Editor)
Una funzionalità distintiva di `agy-pi` è la capacità di fondere il testo digitato dall'utente prima di premere F12 con l'audio registrato:
```typescript
const editorText = (ctx.ui.getEditorText?.() ?? "").trim();
```
Se l'utente ha scritto una nota o del codice nell'editor di `pi` e poi preme **F12** per aggiungere un commento vocale, l'estensione unisce i due input in un unico prompt interpretativo per Gemini:
$$\text{Prompt Finale} = \text{Trascrizione Vocale} + \text{Testo Editor} + \text{Contesto Conversazione}$$
Dopo l'invio riuscito, l'editor dell'interfaccia TUI viene svuotato automaticamente (`setEditorText("")`) per evitare duplicazioni.
### 6. Invio del Prompt all'Agente `pi`
Se `pi` è in stato di attesa (`isIdle()`), l'input viene inviato immediatamente tramite `sendUserMessage(finalText)`. Se `pi` sta eseguendo un altro task, viene accodato come `followUp`.
### 7. Workflow a 2 Fasi con Piano + Conferma (`vocalPlanningMode`)
Con `vocalPlanningMode=true` (default) il flusso di interpretazione vocale è
**plan-first**: Gemini produce **solo** la trascrizione corretta e un **piano
d'azione sintetico** (nessuna esecuzione). Questo evita che l'interpretazione
avvii autonomamente loop agentici o modifiche a sorpresa a causa di errori di STT.
Poi un **overlay TUI** mostra trascrizione + piano e attende la conferma:
```
🎙️ Conferma vocale
Trascrizione: "Aggiorna i docs..."
📋 Piano proposto: ...
Enter esegui • Esc annulla • E modifica • F12 registra di nuovo
```
- **Enter** → esegue (invia il risultato a pi)
- **Esc** → annulla, nessuna azione
- **E** → modifica il testo del piano manualmente
- **F12** → registra di nuovo
Per tornare all'esecuzione diretta (autonomia piena):
`/agy:config set vocalPlanningMode false`.