agnochat - Guida Utente

Introduzione

agnochat è un'applicazione di chat con modelli linguistici (LLM) progettata per essere 100% client-side. Tutto esegue nel tuo browser, senza server né installazioni.

"Un frontend minimale e leggibile per dialogare con i migliori LLM, mantenendo chiavi, conversazioni e preferenze interamente sul tuo dispositivo."

Prima Configurazione — in 3 passi

Segui questi passaggi nell'ordine. Bastano 2 minuti.

1 Configura un Provider LLM

Premi il pulsante LLM nella barra superiore per aprire il selettore dei provider. Scegli uno tra quelli disponibili:

  • Gemini - Modelli Google (es. gemini-2.0-flash)
  • Mistral - Modelli Mistral AI (es. mistral-small)
  • Groq - Modelli ad alta velocità (es. llama-3.3-70b)
  • OpenRouter - Accesso a molti modelli tramite un'unica API
2 Aggiungi una API Key

Ogni provider richiede una chiave API per funzionare. Dal menu laterale (icona hamburger), vai su API Key > Gestisci API Key per aggiungere la tua chiave.

Le chiavi API vengono memorizzate solo nel tuo browser (IndexedDB) e non vengono mai trasmesse a server esterni.
3 Seleziona un Modello

Dopo aver aggiunto la chiave, puoi selezionare un modello specifico dal selettore LLM. Ogni modello ha una "window size" (finestra di contesto) differente che indica quanti token può processare.

Comandi LLM — panoramica rapida

Tutti i comandi LLM sono nel ☰ Menu → sezione LLM. Ecco quando usare ciascuno:

Comando Quando usarlo Cosa fa Dove vedi il risultato
Test LLM Nuovo Vuoi confrontare i modelli già selezionati con lo stesso prompt Testa in sequenza tutti i modelli di un provider (stesso prompt) Spinner + Log + finestra riepilogo 84vw
Seleziona LLM Vuoi scegliere quali modelli compaiono nell'albero Apre elenco con checkbox per provider/modello Albero LLM aggiornato
Aggiorna LLM Vuoi scoprire nuovi modelli dai provider con chiave attiva Scarica + testa modelli, calcola voto Log + elenco per selezione
Reset LLM Selezione rotta o vuoi tornare ai default Svuota selezione e ripristina modelli da data/models/ Albero LLM ricostruito

Selezionare un Provider / Modello

Pulsante LLM in alto → albero provider/modelli. Clicca un provider per espandere i modelli, poi un modello per attivarlo. Il modello attivo resta visibile accanto al pulsante LLM.

Puoi cambiare modello in qualsiasi momento (hot-swap) senza ricaricare la pagina.

Finestra Seleziona LLM

La finestra mostra solo i modelli con voto ≥6 e 4 pulsanti:

  • Salva — sostituisce completamente la selezione con i modelli spuntati
  • Aggiungi — unisce i modelli spuntati a quelli già presenti
  • Annulla — deseleziona tutti i modelli
  • Seleziona Attivi — seleziona solo gli LLM già attivi nell'albero (quelli salvati in selected-models), deseleziona gli altri — inverso di Annulla

Test LLM — guida passo-passo Nuovo

Obiettivo: confrontare, con un solo prompt, tutti i modelli che hai già selezionato per un provider. Utile per scegliere il più veloce o più adatto.

1. PromptScrivi il prompt nell'input
→
2. Avvia☰ → LLM → Test LLM
→
3. ProviderScegli il provider nella finestra
→
4. AttendiSpinner STOP + Log live
→
5. RiepilogoTabella Modello / Response / Tempo

Passo 1 — Prepara il prompt

Scrivi il prompt nella casella di input in basso. È obbligatorio: se manca, l'app mostra "digita prima un prompt di richiesta" e non parte.

Suggerimento: usa lo stesso prompt che useresti in chat, così il confronto è realistico.

Passo 2 — Apri Test LLM

☰ Menu → LLM → Test LLM (è la prima voce della sezione LLM). Tooltip: "test sui modelli selezionabili dal comando LLM".

Si apre la finestra Test LLM con:

  • Il tuo prompt (in alto, non modificabile lì)
  • La lista dei provider che hanno modelli selezionati, ciascuno con conteggio (es. "3 modelli")
Se non hai modelli selezionati, l'app avvisa: "nessun modello selezionato — esegui Reset LLM o Seleziona LLM".

Passo 3 — Scegli il provider

Clicca il provider da testare. La finestra si chiude e parte il ciclo.

  • Parametri uguali per tutte le prove: timeout 60s, max_tokens 512, temperature 0.7
  • Esecuzione sequenziale (un modello alla volta, in ordine di selezione)

Passo 4 — Durante il test

  • Spinner con STOP: copre l'overlay; clicca STOP e conferma per interrompere. La richiesta in corso viene annullata.
  • Log live: il pannello Log si apre da solo e registra per ogni prova:
    >>> provider/modello | req: N char | resp: N char | tempo: s <<<
    oppure in errore: >>> ERRORE provider/modello | codice: X | motivo | req | tempo <<<
Puoi seguire l'avanzamento solo dal Log: la finestra riepilogativa appare solo alla fine.

Passo 5 — Finestra riepilogativa

Alla fine (anche se hai fatto STOP) si apre la finestra Riepilogo [provider], larga 84vw per leggere bene i nomi:

ColonnaCosa mostraEsempio
ModelloNome modello testatogemini-2.0-flash
ResponseDimensione risposta o errore842 char oppure ERRORE codice: 429
Tempo / ErroreTempo in secondi o motivo errore1.8 s oppure Rate limit

Chiudi con X. Il provider/modello attivi precedenti vengono ripristinati automaticamente.

Errori comuni in tabella: NO_KEY (manca API key), NO_MODEL (modello non in catalogo), 429 (rate limit), 5xx (provider sovraccarico).

Gestione delle API Key

Ottenere una API Key da un Provider

La API Key è una stringa segreta che identifica il tuo account presso il provider e abilita le chiamate ai suoi modelli. Si ottiene dalla console web del provider: crea un account, vai alla sezione API Keys e genera una nuova chiave. Copiala subito: molti provider la mostrano una sola volta.

  • Google Gemini — Vai su Google AI Studio, accedi con l'account Google e premi Get API Key → Create API key. Il piano gratuito copre l'uso normale in chat.
  • Mistral AI — Vai su console.mistral.ai, apri API Keys e crea una chiave. Potrebbe servirti un metodo di pagamento o credito prepagato anche per i modelli minori.
  • Groq — Vai su console.groq.com, apri API Keys e premi Create API Key. Il piano gratuito ha limiti di richieste al minuto.
  • OpenRouter — Vai su openrouter.ai, apri Keys e crea una chiave. La maggior parte dei modelli richiede crediti prepagati; alcuni modelli free funzionano a costo zero.
Se una chiave smette di funzionare, rigenerala dalla stessa console e sostituiscila nell'app: le chiavi possono scadere o essere revocate dal provider.

Aggiungere una Chiave API

Dal menu laterale, vai su API Key > Gestisci API Key e compila il modulo in alto:

  • Provider: scegli il provider della chiave dal menu a tendina
  • Nome: un'etichetta a piacere (es. personale, work) per distinguerla
  • API Key: incolla la chiave copiata dalla console del provider

Premi Aggiungi: la chiave compare nell'elenco sotto il suo provider, mostrata in forma mascherata (primi/ultimi caratteri). Puoi salvare più chiavi per lo stesso provider.

Le chiavi vengono memorizzate in modo offuscato nell'IndexedDB del tuo browser.

Attivare e Usare una Chiave

Ogni provider usa una sola chiave attiva alla volta: nell'elenco, seleziona il pallino Attiva sulla riga della chiave da usare. La riga attiva viene evidenziata. Poi:

  • premi il pulsante LLM nella barra superiore per scegliere provider e modello;
  • oppure usa LLM > Aggiorna LLM: testa i modelli dei provider che hanno una chiave attiva e aggiorna l'albero di selezione.
Senza chiave attiva il provider non risponde: vedrai errori come NO_KEY (manca la chiave) o 401 (chiave non valida o scaduta). In tal caso controlla la chiave attiva in API Key > Gestisci API Key.

Ripristinare le Chiavi Default

Seleziona API Key > API Keys Default per ripristinare le chiavi di prova predefinite. Queste chiavi sono offuscate nel codice sorgente e vengono utilizzate solo al primo avvio quando il database è vuoto.

Le chiavi di prova hanno limiti di utilizzo. Per un uso regolare, aggiungi le tue chiavi personali.

Sicurezza delle Chiavi

  • Le chiavi vengono memorizzate solo localmente nel tuo browser
  • Non vengono mai trasmesse a server esterni (tranne al provider LLM scelto)
  • Non vengono mai salvate nel codice sorgente o nei file di configurazione
  • Puoi eliminarle in qualsiasi momento dalla gestione API Key

Gestione delle Conversazioni

Creare una Nuova Conversazione

Dal menu laterale, seleziona Conversazioni > Nuova Conversazione. Questo creerà una nuova conversazione vuota e la attiverà automaticamente.

La conversazione attiva viene salvata automaticamente. Puoi tornare a qualsiasi conversazione precedente.

Gestire le Conversazioni

Seleziona Conversazioni > Gestisci Conversazioni per vedere l'elenco di tutte le conversazioni salvate. Da qui puoi:

  • Attiva - Seleziona una conversazione per continuare a lavorarci
  • Elimina - Rimuovi una conversazione e tutti i suoi messaggi

La conversazione attiva viene indicata con (attiva).

Cronologia dei Messaggi

Tutti i messaggi della conversazione attiva vengono visualizzati nell'area di output. La cronologia viene salvata automaticamente e persiste anche chiudendo e riaprendo il browser.

Prompt di Sistema

Cos'è un Prompt di Sistema

Un prompt di sistema è un'istruzione che viene anteposta a ogni messaggio che invii al modello. Permette di definire il comportamento, lo stile e le regole che il modello deve seguire.

Esempio: "Sei un assistente specializzato in programmazione JavaScript. Rispondi sempre in italiano con esempi di codice pratici."

Creare un Nuovo Prompt

Dal menu laterale, vai su Prompt di Sistema > Nuovo Prompt. Compila:

  • Nome - Un nome descrittivo per identificare il prompt
  • Contenuto - Le istruzioni per il modello

Puoi scegliere tra diversi prompt di esempio predefiniti:

  • Assistente Generale - Utile per conversazioni quotidiane
  • Sviluppatore JavaScript - Specializzato in coding JS
  • Traduttore IT/EN - Per traduzioni italiane/inglesi
  • Sintetizzatore di Testi - Per riassumere testi

Gestire i Prompt

Seleziona Prompt di Sistema > Gestisci Prompt per vedere l'elenco dei prompt salvati. Da qui puoi:

  • Attiva - Seleziona il prompt da usare per le prossime conversazioni
  • Modifica - Modifica nome e contenuto di un prompt esistente
  • Elimina - Rimuovi un prompt non più necessario

Interfaccia Utente

Barra Superiore

  • Menu (icona hamburger) - Apre il menu laterale con tutte le opzioni
  • Help - Apre il manuale rapido dei comandi
  • README - Apre questa guida completa in una nuova scheda
  • LLM - Seleziona provider e modello attivo
  • Modello attivo - Visualizza il modello selezionato
  • Log - Mostra la console tecnica con i messaggi di sistema
  • Tema - Alterna tra tema scuro e chiaro

Aree di Lavoro

  • Area Output - Visualizza i messaggi della conversazione con rendering Markdown
  • Area Input - Scrivi i tuoi messaggi da inviare al modello
  • Barra Documenti - Visualizza i documenti caricati nella conversazione

Pulsanti di Controllo

  • Invia (verde) - Invia il messaggio al modello
  • Cancella Input - Svuota la casella di input
  • Copia Output - Copia tutti i messaggi negli appunti
  • Cancella Output - Svuota l'area di output (non cancella la cronologia)
  • Carica Documento - Allega un file alla conversazione
  • Modifica Ultimo Messaggio - Modifica l'ultimo messaggio inviato

Documenti e Allegati

Caricare Documenti

Puoi allegare documenti alla conversazione utilizzando il pulsante + nella barra degli input. I formati supportati includono:

  • PDF - Documenti PDF
  • Word (.docx) - Documenti Microsoft Word
  • ZIP - Archivi compressi

I documenti vengono analizzati e il loro contenuto viene incluso nel contesto della conversazione.

Gestire i Documenti

I documenti caricati appaiono nella barra documenti sotto l'area di output. Puoi rimuovere singoli documenti cliccando sull'icona di rimozione accanto al nome del file.

I documenti vengono salvati con la conversazione e caricati automaticamente quando la riapri.

Impostazioni e Temi

Cambiare Tema

Clicca il pulsante Tema nella barra superiore per alternare tra tema scuro (default) e tema chiaro. La selezione viene salvata automaticamente.

Reset Completo

Seleziona Menu > Reset per cancellare TUTTI i dati dell'applicazione:

  • Conversazioni e messaggi
  • Prompt di sistema
  • Chiavi API
  • Configurazione provider
Questa operazione non può essere annullata. Tutti i dati verranno persi.

Suggerimenti Utili

  • Memoria della conversazione - Il modello ricorda tutti i messaggi precedenti nella conversazione attiva
  • Prompt di sistema - Usa prompt personalizzati per ottenere risposte più specifiche
  • Hot-swap - Puoi cambiare provider e modello in qualsiasi momento senza ricaricare la pagina
  • Markdown - Le risposte del modello supportano formattazione Markdown (grassetto, corsivo, codice, elenchi)
  • Retry automatico - L'app riprova automaticamente in caso di errori transitori (408, 500, 502, 503, 504)
  • Interruzione - Puoi interrompere una risposta in corso cliccando sul pulsante STOP dello spinner
  • Telemetria minima - Solo eventi di apertura app e avvio conversazione verso il worker WWWANALYZER (implementazione: static/js/services/sender.js); disattivata in automatico in ambiente locale