# 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...
```