Assistente IA

Genera SQL a partire da istruzioni in linguaggio naturale.

Dove si trova: Workspace › Strumenti › IA

Premi IA nella barra di navigazione del workspace. Scrivi la tua richiesta in italiano (o inglese) nell'area di testo in basso, ad esempio: "Dammi i 10 clienti con più acquisti del mese scorso".

L'assistente genera il SQL corrispondente e lo mostra in un pannello di codice. Con un provider pronto — quelli cloud richiedono la tua chiave; Apple Intelligence e Ollama nessuna — le risposte sono generate dal modello di linguaggio.

Parole chiave: ia, ai, intelligenza artificiale, linguaggio naturale, openai, gemini

Scegli il provider dell'assistente: Apple Intelligence non chiede chiave, quelli cloud sì.

Dove si trova: Assistente IA › Impostazioni (ingranaggio)

Premi l'icona a forma di ingranaggio nell'intestazione dell'Assistente IA per aprire il pannello di configurazione. È lì che scegli il provider: Apple Intelligence gira sul dispositivo stesso e non richiede né chiave né account; i provider cloud chiedono la tua API key e permettono anche di scegliere il modello.

Il pannello si disegna in base a ciò che serve al provider scelto. Se non chiede la chiave, la riga della chiave non compare: non manca, non serve.

Con un provider che invece la chiede e non ne ha ancora una, l'assistente funziona in modalità demo, con risposte di esempio basate sulla corrispondenza di pattern.

Parole chiave: api key, openai, gemini, configurare, modello, GPT, apple intelligence, senza chiave, locale

Il modello di sistema, sul dispositivo: senza chiave, senza costi e senza che nulla vada su internet.

Dove si trova: Calíope › Preferenze › Assistente IA

Apple Intelligence è il modello linguistico di sistema. Gira sul dispositivo stesso: non richiede né chiave né account, non ha costi e la tua domanda non va su internet.

Perché compaia nel selettore servono due cose: un dispositivo compatibile e Apple Intelligence attiva in Impostazioni di Sistema. Se ne manca una, il selettore non la offre — non appare disattivata, semplicemente non c'è, e l'assistente continua a funzionare con i provider cloud.

Va bene per richieste brevi: spiegare un errore, scrivere una query su una o due tabelle, ricordare una sintassi. Non va bene con schemi grandi: la sua finestra è piccola, e quando lo schema non entra l'assistente lo dice nella conversazione e propone cosa fare.

Qui entra in gioco l'interruttore Inviare lo schema al modello, nello stesso pannello e anche in Preferenze › Assistente IA. Attivo, vengono inviati i nomi di tabelle, colonne e chiavi esterne del database attivo — mai le righe. Disattivo, dello schema non viene inviato nulla: le tabelle vanno nominate nella domanda.

Consiglio: se la query riguarda poche tabelle, nominale e disattiva l'interruttore. È una riga in più da scrivere, e con Apple Intelligence è anche ciò che evita che lo schema non entri.

Parole chiave: apple intelligence, locale, senza chiave, privacy, finestra di contesto, schema, non entra

Un server di modelli aperti che gira dove dici tu. Senza chiave e senza costo per domanda.

Dove si trova: Calíope › Preferenze › Assistente IA

Ollama è un programma che esegue modelli linguistici aperti sul tuo Mac. Si installa da ollama.com e un modello si scarica con ollama pull <nome> — per esempio ollama pull qwen2.5-coder. Calíope gli parla come a qualsiasi altro provider: senza chiave e senza costo per domanda.

Cosa scrivere nell'indirizzo. Quello di fabbrica — http://127.0.0.1:11434 — va bene quando Ollama gira sullo stesso Mac. Da iPad o iPhone si scrive l'indirizzo del Mac nella tua rete (http://192.168.x.x:11434), e lì c'è un passaggio che si dimentica: di default Ollama ascolta solo se stesso. Perché accetti connessioni dalla rete va avviato con OLLAMA_HOST=0.0.0.0 ollama serve.

Cosa viaggia. La tua domanda e, con l'interruttore Inviare lo schema al modello attivo, i nomi di tabelle, colonne e chiavi esterne del database attivo — mai le righe. E arriva solo a quell'indirizzo: sullo stesso Mac non ne esce; in rete arriva a quel Mac e non oltre.

Quale modello. Uno pensato per il codice dà un SQL molto migliore. Uno piccolo può rispondere in prosa, senza blocco SQL, e allora l'assistente mostra il testo così com'è e non c'è nulla da portare nell'editor; può anche inventarsi nomi di colonna che il tuo schema non ha. Con un modello locale, inoltre, l'attesa la detta il tuo computer: se arriva un errore di tempo, alza il limite di generazione nelle Preferenze.

Se non risponde. L'assistente lo dice, con l'indirizzo dentro. Due cose, da controllare in quest'ordine: che Ollama sia avviato, e che l'indirizzo scritto sia il suo.

Parole chiave: ollama, locale, senza chiave, modello, llama, qwen, rete, OLLAMA_HOST, indirizzo

Un client IA di questo Mac può elencare database, descrivere tabelle e fare query in lettura.

Dove si trova: Calíope › Preferenze › Assistente IA

Con il server MCP acceso, un client IA che gira su questo Mac — Claude Desktop, Cursor, qualunque cosa parli MCP — può chiedere a Calíope di elencare database, descrivere tabelle ed eseguire query di sola lettura sulle connessioni che spunti tu.

Dove gira. Dentro Calíope, in ascolto su 127.0.0.1 — cioè solo su questo Mac — e solo mentre Calíope è aperta. Nulla viene esposto alla tua rete né a internet: non è un'impostazione, è com'è fatto.

Cosa vede. Solo le connessioni che spunti in Preferenze › Assistente IA › Server MCP. Quello che non spunti non esiste per il client: non compare nemmeno nell'elenco.

Cosa può fare. Leggere, e nient'altro. Una istruzione per chiamata, e solo SELECT, SHOW, EXPLAIN o DESCRIBE: un INSERT, un UPDATE, un DROP o un SELECT … FOR UPDATE vengono rifiutati prima di toccare il server. Le risposte sono limitate a 200 righe.

La chiave. Senza di essa il server non risponde. Vive nel Portachiavi di questo Mac, non va su iCloud e non entra nel backup delle impostazioni. Se pensi che sia sfuggita, «Genera una nuova chiave» invalida subito la precedente — e devi incollare di nuovo la configurazione nel client.

Se la porta che scegli è già occupata da un altro programma, Calíope te lo dice e non parte.

Parole chiave: mcp, server, client, claude desktop, cursor, sola lettura, token, porta

Accendere, spuntare le connessioni, copiare la configurazione e incollarla nel client.

Cinque passi, in quest'ordine:

1. In Preferenze › Assistente IA › Server MCP, accendi l'interruttore.
2. Spunta le connessioni che vuoi far vedere al client. Quello che non spunti gli resta invisibile.
3. Premi Copia configurazione. Negli appunti vanno due blocchi, uno per client, con la tua porta e la tua chiave già dentro.
4. Incolla il blocco che ti serve nel file del tuo client:
- Cursor → ~/.cursor/mcp.json
- Claude Desktop → ~/Library/Application Support/Claude/claude_desktop_config.json
5. Riavvia il client. I client leggono la configurazione all'avvio.

Claude Desktop parla solo tramite ingresso e uscita standard, non in HTTP, quindi il suo blocco usa mcp-remote come ponte — è quello che fa npx in quella configurazione.

Calíope deve essere aperta perché il client trovi qualcosa. Se la chiudi, gli strumenti smettono di rispondere finché non la riapri.

Parole chiave: mcp, configurare, cursor, claude desktop, mcp-remote, json, client

Via MCP viaggiano righe. Vanno al tuo client, sulla tua macchina; cosa fa poi lo decide lui.

L'assistente di Calíope manda al modello, al massimo, i nomi dello schema. Il server MCP è un'altra cosa, ed è meglio dirlo chiaro: qui viaggiano righe, perché la risposta a una query sono i dati.

Dove vanno. Al client che hai configurato tu, in esecuzione su questa stessa macchina. Calíope non manda nulla su internet.

E poi. Cosa fa quel client con ciò che riceve — per esempio mandarlo al suo modello nel cloud per scrivere la risposta — lo decidono quel client e la sua informativa sulla privacy, non Calíope. Se questo conta per i tuoi dati, la decisione si prende prima di spuntare la connessione.

Come interromperlo, dal meno al più:
- Togli la spunta alla connessione: smette di esistere per il client.
- Spegni il server: smettono di rispondere tutte.
- Genera una nuova chiave: la precedente smette di funzionare subito, anche se qualcuno l'aveva.

Cosa resta scritto. Tutto ciò che si esegue via MCP finisce nel registro delle query, con la connessione e il risultato, come quello che scrivi tu. Ciò che viene rifiutato non arriva al server e non lascia nessuna riga.

Parole chiave: mcp, privacy, righe, dati, client, cloud, registro delle query

Invia il SQL generato dall'IA direttamente all'Editor SQL.

Dove si trova: Assistente IA › Apri nell'editor

Quando l'assistente genera un blocco SQL, sotto il codice appare il pulsante Apri nell'editor. Premendolo, Calíope apre un nuovo tab dell'Editor SQL con il SQL precaricato, pronto da rivedere ed eseguire.

Parole chiave: caricare, editor, aprire, sql generato, inserire

L'assistente riceve la struttura del database attivo finché l'interruttore è attivo.

Dove si trova: Workspace › Strumenti › IA

Con l'interruttore Inviare lo schema al modello attivo — lo è di fabbrica — e un database selezionato, Calíope legge l'elenco di tabelle, colonne e chiavi esterne dello schema attivo e lo invia al modello insieme alla tua richiesta. È questo che fa uscire SQL adattato alle tue tabelle reali senza descriverle a mano. Non viene inviata nessuna riga di dati. Puoi cambiare il database di contesto dal selettore nell'intestazione dell'assistente; si apre con un campo di filtro, per trovare un database dal nome quando il server ne ha molti.

Con l'interruttore disattivo, dello schema non viene inviato nulla e le tabelle vanno nominate nella domanda. È la scelta giusta quando la query riguarda poche tabelle, e con Apple Intelligence è anche ciò che evita che lo schema non entri nella finestra del modello.

Se l'account del server non ha i permessi per leggere il catalogo, l'assistente avvisa che il contesto non è stato caricato. Quell'avviso riguarda una lettura fallita: disattivare l'interruttore non lo produce, perché allora non è stato letto nulla in quanto nessuno l'ha chiesto.

Parole chiave: schema, contesto, tabelle, information_schema, permessi, schema context

Controlla quanto testo può generare il modello in ogni risposta.

Dove si trova: Calíope › Preferenze › Assistente IA

I modelli di IA lavorano con token — frammenti di testo di circa 0,75 parole ciascuno. L'impostazione Lunghezza massima del SQL stabilisce quanti token può generare il modello in una singola risposta. Riguarda unicamente l'output; non limita la lunghezza della tua richiesta né lo schema inviato.

Opzioni disponibili (in Preferenze › Assistente IA › Generazione):

- Compatto (800 token) — Sufficiente per query semplici: SELECT con una o due tabelle, filtri di base, GROUP BY semplice. Riduce il costo per chiamata e accorcia il tempo di attesa. Usalo se le tue query abituali sono corte e dirette.

- Standard (2 000 token) — Valore predefinito. Adatto alla grande maggioranza delle query, inclusi JOIN tra varie tabelle, subquery e CTE moderate.

- Esteso (4 000 token) — Per query molto complesse: più JOIN concatenati, CTE con vari rami, stored procedure o query analitiche lunghe. Usalo se il SQL appare troncato con le altre opzioni.

Quando aumentare la lunghezza? Se il SQL generato appare incompleto — ad esempio, la clausola FROM appare troncata a metà o manca la chiusura di un JOIN — è segno che il modello ha raggiunto il limite prima di terminare. Passa a Esteso per correggerlo.

Quando ridurla? Se fai solo query di manutenzione o di diagnostica rapida, la modalità Compatto è sufficiente e riduce il costo quando il provider addebita a token, e accorcia l'attesa quando il modello gira sulla tua macchina — lì quello che paghi è tempo.

L'impostazione si applica immediatamente; non è necessario riavviare l'applicazione né riaprire l'assistente.

Parole chiave: token, lunghezza, max token, sql tagliato, troncato, costo, generazione, lunghezza massima

Regola quanto tempo attende Calíope prima di annullare una chiamata all'API di IA.

Dove si trova: Calíope › Preferenze › Assistente IA

Alcuni modelli si prendono il loro tempo: quelli di ragionamento —o1, o3 o o4 di OpenAI, o Gemini Ultra— e quelli che girano sulla tua macchina, che rispondono alla velocità del computer che li esegue. Possono impiegare più di 30 secondi per generare una risposta a query complesse. Se Calíope annulla la chiamata prima che il modello finisca, vedrai un errore di timeout che sembra un guasto dell'app quando in realtà serviva solo più tempo.

In Preferenze › Assistente IA › Generazione ci sono due slider:

- Tempo limite di caricamento dei modelli (5–60 s, predefinito 15 s) — controlla quanto tempo attende Calíope nell'ottenere l'elenco dei modelli che pubblica il provider scelto.

- Tempo limite di generazione SQL (10–120 s, predefinito 30 s) — controlla quanto tempo attende Calíope per ricevere il SQL generato dal modello.

Quando aumentare il tempo di generazione? Se usi un modello di ragionamento, o uno locale su un Mac senza molta memoria, e ricevi errori nel generare query complesse, aumenta il valore a 60–90 s. Questi modelli pensano prima di rispondere e hanno bisogno di più tempo.

Quando lasciarlo al valore predefinito? Con gpt-4o o gemini-1.5-flash i 30 s sono più che sufficienti per la grande maggioranza delle query.

Le modifiche si applicano immediatamente senza riavviare l'applicazione.

Parole chiave: timeout, tempo limite, attesa, lento, o1, o3, o4, gemini ultra, errore, annullare, ragionamento

Usa il microfono per trascrivere le tue richieste all'assistente in tempo reale, senza che la tua voce esca dal dispositivo.

Dove si trova: Assistente IA › Microfono

Premi il pulsante del microfono accanto al campo di testo per attivare la dettatura. Parla nella lingua indicata dalla capsula accanto al microfono; il testo appare in tempo reale mentre parli. L'icona diventa rossa durante la registrazione.

Premendo di nuovo il pulsante la dettatura si ferma e il testo trascritto resta nel campo pronto da modificare o inviare direttamente con ↩.

Prima volta: il sistema chiede un solo permesso, quello del microfono. Quello di riconoscimento vocale non serve più, perché la trascrizione non esce dal dispositivo. Se lo rifiuti, puoi ripristinarlo in Impostazioni di Sistema › Privacy e sicurezza › Microfono.

Lingua: accanto al microfono c'è una capsula con il codice della lingua in cui si ascolta — IT, FR, EN… —, e mentre registri il campo la scrive per intero. Per impostazione predefinita è quella impostata in Calíope, con la variante regionale del tuo sistema quando esiste: l'app in francese su un Mac canadese detta in francese canadese. Premi la capsula per sceglierne un'altra. Le lingue il cui modello non è ancora sul dispositivo lo dicono al momento di offrirle, e se ne scegli una, un avviso sopra il campo ti ricorda che verrà scaricata alla prima dettatura; il download avviene una volta sola e da lì in poi funziona offline.

La tua voce non esce dal dispositivo: la trascrizione avviene interamente qui, senza inviare audio a nessun server, quindi funziona anche offline. Per questo, quando manca il modello della lingua, Calíope te lo dice invece di dettare tramite internet.

Errore all'avvio: se appare un messaggio di errore premendo il microfono, verifica che i permessi siano attivi e che nessun'altra applicazione stia usando il microfono in modo esclusivo.

Parole chiave: voce, microfono, dettatura, trascrizione, parlare, speech, mic, riconoscimento vocale

Salva la cronologia completa della conversazione con l'assistente come file di testo.

Dove si trova: Assistente IA › Esporta (↑)

Premi il pulsante ↑ (quadrato con freccia) nell'intestazione dell'Assistente IA per esportare la conversazione attiva. Il pulsante si attiva solo quando c'è almeno un tuo messaggio nella cronologia.

Premendolo si apre la finestra di dialogo di salvataggio del sistema. Il nome file predefinito include la data e l'ora attuali: caliope_ai_AAAAMMGG_HHmm.txt.

Contenuto del file esportato:
- Intestazione con data e ora di esportazione
- Database attivo, provider di IA e modello usati
- Tutti i messaggi della cronologia, contrassegnati con [Tu] o [Assistente IA]
- Blocchi SQL generati (se presenti), delimitati con --- SQL ---

Il file si salva in testo semplice (.txt) con codifica UTF-8, compatibile con qualsiasi editor di testo o strumento di analisi.

Nota: la cronologia è volatile — si azzera chiudendo il tab dell'assistente. Esporta la conversazione prima di chiuderla se hai bisogno di conservarla.

Parole chiave: esportare, salvare, conversazione, testo, cronologia, export, save, txt, file

Il SQL generato dall'IA richiede verifica e viene inviato a un servizio esterno.

Dove si trova: Assistente IA › Pannello SQL

Avviso «Generato dall'IA»

Ogni blocco SQL prodotto dall'assistente riporta a piè di pagina "Generato dall'IA · Verifica prima di eseguire" e il nome del provider che l'ha generato. Controllalo sempre prima di eseguirlo: i modelli linguistici commettono errori logici e si inventano nomi di tabella.

Dove va la tua domanda

Dipende dal provider che scegli, e sono cinque:

- OpenAI — ai suoi server. Chiave tua: platform.openai.com
- Google Gemini — ai suoi server. Chiave tua: aistudio.google.com
- Anthropic Claude — ai suoi server. Chiave tua: console.anthropic.com
- Apple Intelligence — da nessuna parte: il modello è di sistema e gira sul tuo dispositivo. Senza chiave.
- Ollama — solo all'indirizzo che scrivi tu: la tua macchina, o una della tua rete. Senza chiave.

Con i tre provider cloud, Calíope agisce da client di quel servizio e non memorizza mai la tua chiave su server propri né la condivide: vive nel Portachiavi del tuo dispositivo.

Che cosa viene inviato

Quando mandi una domanda viaggiano il tuo testo, gli ultimi 3 scambi della conversazione e, se l'interruttore «Inviare lo schema al modello» è attivo, i nomi di tabelle, colonne e chiavi esterne del database attivo.

Non vengono mai inviati i dati delle tabelle, le password né le credenziali di connessione.

→ Informativa sulla privacy completa

Parole chiave: avviso legale, generato dall'ia, disclaimer, api key, privacy, openai, gemini, dati inviati, verificare, sicurezza

Ogni conversazione con l'assistente viene salvata e può essere ripresa.

Dove si trova: Assistente IA › Cronologia (orologio)

Fai clic sull'icona dell'orologio nell'intestazione dell'Assistente IA per aprire il pannello della cronologia accanto alla chat. Ogni conversazione viene salvata appena invii la prima domanda, così una risposta fallita o un cambio di connessione non si porta via ciò che hai chiesto.

Riprendere una conversazione. Fai clic su una riga dell'elenco: diventa la conversazione attiva con tutto il suo contesto, e le domande successive proseguono quello stesso filo. Per ricominciare da zero usa il pulsante + dell'intestazione; il filo precedente resta nella cronologia.

Cercare. Il campo in alto cerca testo semplice nel titolo e in tutti i turni — anche nell'SQL generato —, non solo nei titoli.

Cosa mostra ogni riga. Il titolo deriva dalla tua prima domanda; sotto compaiono la data, il database che faceva da contesto e quante domande ha il filo.

Eliminare. Menu contestuale su una riga per rimuoverla, o icona del cestino in basso per cancellare tutta la cronologia.

Dove risiede. Su questo dispositivo, in ~/Library/Application Support/Caliope/ai_history.json. Si conservano le 200 conversazioni più recenti; raggiunto quel limite, il piede del pannello lo segnala. Nelle finestre strette il pannello si richiude a cassetto e resta raggiungibile dalla banda laterale.

Parole chiave: cronologia, conversazioni, salvare, riprendere, cercare, orologio, eliminare

Facoltativo: carica le tue conversazioni sul tuo iCloud privato per averle su tutti i dispositivi.

Dove si trova: Assistente IA › Cronologia › iCloud (nuvola)

La cronologia è locale per impostazione predefinita. La sincronizzazione si attiva con l'icona della nuvola nel piede del pannello, e Calíope chiede prima cosa fare con quanto già presente: caricare le conversazioni esistenti o sincronizzare solo quelle nuove.

Cosa viene caricato. Il titolo, la data, il contesto (connessione, database, fornitore e modello) e il transcript completo: le tue domande, le risposte e l'SQL generato. Finisce nel database privato del tuo account iCloud, non su un server di Calíope.

Credenziali. Prima di lasciare il dispositivo il testo passa per lo stesso oscuramento del registro delle query: un IDENTIFIED BY '…' o un SET PASSWORD diventa '***REDACTED***'. Il file locale conserva il testo originale.

Alla disattivazione Calíope chiede se conservare su questo dispositivo le conversazioni presenti su iCloud; se le scarichi, vengono fuse con quelle locali mantenendo la versione più recente di ciascuna.

Se qualcosa va storto l'icona diventa rossa: premila per vedere il motivo (account iCloud assente, restrizioni, rete) e riprovare o disattivare la sincronizzazione.

Eliminazione. Cancellare una conversazione o tutta la cronologia con la sincronizzazione attiva le rimuove anche da iCloud.

Parole chiave: icloud, sincronizzare, nuvola, cloudkit, dispositivi, privacy, oscurare

Copia una risposta, soltanto il suo SQL o l'intera conversazione.

Dove si trova: Assistente IA › Copia risposta

Sotto ogni fumetto c'è un pulsante Copia risposta: copia il testo e, se la risposta porta un blocco SQL, anche l'SQL. Il pulsante conferma con un segno di spunta per due secondi.

Solo l'SQL. Nell'intestazione del pannello di codice, accanto a Apri nell'editor, c'è Copia SQL.

Un frammento. Il testo dei fumetti e del pannello SQL è selezionabile: trascina su una parte e copia con ⌘C.

L'intera conversazione. Menu contestuale su un fumetto per copiare quel turno, o menu contestuale su una riga della cronologia › Copia conversazione per ottenere il transcript completo con la sua intestazione di data e contesto — lo stesso formato del pulsante di esportazione.

Parole chiave: copiare, appunti, sql, selezionare, transcript, risposta