← Tutti i progetti
Case study · AI · RAG · Agenti · SaaS B2B

Un assistente IA che legge contratti e fatture, cita la frase esatta e agisce solo dopo l’approvazione.

Una piccola azienda dimentica una finestra di cancellazione di 60 giorni e paga per un altro anno. Il personale perde ore a cercare i PDF e nessuno vuole incollare i dati aziendali in un chatbot pubblico. Sanad risponde solo dai documenti dell'azienda, tiene traccia di ogni scadenza e pagamento, isola i dati di ogni azienda all'interno del database e propone azioni che una persona approva.
RuoloSolo: prodotto, backend, AI, frontend, brand
PeriodoSettembre 2026
TipoProdotto auto-iniziato, licenza MIT
TecnologiePython 3.12, FastAPI, Postgres 16 + pgvector, LangGraph, React 19
localhost:8080/
Dashboard Sanad
1.00
recupero ibrido hit · 3
0.94
precisione di citazione
100%
tentativi di iniezione bloccati
45
test su Postgres reale, gated in CI

Panoramica.

A chi serve, cosa va storto oggi, cosa fa Sanad.
Destinatari

Piccole e medie imprese

Un produttore con poche decine di contratti di fornitura, leasing, licenze software e fatture in italiano, inglese e talvolta arabo, e nessun team legale. La società demo è una calzaturiera immaginaria a Civitanova Marche.

Il problema

Le scadenze si nascondono nei PDF

Clausole di rinnovo automatico con 60 o 90 giorni di preavviso, le fatture vengono pagate in ritardo e rispondere "che cosa dice il nostro contratto di locazione..." significa aprire i file uno per uno. I chatbot pubblici sono fuori dalla tabella per i dati aziendali.

Il prodotto

Risposte fondate sui documenti, scadenze e un agente prudente

Carica i documenti una volta. Sanad estrae i termini, costruisce il registro dei contratti, il calendario e la proiezione del flusso di cassa, risponde alle domande con citazioni verificate e redige promemoria e lettere per l'approvazione.

Percorso nelle schermate.

Ogni schermata, catturata dallo script end-to-end del progetto.
01 · Spazio di lavoro

Una società, una chiave, uno spazio di lavoro isolato

Ogni azienda cliente è un tenant con la propria chiave API. L'accesso apre uno spazio di lavoro che vede solo i documenti di quell'azienda, e lo spazio di lavoro demo è un creatore di scarpe fittizio nelle Marche.

localhost:8080/
Schermo di accesso Sanad
Accedi con una chiave per azienda e un'area di lavoro demo con un clic
  • 1
    Chiavi memorizzate come hashViene memorizzato solo lo SHA-256 di ogni chiave API. Le mappe chiave di un tenant e i limiti tariffari per ogni richiesta si applicano.
  • 2
    Isolamento nel databaseOgni richiesta viene eseguita in una transazione che passa a un ruolo non privilegiato e imposta l'id del tenant. Senza questa impostazione, le query non restituiscono nulla.
  • 3
    Dati demo realisticiQuattro contratti, due fatture e due polizze in inglese, italiano e arabo, tra cui un contratto di locazione in .docx e una polizze in chiaro.
02 · Dashboard

Gli impegni dell’azienda e le decisioni da prendere

La dashboard trasforma otto documenti in numeri di cui un proprietario si preoccupa: impegni mensili, le prossime scadenze, il denaro in uscita proiettato e quante proposte di agenti sono in attesa.

localhost:8080/
Dashboard Sanad
Documenti, contratti, impegni mensili, approvazioni in sospeso, cash flow e scadenze
  • 1
    Impegni, non file€ 16.950 al mese nella demo, calcolata dalle commissioni estratte e dalla frequenza di fatturazione, con un totale di 12 mesi di € 219K.
  • 2
    Scadenze con conto alla rovesciaLe date di scadenza della fattura e l'ultimo giorno per dare preavviso su ogni contratto, ciascuno con i giorni rimanenti e un link alla fonte.
  • 3
    Approvazioni emerseLe proposte di agenti in sospeso vengono conteggiate sul dashboard e sul badge della barra laterale, quindi nulla attende inosservato.
03 · Chiedi

Risposte con la frase e la pagina esatte, oppure nessuna risposta

Fai una domanda in inglese, italiano o arabo. Sanad risponde solo dai file della società e mostra da dove proviene ogni citazione. Se non può sostenere una risposta, lo dice.

localhost:8080/ask
Chiedi la schermata con le risposte in inglese e arabo e un'iniezione bloccata
Risposte con citazioni e fiducia, e un tentativo di iniezione bloccato
localhost:8080/ask
Cassetto di citazione con la citazione evidenziata nella pagina
Ogni citazione apre la pagina con la frase citata evidenziata
  • 1
    Quotazioni verificateOgni citazione viene confrontata con il testo recuperato prima che raggiunga lo schermo. Le citazioni che non corrispondono sono cadute e la fiducia scende.
  • 2
    Tre lingueLo stesso gasdotto risponde in inglese, italiano e arabo, tra cui una domanda araba su una politica araba.
  • 3
    Guardie che si spiegano"Ignora tutte le istruzioni precedenti" viene bloccato prima di qualsiasi chiamata di modello, con i modelli abbinati e il punteggio mostrato invece di un errore silenzioso.
04 · Documenti

Carica PDF, documenti Word o testo e ottieni dati strutturati

Caricare contratti, fatture e politiche in uno dei quattro formati. Un operatore di background analizza, ritaglia, incorpora e classifica ogni file, quindi estrae i termini che contano.

localhost:8080/documents
Libreria documenti
Libreria con tipo, stato, lingua, pagine e dimensioni
localhost:8080/documents
Cassetto documenti con condizioni contrattuali estratte
Termini estratti con fiducia e pagine di prova
  • 1
    Tipo rilevato automaticamenteContratto, fattura, polizza o altro, con la lingua rilevata per file. I duplicati vengono catturati dall'hash dei contenuti.
  • 2
    Termini, non riassuntiParti, termine, rinnovo automatico, periodo di preavviso, tariffa e frequenza, termini di pagamento, sanzioni e legge applicabile, ciascuna legata alle pagine da cui proviene.
  • 3
    Valori non plausibili respintiUn periodo di preavviso di 900 giorni o una tassa negativa non raggiunge mai il registro. L'estrazione di nuovo-esecuzione è un clic.
05 · Contratti e fatture

Un registro che conosce l’ultimo giorno utile per disdire

Il registro dei contratti mostra ogni accordo con la sua regola di rinnovo e la data entro la quale deve essere inviata la notifica. Le fatture si siedono accanto ad esso con date di scadenza e totali.

localhost:8080/contracts
Registro dei contratti
Controparte, termine, rinnovo automatico, periodo di preavviso e termine di preavviso
localhost:8080/contracts
Registro delle fatture
Fatture con numeri, emissione e date di scadenza e importi
  • 1
    Termine di comunicazione, calcolatoFine del termine meno il periodo di preavviso, regolato per i cicli di rinnovo. È la data in cui il prodotto esiste.
  • 2
    Valore e termini di pagamentoTassa, frequenza di fatturazione e giorni di pagamento per contratto, quindi il flusso di cassa può essere proiettato da loro.
  • 3
    Prova a un clic di distanzaOgni riga rimanda al documento di origine e alle pagine da cui è stato estratto il valore.
06 · Calendario e flusso di cassa

Scadenze su un calendario, impegni su un grafico

Le scadenze di notifica, le date di scadenza delle fatture e i promemoria manuali condividono un calendario. La visualizzazione del flusso di cassa prevede dodici mesi di pagamenti in uscita da commissioni contrattuali e fatture aperte.

localhost:8080/calendar
Calendario delle scadenze e dei promemoria
Notifica scadenze, scadenze e promemoria per mese
localhost:8080/cashflow
Proiezione del flusso di cassa di 12 mesi
Deflussi impegnati per mese, suddivisi in contratti e fatture
  • 1
    Promemoria che controlliCreare un promemoria a mano o approvare uno l'agente proposto. I promemoria approvati vengono inviati via e-mail quando SMTP è configurato o registrato.
  • 2
    Proiezione dai terminiI prossimi 12 mesi, la media mensile, il mese di punta e l'importo che dipende dai rinnovi si potrebbe ancora annullare.
  • 3
    Contratti vs fattureOgni mese divide le commissioni fisse del contratto dalle fatture aperte, quindi il proprietario vede quale parte è negoziabile.
07 · Agente

Analizza liberamente e chiede conferma prima di agire

Dare a Sanad un obiettivo come "trovare il rinnovo più urgente e redigere una lettera di cancellazione". Un agente LangGraph legge il registro e le scadenze, quindi si ferma con proposte che una persona approva o rifiuta.

localhost:8080/agent
L'agente corre in pausa per l'approvazione con una lettera redatta
Step trace, tool call e tre proposte in attesa di approvazione
localhost:8080/agent
Agente completato
Una corsa completata dopo che le proposte sono state decise
  • 1
    Strumenti di lettura in esecuzione, strumenti di azione in attesaI contratti di quotazione e le scadenze vengono eseguiti immediatamente. Creare un promemoria o redigere una lettera diventa una proposta e il grafico si ferma.
  • 2
    L'approvazione può venire giorni dopoLe esecuzioni vengono controllate in Postgres, quindi una decisione può arrivare da un altro processo dopo un riavvio. Le proposte indecise sono state respinte.
  • 3
    Una traccia completaOgni passaggio, tool call, risultato, proposta e decisione viene archiviato e registrato. Le lettere vengono salvate, mai inviate.
08 · Utilizzo

Quanto costa ogni risposta, per azienda

I token, i costi e la latenza vengono misurati per ogni chiamata di modello e raggruppati per tenant, operazione e modello. Un registro di audit registra ogni decisione umana e ogni azione eseguita.

localhost:8080/usage
Schermata di utilizzo e audit
Chiamate, token e costo per operazione, più il registro di audit
  • 1
    Costo per operazioneI passaggi di incorporazione, classificazione, estrazione, risposta e agente vengono misurati separatamente, quindi la parte costosa è ovvia.
  • 2
    Numeri neutrali per il fornitoreLa stessa visualizzazione funziona offline, con OpenAI o un endpoint compatibile con OpenAI dell'UE o con Claude.
  • 3
    Un audit trail per impostazione predefinitaLe approvazioni, i rifiuti e le azioni eseguite sono scritte come eventi di audit, con chi ha deciso e quando.
Server MCP per Claude Desktop, Claude Code e Cursor
Documenti OpenAPI
Log JSON strutturati con ID di richiesta
Tracciamento Langfuse opzionale
Inizio Docker con un solo comando
Modalità scura
arabo RTL risposte

Valutazione.

Misurato su 44 domande d'oro in CI. La costruzione fallisce al di sotto delle soglie.

Recupero delle fonti · 35 domande con risposta

Modalitàhit@1hit@3MRR
Vector solo0.910.970.95
Solo parole chiave0.941.000.97
Ibrido (RRF)0.941.000.97

Risposte ed estrazione

MetricPunteggio
Risposta corretta0.94
Precisione di citazione0.94
Motivazione1.00
Astensione su una risposta0.80
Tasso di blocco di prompt injection1.00
Precisione del campo di estrazione1.00

Esperimento · Dimensione dei segmenti e sovrapposizione

Chunk / sovrapposizioneibrido hit · 3MRRcorrettezza
400 / 601.000.940.86
800 / 1201.000.970.94
1200 / 1801.000.970.91

Cosa significano i numeri

I punteggi provengono dal provider offline, quindi ogni esecuzione è gratuita e ripetibile. L'aggiunta di intestazioni di blocchi contestuali ha generato un hit solo vettoriale · 1 da 0,85 a 0,91 e un hit ibrido · 3 da 0,97 a 1,00. Il set d'oro copre inglese, italiano e arabo, domande senza risposta e tentativi di iniezione. I restanti errori sono una domanda cross-linguale e due quasi-miss, e la precisione di estrazione 1.00 è una base di regressione sui documenti del campione, non un reclamo su contratti non visti.

Architettura.

Un Postgres per tutto, un'API apolide e un lavoratore e un livello di modello neutrale per il provider.
Clienti
React 19 UIVite · TypeScript · Tailwind v4 · TanStack Query · chiaro e scuro · desktop e mobile
Server MCPCerca, chiedi, il registro dei contratti e le scadenze come strumenti per Claude Desktop, Claude Code o Cursor
REST API31 endpoint con una specifica OpenAPI · una chiave API per azienda
→
Servizi (Python 3.12)
FastAPIAuth · limiti tariffari · guardrails · hybrid RAG · risposte a terra · agent run e decisioni
LavoratoreParse · chunk · embed · classifica · estratto · promemoria · rivendicato da una coda Postgres con SKIP LOCKED e retries
LangGraph agenteStrumenti di lettura vs strumenti di azione · interrupt() per l'approvazione · AsyncPostgresSaver checkpoints
→
Dati e modelli
Postgres 16 + pgvectorVettori HNSW · tsvector full-text · RLS su ogni tabella tenant · coda di lavoro · checkpoint · tabelle di utilizzo e audit
Livello modelloOffline (no key) · OpenAI o qualsiasi endpoint UE compatibile con OpenAI · Antropic Claude · una variabile da cambiare
ConsegneDocker Compose: db, migrazioni, api, worker, ui · GitHub Azioni: ruff, mypy, test, evals, build di immagini, scansione segreta
Circa 5.500 linee di Python nell'API, 700 linee di test e 5.500 linee di TypeScript nell'interfaccia utente, con sei record di decisioni di architettura che spiegano le scelte principali.

Approfondimenti tecnici.

Sei decisioni, ognuna con il suo costo.

1. Le citazioni vengono verificate

Problema
I modelli linguistici inventano citazioni convincenti. In un prodotto sui contratti, una clausola falsa distrugge la fiducia.
Approccio
Il modello cita le fonti numerate. Ogni citazione è normalizzata e abbinata al pezzo recuperato, esattamente o su almeno il 90% dei suoi token per tollerare il rumore OCR. Le citazioni non verificabili vengono eliminate e la fiducia viene abbassata.
Trade-off
Una risposta corretta che parafrasi invece di citare può perdere la sua citazione e mostrare una minore fiducia.
Nel codice: api/app/rag · grounded generation

2. L’isolamento tra aziende risiede in Postgres

Problema
Una perdita tra i contratti di due società terminerebbe il prodotto. "Ricordati di aggiungere WHERE tenant_id" non è un controllo.
Approccio
Ogni tabella tenant ha una politica di sicurezza a livello di riga per le letture e le scritture. Ogni richiesta esegue SET LOCAL ROLE a un ruolo non privilegiato e imposta app.tenant_id solo per quella transazione. Un contesto mancante viene chiuso e non restituisce nulla. La suite di test lo dimostra con SELECT grezzi.
Trade-off
HNSW esegue la scansione prima e RLS filtra dopo, quindi un piccolo tenant tra molti può ottenere meno di k candidati vettoriali.
Nel codice: ADR-003 · migrations · tests/test_rls.py

3. Approvazione solo dove è importante

Problema
Un agente che esamina i contratti è utile. Uno che crea promemoria o scrive ai fornitori da solo è una responsabilità.
Approccio
Gli strumenti sono disponibili in due classi. Gli strumenti di lettura vengono eseguiti non appena il modello li chiama. Gli strumenti di azione non vengono mai eseguiti quando vengono chiamati: diventano proposte e il grafico LangGraph si ferma su interrupt(). Stato è checkpointed in Postgres.
Trade-off
Fermarsi prima di ogni chiamata di strumento allenerebbe le persone a fare clic su approva senza leggere, quindi le letture innocue vengono eseguite incustodite dal design.
Nel codice: ADR-004 · api/app/agent

4. Ricerca ibrida, misurata

Problema
I documenti aziendali mescolano prosa con identificatori che le incorporazioni gestiscono male: numeri di fattura, IBAN, nomi di fornitori, numeri di clausola.
Approccio
La ricerca vettoriale e il testo completo Postgres vengono eseguiti in un'unica istruzione SQL e vengono fusi con la Fusione di rango reciproco. Ogni blocco è incorporato con il suo nome e titolo del documento e ogni risultato mantiene il suo rango di vettore e parola chiave per il debug.
Trade-off
Due indici da mantenere. Con incorporamenti lessicali offline, la ricerca di parole chiave da sola è forte come ibrida su questo corpus.
Nel codice: ADR-002 · api/app/rag/retriever

5. I testi recuperati sono input non attendibile

Problema
Un'istruzione dannosa può nascondersi all'interno di un documento caricato, non solo nella domanda dell'utente. Anche i dati aziendali non dovrebbero essere lasciati in chiaro.
Approccio
La scansione a prompt injection viene eseguita sulla domanda e su ogni blocco recuperato prima che entri nel prompt. IBAN, e-mail, numeri di telefono e codici fiscali italiani vengono mascherati in modo reversibile prima di qualsiasi chiamata di modello esterna e ripristinati nella risposta.
Trade-off
Il rilevamento basato su pattern deve essere mantenuto quando compaiono nuovi fraseggi di attacco.
Nel codice: api/app/guardrails · injection, pii, ratelimit

6. Un provider offline integrato nel sistema

Problema
Test, eval CI e demo di prima esecuzione non dovrebbero avere bisogno di una chiave API o di denaro, e alcuni clienti richiederanno modelli ospitati nell'UE.
Approccio
Ogni attività ha un'implementazione deterministica: incorporazioni lessicali, risposte estrattive, estrazione di regex e una politica di agenti scriptizzati. OpenAI, qualsiasi endpoint UE compatibile con OpenAI o Claude li sostituisce con una variabile di ambiente. I lavori vengono eseguiti da una coda Postgres con SKIP LOCKED.
Trade-off
La qualità offline è onesta ma limitata: manca di sinonimi e domande cross-linguali, e il rapporto eval elenca tali mancanze.
Nel codice: ADR-005 · ADR-006 · api/app/llm

Mobile e tema scuro.

Lo stesso prodotto su un telefono, e dopo ore.
Chiedi schermo sul cellulare
Registro dei contratti su mobile
Menu di navigazione su mobile
localhost:8080/
Dashboard in modalità scura
Dashboard in modalità scura
localhost:8080/agent
Agente in modalità scura
Agente eseguito in modalità scura