agy-pi/README.md

# agy-pi

<p align="center">
  <img src="assets/agy-pi-logo.jpg" alt="agy-pi logo" width="200"/>
</p>

Estensione per **pi** che integra **Google Antigravity CLI (`agy`)** come subagent multimodale.

Anche se il modello di pi è text-only, questa estensione permette a pi di delegare a agy
(che usa **Gemini multimodale**) task che richiedono immagini, audio e video, oltre a
conversazioni di ragionamento multi-turno.

## Capacità

| Capacità | Tool | Esempio |
|---|---|---|
| Conversazione multi-turno | `agy` | `agy(prompt="Analizza questo problema...")` |
| Generazione immagini (strutturata) | `agy_generate` | `agy_generate(subject="un gatto", style="fotorealistico")` |
| Editing controllato (Keep+Change+Add+Render) | `agy_edit` | `agy_edit(baseImage=..., change="...", keep="...")` |
| Editing zona specifica (inpainting) | `agy_inpaint` | `agy_inpaint(baseImage=..., target="il divano", replacement="blu navy")` |
| Style transfer | `agy_style_transfer` | `agy_style_transfer(baseImage=..., style="Van Gogh")` |
| Composizione multi-immagine | `agy_compose` | `agy_compose(images=[...], instruction="...")` |
| Consistenza personaggio | `agy_character` | `agy_character(referenceImage=..., name="Maya", task="...")` |
| Analisi file (imm/audio/video) | `agy_analyze` | `agy_analyze(filePath=..., question="...")` |
| Trascrizione audio | `agy_transcribe` | `agy_transcribe(filePath="voce.wav", language="italiano")` |
| Analisi video | `agy_video` | `agy_video(filePath="clip.mp4", question="...")` |
| Elenco modelli | `agy_models` | `agy_models()` |
| Gestione stato conversazione | `agy_conversation` | `agy_conversation(action="id" \| "list" \| "reset")` |

L'agente (pi) decide autonomamente quale strumento usare in base al task richiesto.

## Configurazione persistente (`/agy:config`)

Tutte le impostazioni dell'estensione si gestiscono con il comando `/agy:config`
(salvate in `~/.config/agy-pi/config.json`, permessi 600):

```
/agy:config                    # elenca tutte le impostazioni
/agy:config get <chiave>       # mostra una chiave
/agy:config set <chiave> <valore>  # imposta una chiave
/agy:config reset              # ripristina i default
```

### Dialog TUI per la chiave Gemini (`/agy:key`)

Per inserire/modificare la **chiave API Gemini** con un'interfaccia grafica in
sovrimpressione (dialog TUI, campo mascherato) usa il comando `/agy:key`:

```
/agy:key
```

Apre un overlay centrato nel terminale:

- mostra la chiave attuale mascherata (`AIza...yfDY`)
- campo di input **mascherato** (digiti la chiave, vedi `•`)
- `Enter` conferma (salva in config + `~/.agy-chat/gemini-key`)
- `Esc` annulla

È il modo interattivo e sicuro per impostare `geminiApiKey` senza digitarla in
chiaro nella cronologia del terminale.

### Diagnostica (`/agy:status`)

Il comando `/agy:status` apre un overlay TUI con lo stato dell'estensione:

- binario agy (trovato/non trovato) e versione
- chiave Gemini valida/mancante (mascherata) e stato
- modello attivo, backend STT, notifiche TTS
- ultimo errore significativo dai log di agy

Chiudi con `Enter` o `Esc`.

### Context Injection (Fase 2) — `pi → agy`

Quando il tool `agy` (o altri con l'opzione `injectContext`) invia un prompt a
Gemini, l'estensione **inietta automaticamente** un blocco di contesto prima
della richiesta utente, seguendo le best practice di context engineering:

```
<environment_snapshot>   ← cwd, OS, data/ora, git branch + file modificati
<session_state>          ← ultimi messaggi utente pi (compatti, non il transcript)
<durable_memory>         ← archivio fatti chiave (memory.json, auto-aggiornato)
<web_context>            ← risultati ricerca web (Strada A, se pertinente)
--------------------------------
[ RICHIESTA UTENTE ]      ← sempre per ultima (anti lost-in-the-middle)
```

- **Tag XML** e richiesta per ultima (evidenze “Lost in the Middle”, TACL 2024)
- **Token cap** default ~1500 (chiave `contextTokens`)
- **Memoria durevole** automatica: oltre una soglia di turni, i punti chiave
  vengono condensati in `~/.config/agy-pi/memory.json` invece di rigirare tutto
- **Ricerca web** (Strada A): con `webSearch=auto|on` l'estensione cerca con
  l'API Gemini (`googleSearch` grounding) e inietta i risultati nel `<web_context>`

| Chiave | Default | Descrizione |
|---|---|---|
| `geminiApiKey` | — | Chiave API Google Gemini (STT/TTS) |
| `enne2ApiKey` | — | Token per il server proxy ai.enne2.net (opzionale) |
| `sttBackend` | `gemini` | Backend trascrizione: `gemini` \| `enne2` |
| `sttUrl` | `https://ai.enne2.net` | URL base backend enne2 |
| `sttModel` | `gemma4:E4B` | Modello STT backend enne2 |
| `sttMaxDuration` | `120` | Durata max registrazione (secondi) |
| `ttsBackend` | `gemini` | Backend TTS: `gemini` \| `enne2` |
| `ttsNotify` | `true` | Notifiche vocali automatiche |
| `ttsModel` | `gemini-2.5-flash-preview-tts` | Modello TTS Gemini |
| `agyBin` | `agy` | Path del binario agy |
| `agyDefaultModel` | — | Modello predefinito per le chiamate agy |
| `agyTimeoutMs` | `180000` | Timeout esecuzione agy (ms) |
| `contextInject` | `true` | Iniezione contesto nel prompt agy |
| `contextTokens` | `1500` | Token cap per il contesto iniettato |
| `webSearch` | `auto` | Ricerca web Strada A: `auto` \| `on` \| `off` |

Le variabili d'ambiente (`GEMINI_API_KEY`, `AGY_STT_BACKEND`, ecc.) hanno
priorità sul file di config quando impostate.

## Registrazione microfono (F12)

Premi **F12** per avviare/fermare la registrazione dal microfono (max 2 min).
Il flusso: registra → taglia il silenzio → **trascrive con la Gemini API diretta**
(`gemini-3.5-flash`, veloce e affidabile — agy CLI non supporta file audio) →
interpreta con Gemini usando il contesto della conversazione → inserisce il
risultato come prompt su pi.

**Requisito**: la key Gemini API in `~/.agy-chat/gemini-key` (chmod 600) o nella
variabile d'ambiente `GEMINI_API_KEY`.

```bash
# una volta sola
echo "LA_TUA_KEY" > ~/.agy-chat/gemini-key && chmod 600 ~/.agy-chat/gemini-key
```

**Backend di trascrizione** (variabile `AGY_STT_BACKEND`):

| Backend | Descrizione | Configurazione |
|---|---|---|
| `gemini` (default) | Gemini API (`gemini-3.5-flash`), veloce e affidabile | key in `~/.agy-chat/gemini-key` |
| `enne2` | Server locale `ai.enne2.net` con `gemma4:E4B` (supporta audio), ~2-3s | `AGY_STT_URL` (default `https://ai.enne2.net`), `AGY_STT_MODEL` (default `gemma4:E4B`) |

```bash
# usa il server locale
export AGY_STT_BACKEND="enne2"
```

Comandi: `/agy:record` (toggle), `/agy:record:stop` (ferma).

## Installazione

Requisito: `agy` installato e autenticato (una volta: `agy`, poi login OAuth nel browser).

```bash
# da un repo git
pi install git:github.com/<tuo-utente>/agy-pi

# oppure da una cartella locale
pi install /percorso/a/agy-pi
```

Per provare senza installare:

```bash
pi -e /percorso/a/agy-pi
```

## Uso

### Come tool (chiamato automaticamente dal modello)

Quando chiedi a pi di generare un'immagine, analizzare un file, o ragionare insieme a un
secondo agente, pi può chiamare il tool `agy`. Esempi di prompt:

```
Genera un'immagine di un paesaggio marziano al tramonto.
Analizza l'immagine /home/utente/foto.jpg e descrivila.
Trascrivi il file audio /home/utente/voce.wav.
Chiedi a agy di ragionare su questo problema e poi confronta la sua risposta con la tua.
```

### Come comando interattivo

```
/agy <prompt>        # invia un prompt a agy
/agy:new             # forza una nuova conversazione
/agy:list            # mostra la conversazione corrente
/agy:reset           # azzera lo stato conversazione
```

## Parametri del tool `agy`

| Parametro | Tipo | Descrizione |
|---|---|---|
| `prompt` | string (obbligatorio) | Il task/prompt per agy |
| `mode` | `chat` \| `image` \| `analyze` | Tipo di operazione (default `chat`) |
| `model` | string | Modello agy (es. `Gemini 3.1 Pro (High)`, `Claude Opus 4.6 (Thinking)`) |
| `effort` | `low` \| `medium` \| `high` | Livello di ragionamento |
| `newConversation` | boolean | Forza una nuova conversazione |
| `addDir` | string | Cartella da aggiungere al workspace agy |
| `filePath` | string | File (immagine/audio/video) da analizzare |
| `yolo` | boolean | `--dangerously-skip-permissions` (necessario per audio/video) |

## Multi-turno

L'estensione mantiene l'ID della conversazione agy in `~/.agy-chat/conversation_id`.
Ogni chiamata a `agy` continua la conversazione precedente, così agy ricorda i turni
precedenti (ragionamento multi-shot). Usa `newConversation: true` per ripartire da zero.

## Note di sicurezza

- `yolo: true` auto-approva tutti gli strumenti di agy. Usalo solo in ambienti fidati.
- Le estensioni pi girano con i permessi completi del sistema. Rivedi il codice prima di
  installare pacchetti di terze parti.

## Struttura

```
agy-pi/
├── package.json          # manifest pi
├── extensions/index.ts   # estensione (tool + comandi)
├── bin/agy-chat.sh       # wrapper bash standalone (opzionale)
└── README.md
```