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