A production-oriented reference system for extracting validated, structured data from logistics invoices. It includes a synthetic-data pipeline, LoRA fine-tuning entry point, offline evaluation, an OpenAI-compatible vLLM adapter, and an API that treats every extraction as an auditable job.
No private invoices or company data are included. The default engine is a deterministic baseline so the full application can run without a GPU; swap to vLLM after fine-tuning for model-backed extraction.
invoice text → idempotent job API → extraction engine → schema validation → result + audit metadata
↘ baseline / vLLM (LoRA-adapted Llama) ↗
synthetic generator → JSONL train/validation data → LoRA training → offline field-level evaluation
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
logistics-extraction generate-data --output data/demo.jsonl --rows 200
logistics-extraction evaluate --input data/demo.jsonl
uvicorn logistics_extraction.api:app --reloadCreate a job:
curl -X POST localhost:8000/v1/extractions \
-H 'Content-Type: application/json' -H 'Idempotency-Key: invoice-001' \
-d '{"document_text":"INVOICE NO: INV-1001\nCarrier: Northstar Freight\nBill To: Acme Retail\nOrigin: Bengaluru\nDestination: Mumbai\nInvoice Date: 2026-01-15\nTotal Amount: INR 12345.67"}'Fetch the job with GET /v1/extractions/{job_id}. Reusing the same idempotency key returns the original job rather than charging or processing it twice.
Install the optional GPU dependencies and run the LoRA entry point with a JSONL dataset produced above:
pip install -e '.[training]'
python -m logistics_extraction.finetune --config configs/lora.yaml --train data/train.jsonl --output artifacts/lora-invoiceServe the merged/adapted model with vLLM, then configure the API:
export EXTRACTION_ENGINE=vllm
export VLLM_BASE_URL=http://vllm:8000/v1
export VLLM_MODEL=invoice-extractor
export EXTRACTION_API_KEY=replace-with-a-secretThe vLLM adapter requests JSON-only output and validates it against the InvoiceExtraction schema before a result is marked complete. Invalid model output becomes a visible failed job, not a silently malformed downstream record.
evaluate reports exact-match rate for identifiers/text fields, numeric tolerance for amount, and a required-field completion rate. Establish the reported score using a held-out, representative dataset before describing any accuracy target; the synthetic demo is only a functional test, not a benchmark.
The included job store is in memory to keep the example runnable. A production deployment should replace it with Postgres/Redis, use a queue worker, persist encrypted document references rather than raw text, add tenant-aware authorization and retention controls, send traces/metrics to observability tooling, and pin the model/dataset versions in a registry.
MIT