📄 Configurazione CSV Custom (Ricerca su CSV)

Guida completa per configurare ricerche su file CSV personalizzati con AI4CALL: carica il tuo database CSV e permetti all'assistente di interrogarlo in tempo reale

Vai in "MARKET" → "Marketplace Plugin" e clicca su Acquista di "CSV Custom" → FREE

Vai in "MARKET" → "I Miei Plugin" e clicca su Configura di "CSV Custom"

🚀 Navigazione rapida:

⚠️ Servizi di terze parti

Le integrazioni descritte fanno riferimento a servizi di terze parti.
Rate limit, modalità di autenticazione, configurazioni tecniche, costi e policy sono definiti esclusivamente dai rispettivi provider e possono variare nel tempo.

I costi dei servizi esterni sono sostenuti direttamente dall’utente finale a favore dei fornitori dei servizi stessi e non sono in alcun modo gestiti o intermediati dal nostro portale (es. Meta o altri fornitori per WhatsApp, Zapier, Calendly, ecc.).

⚠️ IMPORTANTE - Modulo SOLA LETTURA

CSV Custom è progettato ESCLUSIVAMENTE per ricerche (query) sui dati.

L'assistente può:

✅ cercare righe nel CSV usando filtri
✅ leggere e comunicare i dati trovati
✅ combinare ricerche con logica AND

L'assistente NON può:

❌ modificare valori nelle celle
❌ aggiungere nuove righe
❌ eliminare righe esistenti
❌ modificare struttura colonne

Per aggiornare i dati: modifica il CSV manualmente e ricaricalo nel sistema.

Cos'è CSV Custom e quando usarlo

CSV Custom è un modulo MCP per caricare file CSV (Comma-Separated Values) e permettere all'assistente AI di interrogarli tramite ricerche strutturate.

📊 CSV Custom vs Excel Custom:

CSV Custom:

✅ solo file .csv (testo puro separato da virgole/punto e virgola)
✅ più veloce per grandi dataset (100K+ righe)
✅ più leggero in memoria
✅ compatibile con export da qualsiasi database/sistema
❌ no formule, no formattazione, no multi-sheet
❌ solo tabelle piatte (rettangolari)

Excel Custom MCP:

✅ file .xlsx/.xls con formule e formattazione
✅ multi-sheet support
✅ calcoli automatici
⚠️ più pesante, più lento su file grandi

💡 Quando usare CSV Custom

Use case ideali:

1. Database esportati: export da CRM, ERP, database SQL in formato CSV
→ es. clienti, prodotti, ordini, inventario, log

2. Liste strutturate: dati tabulari senza formule
→ es. schede SIM, codici IMEI, cataloghi, tariffari

3. Dataset grandi: migliaia di righe da interrogare velocemente
→ performance migliori vs Excel per volumi alti

4. Integrazione legacy: sistemi che esportano solo CSV
→ compatibilità universale

📋 Requisiti file CSV

Il file CSV deve rispettare questi requisiti:

1. Riga header obbligatoria:
Prima riga = nomi colonne separati da virgola/punto e virgola
numero,imei,idsim

2. Separatore consistente:
Usa sempre lo stesso separatore in tutto il file (virgola o punto e virgola)

3. Encoding UTF-8:
Per supportare caratteri accentati (à, è, ì, ò, ù)

4. Struttura rettangolare:
Tutte le righe devono avere lo stesso numero di colonne

5. No righe vuote:
Rimuovi righe completamente vuote prima del caricamento

Carica il file CSV

Carica il tuo file CSV nel sistema AI4CALL per renderlo disponibile alle ricerche dell'assistente.

🎯 procedura di caricamento:

Seleziona "CSV Custom" dall'elenco dei tuoi Plugin
Nella sezione "Upload Nuovo CSV", clicca "Scegli file"
Seleziona il file .csv dal tuo computer
Il sistema analizza il file e mostra:
- Nome file (es. nwc_gateway_sim_1_)
- Numero colonne rilevate (es. 3 colonne)
Il file appare in "CSV Disponibili"
Seleziona il file per configurarlo (sezione "CSV da configurare")
Verifica che lo stato sia "CSV ATTIVO" (badge verde)

✅ File caricato correttamente

Quando il caricamento è riuscito, vedrai:

Badge verde: nome file con numero colonne (es. "nwc_gateway_sim_1_ (3 colonne)")
Stato Attivo: pulsante "CSV ATTIVO" visibile
Sezione configurazione: tool e mapping colonne disponibili

Puoi ora procedere con la configurazione del tool di ricerca!

⚠️ Errori comuni durante l'upload

Se il caricamento fallisce, verifica:

1. Encoding non UTF-8:

Soluzione: apri CSV in editor testo, salva come UTF-8

2. Righe con numero colonne diverso:

Soluzione: apri in Excel, controlla che ogni riga abbia stesso numero celle, rimuovi righe malformate

3. Caratteri speciali nel nome file:

Soluzione: rinomina file senza spazi, accenti, caratteri speciali (usa underscore: data_clienti.csv)

4. File troppo grande (>10MB):

Soluzione: dividi in più CSV tematici o filtra righe non necessarie

Pannello CSV Custom: upload file, lista CSV disponibili, configurazione tool e mapping colonne

Configura il tool di ricerca

Definisci i parametri del tool che l'assistente userà per interrogare il CSV.

⚙️ campi di configurazione:

Nome Tool: identificativo univoco del tool
→ es. CSV_nwc_gateway_sim_1_, CSV_clienti, CSV_prodotti
→ auto-generato ma puoi modificarlo
→ usa nomi descrittivi se hai più CSV

Max Risultati: limite righe restituite per ricerca
→ es. 100 (raccomandato)
→ previene sovraccarico conversazione con migliaia di risultati
→ valori tipici: 50-200

Descrizione: spiega all'AI cosa contiene il CSV
→ es. "Tool personalizzato per query su database schede SIM"
→ aiuta l'AI a capire quando usare questo tool vs altri
→ sii specifico e conciso

💡 Esempio configurazione: database SIM

CSV: nwc_gateway_sim_1_.csv (3 colonne: numero, imei, idsim)

Nome Tool: CSV_database_sim
→ chiaro e descrittivo

Max Risultati: 100
→ anche con 10.000 SIM, restituisce max 100 risultati per ricerca

Descrizione: Ricerca nel database schede SIM aziendali per numero, IMEI o ID SIM
→ l'AI capisce: questo tool serve per trovare SIM, parametri disponibili sono numero/IMEI/ID

🎯 Best practice Max Risultati

Come scegliere il valore corretto:

50-100: ricerche specifiche (es. cerca per ID univoco)
→ tipicamente 1-10 risultati attesi
→ ottimo per conversazioni rapide

100-200: ricerche generiche (es. cerca per città)
→ 10-100 risultati attesi
→ l'AI può riassumere o chiedere filtri addizionali

200+: solo se necessario per use case specifici
→ attenzione: troppi risultati rallentano risposta e confondono utente

Regola generale: inizia con 100, aumenta solo se necessario. Se ricerche restituiscono sempre Max Risultati (es. sempre 100/100), significa che il filtro è troppo generico - istruisci l'assistente a chiedere parametri più specifici.

Mappa le colonne ricercabili

Definisci quali colonne del CSV sono ricercabili dall'assistente e come interpretarle.

🗺️ mapping colonne (es. 3/3):

Per ogni colonna del CSV, configura:

1. Abilitata (toggle ON/OFF):
→ se ON: colonna è ricercabile dall'AI
→ se OFF: colonna esiste nel CSV ma invisibile all'AI

2. Colonna (nome):
→ nome esatto dalla riga header del CSV
→ es. numero, imei, idsim
→ auto-rilevato dal sistema, non modificare

3. Tipo (Testo/Numero):
→ Testo: ricerca parziale case-insensitive (nomi, descrizioni, codici alfanumerici)
→ Numero: ricerca esatta numerica (ID, quantità, prezzi, codici numerici)

4. Descrizione:
→ spiega all'AI cosa contiene questa colonna
→ es. "numero della sim", "imei della sim", "id della sim"
→ l'AI usa questa descrizione per capire quale parametro usare

📋 Esempio mapping completo: database SIM

CSV header: numero,imei,idsim

Colonna 1:

Abilitata: ✅ ON
Colonna: numero
Tipo: Numero (match esatto)
Descrizione: numero della sim

Colonna 2:

Abilitata: ✅ ON
Colonna: imei
Tipo: Testo (ricerca parziale - IMEI possono avere prefissi)
Descrizione: imei della sim

Colonna 3:

Abilitata: ✅ ON
Colonna: idsim
Tipo: Numero (ID univoco)
Descrizione: id della sim

Con questo mapping, l'assistente può cercare per numero esatto, IMEI parziale, o ID SIM.

⚙️ Tipo Testo vs Tipo Numero: come scegliere

Usa NUMERO quando:

✅ ID numerici (es. customer_id: 12345)
✅ codici numerici puri (es. idsim: 789)
✅ quantità, prezzi, metriche numeriche
✅ vuoi SOLO match esatto (cerca 123 trova solo 123, non 1234)

Usa TESTO quando:

✅ nomi, cognomi, descrizioni
✅ email, indirizzi, note
✅ codici alfanumerici (es. IMEI: "899910...", SKU: "PROD-123")
✅ vuoi ricerca parziale (cerca "Mario" trova "Mario Rossi")

Caso dubbio - codici numerici molto lunghi:
IMEI (15 cifre), codici fiscali numerici, numeri telefono → usa TESTO per ricerca parziale
Altrimenti l'utente deve fornire il codice ESATTO completo

Istruisci l'assistente per usare CSV Custom

Configura il prompt dell'assistente per utilizzare correttamente il tool di ricerca CSV.

📝 Workflow consigliati da inserire nel prompt

1. Ricerca per parametro singolo:
"Se il cliente fornisce un numero di telefono, cerca nel database SIM usando parametro 'numero'. Mostra: numero, IMEI associato, ID SIM. Se non trovato, comunica 'numero non presente nel database'."

2. Ricerca per IMEI:
"Se il cliente fornisce codice IMEI, cerca usando parametro 'imei'. Anche se fornisce solo parte del codice (es. prime 8 cifre), la ricerca funzionerà (tipo Testo). Mostra: SIM associata, numero, ID."

3. Ricerca multipla con filtri:
"Se il cliente cerca con più criteri (es. numero E idsim), usa entrambi i parametri nella stessa ricerca. Restituisci solo righe che matchano TUTTI i criteri."

4. Gestione risultati multipli:
"Se la ricerca restituisce più di 10 risultati, mostra i primi 5 e chiedi al cliente se vuole filtro più specifico o vedere tutti. Se restituisce Max Risultati (100/100), avvisa che ci sono più risultati non mostrati."

🧪 Test del sistema

Verifica che tutto funzioni correttamente:

Chiama l'assistente e chiedi di cercare un valore presente nel CSV (es. "Cerca numero 333-1234567")
L'assistente dovrebbe invocare search_csv con parametro corretto
Verifica che restituisca i dati corretti dalla riga trovata
Prova ricerca con valore NON presente → assistente dovrebbe dire "non trovato"
Prova ricerca con più parametri → verifica AND logic funzioni

Debugging: se non trova risultati attesi, verifica mapping colonne (nome esatto, tipo corretto, toggle ON).

🛠️ Tool search_csv

Specifiche tecniche del tool di ricerca su file CSV configurato.

🔍 search_csv

Esegue ricerca nel file CSV configurato filtrando per i parametri specificati. I parametri disponibili dipendono dal mapping colonne configurato nello step 4.

Parametri dinamici (esempio database SIM):

numero (opzionale, Numero): numero telefono SIM per match esatto
imei (opzionale, Testo): codice IMEI dispositivo per ricerca parziale
idsim (opzionale, Numero): ID univoco SIM per match esatto

Comportamento ricerca:

Parametri multipli: AND logico (devono matchare tutti)
Tipo Numero: match esatto (123 trova solo 123, non 1234)
Tipo Testo: substring case-insensitive ("mario" trova "Mario Rossi")
Limite: Max Risultati configurato (es. 100 righe max)

Response: array di righe CSV che matchano i filtri, con tutti i valori delle colonne mappate

Esempio invocazione:search_csv(numero=3331234567)→ restituisce righe dove colonna "numero" = 3331234567search_csv(imei="89991012")→ restituisce righe dove colonna "imei" contiene "89991012"search_csv(numero=3331234567, idsim=42)→ restituisce righe dove numero=3331234567 AND idsim=42

❓ Domande frequenti

Risposte alle domande più comuni su CSV Custom (Ricerca su CSV)

? Qual è la differenza tra Excel Custom MCP e CSV Custom?

Excel Custom supporta file .xlsx/.xls con formule, formattazione, multi-sheet. CSV Custom supporta solo file .csv (testo separato da virgole) ma è più veloce e leggero per grandi dataset. CSV Custom è ottimizzato per ricerche su dati strutturati semplici (tabelle pure) senza formule o formattazione. Usa CSV Custom per performance, Excel Custom per funzionalità avanzate.

? Posso modificare i dati del CSV tramite l'assistente AI?

No. CSV Custom è un modulo in SOLA LETTURA progettato esclusivamente per ricerche (query). L'assistente può cercare e leggere dati ma non può modificare, aggiungere o eliminare righe/colonne nel file CSV. Per modifiche, devi aggiornare manualmente il CSV e ricaricarlo.

? Cosa significa "Max Risultati" nella configurazione?

Limita il numero massimo di righe restituite da una singola ricerca (es. 100 righe). Previene che l'assistente restituisca migliaia di risultati che sovraccaricherebbero la conversazione. Se una ricerca matcherebbe 500 righe ma Max Risultati=100, verranno restituite solo le prime 100. Usa valori 50-200 per performance ottimali.

? Come funziona il mapping delle colonne?

Il mapping definisce quali colonne del CSV sono ricercabili e come. Ogni colonna mappata diventa un parametro del tool search_csv. Devi specificare: (1) Nome colonna esatto dal CSV, (2) Tipo dato (Testo o Numero) per ricerca ottimizzata, (3) Descrizione che spiega all'AI cosa contiene. Solo colonne mappate sono utilizzabili - colonne non mappate restano invisibili all'AI.

? Qual è la differenza tra tipo Testo e tipo Numero nel mapping?

Tipo Testo: ricerca con match parziale case-insensitive (es. cerca "mario" trova "Mario Rossi"). Tipo Numero: ricerca con match esatto numerico (es. cerca 12345 trova solo 12345, non 123456). Usa Numero per ID, codici numerici, quantità. Usa Testo per nomi, descrizioni, email, codici alfanumerici.

? Posso usare più file CSV contemporaneamente per le ricerche?

No. Il server MCP può esporre un solo file CSV alla volta come tool "search_csv". Puoi caricare e configurare più file, ma solo quello attivato con il bottone "ATTIVA CSV" sarà utilizzabile dall'assistente. Gli altri restano salvati ma non esposti.

? Il file CSV deve avere una riga di intestazione?

Sì, obbligatorio. La prima riga del CSV deve contenere i nomi delle colonne separati da virgola. Questi nomi saranno usati nel mapping. Esempio prima riga: numero,imei,idsim. Se il CSV non ha header, aggiungilo manualmente prima del caricamento, altrimenti il sistema interpreterà la prima riga di dati come nomi colonne.

? Qual è la dimensione massima del file CSV supportato?

Non c'è limite rigido, ma per performance ottimali mantieni CSV sotto 10MB (~100.000 righe). File più grandi rallentano ricerche e caricamento. Per dataset enormi: (1) dividi in più CSV tematici, (2) carica solo dati attivi/recenti, (3) pre-filtra dati non necessari. Il sistema carica CSV in memoria - file giganteschi possono causare timeout.

? Come aggiorno i dati nel CSV già caricato?

Non c'è update automatico. Per aggiornare: (1) elimina il vecchio CSV dalla lista "CSV Disponibili" (icona cestino), (2) carica il nuovo CSV aggiornato con "Upload Nuovo CSV", (3) riconfigura mapping se nomi colonne sono cambiati. Workflow consigliato: esporta dati aggiornati dal sistema sorgente → carica nuovo CSV → elimina vecchio. Non c'è merge automatico.

? Posso cercare con più filtri contemporaneamente?

Sì. L'assistente può usare più parametri nella stessa ricerca search_csv. Esempio: cerca righe con numero=3331234567 AND imei="899910...". Tutti i parametri specificati devono matchare (AND logico). Per ricerche OR (es. numero=X OR numero=Y), l'assistente deve fare ricerche separate e combinare risultati. Istruisci logica appropriata nel prompt.

? Come gestisco CSV con molte colonne (50+)?

Non mappare tutte le colonne - mappa solo quelle rilevanti per ricerche (5-15 colonne tipicamente). Colonne non mappate restano nel CSV ma invisibili all'AI. Priorità: (1) colonne chiave di ricerca (ID, codici), (2) colonne filtro comuni, (3) colonne informative da mostrare nei risultati. Troppi parametri confondono l'AI - meglio CSV multipli tematici che un CSV gigante con 50 parametri.

? Come debuggo se le ricerche non restituiscono risultati attesi?

Checklist: (1) verifica colonna sia mappata e abilitata (toggle ON), (2) controlla tipo dato corretto (Testo vs Numero), (3) verifica spelling esatto nomi colonne nel CSV header, (4) testa con ricerca molto generica prima, poi specifica, (5) controlla log AI4CALL (Risposte Tool) per parametri effettivamente inviati.

? Il sistema supporta CSV con righe duplicate?

Sì, non c'è de-duplicazione automatica. Se il CSV contiene righe duplicate, la ricerca le restituirà tutte (fino a Max Risultati). Se vuoi righe uniche: pulisci duplicati nel CSV sorgente prima del caricamento, oppure istruisci l'assistente a menzionare solo risultati unici se rileva duplicati. Excel/LibreOffice hanno funzione "Rimuovi duplicati".

? Posso usare CSV Custom insieme ad altri MCP server?

Assolutamente. L'assistente può combinare CSV Custom con altri tool. Esempio workflow: (1) cerca cliente in CSV_clienti, (2) verifica disponibilità appuntamenti con Calendly MCP, (3) prenota via Google Calendar MCP, (4) salva interazione su Google Sheets via Zapier, (5) invia conferma via Email SMTP. I tool MCP sono componibili - l'LLM orchestra automaticamente la sequenza ottimale.