Italian Investor: una Agent Skill open source per analizzare portafogli italiani senza inventare la fiscalità

L'intelligenza artificiale è estremamente comoda per analizzare un portafoglio. Posso darle un CSV con le mie posizioni e chiederle di individuare concentrazioni, plusvalenze latenti, esposizione geografica, possibili ribilanciamenti o implicazioni fiscali.

Il problema arriva quando dalle analisi finanziarie si passa alla fiscalità italiana: una risposta apparentemente plausibile può essere completamente sbagliata. Un ETF in guadagno può compensare le minusvalenze nello zainetto? Un ETF governativo è sempre tassato al 12,5%? Come si applica il 48,08% ai BTP? Che cosa succede al costo fiscale di un titolo ricevuto in successione?

Sono domande sulle quali un modello generalista può facilmente mescolare regole italiane, concetti americani, informazioni obsolete e semplificazioni trovate online. Da questo problema è nato Italian Investor: una Agent Skill open source pensata per Claude e altri agenti compatibili, costruita attorno a una regola fondamentale.

Il problema non era far fare i calcoli a Claude

I modelli linguistici sanno fare moltissime cose, ma non sono database normativi. Se chiedo a un chatbot quale sia il trattamento fiscale di uno strumento, potrebbe ricordare correttamente la regola, confonderla con una normativa precedente oppure produrre una risposta molto convincente ma falsa.

Durante lo sviluppo della skill mi è capitato un esempio particolarmente interessante. Stavo verificando direttamente l'articolo del TUIR relativo al riporto delle minusvalenze e un sistema di lettura del PDF mi ha restituito come citazione letterale «nei cinque periodi d'imposta successivi». Sembrava una risposta perfetta: proveniva da un documento ufficiale ed era addirittura presentata come testo testuale. Ma era sbagliata: il testo dice «non oltre il quarto».

Se avessi copiato quella risposta nel motore avrei introdotto un errore proprio durante il processo pensato per eliminare gli errori. Da quel momento il principio del progetto è diventato ancora più rigido: fonte, testo vigente, regola, calcolo. Mai il contrario.

Come funziona Italian Investor

Italian Investor non è semplicemente un prompt molto lungo: la skill separa tre responsabilità. Le fonti normative e i documenti di prodotto alimentano le regole verificate, le regole verificate alimentano calcoli Python deterministici, e solo alla fine Claude interpreta e spiega i risultati.

Claude viene utilizzato per ciò in cui un modello linguistico è particolarmente utile: interpretare i risultati, collegare informazioni, individuare problemi e spiegare le conclusioni. La parte che deve essere deterministica viene invece affidata agli script, mentre la parte normativa deve essere verificata sulle fonti.

Le fonti hanno una gerarchia

Non tutte le fonti hanno lo stesso valore. Italian Investor privilegia, in quest'ordine:

• •Normattiva, Agenzia delle Entrate, MEF, CONSOB, EUR-Lex ed ESMA
• •KID, prospetti e documentazione ufficiale degli emittenti
• •documentazione dei broker e database finanziari
• •blog, forum e discussioni online solamente come pista di ricerca

Una risposta fiscale importante non dovrebbe basarsi su un articolo SEO trovato online se è disponibile la norma o la circolare dell'Agenzia delle Entrate. La skill richiede inoltre di controllare la vigenza temporale della fonte: dal 1° gennaio 2027 sarà applicabile il nuovo testo unico delle imposte sui redditi, con una diversa numerazione degli articoli. Non basta quindi sapere quale sia la norma oggi, bisogna sapere quale norma fosse applicabile nel periodo fiscale analizzato.

ETF e minusvalenze: l'errore più tipico

Una plusvalenza ottenuta da un OICR/ETF non va trattata allo stesso modo di un capital gain azionario. Il guadagno dell'ETF rientra nei redditi di capitale, mentre le minusvalenze fiscali appartengono ai redditi diversi.

Questo significa che avere 5.000 euro di minusvalenze nello zainetto non consente automaticamente di abbattere un guadagno di 5.000 euro ottenuto vendendo un ETF. La perdita realizzata sull'ETF, invece, può alimentare lo zainetto nei limiti previsti dalla normativa. L'asimmetria è controintuitiva ed è esattamente il tipo di errore che un modello generalista tende a commettere.

BTP e il meccanismo del 48,08%

Dire semplicemente che i BTP sono tassati al 12,5% non è sempre sufficiente per implementare correttamente un calcolo. Per i redditi diversi derivanti dai titoli pubblici agevolati entra in gioco il meccanismo del 48,08%, e l'ordine delle operazioni conta.

Se realizzo 1.000 euro di capital gain su un BTP e possiedo 400 euro di minusvalenze utilizzabili, non devo prima sottrarre 400 e poi applicare il trattamento agevolato. Prima viene determinato il reddito fiscalmente rilevante (1.000 × 48,08% = 480,80 €) e solo dopo vengono considerate le minus (480,80 − 400 = 80,80 €). È una differenza apparentemente piccola nella procedura, ma produce risultati fiscali differenti: Italian Investor ha casi di regressione specifici per impedirne la reintroduzione.

Vale un discorso analogo per gli ETF governativi. Anche la frase «questo è un ETF governativo, quindi è tassato al 12,5%» è troppo semplice: per un OICR conta la quota del provento riferibile ai titoli pubblici agevolati, determinata secondo le informazioni dell'emittente o dell'intermediario. Se questa percentuale non è disponibile, Italian Investor non la inventa: restituisce uno scenario e indica esplicitamente il dato mancante.

Lo zainetto fiscale non è più un singolo numero

Un altro problema delle analisi generiche è rappresentare le minusvalenze come un unico totale. Nella realtà serve più contesto, quindi Italian Investor gestisce lo zainetto per lotti, con broker, regime, anno di realizzo e importo. In questo modo l'analisi conosce:

• •intermediario
• •regime fiscale
• •anno di realizzazione
• •scadenza
• •importo ancora disponibile

Nel regime amministrato una plusvalenza realizzata presso un broker non viene quindi automaticamente compensata utilizzando minusvalenze presenti presso un altro intermediario. Il simulatore può inoltre dare priorità alle minus in scadenza più vicina quando confronta differenti strategie.

Non fidarsi nemmeno del CSV

Anche avere una colonna con scritto «tipo: ETF» non significa che lo strumento sia realmente stato classificato. Per questo ho introdotto un piccolo instrument resolver: l'ISIN viene validato formalmente e può essere confrontato con un registry costruito utilizzando KID o prospetti verificati, dove ogni classificazione porta con sé la fonte e la data di verifica.

Se manca la fonte, manca la data o il tipo dichiarato nel portfolio è incompatibile con quello verificato, la modalità strict può bloccare l'analisi fiscale. L'obiettivo non è creare un gigantesco database finanziario interno: è evitare che una classificazione sbagliata all'inizio della catena produca una risposta fiscalmente perfetta... per lo strumento sbagliato.

E quando una regola non è abbastanza sicura?

Il comportamento desiderato è molto semplice: fermarsi. ETC ed ETN, OICR non armonizzati, PIR, previdenza complementare e altri strumenti che richiedono regole specifiche non vengono assimilati automaticamente a qualcosa di simile. Per un ETC/ETN, per esempio, la skill può richiedere di controllare la sezione fiscale del prospetto del singolo prodotto. Preferisco ottenere un NON VERIFICATO piuttosto che una risposta precisa ma potenzialmente falsa.

Successione

La successione è un altro argomento dove una singola frase può nascondere diversi problemi fiscali. Italian Investor obbliga a separare almeno quattro piani:

• •inclusione del titolo nell'attivo ereditario
• •eventuale imposta di successione
• •costo fiscalmente riconosciuto all'erede
• •tassazione di una futura vendita

Il piccolo modulo deterministico incluso nel progetto implementa solamente i casi per cui ho una regola sufficientemente definita. Anche qui il criterio è lo stesso: niente estensioni per analogia.

Ribilanciamento tax-aware

Una strategia di portfolio può essere teoricamente perfetta ma fiscalmente costosa. Per questo il progetto può confrontare diversi modi di avvicinarsi a un'allocazione target:

• •ribilanciamento immediato
• •utilizzo dei nuovi versamenti
• •ribilanciamento parziale
• •vendita prioritaria delle posizioni fiscalmente meno costose

Il calcolo considera anche il fatto che le tasse pagate escono realmente dal portafoglio: il capitale reinvestibile dopo una vendita può quindi essere inferiore al controvalore venduto.

Il claim audit

Alla fine di un'analisi la skill chiede al modello di distinguere le affermazioni prodotte, indicando per ognuna tipo, fonte e livello di confidenza. Il prezzo medio di carico di una posizione è un dato del broker; «il gain di un ETF è reddito di capitale» è una norma verificata; l'imposta stimata è un calcolo del motore Python; «ridurre questa posizione migliora il profilo di rischio» è un'opinione. Un dato, una norma, un calcolo e una raccomandazione non sono la stessa cosa, e nell'output devono restare separati.

Testare anche le regole fiscali

Ogni caso marcato come normativo nel progetto deve indicare fonte, articolo e data di verifica: se i metadati mancano, la CI fallisce. I test coprono oggi, tra gli altri, ETF/OICR, azioni, obbligazioni, BTP e titoli pubblici, componente governativa degli OICR, minusvalenze, zainetto fiscale, commissioni, ISIN, successione e i casi in cui il sistema deve rifiutarsi di calcolare.

Non significa che il software non possa avere bug. Significa però che una correzione normativa può diventare un test permanente invece di rimanere una nota in un prompt.

Cosa non vuole essere Italian Investor

Italian Investor non è un broker, non fornisce quotazioni di mercato, non vuole sostituire strumenti professionali di portfolio analytics, non compila automaticamente la dichiarazione dei redditi e soprattutto non è un consulente finanziario o fiscale.

Può però essere combinato con altri strumenti. Nel mio caso il flusso parte dal portfolio su Google Sheet, passa da un motore di analytics finanziaria che calcola rischio, correlazioni e performance, arriva a Italian Investor per il layer fiscale italiano e finisce a Claude, che mette insieme i risultati e li trasforma in un'analisi comprensibile.

Perché l'ho pubblicato open source

Il progetto nasce inizialmente per una mia esigenza personale. Ma una regola fiscale controllata da più persone è molto più utile di una regola nascosta in un prompt privato. Commercialisti, consulenti, sviluppatori e investitori possono segnalare un caso limite, indicare una fonte migliore, aggiungere un test, correggere un'interpretazione o verificare un nuovo strumento.

Il codice è disponibile pubblicamente su GitHub nel repository eliazv/italian-investor ed è distribuito con licenza MIT. Con Claude Code può essere installato come plugin dal marketplace, oppure la skill può essere clonata e copiata manualmente nella cartella delle skill locali. Gli script utilizzano solamente Python e non richiedono dipendenze esterne.

Stato del progetto

La versione attuale è la v0.4.0. La base include già il motore fiscale, lo zainetto strutturato, il controllo degli strumenti, il ribilanciamento tax-aware, alcuni casi successori e una suite di test automatici. Le aree ancora fuori dal core sono volutamente esplicite: preferisco ampliare il progetto quando emerge un caso reale invece di costruire in anticipo un motore fiscale enorme e difficile da verificare.

Il punto più importante

Italian Investor non nasce perché credo che l'intelligenza artificiale non possa essere utilizzata per la finanza. Nasce quasi per il motivo opposto: trovo estremamente comodo poter dare i miei dati a un agente e chiedergli di analizzarli.

Ma nei domini dove una risposta plausibile non è abbastanza, il modello deve avere strumenti che gli permettano di distinguere ciò che sa da ciò che ha realmente verificato. La parte interessante, per me, non è quindi insegnare a Claude tutte le regole fiscali italiane: è insegnargli quando non deve fidarsi di sé stesso.