diff --git a/.gitignore b/.gitignore index 3c45938..0e9844d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ node_modules/ *.log .DS_Store +site/ +__pycache__/ +*.pyc diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..659a340 --- /dev/null +++ b/docs/architecture.md @@ -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 `` 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 }`). diff --git a/docs/cli-wrapper.md b/docs/cli-wrapper.md new file mode 100644 index 0000000..20ef67c --- /dev/null +++ b/docs/cli-wrapper.md @@ -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 ` | Riprende una conversazione specifica indicando il suo ID | +| `--model ` | Specifica il modello LLM (es. `--model "Gemini 3.1 Pro (High)"`) | +| `--effort ` | Livello di reasoning: `low` \| `medium` \| `high` | +| `--add-dir ` | 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`). diff --git a/docs/commands-keybindings.md b/docs/commands-keybindings.md new file mode 100644 index 0000000..a74a79a --- /dev/null +++ b/docs/commands-keybindings.md @@ -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 `: Stampa il valore di una singola chiave. +- `/agy:config set `: 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 ` | 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. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..62fb764 --- /dev/null +++ b/docs/configuration.md @@ -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 +``` diff --git a/docs/context-injection.md b/docs/context-injection.md new file mode 100644 index 0000000..8e973ff --- /dev/null +++ b/docs/context-injection.md @@ -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. + + +cwd: /home/utente/progetto +os: linux x64 +time: 2026-08-10T17:15:00.000Z +git_branch: main (dirty) +modified: src/index.ts | package.json + + + +Utente: Analizza la struttura di questo componente... +Assistente: Ho controllato i file... + + + +goal: Implementare il nuovo modulo di autenticazione +decisions: Usare token JWT con scadenza 1h | Database Postgres +conventions: TypeScript strict mode + + + +[Risultati ricerca web Gemini grounding su topic pertinente] + + +-------------------------------- +[ RICHIESTA UTENTE ] +``` + +--- + +## I 4 Moduli di Contesto + +### 1. `` +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. `` +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. `` (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. `` (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 ``. +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. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..0ee4810 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,77 @@ +# Panoramica di agy-pi + +

+ agy-pi logo +

+ +**`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 (``, ``, ``, ``) 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... +``` diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 0000000..86f781f --- /dev/null +++ b/docs/tools.md @@ -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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..04a19de --- /dev/null +++ b/docs/troubleshooting.md @@ -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 +``` diff --git a/docs/vocal-workflow.md b/docs/vocal-workflow.md new file mode 100644 index 0000000..b4695a9 --- /dev/null +++ b/docs/vocal-workflow.md @@ -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`. diff --git a/mermaid_fence.py b/mermaid_fence.py new file mode 100644 index 0000000..0e82c27 --- /dev/null +++ b/mermaid_fence.py @@ -0,0 +1,9 @@ +"""Helper per i fence Mermaid in MkDocs. + +`def_fence_mermaid` è stato rimosso da pymdown-extensions moderne; viene +fornito qui come modulo locale che mkdocs risolve via !!python/name:. +""" + + +def def_fence_mermaid(source, language, class_name, options, md, **kwargs): + return '
' + source + "
" diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..170aab3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +site_name: agy-pi Documentation +site_description: Documentazione ufficiale dell'estensione agy-pi per pi coding agent +site_author: agy-pi team +repo_url: https://git.enne2.net/enne2/agy-pi + +theme: + name: material + language: it + palette: + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: cyan + toggle: + icon: material/brightness-4 + name: Passa alla modalità chiara + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: cyan + toggle: + icon: material/brightness-7 + name: Passa alla modalità scura + features: + - navigation.tabs + - navigation.sections + - navigation.top + - navigation.expand + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:mermaid_fence.def_fence_mermaid + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist + - tables + - attr_list + - md_in_html + +nav: + - Home: index.md + - Architettura: architecture.md + - Strumenti (Tools): tools.md + - Comandi & Keybindings: commands-keybindings.md + - Configurazione: configuration.md + - Workflow Vocale (F12): vocal-workflow.md + - Context Injection: context-injection.md + - Wrapper CLI: cli-wrapper.md + - Troubleshooting: troubleshooting.md