blitzid 0.1.0__tar.gz

blitzid-0.1.0/.dockerignore

@@ -0,0 +1,9 @@
+.git
+.venv
+.kilo
+.env
+models/
+images/
+results/
+__pycache__/
+*.pyc

blitzid-0.1.0/.env.example

@@ -0,0 +1,37 @@
+# blitzid environment variables — copy to .env and adjust.
+# All optional; unset means default behavior.
+
+# Directory for all model weights (SCRFD + RapidOCR). Default: the
+# platformdirs user cache (~/.cache/blitzid/models on Linux).
+# For docker compose: point at a mounted volume so containers share
+# one copy instead of re-downloading on every start, e.g.:
+#   volumes: [ "./models:/models" ]
+#   environment: { BLITZID_MODELS_DIR: /models }
+#BLITZID_MODELS_DIR=/models
+
+# Set to 1 to run the OCR/MRZ integration tests (downloads RapidOCR
+# models, needs network). Unit test suites skip them otherwise.
+#BLITZID_OCR_INTEGRATION=1
+
+# ── HTTP API (blitzid[api] extra) ─────────────────────────────
+
+# Redis the API's job store talks to. The docker-compose redis
+# (persistence disabled — jobs live in RAM only) is wired for you;
+# override only for external Redis instances.
+#BLITZID_API_REDIS_URL=redis://redis:6379/0
+
+# Upload size cap in MB (413 above it).
+#BLITZID_API_MAX_UPLOAD_MB=20
+
+# Lifetime of every job key in seconds (result is 410 Gone after).
+#BLITZID_API_JOB_TTL_SECONDS=900
+
+# Queue capacity (503 + Retry-After when full).
+#BLITZID_API_MAX_QUEUED_JOBS=50
+
+# Analyses running at once per API process.
+#BLITZID_API_MAX_CONCURRENT_JOBS=2
+
+# Claim lease in seconds — a worker crash past this lease re-runs the
+# job instead of losing it (lease sweeper).
+#BLITZID_API_JOB_LEASE_SECONDS=120

blitzid-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/ tests/ scripts/
+      - run: uv run ruff format --check src/ tests/ scripts/
+      - run: uv run mypy src/ scripts/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/ -v

blitzid-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,62 @@
+name: Docker
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - name: Build image (amd64)
+        run: |
+          docker build \
+            -t ghcr.io/malvavisc0/blitzid:$GITHUB_REF_NAME \
+            -t ghcr.io/malvavisc0/blitzid:latest .
+
+      - name: Smoke test (compose up, health, analyze, crop)
+        env:
+          BLITZID_IMAGE_TAG: ${{ github.ref_name }}
+        run: |
+          docker compose up -d --no-build --wait
+          test "$(docker compose images -q api)" = "$(docker image inspect -f '{{.Id}}' ghcr.io/malvavisc0/blitzid:$GITHUB_REF_NAME)"
+          curl -fsS http://localhost:8000/health | grep -q '"status":"ok"'
+          JOB=$(curl -fsS \
+            -F image=@images/nl_td1_id_specimen.jpg \
+            -F types=face,ocr,mrz http://localhost:8000/analyze)
+          ID=$(echo "$JOB" | jq -r .job_id)
+          for _ in $(seq 1 60); do
+            RESULT=$(curl -fsS http://localhost:8000/jobs/$ID)
+            STATUS=$(echo "$RESULT" | jq -r .status)
+            if [ "$STATUS" = "done" ] || [ "$STATUS" = "failed" ]; then break; fi
+            sleep 1
+          done
+          echo "$RESULT" | jq .
+          test "$STATUS" = "done"
+          echo "$RESULT" | grep -q "DE BRUIJN"
+          curl -fsS \
+            -F image=@images/nl_td1_id_specimen.jpg \
+            -F side=front http://localhost:8000/crop \
+            | jq -e '.face_found == true' > /dev/null
+          docker compose down -v
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Push image
+        run: |
+          docker push ghcr.io/malvavisc0/blitzid:$GITHUB_REF_NAME
+          docker push ghcr.io/malvavisc0/blitzid:latest

blitzid-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Verify tag matches the package version
+        run: |
+          VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "v$VERSION" = "$GITHUB_REF_NAME"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

blitzid-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checking / linters
+.mypy_cache/
+.pyre/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDEs / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project artifacts
+results/
+
+# Large model files (downloaded at runtime)
+models/**
+!models/
+!models/.gitkeep
+!models/README.md
+
+# Logs
+*.log
+
+# Env files
+.env
+.env.*
+!.env.example
+
+results/*
+data/*

blitzid-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

blitzid-0.1.0/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-01
+
+### Added
+
+- HTTP API (`blitzid[api]` extra: fastapi, uvicorn, python-multipart,
+  redis) exposing the analyses as async jobs: `POST /analyze`
+  (multipart upload + `types` form field; eager validation with
+  422/400/413/415/503), `GET /jobs/{id}` (claim-once results via
+  GETDEL — later reads get `410 Gone`; TTL-bounded), `GET /health`
+  for orchestration (`503` when the job store is unreachable). Jobs
+  run in per-process worker threads bounded by
+  `BLITZID_API_MAX_CONCURRENT_JOBS` with per-engine locks; a Redis
+  queue (persistence off — RAM only) with an atomically enforced cap,
+  TTL, raw-byte job payloads, and token-owned claims: worker
+  heartbeats extend the claim lease, a lost claim discards that
+  worker's result (the re-claimed worker's result wins), and the
+  claim-lease sweeper re-runs only jobs whose worker actually died. Env
+  knobs: `BLITZID_API_REDIS_URL`, `BLITZID_API_MAX_UPLOAD_MB`,
+  `BLITZID_API_JOB_TTL_SECONDS`, `BLITZID_API_MAX_QUEUED_JOBS`,
+  `BLITZID_API_MAX_CONCURRENT_JOBS`, `BLITZID_API_JOB_LEASE_SECONDS`.
+- Docker deployment: multi-stage `Dockerfile` (weights baked to
+  `/models`, non-root, python-urllib HEALTHCHECK) and
+  `docker-compose.yml` (api + RAM-only `redis:8-alpine` with
+  persistence disabled). Tag pushes publish
+  `ghcr.io/malvavisc0/blitzid` via `.github/workflows/docker.yml`,
+  gated on the (now reusable) CI gate plus a compose smoke test that
+  submits a real face/ocr/mrz job and polls it to completion.
+- PyPI publishing: tag pushes matching the package version build and
+  upload the sdist/wheel to PyPI via `.github/workflows/publish.yml`
+  (trusted publishing — no API tokens), gated on the same CI matrix.
+- `DocumentCropper` / `QualityReport` (reading domain, pure CV):
+  locates the largest plausible document quad via Canny edges +
+  contour approximation, warps it into an axis-aligned canonical crop
+  at the quad's own aspect, and quality-checks it (`document_found`,
+  `aspect_ratio` near ID-1/ID-3, `resolution`, `sharpness`,
+  `brightness`, side-aware `face_present` — never fails a document).
+  Optional `FaceDetectorDNN` injection powers the face check
+  (`front` + no face → warn; `back` → not expected) without adding a
+  runtime `reading → face` dependency; an optional `detector_lock`
+  serializes the check against other users of a shared detector. The
+  `POST /crop` API endpoint wraps it: QC verdict plus the canonical
+  `crop_base64` JPEG.
+- `BLITZID_MODELS_DIR` environment variable: relocates all model-weight
+  downloads (SCRFD + RapidOCR) when set; defaults to the platformdirs
+  user cache as before. `scripts/download_models.py` pre-fetches all
+  weights into a directory (default `models/`) for Docker images.
+- `MRZReader` / `MRZRecord` / `MRZError`: ICAO 9303 machine-readable zone
+  reading on top of the `ocr` extra. Selects MRZ lines from OCR output
+  (30/36/44 chars over the MRZ charset, reassembled by bbox position),
+  validates every check digit plus the letter-only fields (document
+  code, issuer, nationality — the ones without check-digit protection),
+  and parses TD1, TD2, and TD3 layouts. No fuzzy OCR-error correction:
+  an unreadable zone raises `MRZError` with the failing field.
+  Document numbers longer than their field follow the ICAO
+  convention — no printed check digit, overflow at the start of
+  `optional_data1` — and are accepted (the composite check digit
+  still covers the full number).
+- `RapidOCRReader` / `OCRText` and the `blitzid[ocr]` extra: OCR text
+  reading for ID documents via RapidOCR (PP-OCR ONNX models on
+  onnxruntime CPU). Models download on first use to
+  `user_cache_dir("blitzid")/models/rapidocr`; `read()` returns text
+  lines sorted by confidence. Core installs stay OCR-free.
+  `scripts/ocr_demo.py` demonstrates the reader from the CLI.
+- `detect_face_landmarks()`, returning the new frozen `Face` dataclass
+  (`bbox`, `confidence`, `landmarks`). SCRFD decodes its 5-point keypoint
+  head — right eye, left eye, nose tip, right mouth corner, left mouth
+  corner — previously discarded. Existing `detect_face()` tuples are
+  unchanged.
+- Positive-path tests on repo image fixtures: the specimen ID card (exactly
+  one face — its portrait) and the 1927 conference photo (29 people). Also
+  fails fast with `ModelError` on an unexpected SCRFD ONNX output layout.
+- Public `FaceDetectorDNN.cache_enabled` property (scripts no longer read
+  the private `_cache` attribute).
+- `face_detector_demo.py` validates `--run` demo names and exits with the
+  valid set on typos; cache CLI knobs are documented as custom-preset-only.
+- Detection caching with configurable LRU cache.
+- Multi-scale detection for improved recall on small faces.
+- Typed package (`py.typed` marker).
+
+### Changed
+
+- Replaced the SSD ResNet-10 Caffe detector with **SCRFD-2.5G** (InsightFace
+  `buffalo_m` ONNX weights) running on **onnxruntime CPU**. OpenCV 5 removed
+  the Caffe importer; inference now fails fast with `ModelError` instead of
+  falling back to other models or providers.
+- `FaceDetectorDNN` gains a `det_size` parameter (default `640x640`, multiples
+  of 32) and letterboxes input images so detections map back to original image
+  coordinates without aspect distortion.
+- `DetectionMetrics.backend` now reports `"ONNXRuntime"`.
+- `detect_faces_batch()` now omits failed images from the result dict; an
+  empty list always means "processed, zero faces". Failed images are still
+  logged. Previously failures were indistinguishable from legitimate
+  zero-face results.
+- `DetectionMetrics.faces` now carries `Face` records (landmarks
+  accessible) instead of legacy `(x, y, w, h, confidence)` tuples.
+  **Breaking** for consumers unpacking metrics entries as tuples.
+- Cache hits report real elapsed cache-lookup time in
+  `DetectionMetrics.processing_time` instead of a hardcoded `0.0`.
+- `scales` runs exactly as configured: `_normalize_scales` no longer
+  silently injects a `1.0` pass, so `scales=(1.5,)` costs one inference,
+  not two.
+- Model downloads stream to a `.tmp` file in 64 KB chunks instead of
+  reading the whole file into memory; the socket timeout now bounds the
+  transfer.
+
+### Fixed
+
+- Model download no longer raises `ModelError` after a successful transfer:
+  the post-download size log stat'ed the already-renamed `.tmp` file. Only
+  affected fresh installs (cached models never re-downloaded).
+- Detection cache keys now cover image `shape` and `dtype` in addition to
+  pixel bytes — arrays sharing byte content but differing in layout no
+  longer collide on one cached result.
+- Restored the 10000px `MAX_DIMENSION` guard in image validation, lost in
+  the SCRFD migration; oversized inputs fail fast with `ImageError`
+  instead of allocating multi-GB arrays.
+- `midv500_face_test.py` face counts now match the crops actually
+  considered for saving when `--max-faces-per-image` truncates the list.
+
+### Removed
+
+- The DeepFace backend entirely: `FaceDetectorDeepFace`,
+  `blitzid[deepface]` extra, the `deepface`/`tf-keras` dependencies,
+  `tests/test_deepface.py`, and the `analyze()` API. SCRFD via onnxruntime
+  is the single detection backend.
+- CUDA backend support: `require_cuda` parameters, the CUDA/CPU auto-fallback
+  chain in `ModelManager.load_network`, the `CUDAConfigError` alias, and
+  `scripts/cuda_diagnostics.py`.
+- Dead dataset-annotation helpers in `scripts/midv500_download.py` with zero
+  call sites (`list_annotation_paths_recursively`, `calculate_intersect_area`,
+  `get_bbox_inside_image`).
+- `FaceDetectorDNN.backend_type` compat alias (superseded by `backend`).

blitzid-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to BlitzID
+
+## Development setup
+
+```bash
+# Clone and install with dev dependencies
+git clone https://github.com/malvavisc0/blitzid.git
+cd blitzid
+uv sync --extra dev
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## Running checks locally
+
+```bash
+# Lint
+uv run ruff check src/ tests/ scripts/
+uv run ruff format --check src/ tests/ scripts/
+
+# Type checking
+uv run mypy src/ scripts/
+
+# Tests
+uv run pytest tests/ -v
+
+# Complexity + dead code (see docs/coding-standard.md)
+uvx radon cc src scripts tests -s | grep -E '\-\s(C|D|E|F)\s'   # must be empty
+uvx vulture src/ tests/ scripts/ --min-confidence 60
+```
+
+## Pull request guidelines
+
+1. Fork the repo and create a feature branch from `main`.
+2. Ensure all checks pass (`ruff`, `mypy`, `pytest`).
+3. Add or update tests for any new functionality.
+4. Update `CHANGELOG.md` under `[Unreleased]`.
+5. Open a PR with a clear description of the change.

blitzid-0.1.0/Dockerfile

@@ -0,0 +1,22 @@
+# ── Builder: install deps and bake model weights ──────────────
+FROM python:3.12-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+WORKDIR /app
+COPY README.md pyproject.toml uv.lock ./
+COPY src/ src/
+COPY scripts/ scripts/
+RUN uv sync --frozen --no-dev --extra api --extra ocr
+RUN uv run --no-sync python scripts/download_models.py --models-dir /models
+
+# ── Runtime: venv + baked weights, non-root ─────────────────────
+FROM python:3.12-slim
+COPY --from=builder /app /app
+COPY --from=builder /models /models
+ENV BLITZID_MODELS_DIR=/models
+ENV PATH=/app/.venv/bin:$PATH
+RUN useradd --create-home appuser
+USER appuser
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD ["python", "-c", "import sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=3).status == 200 else 1)"]
+CMD ["uvicorn", "blitzid.api:app", "--host", "0.0.0.0", "--port", "8000"]

blitzid-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Malvavisc0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.