Dott. Geminiano - Il commercialista AI

🇬🇧 Read in English

TL;DR: Un "commercialista autonomo" open-source e local-first pensato per i forfettari italiani. Ti aiuta a importare ed emettere fatture, tenere traccia degli incassi e stimare le tasse grazie a un agente AI che lavora sotto la tua supervisione.

Nota: Questo progetto non fornisce consulenza fiscale o legale ufficiale. Verifica sempre i risultati con il tuo commercialista di fiducia.

A chi è rivolto?

• Freelance e ditte individuali in Regime Forfettario.
• Sviluppatori interessati a creare agenti AI trasparenti e verificabili.
• Chiunque voglia un "secondo parere" AI da confrontare con il proprio commercialista.

Perché questo progetto

L'idea nasce dal Project Vend di Anthropic: un esperimento per vedere se un'AI potesse gestire un negozio autonomamente. Volevo testare la stessa autonomia su un caso reale e verificabile, quindi ho scelto la mia Partita IVA. L'obiettivo? Confrontare l'operato dell'agente con quello del mio commercialista in carne ed ossa.

Project Vend: Il Contesto

In "Project Vend", Anthropic ha creato un negozio gestito interamente da un'AI di nome "Claudius". I risultati sono stati interessanti ma imperfetti: l'AI faticava a decidere i prezzi, si faceva manipolare dai clienti (che ottenevano sconti assurdi) e aveva persino crisi d'identità. Nella fase due, con strumenti migliori e un "CEO AI" a supervisionarlo, le cose sono migliorate, ma la tendenza dell'AI a compiacere l'utente rimaneva un punto debole.

La lezione è chiara: c'è ancora un grosso divario tra un'AI "capace" e una "robusta", specialmente quando servono negoziazione e giudizio critico.

Un approccio diverso: Adempimenti Fiscali vs. Vendita

Geminiano affronta un problema diverso: la conformità fiscale (compliance). A differenza della vendita al dettaglio, dove i prezzi fluttuano e si negozia, le tasse in Italia seguono regole rigide e deterministiche:

Aspetto	Project Vend (Retail)	Geminiano (Fisco Italiano)
Prezzi	Discrezionali / Mercato	Fissi (in base alla fattura)
Regole	Buon senso / Euristiche	Legge (L. 190/2014 e succ.)
Obiettivo	Profitto	Correttezza (zero errori)
Rischio abusi	Clienti che "tirano" il prezzo	Minimo (è un tool per uso proprio)
Conseguenze errori	Perdita di soldi	Sanzioni fiscali

La domanda quindi cambia: non "l'AI sa fare business?", ma "qual è il giusto equilibrio tra la flessibilità dell'AI e la rigidità delle leggi fiscali?"

L'agente deve essere flessibile per:

• Capire richieste naturali ("fammi una fattura per la Rossi Srl per il lavoro di gennaio")
• Guidarti passo-passo nelle procedure
• Spiegare regole oscure in modo semplice

Ma deve essere rigido e deterministico quando:

• Fa i calcoli (mai "a mente", usa sempre la calcolatrice)
• Controlla i limiti (soglia 85k, marca da bollo, diciture obbligatorie)
• Applica le regole (valida tutto contro un "rulepack" ufficiale)

Il risultato è un sistema ibrido: l'LLM (l'intelligenza artificiale) gestisce il dialogo, ma sono gli strumenti software (il codice) a garantire che le regole siano rispettate.

Funzionalità principali

• Chat Intelligente: Interagisci in linguaggio naturale, ma approvi manualmente ogni operazione critica (fatture, pagamenti).
• Fattura Elettronica: Importa i tuoi XML (FatturaPA) o creane di nuovi con un'anteprima chiara.
• Controllo Requisiti: Verifica automatica di soglie, marche da bollo e diciture di legge.
• Situazione Fiscale: Traccia incassi, contributi INPS e stima le tasse (saldo e acconti) in tempo reale.
• Privacy Totale: I tuoi dati (ledger, profilo, clienti) restano sul tuo computer nella cartella data/.

---

Architettura del Sistema

Il core del sistema è ChatConductor, un agente orchestratore basato su Gemini 3 Flash che implementa il pattern ToolLoopAgent di AI SDK v6.

Principi Architetturali

1. Orchestrazione Centralizzata: Un singolo agente gestisce l'intero ciclo di vita delle richieste, dal parsing del linguaggio naturale all'esecuzione di workflow complessi (es. emissione fattura).
2. Determinismo Computazionale: L'LLM delega ogni operazione logico-matematica a strumenti (tools) deterministici. Questo elimina le allucinazioni su calcoli fiscali e verifiche di conformità.
3. Human-in-the-Loop: Le operazioni di scrittura (side-effects) sono protette da gate di approvazione. L'agente propone un'azione strutturata (preview), ma l'esecuzione richiede conferma esplicita.
4. Validazione Policy-Driven: Ogni operazione è validata a runtime contro un "rulepack" versionato, garantendo la conformità alle normative vigenti indipendentemente dal prompt dell'utente.

Contesti di Esecuzione

L'agente adatta il proprio comportamento e il set di strumenti disponibili in base al contesto operativo (Mode Switching):

Modalità	Scopo	Strumenti Attivi
general	Consultazione stato, analisi fiscale, Q&A normativo	Full Access
invoice	Workflow di fatturazione attiva	Scoped: Ricerca anagrafica, Preview, Emissione
import	Ingestione dati (XML legacy)	Scoped: Parser XML, Ledger Commit

---

Sistema di Tooling

L'agente interagisce con il sistema tramite interfacce funzionali tipizzate, suddivise per livello di sicurezza (Safety Tiering):

1. Read Tools (Side-Effect Free)

Operazioni di sola lettura sicure per esecuzione autonoma.

Strumento	Funzione
get_state	Recupera lo snapshot corrente del ledger (fatturato, incassato, esposizione fiscale)
get_dashboard	Genera la vista sintetica in markdown per la UI
get_rulepack	Accede alle definizioni normative (soglie, aliquote, metadati)
get_profile	Recupera i dati anagrafici e fiscali dell'utente
profile_readiness_check	Valida la completezza del profilo fiscale
clients_list/search	Interroga il database anagrafico clienti

2. Compute Tools (Deterministic)

Motori di calcolo puri. Garantiscono riproducibilità e precisione decimale (nessuna inferenza probabilistica).

Strumento	Funzione
tax_calc_forfettario	Motore di calcolo imposta sostitutiva e deduzioni
invoice_preview	Pre-validatore fattura: verifica soglie, calcolo bollo, next-hop numerazione
inps_due	Calcolatore contributivo (Gestione Separata)
tax_schedule	Generatore scadenziario fiscale (Saldo/Acconti)

3. Write Tools (Approval Gated)

Operazioni che mutano lo stato del ledger. Richiedono token di approvazione esplicito.

Strumento	Funzione
invoice_issue	Transazione atomica di emissione (assegnazione protocollo + persistenza)
import_invoice_xml	Ingestione e normalizzazione di FatturaPA esistenti
record_payment	Registrazione incasso (cash basis accounting)
record_tax_payment	Registrazione versamenti F24 (Erario)
record_inps_payment	Registrazione versamenti F24 (Previdenza)
upsert_profile	Gestione anagrafica utente/clienti

Questi strumenti implementano un modello di sicurezza a doppio livello:

1. UX Gate: Interruzione del flusso per conferma utente (Human-in-the-Loop).
2. Correctness Gate: Validazione server-side pre-commit (Business Logic Validation).

---

Rulepack: Single Source of Truth

L'architettura disaccoppia la logica dell'agente dalle regole fiscali. Il file config/rules/forfettario.rulepack.json funge da Single Source of Truth per la compliance:

• Soglie Dimensionali: €85k (Soft Cap - uscita differita), €100k (Hard Cap - cessazione immediata).
• Protocolli di Fatturazione: Codici RF19/N2.2, logica marca da bollo (€2.00 > €77.47), diciture di legge.
• Parametri Fiscali: Coefficienti di redditività ATECO, aliquote sostitutive (5%/15%), deducibilità INPS.
• Previdenza: Aliquote Gestione Separata indicizzate per anno fiscale.

Il sistema implementa un controllo di Freshness sui metadati del rulepack, allertando l'utente in caso di definizioni normative obsolete (> 6 mesi).

---

Data Flow & Persistenza

Il sistema utilizza un'architettura Event Sourcing su file system locale:

1. Ledger (Append-Only): Ogni mutazione di stato è un evento immutabile registrato in data/ledger/journal.csv.
2. Derived State: Lo stato corrente (state.json) è una proiezione effimera ricostruita processando sequenzialmente il ledger.

---

Per iniziare (Quickstart)

Nota Local-First: Geminiano è progettato per l'esecuzione locale (localhost). Non richiede database esterni o infrastrutture cloud complesse (eccetto la chiamata API al modello).

1. Installa le dipendenze:

   bun install

2. Crea il file .env.local con la tua chiave API:

   GOOGLE_GENERATIVE_AI_API_KEY="LA_TUA_CHIAVE_GOOGLE_AI_STUDIO"

3. Avvia il server di sviluppo:

   bun run dev

   L'interfaccia sarà disponibile su http://localhost:3000.

Gestione Dati e Privacy

I dati risiedono esclusivamente in data/ (gitignored).

Comando	Scope	Effetto
bun run data:wipe	Ledger, Logs, Drafts	Soft Reset: Elimina transazioni ma mantiene configurazione (Profilo, Rulepack)
bun run data:wipe:all	Intera directory data/	Factory Reset: Elimina tutto, inclusa identità fiscale

Gestione Errori e Compliance

Il sistema adotta una politica di Fail-Closed per le violazioni normative.

Codice Errore	Severità	Descrizione Tecnica
THRESHOLD_HARD_CAP	Blocking	Rilevato superamento soglia €100k. Inibizione emissione fattura per decadenza immediata regime.
THRESHOLD_SOFT_CAP	Warning	Superamento soglia €85k. Flag per transizione a regime ordinario anno n+1.
MISSING_BOLLO	Reject	Mancata applicazione bollo virtuale su importo > €77.47 (DPR 642/72).
WRONG_REGIME	Reject	Rilevato codice regime incompatibile (Atteso: RF19).
OUT_OF_SCOPE	Escalate	Operazione non supportata dal rulepack corrente (es. Intrastat, Reverse Charge).

Cosa NON fa ancora (Out of Scope)

Per design, Geminiano non gestisce scenari che richiedono discrezionalità interpretativa o compliance complessa:

• Operazioni Estere (Intrastat, VIES, Dogana)
• Gestione Personale Dipendente
• Cespiti e Ammortamenti
• Trading/Plusvalenze Finanziarie

Contribuire

Le Pull Request sono benvenute! Leggi CONTRIBUTING.md prima di iniziare.

Licenza

MIT (vedi package.json).