enne2
2137150da3
- Aggiunti docs/ (9 pagine MkDocs, tema Material) + mkdocs.yml - Fix mkdocs.yml: repo_url -> git.enne2.net, tasklist (era taskbuttons), fence Mermaid via helper locale mermaid_fence.py (def_fence_mermaid rimosso da pymdown-extensions moderne) - Documentate le nuove funzionalità: agy_create_verified (generazione verificata con verifica OpenCV DINAMICA generata dall'LLM), workflow vocale a 2 fasi (vocalPlanningMode), chiavi config context/webSearch - tools.md ora documenta 14 tool; vocal-workflow.md include l'overlay di conferma piano; configuration.md include vocalPlanningMode - .gitignore: esclusi site/ e __pycache__/ - Build MkDocs verificata (site/ generato correttamente)
88 lines
3.7 KiB
Markdown
88 lines
3.7 KiB
Markdown
# 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
|
|
```
|