Skip to content
Factum ParseFactum ParseFactum Parse

Factum Parse

Deterministic Italian Invoice Parsing & In-RAM Privacy Engine
Get an API keyAPI ReferenceSecurity & ZDR

Fatto, compiuto, verificato

Section titled “Fatto, compiuto, verificato”

Factum Parse estrae dati strutturati da documenti amministrativi italiani — FatturaPA XML, fatture PDF, F24 — con un contratto di output unico e versionato (DocumentEnvelope v2). Unione discriminata Pydantic v2 validata, mai JSON piatto.

Il percorso deterministico gestisce FatturaPA XML senza LLM; il PDF e il testo attraversano il confine di privacy solo dopo pseudonimizzazione PII locale.

41 ms**
Fast-Path · FatturaPA XML
Produzione misurata
$0.00**
Costo per XML deterministico
Zero token LLM
83.4%**
Test-suite coverage
284 passed / 6 skipped
100%
In-RAM mapping
Per-request PII

** Repository measurements, not a live SLA. 41 ms and 83.4% are historical — re-run benchmarks and build before relying on current values. $0.00 applies to the deterministic fast path, not to LLM-backed extraction (which incurs token cost). “In-RAM mapping” is an architectural property of the Rizzo restore boundary, not a claim that every artifact has zero retention — upload artifacts have explicit TTL/storage semantics.

Input → Output

Section titled “Input → Output”
Formato input Endpoint Output
XML FatturaPA (application/xml) POST /v1/uploads → file DocumentEnvelope v2 — kind: "invoice"
PDF fattura (application/pdf) POST /v1/uploads → file DocumentEnvelope v2 — kind: "invoice"
Testo diretto (F24, contratti, testi liberi) POST /v1/parse → { "text": "…" } DocumentEnvelope v2 — kind: "generic"

DocumentEnvelope v2 — contratto canonico

Section titled “DocumentEnvelope v2 — contratto canonico”
{
  "schema_version": "2.0",
  "document_type": "invoice",
  "meta": { "cost_eur": 0.0, "confidence": 0.97, "provider": "", "prompt_version": "" },
  "payload": {
    "kind": "invoice",
    "dati_trasmissione": { "IdTrasmittente": { "IdPaese": "IT", "IdCodice": "01234567890" } },
    "cedente_prestatore": { "Denominazione": "Mario Rossi S.r.l." },
    "cessionario_committente": { "Denominazione": "Cliente S.p.A." },
    "corpi": [ { "DatiGenerali": {}, "DatiBeniServizi": {} } ]
  }
}

Il payload è una union discriminata validata da Pydantic: il campo kind seleziona il ramo esatto (invoice | generic). Il modello canonico è generato da backend/app/schemas/envelope.py. Tutti gli output seguono questo contratto unico.

Architecture

Section titled “Architecture”
FatturaPA XML ────────────────► deterministic fast path ───► Envelope v2
                                      │
PDF / text ─► Rizzo /analyze ─► pseudonymized text ─► LLM ─► restore() ─► response
                                      │                              │
                                      └────────── mapping in RAM ────┘
                                                     │
                                                     ▼
                                                  DROP

Il confine di privacy è esplicito: il modello LLM esterno riceve la rappresentazione pseudonimizzata, mentre il mapping placeholder→valore reale rimane locale alla richiesta.

Public API surface

Section titled “Public API surface”
Method Route Auth Purpose
GET /health — Liveness
GET /status — Public operational status
POST /v1/uploads X-API-Key Ingest XML/PDF
GET /v1/uploads/{job_id} X-API-Key Poll upload job
POST /v1/parse X-API-Key Parse text or an uploaded job

Sovranità dei dati

Section titled “Sovranità dei dati”

Clear-text PII never leaves the EU-hosted processing boundary. External LLM providers receive only the pseudonymized representation when the deterministic path does not resolve the document. Il mapping PII → placeholder è generato localmente dal sidecar Rizzo (CPU, RAM, nessuna chiamata esterna), e il ripristino avviene dopo il completamento LLM — prima di restituire la risposta HTTP.

L’infrastruttura di produzione è su Hetzner eu-central (Nürnberg) gestita da Coolify — il confine privacy è architetturale e il sidecar Rizzo è configurato per il deployment ma non ancora deployato nell’inventario corrente.

  • Riconoscimento PII: Rizzo AI Academy (rizzo-pii-0.3B) per 22 categorie
  • In-RAM: il mapping vive solo per la durata della richiesta, drop immediato
  • Sidecar down = 503 fail-closed: mai testo scoperto all’LLM

Piano di implementazione

Section titled “Piano di implementazione”
Funzionalità Stato Note
Upload FatturaPA XML (deterministico) ✅ Production Fast-path 41 ms, $0.00
Upload PDF (deterministico + LLM) ✅ Production Pseudonimizzazione Rizzo
Parse testo diretto /v1/parse ✅ Production XOR con job_id, zero-retention
Rizzo PII sidecar ✅ Production 22 categorie, GC patch attiva
MCP Server Integration 🧭 Roadmap Tools in design review

Inizia

Section titled “Inizia”

Ottieni una chiave API su Zyla API Hub per iniziare.