Finance Assistant

Il problema

La maggior parte delle app di finanza ti dà categorie fisse e si fida della propria classificazione automatica. Io volevo sapere esattamente quanto spende una famiglia in bollette, per i figli o in qualche acquisto d'impulso, su più banche, con numeri di cui potermi fidare. Ogni progetto (una famiglia, uno studio, una piccola impresa) ha il suo blueprint di categorie, gruppi e regole.

Cosa ho realizzato

Un monorepo in cinque parti, che si avvia con un solo comando:

• Un'interfaccia Next.js con chat, dashboard, import degli estratti conto, coda di revisione e un editor visuale dei blueprint.

• Un servizio FastAPI con il database (SQLite di default, Postgres opzionale) e migrazioni che girano all'avvio.

• Un servizio assistant che fa streaming della chat via SSE ed esegue i job batch.

• Un registry di tool servito come server MCP, e un plugin di Claude Code con i comandi e le regole di dominio.

Ero l'unico sviluppatore umano, responsabile di design, architettura e review. Parte dell'implementazione è stata fatta da agenti AI per il coding, tra cui il coding agent di GitHub Copilot.

Come funziona l'agente

• Agente blindato. Per ogni sessione di chat gira un processo headless di Claude Code con tutti i suoi tool nativi disattivati: niente shell, niente file. Può chiamare solo i tool di finanza, e le sessioni vengono riprese dopo un periodo di inattività ed eliminate dopo qualche ora.

• Regole di dominio come skill. Il system prompt vive nel plugin: convenzioni sui segni, date assolute, leggere prima di scrivere, chiedere conferma prima di cancellazioni o azioni massive, e una tabella che indica quando mostrare un componente UI invece del testo.

• L'AI propone, l'utente conferma. Ogni transazione registra chi ha deciso la sua categoria. L'agente non può salvare un blueprint: lo valida, mostra l'impatto sulle transazioni esistenti in una card di revisione, e il salvataggio è un pulsante che preme l'utente.

• Totali esatti. All'agente è vietato sommare numeri. Per qualsiasi totale chiama un report che somma i dati salvati, esclude i trasferimenti tra conti propri e restituisce la quota confermata rispetto a quella suggerita.

• Classificazione vincolata. All'import l'ordine è: regola salvata, poi la colonna categoria del file stesso, poi un modello limitato alle categorie foglia tramite uno schema enum, con fallback sulle regole quando nessun modello è disponibile.

Scelte interessanti

• Un solo registry di tool, due motori: gli stessi tool sono serviti via MCP per Claude Code ed esportati come function calling per OpenAI, così la UI non sa quale motore risponde.

• Lo scoping per progetto è imposto a livello di sessione del database invece che in ogni endpoint.

• Gli import riconoscono il formato del file dal contenuto, deduplicano tra estratti conto sovrapposti e si possono annullare in blocco.

• Confermare un esercente crea una regola riutilizzata dagli import futuri, anche tra banche diverse. Rinominare una categoria non riscrive mai i dati, grazie a chiavi stabili e alias.

• Local first: i servizi ascoltano solo su localhost e i dati stanno in un database locale. La documentazione dice chiaramente che il testo degli estratti conto viene inviato al provider del modello per la classificazione.