blitzid 0.3.1__tar.gz → 0.3.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. {blitzid-0.3.1 → blitzid-0.3.2}/.github/workflows/ci.yml +3 -1
  2. {blitzid-0.3.1 → blitzid-0.3.2}/CHANGELOG.md +14 -0
  3. {blitzid-0.3.1 → blitzid-0.3.2}/Dockerfile +5 -4
  4. {blitzid-0.3.1 → blitzid-0.3.2}/PKG-INFO +86 -14
  5. {blitzid-0.3.1 → blitzid-0.3.2}/README.md +82 -13
  6. {blitzid-0.3.1 → blitzid-0.3.2}/docs/coding-standard.md +20 -10
  7. {blitzid-0.3.1 → blitzid-0.3.2}/docs/integration.md +17 -12
  8. {blitzid-0.3.1 → blitzid-0.3.2}/pyproject.toml +8 -2
  9. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/__init__.py +9 -1
  10. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/_dates.py +8 -2
  11. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_analyze.py +28 -3
  12. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_app.py +42 -18
  13. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/exceptions.py +4 -0
  14. blitzid-0.3.2/src/blitzid/reading/barcode.py +364 -0
  15. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_api.py +82 -1
  16. blitzid-0.3.2/tests/test_barcode.py +396 -0
  17. {blitzid-0.3.1 → blitzid-0.3.2}/uv.lock +714 -792
  18. {blitzid-0.3.1 → blitzid-0.3.2}/.dockerignore +0 -0
  19. {blitzid-0.3.1 → blitzid-0.3.2}/.env.example +0 -0
  20. {blitzid-0.3.1 → blitzid-0.3.2}/.github/workflows/docker.yml +0 -0
  21. {blitzid-0.3.1 → blitzid-0.3.2}/.github/workflows/publish.yml +0 -0
  22. {blitzid-0.3.1 → blitzid-0.3.2}/.gitignore +0 -0
  23. {blitzid-0.3.1 → blitzid-0.3.2}/.pre-commit-config.yaml +0 -0
  24. {blitzid-0.3.1 → blitzid-0.3.2}/CONTRIBUTING.md +0 -0
  25. {blitzid-0.3.1 → blitzid-0.3.2}/LICENSE +0 -0
  26. {blitzid-0.3.1 → blitzid-0.3.2}/docker-compose.dev.yml +0 -0
  27. {blitzid-0.3.1 → blitzid-0.3.2}/docker-compose.gpu.yml +0 -0
  28. {blitzid-0.3.1 → blitzid-0.3.2}/docker-compose.yml +0 -0
  29. {blitzid-0.3.1 → blitzid-0.3.2}/images/README.md +0 -0
  30. {blitzid-0.3.1 → blitzid-0.3.2}/images/bub_der_personalausweis_kopie.jpg +0 -0
  31. {blitzid-0.3.1 → blitzid-0.3.2}/images/nl_td1_id_specimen.jpg +0 -0
  32. {blitzid-0.3.1 → blitzid-0.3.2}/images/ny_license_plate_wrap.jpg +0 -0
  33. {blitzid-0.3.1 → blitzid-0.3.2}/images/nys_driver_license_sample.webp +0 -0
  34. {blitzid-0.3.1 → blitzid-0.3.2}/images/solvay_conference_1927.jpg +0 -0
  35. {blitzid-0.3.1 → blitzid-0.3.2}/images/td3_passport_specimen.jpg +0 -0
  36. {blitzid-0.3.1 → blitzid-0.3.2}/images/tlc_driver_license_sample.png +0 -0
  37. {blitzid-0.3.1 → blitzid-0.3.2}/models/.gitkeep +0 -0
  38. {blitzid-0.3.1 → blitzid-0.3.2}/models/README.md +0 -0
  39. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/README.md +0 -0
  40. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/api_smoke.py +0 -0
  41. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/benchmark.py +0 -0
  42. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/demo_cli.py +0 -0
  43. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/download_models.py +0 -0
  44. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/face_detector_demo.py +0 -0
  45. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/midv500.py +0 -0
  46. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/ocr_demo.py +0 -0
  47. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/structurize_smoke.py +0 -0
  48. {blitzid-0.3.1 → blitzid-0.3.2}/scripts/verify_smoke.py +0 -0
  49. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/_image.py +0 -0
  50. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/_models.py +0 -0
  51. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/__init__.py +0 -0
  52. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_jobs.py +0 -0
  53. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_liveness.py +0 -0
  54. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_schemas.py +0 -0
  55. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/api/_upload.py +0 -0
  56. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/__init__.py +0 -0
  57. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_antispoof.py +0 -0
  58. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_arcface.py +0 -0
  59. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_attributes.py +0 -0
  60. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_face.py +0 -0
  61. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_motion.py +0 -0
  62. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/_scrfd.py +0 -0
  63. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/detector.py +0 -0
  64. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/face/verifier.py +0 -0
  65. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/py.typed +0 -0
  66. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/__init__.py +0 -0
  67. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/_observability.py +0 -0
  68. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/consistency.py +0 -0
  69. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/document.py +0 -0
  70. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/mrz.py +0 -0
  71. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/ocr.py +0 -0
  72. {blitzid-0.3.1 → blitzid-0.3.2}/src/blitzid/reading/structurize.py +0 -0
  73. {blitzid-0.3.1 → blitzid-0.3.2}/tests/conftest.py +0 -0
  74. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_antispoof.py +0 -0
  75. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_attributes.py +0 -0
  76. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_consistency.py +0 -0
  77. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_detector.py +0 -0
  78. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_detector_helpers.py +0 -0
  79. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_document.py +0 -0
  80. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_exceptions.py +0 -0
  81. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_image.py +0 -0
  82. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_models.py +0 -0
  83. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_motion.py +0 -0
  84. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_mrz.py +0 -0
  85. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_ocr.py +0 -0
  86. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_refactored.py +0 -0
  87. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_structurize.py +0 -0
  88. {blitzid-0.3.1 → blitzid-0.3.2}/tests/test_verifier.py +0 -0
@@ -27,5 +27,7 @@ jobs:
27
27
  - uses: astral-sh/setup-uv@v8.1.0
28
28
  with:
29
29
  python-version: ${{ matrix.python-version }}
30
- - run: uv sync --extra dev
30
+ # The barcode extra enables the zxing-cpp round-trip tier;
31
+ # without it those tests skip, not fail.
32
+ - run: uv sync --extra dev --extra barcode
31
33
  - run: uv run pytest tests/ -v
@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.3.2] - 2026-10-06
8
+
9
+ ### Added
10
+
11
+ - PDF417 barcode reading for US and Canadian driver's licenses
12
+ (`blitzid[barcode]` extra, zxing-cpp): `BarcodeReader` /
13
+ `BarcodeRecord` / `BarcodeError` decode the back-of-card PDF417 and
14
+ parse the AAMVA DL/ID payload (versions 02–14). The parser validates
15
+ the header's subfile offsets, lengths, and number-of-entries count,
16
+ gates the mandatory fields with per-edition tag maps pinned by
17
+ fixture tests, and keeps every un-mapped tag raw in `extra_tags`.
18
+ The HTTP API gains a `barcode` analysis type and a `/health` flag;
19
+ a missing `barcode` extra degrades to the per-engine `400`.
20
+
7
21
  ## [0.3.1] - 2026-10-06
8
22
 
9
23
  ### Fixed
@@ -6,10 +6,11 @@ COPY README.md pyproject.toml uv.lock ./
6
6
  COPY src/ src/
7
7
  COPY scripts/ scripts/
8
8
  # Every runtime feature ships in the image: the HTTP API (api), face
9
- # detection/verification in the core, OCR, MRZ, LLM-backed structured
10
- # extraction and Langfuse tracing (ocr), and the bundled scripts
11
- # (scripts). Only the dev toolchain stays out.
12
- RUN uv sync --frozen --no-dev --extra api --extra ocr --extra scripts
9
+ # detection/verification in the core, OCR, MRZ, PDF417 barcode reading
10
+ # (barcode), LLM-backed structured extraction and Langfuse tracing
11
+ # (ocr), and the bundled scripts (scripts). Only the dev toolchain
12
+ # stays out.
13
+ RUN uv sync --frozen --no-dev --extra api --extra barcode --extra ocr --extra scripts
13
14
  # Bake every engine's weights (SCRFD, ArcFace, RapidOCR) so cold start
14
15
  # needs no downloads.
15
16
  RUN uv run --no-sync python scripts/download_models.py --models-dir /models
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitzid
3
- Version: 0.3.1
3
+ Version: 0.3.2
4
4
  Summary: Modular DNN-based ID document reading framework (face detection, OCR, MRZ) optimized for CPU deployment
5
5
  Project-URL: Homepage, https://github.com/malvavisc0/blitzid
6
6
  Project-URL: Repository, https://github.com/malvavisc0/blitzid
@@ -38,11 +38,14 @@ Requires-Dist: ruff; extra == 'all'
38
38
  Requires-Dist: tqdm; extra == 'all'
39
39
  Requires-Dist: types-tqdm; extra == 'all'
40
40
  Requires-Dist: uvicorn[standard]; extra == 'all'
41
+ Requires-Dist: zxing-cpp; extra == 'all'
41
42
  Provides-Extra: api
42
43
  Requires-Dist: fastapi; extra == 'api'
43
44
  Requires-Dist: python-multipart; extra == 'api'
44
45
  Requires-Dist: redis; extra == 'api'
45
46
  Requires-Dist: uvicorn[standard]; extra == 'api'
47
+ Provides-Extra: barcode
48
+ Requires-Dist: zxing-cpp; extra == 'barcode'
46
49
  Provides-Extra: dev
47
50
  Requires-Dist: fakeredis; extra == 'dev'
48
51
  Requires-Dist: fastapi; extra == 'dev'
@@ -72,8 +75,9 @@ Description-Content-Type: text/markdown
72
75
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
73
76
 
74
77
  Read identity documents from images: find and compare faces, read printed
75
- text, and parse the machine-readable zone, in one typed Python library
76
- that runs on an ordinary CPU.
78
+ text, parse the machine-readable zone, and decode the PDF417 barcode on
79
+ US and Canadian driver's licenses, in one typed Python library that
80
+ runs on an ordinary CPU.
77
81
 
78
82
  No GPU and no CUDA stack: inference runs on onnxruntime's CPU provider,
79
83
  face detection takes about 4 ms per image on a laptop, and the weights
@@ -85,9 +89,10 @@ results in RAM only.
85
89
 
86
90
  ## Why blitzid
87
91
 
88
- - **One install, one API.** Face detection, OCR, MRZ parsing, and
89
- document crop/QC behind a single typed surface, instead of stitching
90
- a detector, an OCR engine, and your own MRZ code together.
92
+ - **One install, one API.** Face detection, OCR, MRZ parsing, PDF417
93
+ barcode reading, and document crop/QC behind a single typed surface,
94
+ instead of stitching a detector, an OCR engine, and your own MRZ code
95
+ together.
91
96
  - **Validation over guessing.** Every MRZ field is gated by ICAO 9303
92
97
  check digits. Obvious OCR confusions (0/O, 1/I, …) are undone by
93
98
  each field's alphabet before validation, and a zone that still does
@@ -110,6 +115,7 @@ results in RAM only.
110
115
  ```bash
111
116
  pip install blitzid # or: uv add blitzid
112
117
  pip install blitzid[ocr] # with OCR text reading (RapidOCR)
118
+ pip install blitzid[barcode] # with PDF417/AAMVA barcode reading (zxing-cpp)
113
119
  pip install blitzid[api] # with the HTTP API server
114
120
  ```
115
121
 
@@ -199,6 +205,15 @@ nationality), and parses TD1 (3x30), TD2 (2x36), and TD3 (2x44) into an
199
205
  convention (overflow at the start of `optional_data1`, no printed check
200
206
  digit).
201
207
 
208
+ **PDF417 barcode reading.** `BarcodeReader` (the `barcode` extra,
209
+ zxing-cpp) decodes the PDF417 code on the back of US and Canadian
210
+ driver's licenses and parses the AAMVA DL/ID payload into a typed
211
+ `BarcodeRecord` — jurisdiction, AAMVA version, names, dates, sex, and
212
+ license number, plus the raw jurisdiction-specific extras. The header's
213
+ subfile offsets, lengths, and number-of-entries count are validated and
214
+ the mandatory fields are gated, so a malformed payload raises
215
+ `BarcodeError` naming the offending field.
216
+
202
217
  **Structured extraction.** `StructuredOCRReader` (same extra) feeds the
203
218
  OCR lines to an OpenAI-compatible chat endpoint (e.g. a local vLLM
204
219
  server) and returns a typed `StructuredOCR` record; fields the model
@@ -221,8 +236,8 @@ face). Returns the crop plus a `QualityReport` verdict.
221
236
 
222
237
  **HTTP API and Docker.** The `api` extra adds a FastAPI service: an
223
238
  async job queue (Redis, persistence disabled) for
224
- face/attributes/antispoof/OCR/MRZ/structured/consistency, synchronous
225
- `/crop` (document QC), `/verify` (1:1 face comparison), and
239
+ face/attributes/antispoof/OCR/MRZ/barcode/structured/consistency,
240
+ synchronous `/crop` (document QC), `/verify` (1:1 face comparison), and
226
241
  `/liveness` (challenge-response liveness), and `/health` for
227
242
  orchestration.
228
243
  `docker compose up` runs it with all weights baked in.
@@ -249,9 +264,10 @@ curl http://localhost:8000/api/health
249
264
  file (any OpenCV-decodable format; PDFs get a precise `415`) and
250
265
  `types` (repeated and/or comma-separated: `face`, `attributes`,
251
266
  `antispoof`, `ocr`,
252
- `mrz`, `structured`, `consistency` — `attributes` predicts age group,
253
- gender, and race per face, `antispoof` scores live vs printed vs
254
- screen photos, `structured` rebuilds the OCR text into a
267
+ `mrz`, `barcode`, `structured`, `consistency` — `attributes` predicts
268
+ age group, gender, and race per face, `antispoof` scores live vs
269
+ printed vs screen photos, `barcode` decodes the PDF417/AAMVA payload
270
+ from a driver's-license back, `structured` rebuilds the OCR text into a
255
271
  typed record via the LLM, and `consistency` cross-checks that printed
256
272
  record against the machine-readable zone and the portrait's age band
257
273
  and gender against the birth date and sex; the photo rows need the
@@ -259,8 +275,8 @@ and gender against the birth date and sex; the photo rows need the
259
275
  `BLITZID_LLM_*` config).
260
276
  Validation is eager, before the job exists: `422` unknown type or
261
277
  missing fields, `400` undecodable bytes or an analysis whose engine is
262
- unavailable (`ocr`/`mrz` without the `ocr` extra, `structured`/
263
- `consistency` without
278
+ unavailable (`ocr`/`mrz` without the `ocr` extra, `barcode` without the
279
+ `barcode` extra, `structured`/`consistency` without
264
280
  the extra or the LLM config), `413` above the
265
281
  upload cap, `503` + `Retry-After` when the queue is full or Redis is
266
282
  down. Accepted jobs return `202`:
@@ -273,7 +289,7 @@ curl -F image=@id.jpg -F types=face,ocr localhost:8000/api/analyze
273
289
  **GET /jobs/{job_id}** polls: `{"status": "queued"}` / `running`; done
274
290
  returns `200` with one section per requested type (`face`,
275
291
  `attributes`, `antispoof`, `ocr`,
276
- `mrz`, `structured`, `consistency`; a failing section carries
292
+ `mrz`, `barcode`, `structured`, `consistency`; a failing section carries
277
293
  `{"error": ...}` while
278
294
  the others still return). The read claims the result, so every later
279
295
  read gets `410 Gone`; unknown ids get `404` (an expired job reads `410` until
@@ -349,6 +365,30 @@ What a done result looks like on the specimen ID (abbreviated):
349
365
  }
350
366
  ```
351
367
 
368
+ On a US driver's-license back, a `barcode` section looks like this:
369
+
370
+ ```json
371
+ {
372
+ "record": {
373
+ "jurisdiction": "636014",
374
+ "aamva_version": "08",
375
+ "jurisdiction_version": "00",
376
+ "family_name": "PUBLIC",
377
+ "given_name": "JOHN",
378
+ "middle_name": "QUINCY",
379
+ "birth_date": "1989-01-24",
380
+ "issue_date": "2013-06-04",
381
+ "expiry_date": "2035-01-31",
382
+ "sex": "M",
383
+ "license_number": "D12345678",
384
+ "height": "069 in",
385
+ "extra_tags": {"ZCB": "…"},
386
+ "symbology": "PDF417"
387
+ },
388
+ "processing_time_ms": 87.2
389
+ }
390
+ ```
391
+
352
392
  **POST /crop** is synchronous document QC (contour detection plus one
353
393
  SCRFD pass runs in tens of ms): the perspective-corrected canonical
354
394
  crop plus quality checks (`document_found`, `aspect_ratio`,
@@ -596,6 +636,37 @@ record = MRZReader().read("id_card.jpg")
596
636
  print(record.mrz_type, record.document_number, record.surname)
597
637
  ```
598
638
 
639
+ ### `BarcodeReader`
640
+
641
+ Defined in [`reading/barcode.py`](src/blitzid/reading/barcode.py);
642
+ requires the `barcode` extra (`pip install blitzid[barcode]`). Decodes
643
+ the PDF417 code on the back of US and Canadian driver's licenses with
644
+ zxing-cpp and parses the AAMVA DL/ID payload (versions 02–14). The
645
+ header's subfile offsets, lengths, and number-of-entries count are
646
+ validated, the mandatory fields are gated, and a failing payload raises
647
+ `BarcodeError` naming the offending field — nothing is invented or
648
+ repaired.
649
+
650
+ | Method | Description |
651
+ |---|---|
652
+ | `read(image_input)` | Decodes and returns a `BarcodeRecord` |
653
+
654
+ **`BarcodeRecord`** — frozen dataclass: `jurisdiction` (the issuer's
655
+ identification number), `aamva_version` (AAMVA version, `"02"`–`"14"`),
656
+ `jurisdiction_version`, `family_name`, `given_name`, `middle_name`,
657
+ `birth_date` / `issue_date` / `expiry_date` (`datetime.date`), `sex`
658
+ (`"M"`/`"F"`/`"X"`), `license_number`, `height` (with its unit, or
659
+ None), `extra_tags` (every un-mapped element kept raw, jurisdiction
660
+ `Z..` extras included), and `symbology` (the decoded barcode symbology,
661
+ stamped by the reader).
662
+
663
+ ```python
664
+ from blitzid import BarcodeReader
665
+
666
+ record = BarcodeReader().read("license_back.jpg")
667
+ print(record.aamva_version, record.family_name, record.expiry_date)
668
+ ```
669
+
599
670
  ### `StructuredOCRReader`
600
671
 
601
672
  Defined in [`reading/structurize.py`](src/blitzid/reading/structurize.py);
@@ -661,6 +732,7 @@ Defined in [`exceptions.py`](src/blitzid/exceptions.py).
661
732
  | `ModelError` | Model download or load failure |
662
733
  | `ImageError` | Image loading, validation, or processing failure |
663
734
  | `MRZError` | MRZ not found, malformed, or failed check-digit validation |
735
+ | `BarcodeError` | PDF417 barcode not found, malformed, or failed AAMVA validation |
664
736
  | `FaceVerificationError` | Face verification failure (no detectable face, missing landmarks) |
665
737
 
666
738
  Backward-compatibility aliases (`FaceDetectorError`, `ModelDownloadError`, `ImageLoadError`, etc.) are re-exported from `__init__.py`.
@@ -6,8 +6,9 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
7
 
8
8
  Read identity documents from images: find and compare faces, read printed
9
- text, and parse the machine-readable zone, in one typed Python library
10
- that runs on an ordinary CPU.
9
+ text, parse the machine-readable zone, and decode the PDF417 barcode on
10
+ US and Canadian driver's licenses, in one typed Python library that
11
+ runs on an ordinary CPU.
11
12
 
12
13
  No GPU and no CUDA stack: inference runs on onnxruntime's CPU provider,
13
14
  face detection takes about 4 ms per image on a laptop, and the weights
@@ -19,9 +20,10 @@ results in RAM only.
19
20
 
20
21
  ## Why blitzid
21
22
 
22
- - **One install, one API.** Face detection, OCR, MRZ parsing, and
23
- document crop/QC behind a single typed surface, instead of stitching
24
- a detector, an OCR engine, and your own MRZ code together.
23
+ - **One install, one API.** Face detection, OCR, MRZ parsing, PDF417
24
+ barcode reading, and document crop/QC behind a single typed surface,
25
+ instead of stitching a detector, an OCR engine, and your own MRZ code
26
+ together.
25
27
  - **Validation over guessing.** Every MRZ field is gated by ICAO 9303
26
28
  check digits. Obvious OCR confusions (0/O, 1/I, …) are undone by
27
29
  each field's alphabet before validation, and a zone that still does
@@ -44,6 +46,7 @@ results in RAM only.
44
46
  ```bash
45
47
  pip install blitzid # or: uv add blitzid
46
48
  pip install blitzid[ocr] # with OCR text reading (RapidOCR)
49
+ pip install blitzid[barcode] # with PDF417/AAMVA barcode reading (zxing-cpp)
47
50
  pip install blitzid[api] # with the HTTP API server
48
51
  ```
49
52
 
@@ -133,6 +136,15 @@ nationality), and parses TD1 (3x30), TD2 (2x36), and TD3 (2x44) into an
133
136
  convention (overflow at the start of `optional_data1`, no printed check
134
137
  digit).
135
138
 
139
+ **PDF417 barcode reading.** `BarcodeReader` (the `barcode` extra,
140
+ zxing-cpp) decodes the PDF417 code on the back of US and Canadian
141
+ driver's licenses and parses the AAMVA DL/ID payload into a typed
142
+ `BarcodeRecord` — jurisdiction, AAMVA version, names, dates, sex, and
143
+ license number, plus the raw jurisdiction-specific extras. The header's
144
+ subfile offsets, lengths, and number-of-entries count are validated and
145
+ the mandatory fields are gated, so a malformed payload raises
146
+ `BarcodeError` naming the offending field.
147
+
136
148
  **Structured extraction.** `StructuredOCRReader` (same extra) feeds the
137
149
  OCR lines to an OpenAI-compatible chat endpoint (e.g. a local vLLM
138
150
  server) and returns a typed `StructuredOCR` record; fields the model
@@ -155,8 +167,8 @@ face). Returns the crop plus a `QualityReport` verdict.
155
167
 
156
168
  **HTTP API and Docker.** The `api` extra adds a FastAPI service: an
157
169
  async job queue (Redis, persistence disabled) for
158
- face/attributes/antispoof/OCR/MRZ/structured/consistency, synchronous
159
- `/crop` (document QC), `/verify` (1:1 face comparison), and
170
+ face/attributes/antispoof/OCR/MRZ/barcode/structured/consistency,
171
+ synchronous `/crop` (document QC), `/verify` (1:1 face comparison), and
160
172
  `/liveness` (challenge-response liveness), and `/health` for
161
173
  orchestration.
162
174
  `docker compose up` runs it with all weights baked in.
@@ -183,9 +195,10 @@ curl http://localhost:8000/api/health
183
195
  file (any OpenCV-decodable format; PDFs get a precise `415`) and
184
196
  `types` (repeated and/or comma-separated: `face`, `attributes`,
185
197
  `antispoof`, `ocr`,
186
- `mrz`, `structured`, `consistency` — `attributes` predicts age group,
187
- gender, and race per face, `antispoof` scores live vs printed vs
188
- screen photos, `structured` rebuilds the OCR text into a
198
+ `mrz`, `barcode`, `structured`, `consistency` — `attributes` predicts
199
+ age group, gender, and race per face, `antispoof` scores live vs
200
+ printed vs screen photos, `barcode` decodes the PDF417/AAMVA payload
201
+ from a driver's-license back, `structured` rebuilds the OCR text into a
189
202
  typed record via the LLM, and `consistency` cross-checks that printed
190
203
  record against the machine-readable zone and the portrait's age band
191
204
  and gender against the birth date and sex; the photo rows need the
@@ -193,8 +206,8 @@ and gender against the birth date and sex; the photo rows need the
193
206
  `BLITZID_LLM_*` config).
194
207
  Validation is eager, before the job exists: `422` unknown type or
195
208
  missing fields, `400` undecodable bytes or an analysis whose engine is
196
- unavailable (`ocr`/`mrz` without the `ocr` extra, `structured`/
197
- `consistency` without
209
+ unavailable (`ocr`/`mrz` without the `ocr` extra, `barcode` without the
210
+ `barcode` extra, `structured`/`consistency` without
198
211
  the extra or the LLM config), `413` above the
199
212
  upload cap, `503` + `Retry-After` when the queue is full or Redis is
200
213
  down. Accepted jobs return `202`:
@@ -207,7 +220,7 @@ curl -F image=@id.jpg -F types=face,ocr localhost:8000/api/analyze
207
220
  **GET /jobs/{job_id}** polls: `{"status": "queued"}` / `running`; done
208
221
  returns `200` with one section per requested type (`face`,
209
222
  `attributes`, `antispoof`, `ocr`,
210
- `mrz`, `structured`, `consistency`; a failing section carries
223
+ `mrz`, `barcode`, `structured`, `consistency`; a failing section carries
211
224
  `{"error": ...}` while
212
225
  the others still return). The read claims the result, so every later
213
226
  read gets `410 Gone`; unknown ids get `404` (an expired job reads `410` until
@@ -283,6 +296,30 @@ What a done result looks like on the specimen ID (abbreviated):
283
296
  }
284
297
  ```
285
298
 
299
+ On a US driver's-license back, a `barcode` section looks like this:
300
+
301
+ ```json
302
+ {
303
+ "record": {
304
+ "jurisdiction": "636014",
305
+ "aamva_version": "08",
306
+ "jurisdiction_version": "00",
307
+ "family_name": "PUBLIC",
308
+ "given_name": "JOHN",
309
+ "middle_name": "QUINCY",
310
+ "birth_date": "1989-01-24",
311
+ "issue_date": "2013-06-04",
312
+ "expiry_date": "2035-01-31",
313
+ "sex": "M",
314
+ "license_number": "D12345678",
315
+ "height": "069 in",
316
+ "extra_tags": {"ZCB": "…"},
317
+ "symbology": "PDF417"
318
+ },
319
+ "processing_time_ms": 87.2
320
+ }
321
+ ```
322
+
286
323
  **POST /crop** is synchronous document QC (contour detection plus one
287
324
  SCRFD pass runs in tens of ms): the perspective-corrected canonical
288
325
  crop plus quality checks (`document_found`, `aspect_ratio`,
@@ -530,6 +567,37 @@ record = MRZReader().read("id_card.jpg")
530
567
  print(record.mrz_type, record.document_number, record.surname)
531
568
  ```
532
569
 
570
+ ### `BarcodeReader`
571
+
572
+ Defined in [`reading/barcode.py`](src/blitzid/reading/barcode.py);
573
+ requires the `barcode` extra (`pip install blitzid[barcode]`). Decodes
574
+ the PDF417 code on the back of US and Canadian driver's licenses with
575
+ zxing-cpp and parses the AAMVA DL/ID payload (versions 02–14). The
576
+ header's subfile offsets, lengths, and number-of-entries count are
577
+ validated, the mandatory fields are gated, and a failing payload raises
578
+ `BarcodeError` naming the offending field — nothing is invented or
579
+ repaired.
580
+
581
+ | Method | Description |
582
+ |---|---|
583
+ | `read(image_input)` | Decodes and returns a `BarcodeRecord` |
584
+
585
+ **`BarcodeRecord`** — frozen dataclass: `jurisdiction` (the issuer's
586
+ identification number), `aamva_version` (AAMVA version, `"02"`–`"14"`),
587
+ `jurisdiction_version`, `family_name`, `given_name`, `middle_name`,
588
+ `birth_date` / `issue_date` / `expiry_date` (`datetime.date`), `sex`
589
+ (`"M"`/`"F"`/`"X"`), `license_number`, `height` (with its unit, or
590
+ None), `extra_tags` (every un-mapped element kept raw, jurisdiction
591
+ `Z..` extras included), and `symbology` (the decoded barcode symbology,
592
+ stamped by the reader).
593
+
594
+ ```python
595
+ from blitzid import BarcodeReader
596
+
597
+ record = BarcodeReader().read("license_back.jpg")
598
+ print(record.aamva_version, record.family_name, record.expiry_date)
599
+ ```
600
+
533
601
  ### `StructuredOCRReader`
534
602
 
535
603
  Defined in [`reading/structurize.py`](src/blitzid/reading/structurize.py);
@@ -595,6 +663,7 @@ Defined in [`exceptions.py`](src/blitzid/exceptions.py).
595
663
  | `ModelError` | Model download or load failure |
596
664
  | `ImageError` | Image loading, validation, or processing failure |
597
665
  | `MRZError` | MRZ not found, malformed, or failed check-digit validation |
666
+ | `BarcodeError` | PDF417 barcode not found, malformed, or failed AAMVA validation |
598
667
  | `FaceVerificationError` | Face verification failure (no detectable face, missing landmarks) |
599
668
 
600
669
  Backward-compatibility aliases (`FaceDetectorError`, `ModelDownloadError`, `ImageLoadError`, etc.) are re-exported from `__init__.py`.
@@ -14,7 +14,8 @@ layers. Face detection (`src/blitzid/face/`): SCRFD-2.5G ONNX model
14
14
  an onnxruntime CPU session, with LRU result cache, multi-scale
15
15
  detection, NMS + size filtering, batch processing, and bbox
16
16
  visualization. Document reading (`src/blitzid/reading/`): RapidOCR
17
- text lines (`ocr` extra) and ICAO 9303 MRZ parsing (TD1/TD2/TD3).
17
+ text lines (`ocr` extra), ICAO 9303 MRZ parsing (TD1/TD2/TD3), and
18
+ AAMVA PDF417 driver's-license parsing (`barcode` extra).
18
19
  Inputs are file paths, NumPy arrays, or PIL Images; outputs are
19
20
  `(x, y, w, h, confidence)` tuples and crops.
20
21
 
@@ -22,9 +23,10 @@ Inputs are file paths, NumPy arrays, or PIL Images; outputs are
22
23
  - python 3.12+ (CI matrix: 3.12 / 3.13 / 3.14), uv, pyproject.toml
23
24
  (hatchling backend, src layout, `py.typed`)
24
25
  - core deps: numpy, onnxruntime (CPU), opencv-python-headless>=5,
25
- platformdirs
26
- - optional extras: `scripts` (tqdm), `dev` (pytest, ruff, mypy,
27
- pre-commit)
26
+ platformdirs, pydantic
27
+ - optional extras: `ocr` (rapidocr, pydantic-ai, langfuse), `barcode`
28
+ (zxing-cpp), `api` (fastapi, uvicorn, redis), `scripts` (tqdm),
29
+ `dev` (pytest, ruff, mypy, pre-commit)
28
30
  - Type checker: **mypy** (`strict = true` in pyproject.toml)
29
31
  - Lint/format: **ruff** (line-length 88, target py312; E, W, F, I, UP,
30
32
  B, SIM, RUF)
@@ -125,7 +127,8 @@ Write the simplest correct solution. Delete anything that isn't needed.
125
127
  `src/blitzid/face/` (`detector.py` — `FaceDetectorDNN` plus NMS /
126
128
  IoU / size filter; `_face.py` — `Face`, `DetectionMetrics`, cache,
127
129
  drawing; `_scrfd.py` — SCRFD preprocess/decode). Document reading in
128
- `src/blitzid/reading/` (`ocr.py`, `mrz.py`). Shared helpers at the
130
+ `src/blitzid/reading/` (`ocr.py`, `mrz.py`, `barcode.py`,
131
+ `structurize.py`, `consistency.py`, `document.py`). Shared helpers at the
129
132
  top level: `_image.py` (input loading and normalization), `_models.py`
130
133
  (`ModelManager` — SCRFD ONNX download + CPU
131
134
  `onnxruntime.InferenceSession`, default cache dir via `platformdirs`).
@@ -134,10 +137,12 @@ Write the simplest correct solution. Delete anything that isn't needed.
134
137
  - Exceptions in `src/blitzid/exceptions.py`: `BlitzIDError` base,
135
138
  `ModelError` (model download/load), `ImageError` (load/validate/
136
139
  process), `MRZError` (MRZ not found / malformed / failed check-digit
137
- validation), `FaceVerificationError` (no face for verification).
138
- - Optional deps (PIL, rapidocr via the `ocr` extra) are lazy-imported
139
- inside functions, guarded, with targeted `# type: ignore` codes; core
140
- must work without them.
140
+ validation), `BarcodeError` (PDF417 not found / malformed / failed
141
+ AAMVA validation), `FaceVerificationError` (no face for
142
+ verification).
143
+ - Optional deps (PIL, rapidocr via the `ocr` extra, zxing-cpp via the
144
+ `barcode` extra) are lazy-imported inside functions, guarded, with
145
+ targeted `# type: ignore` codes; core must work without them.
141
146
  - The MRZ layer (`src/blitzid/reading/mrz.py`) is pure ICAO 9303 logic
142
147
  over the OCR reader's text lines — no new models, no guessy repair:
143
148
  obvious OCR confusions (0/O, 1/I, 2/Z, 5/S, 6/G, 8/B) resolve
@@ -161,7 +166,12 @@ Write the simplest correct solution. Delete anything that isn't needed.
161
166
  surface is `RapidOCRReader.read()` returning `OCRText` records — one
162
167
  engine (RapidOCR on onnxruntime CPU), lazy-imported from the `ocr`
163
168
  extra. The MRZ surface is `MRZReader.read()` returning an
164
- `MRZRecord` (same `ocr` extra).
169
+ `MRZRecord` (same `ocr` extra). The barcode surface is
170
+ `BarcodeReader.read()` returning a `BarcodeRecord` (`barcode`
171
+ extra, zxing-cpp decoder; the parser validates the AAMVA header's
172
+ subfile offsets/lengths/count, gates mandatory fields per
173
+ edition-pinned tag maps, keeps unknown tags raw in `extra_tags`,
174
+ and raises `BarcodeError` naming the offending field).
165
175
  - `scripts/` are demos, diagnostics, and dataset benchmarks — not part
166
176
  of the shipped package; they may use the `scripts` extra.
167
177
  - Tests go in `tests/`; validation tests must run without model
@@ -12,6 +12,7 @@ against a local stack.
12
12
 
13
13
  The service quality-checks document photos, reads the printed text and
14
14
  the machine-readable code strip, validates the strip's check digits,
15
+ decodes the PDF417 barcode on US and Canadian driver's-license backs,
15
16
  compares a selfie to a document portrait, estimates age group, gender,
16
17
  and race per face, and cross-checks the copies inside one document.
17
18
 
@@ -60,17 +61,18 @@ would trust with that.
60
61
 
61
62
  ### Check it is healthy
62
63
 
63
- `GET /health` returns `200` with seven model flags: `face`, `verify`,
64
- `attributes`, `antispoof`, `ocr`, `mrz`, `structured`. A `false` flag
65
- means that analysis returns `400` with the missing piece named. `503`
66
- means the job store is down and the container cannot accept work.
64
+ `GET /health` returns `200` with eight model flags: `face`, `verify`,
65
+ `attributes`, `antispoof`, `ocr`, `mrz`, `barcode`, `structured`. A
66
+ `false` flag means that analysis returns `400` with the missing piece
67
+ named. `503` means the job store is down and the container cannot
68
+ accept work.
67
69
 
68
70
  ## The blocks
69
71
 
70
72
  | Block | Call | Gives you |
71
73
  |---|---|---|
72
74
  | Photo quality gate | `POST /crop` | `pass`/`warn`/`reject` verdict, per-check detail, and a corrected crop. Works on documents and selfies alike |
73
- | Data extraction | `POST /analyze -F types=ocr,mrz,structured` | printed fields, code-strip fields (check digits validated), typed records |
75
+ | Data extraction | `POST /analyze -F types=ocr,mrz,barcode,structured` | printed fields, code-strip fields (check digits validated), the PDF417/AAMVA record from a license back, typed records |
74
76
  | Age signal | `POST /analyze -F types=attributes` | age band, gender, and race per face |
75
77
  | Spoof signal | `POST /analyze -F types=antispoof` | per-face scores: live, printed photo, screen photo |
76
78
  | Document self-check | `POST /analyze -F types=consistency` | printed text vs code strip vs portrait, per-field verdicts |
@@ -119,8 +121,9 @@ One document, both sides where the card has a back:
119
121
  - **Passport**: one photo, the data page. The code strip is at the
120
122
  bottom of the same page.
121
123
  - **ID card**: front and back. The back carries the code strip.
122
- - **Driver license**: front and back. The back carries the barcode
123
- (see the gap list at the end).
124
+ - **Driver license**: front and back. The back carries the PDF417
125
+ barcode with the AAMVA record (a machine copy of the printed data,
126
+ validated by the `barcode` analysis).
124
127
 
125
128
  Capture paths depend on what the user must prove. "Selfie, then ID
126
129
  front and back" is the base. "Selfie, then passport" is the same flow
@@ -163,7 +166,8 @@ Pick types per document:
163
166
  | Passport data page | `face,ocr,mrz,structured,consistency` |
164
167
  | ID card (back photographed) | `face,ocr,mrz,structured,consistency` |
165
168
  | ID card (front only) | `face,ocr,structured` (no code strip to read) |
166
- | Driver license | `face,ocr,structured,attributes` |
169
+ | Driver license (back photographed) | `face,ocr,mrz,barcode,structured,consistency` |
170
+ | Driver license (front only) | `face,ocr,structured,attributes` (no barcode or MRZ on the front) |
167
171
  | Vehicle registration / insurance | `ocr,structured` |
168
172
  | Plate photo | `structured` |
169
173
 
@@ -272,10 +276,11 @@ the two crops, not a boolean.
272
276
 
273
277
  Read this before you promise a flow:
274
278
 
275
- - **Barcode (PDF417/AAMVA) on US and Canadian licenses.** The back of
276
- those cards carries a machine copy with its own checksums, better
277
- than any OCR. Today the `ocr` and `structured` passes read the
278
- printed front only.
279
+ - **Barcode-vs-print cross-check.** The `barcode` analysis decodes the
280
+ PDF417/AAMVA record on US and Canadian license backs, but the
281
+ `consistency` section does not compare it against the printed front
282
+ yet — the strongest tamper signal those cards have. It compares the
283
+ code strip (when the card has one) today.
279
284
  - **Video replay and generated faces.** The liveness block stops
280
285
  static spoofs and the `antispoof` block flags cameras pointed at
281
286
  photos and displays. Filming a screen that plays a live video, or a
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "blitzid"
3
- version = "0.3.1"
3
+ version = "0.3.2"
4
4
  description = "Modular DNN-based ID document reading framework (face detection, OCR, MRZ) optimized for CPU deployment"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -47,6 +47,11 @@ ocr = [
47
47
  # Optional: Langfuse tracing of the LLM calls (env-gated).
48
48
  "langfuse",
49
49
  ]
50
+ barcode = [
51
+ # PDF417 decoding for AAMVA driver's-license payloads (also the
52
+ # encoder the test suite round-trips synthetic payloads with).
53
+ "zxing-cpp",
54
+ ]
50
55
  api = [
51
56
  "fastapi",
52
57
  "uvicorn[standard]",
@@ -74,7 +79,7 @@ dev = [
74
79
  "fakeredis",
75
80
  ]
76
81
  all = [
77
- "blitzid[api,ocr,scripts,dev]",
82
+ "blitzid[api,barcode,ocr,scripts,dev]",
78
83
  ]
79
84
 
80
85
  # ── Build system ───────────────────────────────────────────
@@ -134,6 +139,7 @@ module = [
134
139
  "PIL.*",
135
140
  "rapidocr",
136
141
  "rapidocr.*",
142
+ "zxingcpp",
137
143
  "pydantic_ai",
138
144
  "pydantic_ai.*",
139
145
  "langfuse",
@@ -15,6 +15,9 @@ Public API
15
15
  - ``OCRText`` — recognized text line (bbox, text, confidence).
16
16
  - ``MRZReader`` — the ICAO 9303 machine-readable zone reader (``ocr`` extra).
17
17
  - ``MRZRecord`` — parsed MRZ fields.
18
+ - ``BarcodeReader`` — the AAMVA PDF417 driver's-license reader
19
+ (``barcode`` extra).
20
+ - ``BarcodeRecord`` — parsed AAMVA payload fields.
18
21
  - ``StructuredOCRReader`` — LLM-backed structured output from OCR lines
19
22
  (``ocr`` extra).
20
23
  - ``StructuredOCR``, ``ExtractedField`` — structured-output schemas.
@@ -25,10 +28,11 @@ Public API
25
28
  - ``DocumentCropper`` — document localization, perspective crop, and QC.
26
29
  - ``QualityReport`` — document crop quality-check verdict.
27
30
  - ``BlitzIDError``, ``ModelError``, ``ImageError``, ``MRZError``,
28
- ``FaceVerificationError`` — exception hierarchy.
31
+ ``BarcodeError``, ``FaceVerificationError`` — exception hierarchy.
29
32
  """
30
33
 
31
34
  from blitzid.exceptions import (
35
+ BarcodeError,
32
36
  BlitzIDError,
33
37
  FaceVerificationError,
34
38
  ImageError,
@@ -40,6 +44,7 @@ from blitzid.face._attributes import FaceAttributeReader, FaceAttributes
40
44
  from blitzid.face._face import DetectionMetrics, Face, VerificationResult
41
45
  from blitzid.face.detector import FaceDetectorDNN
42
46
  from blitzid.face.verifier import FaceVerifier
47
+ from blitzid.reading.barcode import BarcodeReader, BarcodeRecord
43
48
  from blitzid.reading.consistency import (
44
49
  ConsistencyReport,
45
50
  FieldComparison,
@@ -64,6 +69,9 @@ InvalidParameterError = BlitzIDError
64
69
  __all__ = [
65
70
  "AntiSpoofReader",
66
71
  "AntiSpoofResult",
72
+ "BarcodeError",
73
+ "BarcodeReader",
74
+ "BarcodeRecord",
67
75
  "BlitzIDError",
68
76
  "ConsistencyReport",
69
77
  "DetectionMetrics",
@@ -1,4 +1,10 @@
1
- """Date coercion shared by the reading pipeline."""
1
+ """Date coercion shared by the reading pipeline.
2
+
3
+ Alongside the pipeline's ISO 8601 and ``DD.MM.YYYY`` shapes, the AAMVA
4
+ barcode reader feeds MMDDYYYY (U.S.) and CCYYMMDD (Canada) date
5
+ elements through these formats; ``%m%d%Y`` is tried first so a string
6
+ valid in both shapes (a US date) keeps the US reading.
7
+ """
2
8
 
3
9
  from __future__ import annotations
4
10
 
@@ -7,7 +13,7 @@ from datetime import datetime
7
13
 
8
14
  __all__ = ["parse_date"]
9
15
 
10
- _DATE_FORMATS = ("%Y-%m-%d", "%d.%m.%Y")
16
+ _DATE_FORMATS = ("%Y-%m-%d", "%d.%m.%Y", "%m%d%Y", "%Y%m%d")
11
17
 
12
18
 
13
19
  def parse_date(value: object) -> object: