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

refactor: remove direct Gemini API integrations

Browse Source 
Route F12 and audio transcription exclusively through Antigravity OAuth, and preserve cross-model history without reusing incompatible signatures.\n\nRemove direct Gemini API keys, web grounding, internal TTS, verified image generation, obsolete commands and configuration. Update documentation and restore the local voice workflow helpers required at runtime.
This commit is contained in:
enne2
2026-09-03 12:52:13 +02:00
parent cde5aaa9b7
commit 4a88084b2b
13 changed files with 198 additions and 2197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+23 -258
View File
@@ -1,276 +1,41 @@
# 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.
Estensione per [pi](https://github.com/badlogic/pi-mono) che integra il client OAuth **Google Antigravity** (`agy`) come subagent multimodale. Non usa né gestisce chiavi Google AI Studio/Gemini API.
## 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="...")` |
| **Generazione verificata iterativa** | **`agy_create_verified`** | `agy_create_verified(requirements=..., maxIterations=3, useOpenCV=true)` |
| 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")` |
- chat e ragionamento multi-turno;
- generazione, editing, composizione e analisi immagini;
- analisi video;
- trascrizione audio e input vocale F12 tramite Antigravity;
- catalogo modelli e stato conversazione Antigravity.
L'agente (pi) decide autonomamente quale strumento usare in base al task richiesto.
Strumenti principali: `agy`, `agy_generate`, `agy_edit`, `agy_inpaint`, `agy_style_transfer`, `agy_compose`, `agy_character`, `agy_analyze`, `agy_transcribe`, `agy_video`, `agy_models`, `agy_conversation`, `antigravity_chat`.
### Generazione verificata (`agy_create_verified`)
Non include TTS interno né generazione immagini verificata iterativa.
Quando l'orchestratore di pi **non ha visione** e serve un'immagine conforme a
specifiche precise, `agy_create_verified` esegue un loop self-contained:
## Audio e F12
```
genera immagine (agy) → analizza con visione (PASS/FAIL vs requisiti)
→ verifica OpenCV (dimensioni, colori, luminosità, bordi)
→ rigenera con prompt di correzione se FAIL → ripete fino a maxIterations
Premi **F12** per avviare/fermare la registrazione. L'audio viene ottimizzato, convertito in Opus/OGG e inviato al modello `voiceModel` tramite il gateway Antigravity OAuth. Il workflow genera trascrizione e prompt pulito; con `vocalPlanningMode=true` richiede una conferma nell'overlay prima dell'invio a pi.
`agy_transcribe` usa la stessa pipeline Antigravity. Non esistono fallback a servizi con chiave API esterna. I suoni di start/stop/done sono effetti locali, non sintesi vocale.
## Configurazione
```text
/agy:config
/agy:config set voiceModel gemini-3.7-flash-medium
/agy:status
```
Restituisce l'immagine candidata finale + report di verifica (verdetto visione,
metriche OpenCV ed eventuale edit programmatico per ogni iterazione). Parametri:
`requirements`, `outputDir`, `maxIterations` (default 3), `useOpenCV` (default true),
`editInstructions`, `editScript`, `model`.
Con `editInstructions` il tool genera una trasformazione deterministica da applicare
prima della verifica a ogni iterazione. In alternativa `editScript` accetta uno script
Python esplicito con contratto `sys.argv[1]` input e `sys.argv[2]` output. Gli script
sono eseguiti con timeout, directory di lavoro temporanea e allowlist di `cv2`,
`numpy`, `PIL`, `json`, `sys` e `math`; import, rete, subprocess e accesso arbitrario
al filesystem vengono rifiutati. Un edit fallito rende automaticamente non conforme
l'iterazione.
## 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` |
| `vocalPlanningMode` | `true` | Piano + conferma in overlay dopo il vocale |
| `sttDirectGemini` | `true` | Interpretazione multimodale diretta Gemini (anche con DeepSeek/Claude) |
| `voiceModel` | `gemini-3.7-flash-medium` | Modello Gemini per l'audio |
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.
Con `vocalPlanningMode=true` (default) il flusso è **a 2 fasi con overlay TUI**:
dopo la trascrizione, l'estensione genera un **piano** e mostra un popup di
conferma con la trascrizione e il piano proposto:
```
🎙️ Conferma vocale
Trascrizione: "Aggiorna i docs..."
📋 Piano proposto: ...
Enter esegui • Esc annulla • E modifica • Spazio testo letterale • F12 registra di nuovo
```
- **Enter** → esegue il piano (invia il risultato a pi)
- **Esc** → annulla, nessuna azione
- **E** → modifica il testo del piano manualmente
- **Spazio** → chiude il popup e inserisce nell'editor la **trascrizione letterale** di quanto dettato, senza inviare il piano proposto
- **F12** → registra di nuovo
Questa modalità evita che l'interpretazione vocale avvii autonomamente loop
agentici o modifiche a sorpresa: la direttiva di Gemini è "produci solo il piano,
non eseguire nulla", e l'esecuzione parte solo dopo la tua conferma. Per tornare
all'esecuzione diretta, imposta `vocalPlanningMode=false` con
`/agy:config set vocalPlanningMode false`.
Il testo scritto nel campo editor prima di avviare la registrazione viene letto
(`getEditorText`) e **combinato con la trascrizione audio** nel piano, poi
l'editor viene svuotato per evitare reinvii duplicati.
**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).
Le impostazioni sono in `~/.config/agy-pi/config.json`. Serve solo completare il login OAuth del client `agy`.
## 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 install git:git.enne2.net/enne2/agy-pi
# oppure
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
```
Consulta `docs/configuration.md`, `docs/tools.md` e `docs/vocal-workflow.md` per i dettagli.