v1.7.1

.gitea/workflows/docker_nottags.yaml

@@ -0,0 +1,67 @@
+name: Docker (no tags)
+
+on:
+  push:
+    tags-ignore:
+      - '**'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_LOGIN_DOCKER_DOCKERREGISTRY: ${{ secrets.NPMCI_LOGIN_DOCKER_DOCKERREGISTRY }}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+        continue-on-error: true
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci command npm run build

.gitea/workflows/docker_tags.yaml

@@ -0,0 +1,101 @@
+name: Docker (tags)
+
+on:
+  push:
+    tags:
+      - '*'
+
+env:
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
+  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_LOGIN_DOCKER_DOCKERREGISTRY: ${{ secrets.NPMCI_LOGIN_DOCKER_DOCKERREGISTRY }}
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+    continue-on-error: true
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Audit production dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --prod
+        continue-on-error: true
+
+      - name: Audit development dependencies
+        run: |
+          npmci command npm config set registry https://registry.npmjs.org
+          npmci command pnpm audit --audit-level=high --dev
+        continue-on-error: true
+
+  test:
+    needs: security
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+          npmci npm prepare
+
+      - name: Test stable
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci npm test
+        continue-on-error: true
+
+      - name: Test build
+        run: |
+          npmci node install stable
+          npmci npm install
+          npmci command npm run build
+
+  release:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: code.foss.global/host.today/ht-docker-dbase:npmci
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Prepare
+        run: |
+          pnpm install -g pnpm
+          pnpm install -g @ship.zone/npmci
+
+      - name: Release
+        run: |
+          npmci docker login
+          npmci docker build
+          npmci docker push code.foss.global
+
+  metadata:
+    needs: test
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ env.IMAGE }}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Trigger
+        run: npmci trigger

Dockerfile_minicpm45v_cpu

@@ -14,7 +14,7 @@ ENV OLLAMA_ORIGINS="*"
 ENV CUDA_VISIBLE_DEVICES=""
 
 # Copy and setup entrypoint
-COPY image_support_files/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+COPY image_support_files/minicpm45v_entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 # Expose Ollama API port

Dockerfile_minicpm45v_gpu

@@ -12,7 +12,7 @@ ENV OLLAMA_HOST="0.0.0.0"
 ENV OLLAMA_ORIGINS="*"
 
 # Copy and setup entrypoint
-COPY image_support_files/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+COPY image_support_files/minicpm45v_entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 # Expose Ollama API port

Dockerfile_paddleocr

@@ -1,51 +0,0 @@
-# PaddleOCR GPU Variant
-# OCR processing with NVIDIA GPU support using PaddlePaddle
-FROM paddlepaddle/paddle:3.0.0-gpu-cuda11.8-cudnn8.9-trt8.6
-
-LABEL maintainer="Task Venture Capital GmbH <hello@task.vc>"
-LABEL description="PaddleOCR PP-OCRv4 - GPU optimized"
-LABEL org.opencontainers.image.source="https://code.foss.global/host.today/ht-docker-ai"
-
-# Environment configuration
-ENV OCR_LANGUAGE="en"
-ENV SERVER_PORT="5000"
-ENV SERVER_HOST="0.0.0.0"
-ENV PYTHONUNBUFFERED=1
-
-# Set working directory
-WORKDIR /app
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1-mesa-glx \
-    libglib2.0-0 \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install Python dependencies
-RUN pip install --no-cache-dir \
-    paddleocr \
-    fastapi \
-    uvicorn[standard] \
-    python-multipart \
-    opencv-python-headless \
-    pillow
-
-# Copy server files
-COPY image_support_files/paddleocr-server.py /app/paddleocr-server.py
-COPY image_support_files/paddleocr-entrypoint.sh /usr/local/bin/paddleocr-entrypoint.sh
-RUN chmod +x /usr/local/bin/paddleocr-entrypoint.sh
-
-# Pre-download OCR models during build (PP-OCRv4)
-RUN python -c "from paddleocr import PaddleOCR; \
-    ocr = PaddleOCR(use_angle_cls=True, lang='en', use_gpu=False, show_log=True); \
-    print('English model downloaded')"
-
-# Expose API port
-EXPOSE 5000
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
-    CMD curl -f http://localhost:5000/health || exit 1
-
-ENTRYPOINT ["/usr/local/bin/paddleocr-entrypoint.sh"]

Dockerfile_paddleocr_cpu

@@ -1,54 +0,0 @@
-# PaddleOCR CPU Variant
-# OCR processing optimized for CPU-only inference
-FROM python:3.10-slim
-
-LABEL maintainer="Task Venture Capital GmbH <hello@task.vc>"
-LABEL description="PaddleOCR PP-OCRv4 - CPU optimized"
-LABEL org.opencontainers.image.source="https://code.foss.global/host.today/ht-docker-ai"
-
-# Environment configuration for CPU-only mode
-ENV OCR_LANGUAGE="en"
-ENV SERVER_PORT="5000"
-ENV SERVER_HOST="0.0.0.0"
-ENV PYTHONUNBUFFERED=1
-# Disable GPU usage for CPU-only variant
-ENV CUDA_VISIBLE_DEVICES="-1"
-
-# Set working directory
-WORKDIR /app
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1-mesa-glx \
-    libglib2.0-0 \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install Python dependencies (CPU version of PaddlePaddle)
-RUN pip install --no-cache-dir \
-    paddlepaddle \
-    paddleocr \
-    fastapi \
-    uvicorn[standard] \
-    python-multipart \
-    opencv-python-headless \
-    pillow
-
-# Copy server files
-COPY image_support_files/paddleocr-server.py /app/paddleocr-server.py
-COPY image_support_files/paddleocr-entrypoint.sh /usr/local/bin/paddleocr-entrypoint.sh
-RUN chmod +x /usr/local/bin/paddleocr-entrypoint.sh
-
-# Pre-download OCR models during build (PP-OCRv4)
-RUN python -c "from paddleocr import PaddleOCR; \
-    ocr = PaddleOCR(use_angle_cls=True, lang='en', use_gpu=False, show_log=True); \
-    print('English model downloaded')"
-
-# Expose API port
-EXPOSE 5000
-
-# Health check (longer start-period for CPU variant)
-HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
-    CMD curl -f http://localhost:5000/health || exit 1
-
-ENTRYPOINT ["/usr/local/bin/paddleocr-entrypoint.sh"]

Dockerfile_paddleocr_vl_cpu

@@ -0,0 +1,57 @@
+# PaddleOCR-VL CPU Variant
+# Vision-Language Model for document parsing using transformers (slower, no GPU required)
+FROM python:3.11-slim-bookworm
+
+LABEL maintainer="Task Venture Capital GmbH <hello@task.vc>"
+LABEL description="PaddleOCR-VL 0.9B CPU - Vision-Language Model for document parsing"
+LABEL org.opencontainers.image.source="https://code.foss.global/host.today/ht-docker-ai"
+
+# Environment configuration
+ENV PYTHONUNBUFFERED=1
+ENV HF_HOME=/root/.cache/huggingface
+ENV CUDA_VISIBLE_DEVICES=""
+ENV SERVER_PORT=8000
+ENV SERVER_HOST=0.0.0.0
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libgomp1 \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+    torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cpu && \
+    pip install --no-cache-dir \
+    transformers \
+    accelerate \
+    safetensors \
+    pillow \
+    fastapi \
+    uvicorn[standard] \
+    python-multipart \
+    httpx \
+    protobuf \
+    sentencepiece \
+    einops
+
+# Copy server files
+COPY image_support_files/paddleocr_vl_server.py /app/paddleocr_vl_server.py
+COPY image_support_files/paddleocr_vl_entrypoint.sh /usr/local/bin/paddleocr-vl-cpu-entrypoint.sh
+RUN chmod +x /usr/local/bin/paddleocr-vl-cpu-entrypoint.sh
+
+# Expose API port
+EXPOSE 8000
+
+# Health check (longer start-period for CPU + model download)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+ENTRYPOINT ["/usr/local/bin/paddleocr-vl-cpu-entrypoint.sh"]

Dockerfile_paddleocr_vl_full

@@ -0,0 +1,90 @@
+# PaddleOCR-VL Full Pipeline (PP-DocLayoutV2 + PaddleOCR-VL + Structured Output)
+# Self-contained GPU image with complete document parsing pipeline
+FROM nvidia/cuda:12.4.0-devel-ubuntu22.04
+
+LABEL maintainer="Task Venture Capital GmbH <hello@task.vc>"
+LABEL description="PaddleOCR-VL Full Pipeline - Layout Detection + VL Recognition + JSON/Markdown Output"
+LABEL org.opencontainers.image.source="https://code.foss.global/host.today/ht-docker-ai"
+
+# Environment configuration
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+ENV HF_HOME=/root/.cache/huggingface
+ENV PADDLEOCR_HOME=/root/.paddleocr
+ENV SERVER_PORT=8000
+ENV SERVER_HOST=0.0.0.0
+ENV VLM_PORT=8080
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.11 \
+    python3.11-venv \
+    python3.11-dev \
+    python3-pip \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libgomp1 \
+    libsm6 \
+    libxext6 \
+    libxrender1 \
+    curl \
+    git \
+    wget \
+    && rm -rf /var/lib/apt/lists/* \
+    && update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1 \
+    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
+
+# Create and activate virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Upgrade pip
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel
+
+# Install PaddlePaddle GPU (CUDA 12.x)
+RUN pip install --no-cache-dir \
+    paddlepaddle-gpu==3.2.1 \
+    --extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu126/
+
+# Install PaddleOCR with doc-parser (includes PP-DocLayoutV2)
+RUN pip install --no-cache-dir \
+    "paddleocr[doc-parser]" \
+    safetensors
+
+# Install PyTorch with CUDA support
+RUN pip install --no-cache-dir \
+    torch==2.5.1 \
+    torchvision \
+    --index-url https://download.pytorch.org/whl/cu124
+
+# Install transformers for PaddleOCR-VL inference (no vLLM - use local inference)
+# PaddleOCR-VL requires transformers>=4.55.0 for use_kernel_forward_from_hub
+RUN pip install --no-cache-dir \
+    transformers>=4.55.0 \
+    accelerate \
+    hf-kernels
+
+# Install our API server dependencies
+RUN pip install --no-cache-dir \
+    fastapi \
+    uvicorn[standard] \
+    python-multipart \
+    httpx \
+    pillow
+
+# Copy server files
+COPY image_support_files/paddleocr_vl_full_server.py /app/server.py
+COPY image_support_files/paddleocr_vl_full_entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+# Expose ports (8000 = API, 8080 = internal VLM server)
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

Dockerfile_paddleocr_vl_gpu

@@ -0,0 +1,71 @@
+# PaddleOCR-VL GPU Variant (Transformers-based, not vLLM)
+# Vision-Language Model for document parsing using transformers with CUDA
+FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04
+
+LABEL maintainer="Task Venture Capital GmbH <hello@task.vc>"
+LABEL description="PaddleOCR-VL 0.9B GPU - Vision-Language Model using transformers"
+LABEL org.opencontainers.image.source="https://code.foss.global/host.today/ht-docker-ai"
+
+# Environment configuration
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+ENV HF_HOME=/root/.cache/huggingface
+ENV SERVER_PORT=8000
+ENV SERVER_HOST=0.0.0.0
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.11 \
+    python3.11-venv \
+    python3.11-dev \
+    python3-pip \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libgomp1 \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/* \
+    && update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1 \
+    && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
+
+# Create and activate virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install PyTorch with CUDA support
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+    torch==2.5.1 \
+    torchvision \
+    --index-url https://download.pytorch.org/whl/cu124
+
+# Install Python dependencies (transformers-based, not vLLM)
+RUN pip install --no-cache-dir \
+    transformers \
+    accelerate \
+    safetensors \
+    pillow \
+    fastapi \
+    uvicorn[standard] \
+    python-multipart \
+    httpx \
+    protobuf \
+    sentencepiece \
+    einops
+
+# Copy server files (same as CPU variant - it auto-detects CUDA)
+COPY image_support_files/paddleocr_vl_server.py /app/paddleocr_vl_server.py
+COPY image_support_files/paddleocr_vl_entrypoint.sh /usr/local/bin/paddleocr-vl-entrypoint.sh
+RUN chmod +x /usr/local/bin/paddleocr-vl-entrypoint.sh
+
+# Expose API port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=300s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+ENTRYPOINT ["/usr/local/bin/paddleocr-vl-entrypoint.sh"]

build-images.sh

@@ -16,7 +16,7 @@ echo -e "${BLUE}Building ht-docker-ai images...${NC}"
 # Build GPU variant
 echo -e "${GREEN}Building MiniCPM-V 4.5 GPU variant...${NC}"
 docker build \
-    -f Dockerfile_minicpm45v \
+    -f Dockerfile_minicpm45v_gpu \
     -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:minicpm45v \
     -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:minicpm45v-gpu \
     -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:latest \
@@ -29,9 +29,30 @@ docker build \
     -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:minicpm45v-cpu \
     .
 
+# Build PaddleOCR-VL GPU variant
+echo -e "${GREEN}Building PaddleOCR-VL GPU variant...${NC}"
+docker build \
+    -f Dockerfile_paddleocr_vl_gpu \
+    -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl \
+    -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl-gpu \
+    .
+
+# Build PaddleOCR-VL CPU variant
+echo -e "${GREEN}Building PaddleOCR-VL CPU variant...${NC}"
+docker build \
+    -f Dockerfile_paddleocr_vl_cpu \
+    -t ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl-cpu \
+    .
+
 echo -e "${GREEN}All images built successfully!${NC}"
 echo ""
 echo "Available images:"
+echo "  MiniCPM-V 4.5:"
 echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:minicpm45v (GPU)"
 echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:minicpm45v-cpu (CPU)"
 echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:latest (GPU)"
+echo ""
+echo "  PaddleOCR-VL (Vision-Language Model):"
+echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl (GPU/vLLM)"
+echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl-gpu (GPU/vLLM)"
+echo "  - ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:paddleocr-vl-cpu (CPU)"

changelog.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 2026-01-17 - 1.7.1 - fix(docker)
+standardize Dockerfile and entrypoint filenames; add GPU-specific Dockerfiles and update build and test references
+
+- Added Dockerfile_minicpm45v_gpu and image_support_files/minicpm45v_entrypoint.sh; removed the old Dockerfile_minicpm45v and docker-entrypoint.sh
+- Renamed and simplified PaddleOCR entrypoint to image_support_files/paddleocr_vl_entrypoint.sh and updated CPU/GPU Dockerfile references
+- Updated build-images.sh to use *_gpu Dockerfiles and clarified PaddleOCR GPU build log
+- Updated test/helpers/docker.ts to point to Dockerfile_minicpm45v_gpu so tests build the GPU variant
+
+## 2026-01-17 - 1.7.0 - feat(tests)
+use Qwen2.5 (Ollama) for invoice extraction tests and add helpers for model management; normalize dates and coerce numeric fields
+
+- Added ensureOllamaModel and ensureQwen25 test helpers to pull/check Ollama models via localhost:11434
+- Updated invoices test to use qwen2.5:7b instead of MiniCPM and removed image payload from the text-only extraction step
+- Increased Markdown truncate limit from 8000 to 12000 and reduced model num_predict from 2048 to 512
+- Rewrote extraction prompt to require strict JSON output and added post-processing to parse/convert numeric fields
+- Added normalizeDate and improved compareInvoice to normalize dates and handle numeric formatting/tolerance
+- Updated test setup to ensure Qwen2.5 is available and adjusted logging/messages to reflect the Qwen2.5-based workflow
+
+## 2026-01-17 - 1.6.0 - feat(paddleocr-vl)
+add PaddleOCR-VL full pipeline Docker image and API server, plus integration tests and docker helpers
+
+- Add Dockerfile_paddleocr_vl_full and entrypoint script to build a GPU-enabled image with PP-DocLayoutV2 + PaddleOCR-VL and a FastAPI server
+- Introduce image_support_files/paddleocr_vl_full_server.py implementing the full pipeline API (/parse, OpenAI-compatible /v1/chat/completions) and a /formats endpoint
+- Improve image handling: decode_image supports data URLs, HTTP(S), raw base64 and file paths; add optimize_image_resolution to auto-scale images into the recommended 1080-2048px range
+- Add test helpers (test/helpers/docker.ts) to build/start/health-check Docker images and new ensurePaddleOcrVlFull workflow
+- Add comprehensive integration tests for bank statements and invoices (MiniCPM and PaddleOCR-VL variants) and update tests to ensure required containers are running before tests
+- Switch MiniCPM model references to 'minicpm-v:latest' and increase health/timeout expectations for the full pipeline
+
+## 2026-01-17 - 1.5.0 - feat(paddleocr-vl)
+add PaddleOCR-VL GPU Dockerfile, pin vllm, update CPU image deps, and improve entrypoint and tests
+
+- Add a new GPU Dockerfile for PaddleOCR-VL (transformers-based) with CUDA support, healthcheck, and entrypoint.
+- Pin vllm to 0.11.1 in Dockerfile_paddleocr_vl to use the first stable release with PaddleOCR-VL support.
+- Update CPU image: add torchvision==0.20.1 and extra Python deps (protobuf, sentencepiece, einops) required by the transformers-based server.
+- Rewrite paddleocr-vl-entrypoint.sh to build vllm args array, add MAX_MODEL_LEN and ENFORCE_EAGER env vars, include --limit-mm-per-prompt and optional --enforce-eager, and switch to exec vllm with constructed args.
+- Update tests to use the OpenAI-compatible PaddleOCR-VL chat completions API (/v1/chat/completions) with image+text message payload and model 'paddleocr-vl'.
+- Add @types/node to package.json dependencies and tidy devDependencies ordering.
+
+## 2026-01-16 - 1.4.0 - feat(invoices)
+add hybrid OCR + vision invoice/document parsing with PaddleOCR, consensus voting, and prompt/test refactors
+
+- Add hybrid pipeline documentation and examples (PaddleOCR + MiniCPM-V) and architecture diagram in recipes/document.md
+- Integrate PaddleOCR: new OCR extraction functions and OCR-only prompt flow in test/test.node.ts
+- Add consensus voting and parallel-pass optimization to improve reliability (multiple passes, hashing, and majority voting)
+- Refactor prompts and tests: introduce /nothink token, OCR truncation limits, separate visual and OCR-only prompts, and improved prompt building in test/test.invoices.ts
+- Update image conversion defaults (200 DPI, filename change) and add TypeScript helper functions for extraction and consensus handling
+
+## 2026-01-16 - 1.3.0 - feat(paddleocr)
+add PaddleOCR OCR service (Docker images, server, tests, docs) and CI workflows
+
+- Add GPU and CPU PaddleOCR Dockerfiles; pin paddlepaddle/paddle and paddleocr to stable 2.x and install libgomp1 for CPU builds
+- Avoid pre-downloading OCR models at build-time to prevent build-time segfaults; models are downloaded on first run
+- Refactor PaddleOCR FastAPI server: respect CUDA_VISIBLE_DEVICES, support per-request language, cache default language instance and create temporary instances for other languages
+- Add comprehensive tests (test.paddleocr.ts) and improve invoice extraction tests (parallelize passes, JSON OCR API usage, prioritize certain test cases)
+- Add Gitea CI workflows for tag and non-tag Docker runs and release pipeline (docker build/push, metadata trigger)
+- Update documentation (readme.hints.md) with PaddleOCR usage and add docker registry entry to npmextra.json
+
+## 2026-01-16 - 1.2.0 - feat(paddleocr)
+add PaddleOCR support: Docker images, FastAPI server, entrypoint and tests
+
+- Add PaddleOCR FastAPI server implementation at image_support_files/paddleocr_server.py
+- Remove old image_support_files/paddleocr-server.py and update entrypoint to import paddleocr_server:app
+- Extend build-images.sh to build paddleocr (GPU) and paddleocr-cpu images and list them
+- Extend test-images.sh to add paddleocr health/OCR tests, new test_paddleocr_image function, port config, and cleanup; rename test_image -> test_minicpm_image
+
 ## 2026-01-16 - 1.1.0 - feat(ocr)
 add PaddleOCR GPU Docker image and FastAPI OCR server with entrypoint; implement OCR endpoints and consensus extraction testing
 

image_support_files/paddleocr-entrypoint.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-set -e
-
-# Configuration from environment
-OCR_LANGUAGE="${OCR_LANGUAGE:-en}"
-SERVER_PORT="${SERVER_PORT:-5000}"
-SERVER_HOST="${SERVER_HOST:-0.0.0.0}"
-
-echo "Starting PaddleOCR Server..."
-echo "  Language: ${OCR_LANGUAGE}"
-echo "  Host: ${SERVER_HOST}"
-echo "  Port: ${SERVER_PORT}"
-
-# Check GPU availability
-if [ "${CUDA_VISIBLE_DEVICES}" = "-1" ]; then
-    echo "  GPU: Disabled (CPU mode)"
-else
-    echo "  GPU: Enabled"
-fi
-
-# Start the FastAPI server with uvicorn
-exec python -m uvicorn paddleocr-server:app \
-    --host "${SERVER_HOST}" \
-    --port "${SERVER_PORT}" \
-    --workers 1

image_support_files/paddleocr-server.py

@@ -1,258 +0,0 @@
-#!/usr/bin/env python3
-"""
-PaddleOCR FastAPI Server
-Provides REST API for OCR operations using PaddleOCR
-"""
-
-import os
-import io
-import base64
-import logging
-from typing import Optional, List, Any
-
-from fastapi import FastAPI, File, UploadFile, Form, HTTPException
-from fastapi.responses import JSONResponse
-from pydantic import BaseModel
-import numpy as np
-from PIL import Image
-from paddleocr import PaddleOCR
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-)
-logger = logging.getLogger(__name__)
-
-# Environment configuration
-OCR_LANGUAGE = os.environ.get('OCR_LANGUAGE', 'en')
-USE_GPU = os.environ.get('CUDA_VISIBLE_DEVICES', '') != '-1'
-
-# Initialize FastAPI app
-app = FastAPI(
-    title="PaddleOCR Server",
-    description="REST API for OCR operations using PaddleOCR PP-OCRv4",
-    version="1.0.0"
-)
-
-# Global OCR instance
-ocr_instance: Optional[PaddleOCR] = None
-
-
-class OCRRequest(BaseModel):
-    """Request model for base64 image OCR"""
-    image: str
-    language: Optional[str] = None
-
-
-class BoundingBox(BaseModel):
-    """Bounding box for detected text"""
-    points: List[List[float]]
-
-
-class OCRResult(BaseModel):
-    """Single OCR detection result"""
-    text: str
-    confidence: float
-    box: List[List[float]]
-
-
-class OCRResponse(BaseModel):
-    """OCR response model"""
-    success: bool
-    results: List[OCRResult]
-    error: Optional[str] = None
-
-
-class HealthResponse(BaseModel):
-    """Health check response"""
-    status: str
-    model: str
-    language: str
-    gpu_enabled: bool
-
-
-def get_ocr() -> PaddleOCR:
-    """Get or initialize the OCR instance"""
-    global ocr_instance
-    if ocr_instance is None:
-        logger.info(f"Initializing PaddleOCR with language={OCR_LANGUAGE}, use_gpu={USE_GPU}")
-        ocr_instance = PaddleOCR(
-            use_angle_cls=True,
-            lang=OCR_LANGUAGE,
-            use_gpu=USE_GPU,
-            show_log=False
-        )
-        logger.info("PaddleOCR initialized successfully")
-    return ocr_instance
-
-
-def decode_base64_image(base64_string: str) -> np.ndarray:
-    """Decode base64 string to numpy array"""
-    # Remove data URL prefix if present
-    if ',' in base64_string:
-        base64_string = base64_string.split(',')[1]
-
-    image_data = base64.b64decode(base64_string)
-    image = Image.open(io.BytesIO(image_data))
-
-    # Convert to RGB if necessary
-    if image.mode != 'RGB':
-        image = image.convert('RGB')
-
-    return np.array(image)
-
-
-def process_ocr_result(result: Any) -> List[OCRResult]:
-    """Process PaddleOCR result into structured format"""
-    results = []
-
-    if result is None or len(result) == 0:
-        return results
-
-    # PaddleOCR returns list of results per image
-    # Each result is a list of [box, (text, confidence)]
-    for line in result[0] if result[0] else []:
-        if line is None:
-            continue
-
-        box = line[0]  # [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
-        text_info = line[1]  # (text, confidence)
-
-        results.append(OCRResult(
-            text=text_info[0],
-            confidence=float(text_info[1]),
-            box=[[float(p[0]), float(p[1])] for p in box]
-        ))
-
-    return results
-
-
-@app.on_event("startup")
-async def startup_event():
-    """Pre-warm the OCR model on startup"""
-    logger.info("Pre-warming OCR model...")
-    try:
-        ocr = get_ocr()
-        # Create a small test image to warm up the model
-        test_image = np.zeros((100, 100, 3), dtype=np.uint8)
-        test_image.fill(255)  # White image
-        ocr.ocr(test_image, cls=True)
-        logger.info("OCR model pre-warmed successfully")
-    except Exception as e:
-        logger.error(f"Failed to pre-warm OCR model: {e}")
-
-
-@app.get("/health", response_model=HealthResponse)
-async def health_check():
-    """Health check endpoint"""
-    try:
-        # Ensure OCR is initialized
-        get_ocr()
-        return HealthResponse(
-            status="healthy",
-            model="PP-OCRv4",
-            language=OCR_LANGUAGE,
-            gpu_enabled=USE_GPU
-        )
-    except Exception as e:
-        logger.error(f"Health check failed: {e}")
-        raise HTTPException(status_code=503, detail=str(e))
-
-
-@app.post("/ocr", response_model=OCRResponse)
-async def ocr_base64(request: OCRRequest):
-    """
-    Perform OCR on a base64-encoded image
-
-    Args:
-        request: OCRRequest with base64 image and optional language
-
-    Returns:
-        OCRResponse with detected text, confidence scores, and bounding boxes
-    """
-    try:
-        # Decode image
-        image = decode_base64_image(request.image)
-
-        # Get OCR instance (use request language if provided)
-        ocr = get_ocr()
-
-        # If a different language is requested, create a new instance
-        if request.language and request.language != OCR_LANGUAGE:
-            logger.info(f"Creating OCR instance for language: {request.language}")
-            temp_ocr = PaddleOCR(
-                use_angle_cls=True,
-                lang=request.language,
-                use_gpu=USE_GPU,
-                show_log=False
-            )
-            result = temp_ocr.ocr(image, cls=True)
-        else:
-            result = ocr.ocr(image, cls=True)
-
-        # Process results
-        results = process_ocr_result(result)
-
-        return OCRResponse(success=True, results=results)
-
-    except Exception as e:
-        logger.error(f"OCR processing failed: {e}")
-        return OCRResponse(success=False, results=[], error=str(e))
-
-
-@app.post("/ocr/upload", response_model=OCRResponse)
-async def ocr_upload(
-    img: UploadFile = File(...),
-    language: Optional[str] = Form(None)
-):
-    """
-    Perform OCR on an uploaded image file
-
-    Args:
-        img: Uploaded image file
-        language: Optional language code (default: env OCR_LANGUAGE)
-
-    Returns:
-        OCRResponse with detected text, confidence scores, and bounding boxes
-    """
-    try:
-        # Read image
-        contents = await img.read()
-        image = Image.open(io.BytesIO(contents))
-
-        # Convert to RGB if necessary
-        if image.mode != 'RGB':
-            image = image.convert('RGB')
-
-        image_array = np.array(image)
-
-        # Get OCR instance
-        ocr = get_ocr()
-
-        # If a different language is requested, create a new instance
-        if language and language != OCR_LANGUAGE:
-            logger.info(f"Creating OCR instance for language: {language}")
-            temp_ocr = PaddleOCR(
-                use_angle_cls=True,
-                lang=language,
-                use_gpu=USE_GPU,
-                show_log=False
-            )
-            result = temp_ocr.ocr(image_array, cls=True)
-        else:
-            result = ocr.ocr(image_array, cls=True)
-
-        # Process results
-        results = process_ocr_result(result)
-
-        return OCRResponse(success=True, results=results)
-
-    except Exception as e:
-        logger.error(f"OCR processing failed: {e}")
-        return OCRResponse(success=False, results=[], error=str(e))
-
-
-if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=5000)

image_support_files/paddleocr_vl_entrypoint.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -e
+
+echo "==================================="
+echo "PaddleOCR-VL Server (CPU)"
+echo "==================================="
+
+HOST="${SERVER_HOST:-0.0.0.0}"
+PORT="${SERVER_PORT:-8000}"
+
+echo "Host: ${HOST}"
+echo "Port: ${PORT}"
+echo "Device: CPU (no GPU)"
+echo ""
+
+echo "Starting PaddleOCR-VL CPU server..."
+echo "==================================="
+
+exec python /app/paddleocr_vl_server.py

image_support_files/paddleocr_vl_full_entrypoint.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -e
+
+echo "Starting PaddleOCR-VL Full Pipeline Server (Transformers backend)..."
+
+# Environment
+SERVER_PORT=${SERVER_PORT:-8000}
+SERVER_HOST=${SERVER_HOST:-0.0.0.0}
+
+# Start our API server directly (no vLLM - uses local transformers inference)
+echo "Starting API server on port $SERVER_PORT..."
+exec python /app/server.py

image_support_files/paddleocr_vl_full_server.py

@@ -0,0 +1,443 @@
+#!/usr/bin/env python3
+"""
+PaddleOCR-VL Full Pipeline API Server (Transformers backend)
+
+Provides REST API for document parsing using:
+- PP-DocLayoutV2 for layout detection
+- PaddleOCR-VL (transformers) for recognition
+- Structured JSON/Markdown output
+"""
+
+import os
+import io
+import base64
+import logging
+import tempfile
+import time
+import json
+from typing import Optional, List, Union
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, UploadFile, File, Form
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+from PIL import Image
+import torch
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Environment configuration
+SERVER_HOST = os.environ.get('SERVER_HOST', '0.0.0.0')
+SERVER_PORT = int(os.environ.get('SERVER_PORT', '8000'))
+MODEL_NAME = "PaddlePaddle/PaddleOCR-VL"
+
+# Device configuration
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+logger.info(f"Using device: {DEVICE}")
+
+# Task prompts
+TASK_PROMPTS = {
+    "ocr": "OCR:",
+    "table": "Table Recognition:",
+    "formula": "Formula Recognition:",
+    "chart": "Chart Recognition:",
+}
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="PaddleOCR-VL Full Pipeline Server",
+    description="Document parsing with PP-DocLayoutV2 + PaddleOCR-VL (transformers)",
+    version="1.0.0"
+)
+
+# Global model instances
+vl_model = None
+vl_processor = None
+layout_model = None
+
+
+def load_vl_model():
+    """Load the PaddleOCR-VL model for element recognition"""
+    global vl_model, vl_processor
+
+    if vl_model is not None:
+        return
+
+    logger.info(f"Loading PaddleOCR-VL model: {MODEL_NAME}")
+    from transformers import AutoModelForCausalLM, AutoProcessor
+
+    vl_processor = AutoProcessor.from_pretrained(MODEL_NAME, trust_remote_code=True)
+
+    if DEVICE == "cuda":
+        vl_model = AutoModelForCausalLM.from_pretrained(
+            MODEL_NAME,
+            trust_remote_code=True,
+            torch_dtype=torch.bfloat16,
+        ).to(DEVICE).eval()
+    else:
+        vl_model = AutoModelForCausalLM.from_pretrained(
+            MODEL_NAME,
+            trust_remote_code=True,
+            torch_dtype=torch.float32,
+            low_cpu_mem_usage=True,
+        ).eval()
+
+    logger.info("PaddleOCR-VL model loaded successfully")
+
+
+def load_layout_model():
+    """Load the LayoutDetection model for layout detection"""
+    global layout_model
+
+    if layout_model is not None:
+        return
+
+    try:
+        logger.info("Loading LayoutDetection model (PP-DocLayout_plus-L)...")
+        from paddleocr import LayoutDetection
+
+        layout_model = LayoutDetection()
+        logger.info("LayoutDetection model loaded successfully")
+    except Exception as e:
+        logger.warning(f"Could not load LayoutDetection: {e}")
+        logger.info("Falling back to VL-only mode (no layout detection)")
+
+
+def recognize_element(image: Image.Image, task: str = "ocr") -> str:
+    """Recognize a single element using PaddleOCR-VL"""
+    load_vl_model()
+
+    prompt = TASK_PROMPTS.get(task, TASK_PROMPTS["ocr"])
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "image", "image": image},
+                {"type": "text", "text": prompt},
+            ]
+        }
+    ]
+
+    inputs = vl_processor.apply_chat_template(
+        messages,
+        tokenize=True,
+        add_generation_prompt=True,
+        return_dict=True,
+        return_tensors="pt"
+    )
+
+    if DEVICE == "cuda":
+        inputs = {k: v.to(DEVICE) for k, v in inputs.items()}
+
+    with torch.inference_mode():
+        outputs = vl_model.generate(
+            **inputs,
+            max_new_tokens=4096,
+            do_sample=False,
+            use_cache=True
+        )
+
+    response = vl_processor.batch_decode(outputs, skip_special_tokens=True)[0]
+
+    # Extract only the assistant's response content
+    # The response format is: "User: <prompt>\nAssistant: <content>"
+    # We want to extract just the content after "Assistant:"
+    if "Assistant:" in response:
+        parts = response.split("Assistant:")
+        if len(parts) > 1:
+            response = parts[-1].strip()
+    elif "assistant:" in response.lower():
+        # Case-insensitive fallback
+        import re
+        match = re.split(r'[Aa]ssistant:', response)
+        if len(match) > 1:
+            response = match[-1].strip()
+
+    return response
+
+
+def detect_layout(image: Image.Image) -> List[dict]:
+    """Detect layout regions in the image"""
+    load_layout_model()
+
+    if layout_model is None:
+        # No layout model - return a single region covering the whole image
+        return [{
+            "type": "text",
+            "bbox": [0, 0, image.width, image.height],
+            "score": 1.0
+        }]
+
+    # Save image to temp file
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
+        image.save(tmp.name, "PNG")
+        tmp_path = tmp.name
+
+    try:
+        results = layout_model.predict(tmp_path)
+        regions = []
+
+        for res in results:
+            # LayoutDetection returns boxes in 'boxes' key
+            for box in res.get("boxes", []):
+                coord = box.get("coordinate", [0, 0, image.width, image.height])
+                # Convert numpy floats to regular floats
+                bbox = [float(c) for c in coord]
+                regions.append({
+                    "type": box.get("label", "text"),
+                    "bbox": bbox,
+                    "score": float(box.get("score", 1.0))
+                })
+
+        # Sort regions by vertical position (top to bottom)
+        regions.sort(key=lambda r: r["bbox"][1])
+
+        return regions if regions else [{
+            "type": "text",
+            "bbox": [0, 0, image.width, image.height],
+            "score": 1.0
+        }]
+
+    finally:
+        os.unlink(tmp_path)
+
+
+def process_document(image: Image.Image) -> dict:
+    """Process a document through the full pipeline"""
+    logger.info(f"Processing document: {image.size}")
+
+    # Step 1: Detect layout
+    regions = detect_layout(image)
+    logger.info(f"Detected {len(regions)} layout regions")
+
+    # Step 2: Recognize each region
+    blocks = []
+    for i, region in enumerate(regions):
+        region_type = region["type"].lower()
+        bbox = region["bbox"]
+
+        # Crop region from image
+        x1, y1, x2, y2 = [int(c) for c in bbox]
+        region_image = image.crop((x1, y1, x2, y2))
+
+        # Determine task based on region type
+        if "table" in region_type:
+            task = "table"
+        elif "formula" in region_type or "math" in region_type:
+            task = "formula"
+        elif "chart" in region_type or "figure" in region_type:
+            task = "chart"
+        else:
+            task = "ocr"
+
+        # Recognize the region
+        try:
+            content = recognize_element(region_image, task)
+            blocks.append({
+                "index": i,
+                "type": region_type,
+                "bbox": bbox,
+                "content": content,
+                "task": task
+            })
+            logger.info(f"  Region {i} ({region_type}): {len(content)} chars")
+        except Exception as e:
+            logger.error(f"  Region {i} error: {e}")
+            blocks.append({
+                "index": i,
+                "type": region_type,
+                "bbox": bbox,
+                "content": "",
+                "error": str(e)
+            })
+
+    return {"blocks": blocks, "image_size": list(image.size)}
+
+
+def result_to_markdown(result: dict) -> str:
+    """Convert result to Markdown format"""
+    lines = []
+
+    for block in result.get("blocks", []):
+        block_type = block.get("type", "text")
+        content = block.get("content", "")
+
+        if "table" in block_type.lower():
+            lines.append(f"\n{content}\n")
+        elif "formula" in block_type.lower():
+            lines.append(f"\n$$\n{content}\n$$\n")
+        else:
+            lines.append(content)
+
+    return "\n\n".join(lines)
+
+
+# Request/Response models
+class ParseRequest(BaseModel):
+    image: str  # base64 encoded image
+    output_format: Optional[str] = "json"
+
+
+class ParseResponse(BaseModel):
+    success: bool
+    format: str
+    result: Union[dict, str]
+    processing_time: float
+    error: Optional[str] = None
+
+
+def decode_image(image_source: str) -> Image.Image:
+    """Decode image from base64 or data URL"""
+    if image_source.startswith("data:"):
+        header, data = image_source.split(",", 1)
+        image_data = base64.b64decode(data)
+    else:
+        image_data = base64.b64decode(image_source)
+
+    return Image.open(io.BytesIO(image_data)).convert("RGB")
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Pre-load models on startup"""
+    logger.info("Starting PaddleOCR-VL Full Pipeline Server...")
+    try:
+        load_vl_model()
+        load_layout_model()
+        logger.info("Models loaded successfully")
+    except Exception as e:
+        logger.error(f"Failed to pre-load models: {e}")
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy" if vl_model is not None else "loading",
+        "service": "PaddleOCR-VL Full Pipeline (Transformers)",
+        "device": DEVICE,
+        "vl_model_loaded": vl_model is not None,
+        "layout_model_loaded": layout_model is not None
+    }
+
+
+@app.get("/formats")
+async def supported_formats():
+    """List supported output formats"""
+    return {
+        "output_formats": ["json", "markdown"],
+        "image_formats": ["PNG", "JPEG", "WebP", "BMP", "GIF", "TIFF"],
+        "capabilities": [
+            "Layout detection (PP-DocLayoutV2)",
+            "Text recognition (OCR)",
+            "Table recognition",
+            "Formula recognition (LaTeX)",
+            "Chart recognition",
+            "Multi-language support (109 languages)"
+        ]
+    }
+
+
+@app.post("/parse", response_model=ParseResponse)
+async def parse_document_endpoint(request: ParseRequest):
+    """Parse a document image and return structured output"""
+    try:
+        start_time = time.time()
+
+        image = decode_image(request.image)
+        result = process_document(image)
+
+        if request.output_format == "markdown":
+            markdown = result_to_markdown(result)
+            output = {"markdown": markdown}
+        else:
+            output = result
+
+        elapsed = time.time() - start_time
+        logger.info(f"Processing complete in {elapsed:.2f}s")
+
+        return ParseResponse(
+            success=True,
+            format=request.output_format,
+            result=output,
+            processing_time=elapsed
+        )
+
+    except Exception as e:
+        logger.error(f"Error processing document: {e}", exc_info=True)
+        return ParseResponse(
+            success=False,
+            format=request.output_format,
+            result={},
+            processing_time=0,
+            error=str(e)
+        )
+
+
+@app.post("/v1/chat/completions")
+async def chat_completions(request: dict):
+    """OpenAI-compatible chat completions endpoint"""
+    try:
+        messages = request.get("messages", [])
+        output_format = request.get("output_format", "json")
+
+        # Find user message with image
+        image = None
+        for msg in reversed(messages):
+            if msg.get("role") == "user":
+                content = msg.get("content", [])
+                if isinstance(content, list):
+                    for item in content:
+                        if item.get("type") == "image_url":
+                            url = item.get("image_url", {}).get("url", "")
+                            image = decode_image(url)
+                            break
+                break
+
+        if image is None:
+            raise HTTPException(status_code=400, detail="No image provided")
+
+        start_time = time.time()
+        result = process_document(image)
+
+        if output_format == "markdown":
+            content = result_to_markdown(result)
+        else:
+            content = json.dumps(result, ensure_ascii=False, indent=2)
+
+        elapsed = time.time() - start_time
+
+        return {
+            "id": f"chatcmpl-{int(time.time()*1000)}",
+            "object": "chat.completion",
+            "created": int(time.time()),
+            "model": "paddleocr-vl-full",
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": content},
+                "finish_reason": "stop"
+            }],
+            "usage": {
+                "prompt_tokens": 100,
+                "completion_tokens": len(content) // 4,
+                "total_tokens": 100 + len(content) // 4
+            },
+            "processing_time": elapsed
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error in chat completions: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host=SERVER_HOST, port=SERVER_PORT)

image_support_files/paddleocr_vl_server.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+PaddleOCR-VL FastAPI Server (CPU variant)
+Provides OpenAI-compatible REST API for document parsing using PaddleOCR-VL
+"""
+
+import os
+import io
+import base64
+import logging
+import time
+from typing import Optional, List, Any, Dict, Union
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+import torch
+from PIL import Image
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Environment configuration
+SERVER_HOST = os.environ.get('SERVER_HOST', '0.0.0.0')
+SERVER_PORT = int(os.environ.get('SERVER_PORT', '8000'))
+MODEL_NAME = os.environ.get('MODEL_NAME', 'PaddlePaddle/PaddleOCR-VL')
+
+# Device configuration
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+logger.info(f"Using device: {DEVICE}")
+
+# Task prompts for PaddleOCR-VL
+TASK_PROMPTS = {
+    "ocr": "OCR:",
+    "table": "Table Recognition:",
+    "formula": "Formula Recognition:",
+    "chart": "Chart Recognition:",
+}
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="PaddleOCR-VL Server",
+    description="OpenAI-compatible REST API for document parsing using PaddleOCR-VL",
+    version="1.0.0"
+)
+
+# Global model instances
+model = None
+processor = None
+
+
+# Request/Response models (OpenAI-compatible)
+class ImageUrl(BaseModel):
+    url: str
+
+
+class ContentItem(BaseModel):
+    type: str
+    text: Optional[str] = None
+    image_url: Optional[ImageUrl] = None
+
+
+class Message(BaseModel):
+    role: str
+    content: Union[str, List[ContentItem]]
+
+
+class ChatCompletionRequest(BaseModel):
+    model: str = "paddleocr-vl"
+    messages: List[Message]
+    temperature: Optional[float] = 0.0
+    max_tokens: Optional[int] = 4096
+
+
+class Choice(BaseModel):
+    index: int
+    message: Message
+    finish_reason: str
+
+
+class Usage(BaseModel):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class ChatCompletionResponse(BaseModel):
+    id: str
+    object: str = "chat.completion"
+    created: int
+    model: str
+    choices: List[Choice]
+    usage: Usage
+
+
+class HealthResponse(BaseModel):
+    status: str
+    model: str
+    device: str
+
+
+def load_model():
+    """Load the PaddleOCR-VL model and processor"""
+    global model, processor
+
+    if model is not None:
+        return
+
+    logger.info(f"Loading PaddleOCR-VL model: {MODEL_NAME}")
+
+    from transformers import AutoModelForCausalLM, AutoProcessor
+
+    # Load processor
+    processor = AutoProcessor.from_pretrained(MODEL_NAME, trust_remote_code=True)
+
+    # Load model with appropriate settings for CPU/GPU
+    if DEVICE == "cuda":
+        model = AutoModelForCausalLM.from_pretrained(
+            MODEL_NAME,
+            trust_remote_code=True,
+            torch_dtype=torch.bfloat16,
+        ).to(DEVICE).eval()
+    else:
+        # CPU mode - use float32 for compatibility
+        model = AutoModelForCausalLM.from_pretrained(
+            MODEL_NAME,
+            trust_remote_code=True,
+            torch_dtype=torch.float32,
+            low_cpu_mem_usage=True,
+        ).eval()
+
+    logger.info("PaddleOCR-VL model loaded successfully")
+
+
+def optimize_image_resolution(image: Image.Image, max_size: int = 2048, min_size: int = 1080) -> Image.Image:
+    """
+    Optimize image resolution for PaddleOCR-VL.
+
+    Best results are achieved with images in the 1080p-2K range.
+    - Images larger than max_size are scaled down
+    - Very small images are scaled up to min_size
+    """
+    width, height = image.size
+    max_dim = max(width, height)
+    min_dim = min(width, height)
+
+    # Scale down if too large (4K+ images often miss text)
+    if max_dim > max_size:
+        scale = max_size / max_dim
+        new_width = int(width * scale)
+        new_height = int(height * scale)
+        logger.info(f"Scaling down image from {width}x{height} to {new_width}x{new_height}")
+        image = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    # Scale up if too small
+    elif max_dim < min_size and min_dim < min_size:
+        scale = min_size / max_dim
+        new_width = int(width * scale)
+        new_height = int(height * scale)
+        logger.info(f"Scaling up image from {width}x{height} to {new_width}x{new_height}")
+        image = image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    else:
+        logger.info(f"Image size {width}x{height} is optimal, no scaling needed")
+
+    return image
+
+
+def decode_image(image_source: str, optimize: bool = True) -> Image.Image:
+    """
+    Decode image from various sources.
+
+    Supported formats:
+    - Base64 data URL: data:image/png;base64,... or data:image/jpeg;base64,...
+    - HTTP/HTTPS URL: https://example.com/image.png
+    - Raw base64 string
+    - Local file path
+
+    Supported image types: PNG, JPEG, WebP, BMP, GIF, TIFF
+    """
+    image = None
+
+    if image_source.startswith("data:"):
+        # Base64 encoded image with MIME type header
+        # Supports: data:image/png;base64,... data:image/jpeg;base64,... etc.
+        header, data = image_source.split(",", 1)
+        image_data = base64.b64decode(data)
+        image = Image.open(io.BytesIO(image_data)).convert("RGB")
+        logger.debug(f"Decoded base64 image with header: {header}")
+    elif image_source.startswith("http://") or image_source.startswith("https://"):
+        # URL - fetch image
+        import httpx
+        response = httpx.get(image_source, timeout=30.0)
+        response.raise_for_status()
+        image = Image.open(io.BytesIO(response.content)).convert("RGB")
+        logger.debug(f"Fetched image from URL: {image_source[:50]}...")
+    else:
+        # Assume it's a file path or raw base64
+        try:
+            image_data = base64.b64decode(image_source)
+            image = Image.open(io.BytesIO(image_data)).convert("RGB")
+            logger.debug("Decoded raw base64 image")
+        except:
+            # Try as file path
+            image = Image.open(image_source).convert("RGB")
+            logger.debug(f"Loaded image from file: {image_source}")
+
+    # Optimize resolution for best OCR results
+    if optimize:
+        image = optimize_image_resolution(image)
+
+    return image
+
+
+def extract_image_and_text(content: Union[str, List[ContentItem]]) -> tuple:
+    """Extract image and text prompt from message content"""
+    if isinstance(content, str):
+        return None, content
+
+    image = None
+    text = ""
+
+    for item in content:
+        if item.type == "image_url" and item.image_url:
+            image = decode_image(item.image_url.url)
+        elif item.type == "text" and item.text:
+            text = item.text
+
+    return image, text
+
+
+def generate_response(image: Image.Image, prompt: str, max_tokens: int = 4096) -> str:
+    """Generate response using PaddleOCR-VL"""
+    load_model()
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "image", "image": image},
+                {"type": "text", "text": prompt},
+            ]
+        }
+    ]
+
+    inputs = processor.apply_chat_template(
+        messages,
+        tokenize=True,
+        add_generation_prompt=True,
+        return_dict=True,
+        return_tensors="pt"
+    )
+
+    if DEVICE == "cuda":
+        inputs = {k: v.to(DEVICE) for k, v in inputs.items()}
+
+    with torch.inference_mode():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=max_tokens,
+            do_sample=False,
+            use_cache=True
+        )
+
+    response = processor.batch_decode(outputs, skip_special_tokens=True)[0]
+
+    # Extract the assistant's response (after the prompt)
+    if "assistant" in response.lower():
+        parts = response.split("assistant")
+        if len(parts) > 1:
+            response = parts[-1].strip()
+
+    return response
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Pre-load the model on startup"""
+    logger.info("Pre-loading PaddleOCR-VL model...")
+    try:
+        load_model()
+        logger.info("Model pre-loaded successfully")
+    except Exception as e:
+        logger.error(f"Failed to pre-load model: {e}")
+        # Don't fail startup - model will be loaded on first request
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Health check endpoint"""
+    return HealthResponse(
+        status="healthy" if model is not None else "loading",
+        model=MODEL_NAME,
+        device=DEVICE
+    )
+
+
+@app.get("/formats")
+async def supported_formats():
+    """List supported image formats and input methods"""
+    return {
+        "image_formats": {
+            "supported": ["PNG", "JPEG", "WebP", "BMP", "GIF", "TIFF"],
+            "recommended": ["PNG", "JPEG"],
+            "mime_types": [
+                "image/png",
+                "image/jpeg",
+                "image/webp",
+                "image/bmp",
+                "image/gif",
+                "image/tiff"
+            ]
+        },
+        "input_methods": {
+            "base64_data_url": {
+                "description": "Base64 encoded image with MIME type header",
+                "example": "data:image/png;base64,iVBORw0KGgo..."
+            },
+            "http_url": {
+                "description": "Direct HTTP/HTTPS URL to image",
+                "example": "https://example.com/image.png"
+            },
+            "raw_base64": {
+                "description": "Raw base64 string without header",
+                "example": "iVBORw0KGgo..."
+            }
+        },
+        "resolution": {
+            "optimal_range": "1080p to 2K (1080-2048 pixels on longest side)",
+            "auto_scaling": True,
+            "note": "Images are automatically scaled to optimal range. 4K+ images are scaled down for better accuracy."
+        },
+        "task_prompts": TASK_PROMPTS
+    }
+
+
+@app.get("/v1/models")
+async def list_models():
+    """List available models (OpenAI-compatible)"""
+    return {
+        "object": "list",
+        "data": [
+            {
+                "id": "paddleocr-vl",
+                "object": "model",
+                "created": int(time.time()),
+                "owned_by": "paddlepaddle"
+            }
+        ]
+    }
+
+
+@app.post("/v1/chat/completions", response_model=ChatCompletionResponse)
+async def chat_completions(request: ChatCompletionRequest):
+    """
+    OpenAI-compatible chat completions endpoint for PaddleOCR-VL
+
+    Supports tasks:
+    - "OCR:" - Text recognition
+    - "Table Recognition:" - Table extraction
+    - "Formula Recognition:" - Formula extraction
+    - "Chart Recognition:" - Chart extraction
+    """
+    try:
+        # Get the last user message
+        user_message = None
+        for msg in reversed(request.messages):
+            if msg.role == "user":
+                user_message = msg
+                break
+
+        if not user_message:
+            raise HTTPException(status_code=400, detail="No user message found")
+
+        # Extract image and prompt
+        image, prompt = extract_image_and_text(user_message.content)
+
+        if image is None:
+            raise HTTPException(status_code=400, detail="No image provided in message")
+
+        # Default to OCR if no specific prompt
+        if not prompt or prompt.strip() == "":
+            prompt = "OCR:"
+
+        logger.info(f"Processing request with prompt: {prompt[:50]}...")
+
+        # Generate response
+        start_time = time.time()
+        response_text = generate_response(image, prompt, request.max_tokens or 4096)
+        elapsed = time.time() - start_time
+
+        logger.info(f"Generated response in {elapsed:.2f}s ({len(response_text)} chars)")
+
+        # Build OpenAI-compatible response
+        return ChatCompletionResponse(
+            id=f"chatcmpl-{int(time.time()*1000)}",
+            created=int(time.time()),
+            model=request.model,
+            choices=[
+                Choice(
+                    index=0,
+                    message=Message(role="assistant", content=response_text),
+                    finish_reason="stop"
+                )
+            ],
+            usage=Usage(
+                prompt_tokens=100,  # Approximate
+                completion_tokens=len(response_text) // 4,
+                total_tokens=100 + len(response_text) // 4
+            )
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error processing request: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# Legacy endpoint for compatibility with old PaddleOCR API
+class LegacyOCRRequest(BaseModel):
+    image: str
+    task: Optional[str] = "ocr"
+
+
+class LegacyOCRResponse(BaseModel):
+    success: bool
+    result: str
+    task: str
+    error: Optional[str] = None
+
+
+@app.post("/ocr", response_model=LegacyOCRResponse)
+async def legacy_ocr(request: LegacyOCRRequest):
+    """
+    Legacy OCR endpoint for backwards compatibility
+
+    Tasks: ocr, table, formula, chart
+    """
+    try:
+        image = decode_image(request.image)
+        prompt = TASK_PROMPTS.get(request.task, TASK_PROMPTS["ocr"])
+
+        result = generate_response(image, prompt)
+
+        return LegacyOCRResponse(
+            success=True,
+            result=result,
+            task=request.task
+        )
+    except Exception as e:
+        logger.error(f"Legacy OCR error: {e}")
+        return LegacyOCRResponse(
+            success=False,
+            result="",
+            task=request.task,
+            error=str(e)
+        )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host=SERVER_HOST, port=SERVER_PORT)

npmextra.json

@@ -1,7 +1,10 @@
 {
   "npmci": {
     "npmGlobalTools": [],
-    "npmAccessLevel": "public"
+    "npmAccessLevel": "public",
+    "dockerRegistries": [
+      "code.foss.global"
+    ]
   },
   "gitzone": {
     "projectType": "docker",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@host.today/ht-docker-ai",
-  "version": "1.1.0",
+  "version": "1.7.1",
   "type": "module",
   "private": false,
   "description": "Docker images for AI vision-language models including MiniCPM-V 4.5",
@@ -13,8 +13,8 @@
     "test": "tstest test/ --verbose"
   },
   "devDependencies": {
-    "@git.zone/tstest": "^1.0.90",
+    "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tsrun": "^1.3.3"
+    "@git.zone/tstest": "^1.0.90"
   },
   "repository": {
     "type": "git",
@@ -28,5 +28,8 @@
     "minicpm",
     "ollama",
     "multimodal"
-  ]
+  ],
+  "dependencies": {
+    "@types/node": "^25.0.9"
+  }
 }

pnpm-lock.yaml

@@ -7,6 +7,10 @@ settings:
 importers:
 
   .:
+    dependencies:
+      '@types/node':
+        specifier: ^25.0.9
+        version: 25.0.9
     devDependencies:
       '@git.zone/tsrun':
         specifier: ^1.3.3

readme.hints.md

@@ -77,6 +77,95 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
 
 CPU variant has longer `start-period` (120s) due to slower startup.
 
+## PaddleOCR-VL (Recommended)
+
+### Overview
+
+PaddleOCR-VL is a 0.9B parameter Vision-Language Model specifically optimized for document parsing. It replaces the older PP-Structure approach with native VLM understanding.
+
+**Key advantages over PP-Structure:**
+- Native table understanding (no HTML parsing needed)
+- 109 language support
+- Better handling of complex multi-row tables
+- Structured Markdown/JSON output
+
+### Docker Images
+
+| Tag | Description |
+|-----|-------------|
+| `paddleocr-vl` | GPU variant using vLLM (recommended) |
+| `paddleocr-vl-cpu` | CPU variant using transformers |
+
+### API Endpoints (OpenAI-compatible)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check with model info |
+| `/v1/models` | GET | List available models |
+| `/v1/chat/completions` | POST | OpenAI-compatible chat completions |
+| `/ocr` | POST | Legacy OCR endpoint |
+
+### Request/Response Format
+
+**POST /v1/chat/completions (OpenAI-compatible)**
+```json
+{
+  "model": "paddleocr-vl",
+  "messages": [
+    {
+      "role": "user",
+      "content": [
+        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
+        {"type": "text", "text": "Table Recognition:"}
+      ]
+    }
+  ],
+  "temperature": 0.0,
+  "max_tokens": 8192
+}
+```
+
+**Task Prompts:**
+- `"OCR:"` - Text recognition
+- `"Table Recognition:"` - Table extraction (returns markdown)
+- `"Formula Recognition:"` - Formula extraction
+- `"Chart Recognition:"` - Chart extraction
+
+**Response**
+```json
+{
+  "id": "chatcmpl-...",
+  "object": "chat.completion",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "| Date | Description | Amount |\n|---|---|---|\n| 2021-06-01 | GITLAB INC | -119.96 |"
+      },
+      "finish_reason": "stop"
+    }
+  ]
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODEL_NAME` | `PaddlePaddle/PaddleOCR-VL` | Model to load |
+| `HOST` | `0.0.0.0` | Server host |
+| `PORT` | `8000` | Server port |
+| `MAX_BATCHED_TOKENS` | `16384` | vLLM max batch tokens |
+| `GPU_MEMORY_UTILIZATION` | `0.9` | GPU memory usage (0-1) |
+
+### Performance
+
+- **GPU (vLLM)**: ~2-5 seconds per page
+- **CPU**: ~30-60 seconds per page
+
+---
+
 ## Adding New Models
 
 To add a new model variant:
@@ -118,6 +207,43 @@ npmci docker build
 npmci docker push code.foss.global
 ```
 
+## Multi-Pass Extraction Strategy
+
+The bank statement extraction uses a dual-VLM consensus approach:
+
+### Architecture: Dual-VLM Consensus
+
+| VLM | Model | Purpose |
+|-----|-------|---------|
+| **MiniCPM-V 4.5** | 8B params | Primary visual extraction |
+| **PaddleOCR-VL** | 0.9B params | Table-specialized extraction |
+
+### Extraction Strategy
+
+1. **Pass 1**: MiniCPM-V visual extraction (images → JSON)
+2. **Pass 2**: PaddleOCR-VL table recognition (images → markdown → JSON)
+3. **Consensus**: If Pass 1 == Pass 2 → Done (fast path)
+4. **Pass 3+**: MiniCPM-V visual if no consensus
+
+### Why Dual-VLM Works
+
+- **Different architectures**: Two independent models cross-check each other
+- **Specialized strengths**: PaddleOCR-VL optimized for tables, MiniCPM-V for general vision
+- **No structure loss**: Both VLMs see the original images directly
+- **Fast consensus**: Most documents complete in 2 passes when VLMs agree
+
+### Comparison vs Old PP-Structure Approach
+
+| Approach | Bank Statement Result | Issue |
+|----------|----------------------|-------|
+| MiniCPM-V Visual | 28 transactions ✓ | - |
+| PP-Structure HTML + Visual | 13 transactions ✗ | HTML merged rows incorrectly |
+| PaddleOCR-VL Table | 28 transactions ✓ | Native table understanding |
+
+**Key insight**: PP-Structure's HTML output loses structure for complex tables. PaddleOCR-VL's native VLM approach maintains table integrity.
+
+---
+
 ## Related Resources
 
 - [Ollama Documentation](https://ollama.ai/docs)

recipes/document.md

@@ -1,129 +1,250 @@
-# Bank Statement Parsing with MiniCPM-V 4.5
+# Document Recognition with Hybrid OCR + Vision AI
 
-Recipe for extracting transactions from bank statement PDFs using vision-language AI.
+Recipe for extracting structured data from invoices and documents using a hybrid approach:
+PaddleOCR for text extraction + MiniCPM-V 4.5 for intelligent parsing.
 
-## Model
+## Architecture
 
-- **Model**: MiniCPM-V 4.5 (8B parameters)
+```
-- **Ollama Name**: `openbmb/minicpm-v4.5:q8_0`
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
-- **Quantization**: Q8_0 (9.8GB VRAM)
+│  PDF/Image   │ ───> │  PaddleOCR   │ ───> │   Raw Text   │
-- **Runtime**: Ollama on GPU
+└──────────────┘      └──────────────┘      └──────┬───────┘
+                                                   │
+                      ┌──────────────┐             │
+                      │  MiniCPM-V   │ <───────────┘
+                      │   4.5 VLM    │ <─── Image
+                      └──────┬───────┘
+                             │
+                      ┌──────▼───────┐
+                      │ Structured   │
+                      │    JSON      │
+                      └──────────────┘
+```
+
+## Why Hybrid?
+
+| Approach | Accuracy | Speed | Best For |
+|----------|----------|-------|----------|
+| VLM Only | 85-90% | Fast | Simple layouts |
+| OCR Only | N/A | Fast | Just text extraction |
+| **Hybrid** | **91%+** | Medium | Complex invoices |
+
+The hybrid approach provides OCR text as context to the VLM, improving accuracy on:
+- Small text and numbers
+- Low contrast documents
+- Dense tables
+
+## Services
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| PaddleOCR | 5000 | Text extraction |
+| Ollama (MiniCPM-V) | 11434 | Intelligent parsing |
+
+## Running the Containers
+
+**Start both services:**
+
+```bash
+# PaddleOCR (CPU is sufficient for OCR)
+docker run -d --name paddleocr -p 5000:5000 \
+  code.foss.global/host.today/ht-docker-ai:paddleocr-cpu
+
+# MiniCPM-V 4.5 (GPU recommended)
+docker run -d --name minicpm --gpus all -p 11434:11434 \
+  -v ollama-data:/root/.ollama \
+  code.foss.global/host.today/ht-docker-ai:minicpm45v
+```
 
 ## Image Conversion
 
-Convert PDF to PNG at 300 DPI for optimal OCR accuracy.
+Convert PDF to PNG at 200 DPI:
 
 ```bash
-convert -density 300 -quality 100 input.pdf \
+convert -density 200 -quality 90 input.pdf \
   -background white -alpha remove \
-  output-%d.png
+  page-%d.png
 ```
 
-**Parameters:**
+## Step 1: Extract OCR Text
-- `-density 300`: 300 DPI resolution (critical for accuracy)
-- `-quality 100`: Maximum quality
-- `-background white -alpha remove`: Remove transparency
-- `output-%d.png`: Outputs page-0.png, page-1.png, etc.
 
-**Dependencies:**
+```typescript
-```bash
+async function extractOcrText(imageBase64: string): Promise<string> {
-apt-get install imagemagick
+  const response = await fetch('http://localhost:5000/ocr', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ image: imageBase64 }),
+  });
+
+  const data = await response.json();
+  if (data.success && data.results) {
+    return data.results.map((r: { text: string }) => r.text).join('\n');
+  }
+  return '';
+}
 ```
 
-## Prompt
+## Step 2: Build Enhanced Prompt
 
-```
+```typescript
-You are a bank statement parser. Extract EVERY transaction from the table.
+function buildPrompt(ocrText: string): string {
+  const base = `You are an invoice parser. Extract the following fields:
 
-Read the Amount column carefully:
+1. invoice_number: The invoice/receipt number
-- "- 21,47 €" means DEBIT, output as: -21.47
+2. invoice_date: Date in YYYY-MM-DD format
-- "+ 1.000,00 €" means CREDIT, output as: 1000.00
+3. vendor_name: Company that issued the invoice
-- European format: comma = decimal point
+4. currency: EUR, USD, etc.
+5. net_amount: Amount before tax (if shown)
+6. vat_amount: Tax/VAT amount (0 if reverse charge)
+7. total_amount: Final amount due
 
-For each row output: {"date":"YYYY-MM-DD","counterparty":"NAME","amount":-21.47}
+Return ONLY valid JSON:
+{"invoice_number":"XXX","invoice_date":"YYYY-MM-DD","vendor_name":"Company","currency":"EUR","net_amount":100.00,"vat_amount":19.00,"total_amount":119.00}`;
 
-Do not skip any rows. Return complete JSON array:
+  if (ocrText) {
+    return `${base}
+
+OCR text extracted from the invoice:
+---
+${ocrText}
+---
+
+Cross-reference the image with the OCR text above for accuracy.`;
+  }
+  return base;
+}
 ```
 
-## API Call
+## Step 3: Call Vision-Language Model
 
-```python
+```typescript
-import base64
+async function extractInvoice(images: string[], ocrText: string): Promise<Invoice> {
-import requests
+  const payload = {
+    model: 'openbmb/minicpm-v4.5:q8_0',
+    prompt: buildPrompt(ocrText),
+    images,  // Base64 encoded
+    stream: false,
+    options: {
+      num_predict: 2048,
+      temperature: 0.1,
+    },
+  };
 
-# Load images
+  const response = await fetch('http://localhost:11434/api/generate', {
-with open('page-0.png', 'rb') as f:
+    method: 'POST',
-    page0 = base64.b64encode(f.read()).decode('utf-8')
+    headers: { 'Content-Type': 'application/json' },
-with open('page-1.png', 'rb') as f:
+    body: JSON.stringify(payload),
-    page1 = base64.b64encode(f.read()).decode('utf-8')
+  });
 
-payload = {
+  const result = await response.json();
-    "model": "openbmb/minicpm-v4.5:q8_0",
+  return JSON.parse(result.response);
-    "prompt": prompt,
+}
-    "images": [page0, page1],  # Multiple pages supported
+```
-    "stream": False,
+
-    "options": {
+## Consensus Voting
-        "num_predict": 16384,
+
-        "temperature": 0.1
+For production reliability, run multiple extraction passes and require consensus:
+
+```typescript
+async function extractWithConsensus(images: string[], maxPasses: number = 5): Promise<Invoice> {
+  const results: Map<string, { invoice: Invoice; count: number }> = new Map();
+
+  // Optimization: Run Pass 1 (no OCR) parallel with OCR + Pass 2
+  const [pass1Result, ocrText] = await Promise.all([
+    extractInvoice(images, ''),
+    extractOcrText(images[0]),
+  ]);
+
+  // Add Pass 1 result
+  addResult(results, pass1Result);
+
+  // Pass 2 with OCR context
+  const pass2Result = await extractInvoice(images, ocrText);
+  addResult(results, pass2Result);
+
+  // Check for consensus (2 matching results)
+  for (const [hash, data] of results) {
+    if (data.count >= 2) {
+      return data.invoice;  // Consensus reached!
     }
+  }
+
+  // Continue until consensus or max passes
+  for (let pass = 3; pass <= maxPasses; pass++) {
+    const result = await extractInvoice(images, ocrText);
+    addResult(results, result);
+    // Check consensus...
+  }
+
+  // Return most common result
+  return getMostCommon(results);
 }
 
-response = requests.post(
+function hashInvoice(inv: Invoice): string {
-    'http://localhost:11434/api/generate',
+  return `${inv.invoice_number}|${inv.invoice_date}|${inv.total_amount.toFixed(2)}`;
-    json=payload,
+}
-    timeout=600
-)
-
-result = response.json()['response']
 ```
 
 ## Output Format
 
 ```json
-[
+{
-  {"date":"2022-04-01","counterparty":"DIGITALOCEAN.COM","amount":-21.47},
+  "invoice_number": "INV-2024-001234",
-  {"date":"2022-04-01","counterparty":"DIGITALOCEAN.COM","amount":-58.06},
+  "invoice_date": "2024-08-15",
-  {"date":"2022-04-12","counterparty":"LOSSLESS GMBH","amount":1000.00}
+  "vendor_name": "Hetzner Online GmbH",
-]
+  "currency": "EUR",
+  "net_amount": 167.52,
+  "vat_amount": 31.83,
+  "total_amount": 199.35
+}
 ```
 
-## Running the Container
-
-**GPU (recommended):**
-```bash
-docker run -d --gpus all -p 11434:11434 \
-  -v ollama-data:/root/.ollama \
-  -e MODEL_NAME="openbmb/minicpm-v4.5:q8_0" \
-  ht-docker-ai:minicpm45v
-```
-
-**CPU (slower):**
-```bash
-docker run -d -p 11434:11434 \
-  -v ollama-data:/root/.ollama \
-  -e MODEL_NAME="openbmb/minicpm-v4.5:q4_0" \
-  ht-docker-ai:minicpm45v-cpu
-```
-
-## Hardware Requirements
-
-| Quantization | VRAM/RAM | Speed |
-|--------------|----------|-------|
-| Q8_0 (GPU)   | 10GB     | Fast  |
-| Q4_0 (CPU)   | 8GB      | Slow  |
-
 ## Test Results
 
-| Statement | Pages | Transactions | Accuracy |
+Tested on 46 real invoices from various vendors:
-|-----------|-------|--------------|----------|
+
-| bunq-2022-04 | 2 | 26 | 100% |
+| Metric | Value |
-| bunq-2021-06 | 3 | 28 | 100% |
+|--------|-------|
+| **Accuracy** | 91.3% (42/46) |
+| **Avg Time** | 42.7s per invoice |
+| **Consensus Rate** | 85% in 2 passes |
+
+### Per-Vendor Results
+
+| Vendor | Invoices | Accuracy |
+|--------|----------|----------|
+| Hetzner | 3 | 100% |
+| DigitalOcean | 4 | 100% |
+| Adobe | 3 | 100% |
+| Cloudflare | 1 | 100% |
+| Wasabi | 4 | 100% |
+| Figma | 3 | 100% |
+| Google Cloud | 1 | 100% |
+| MongoDB | 3 | 0% (date parsing) |
+
+## Hardware Requirements
+
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| PaddleOCR (CPU) | 4GB RAM | 8GB RAM |
+| MiniCPM-V (GPU) | 10GB VRAM | 12GB VRAM |
+| MiniCPM-V (CPU) | 16GB RAM | 32GB RAM |
 
 ## Tips
 
-1. **DPI matters**: 150 DPI causes missed rows; 300 DPI is optimal
+1. **Use hybrid approach**: OCR text dramatically improves number/date accuracy
-2. **PNG over JPEG**: PNG preserves text clarity better
+2. **Consensus voting**: Run 2-5 passes to catch hallucinations
-3. **Remove alpha**: Some models struggle with transparency
+3. **200 DPI is optimal**: Higher doesn't help, lower loses detail
-4. **Multi-page**: Pass all pages in single request for context
+4. **PNG over JPEG**: Preserves text clarity
 5. **Temperature 0.1**: Low temperature for consistent output
-6. **European format**: Explicitly explain comma=decimal in prompt
+6. **Multi-page support**: Pass all pages in single request for context
+7. **Normalize for comparison**: Ignore case/whitespace when comparing invoice numbers
+
+## Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Wrong date | Multiple dates on invoice | Be specific in prompt about which date |
+| Wrong currency | Symbol vs code mismatch | OCR helps disambiguate |
+| Missing digits | Low resolution | Increase density to 300 DPI |
+| Hallucinated data | VLM uncertainty | Use consensus voting |

test-images.sh

@@ -5,7 +5,8 @@ set -e
 REGISTRY="code.foss.global"
 NAMESPACE="host.today"
 IMAGE_NAME="ht-docker-ai"
-TEST_PORT=11434
+MINICPM_PORT=11434
+PADDLEOCR_PORT=5000
 
 # Colors for output
 GREEN='\033[0;32m'
@@ -17,11 +18,13 @@ cleanup() {
     echo -e "${BLUE}Cleaning up test containers...${NC}"
     docker rm -f test-minicpm-gpu 2>/dev/null || true
     docker rm -f test-minicpm-cpu 2>/dev/null || true
+    docker rm -f test-paddleocr-gpu 2>/dev/null || true
+    docker rm -f test-paddleocr-cpu 2>/dev/null || true
 }
 
 trap cleanup EXIT
 
-test_image() {
+test_minicpm_image() {
     local tag=$1
     local container_name=$2
     local extra_args=$3
@@ -31,7 +34,7 @@ test_image() {
     # Start container
     docker run -d \
         --name ${container_name} \
-        -p ${TEST_PORT}:11434 \
+        -p ${MINICPM_PORT}:11434 \
         ${extra_args} \
         ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:${tag}
 
@@ -41,7 +44,7 @@ test_image() {
 
     # Test API endpoint
     echo "Testing API endpoint..."
-    if curl -s -f http://localhost:${TEST_PORT}/api/tags > /dev/null; then
+    if curl -s -f http://localhost:${MINICPM_PORT}/api/tags > /dev/null; then
         echo -e "${GREEN}API endpoint responding!${NC}"
     else
         echo -e "${RED}API endpoint not responding!${NC}"
@@ -56,17 +59,85 @@ test_image() {
     echo ""
 }
 
+test_paddleocr_image() {
+    local tag=$1
+    local container_name=$2
+    local extra_args=$3
+
+    echo -e "${BLUE}Testing ${tag}...${NC}"
+
+    # Start container
+    docker run -d \
+        --name ${container_name} \
+        -p ${PADDLEOCR_PORT}:5000 \
+        ${extra_args} \
+        ${REGISTRY}/${NAMESPACE}/${IMAGE_NAME}:${tag}
+
+    # Wait for startup (PaddleOCR takes longer to initialize)
+    echo "Waiting for container to start..."
+    sleep 30
+
+    # Test health endpoint
+    echo "Testing health endpoint..."
+    if curl -s -f http://localhost:${PADDLEOCR_PORT}/health > /dev/null; then
+        echo -e "${GREEN}Health endpoint responding!${NC}"
+    else
+        echo -e "${RED}Health endpoint not responding!${NC}"
+        docker logs ${container_name}
+        return 1
+    fi
+
+    # Test OCR endpoint with a minimal base64 image (1x1 white pixel PNG)
+    echo "Testing OCR endpoint..."
+    local test_image="iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
+    local response=$(curl -s -X POST http://localhost:${PADDLEOCR_PORT}/ocr \
+        -H "Content-Type: application/json" \
+        -d "{\"image\": \"${test_image}\"}")
+
+    if echo "$response" | grep -q '"success"'; then
+        echo -e "${GREEN}OCR endpoint responding!${NC}"
+    else
+        echo -e "${RED}OCR endpoint not responding correctly!${NC}"
+        echo "Response: $response"
+        docker logs ${container_name}
+        return 1
+    fi
+
+    # Cleanup this container
+    docker rm -f ${container_name}
+
+    echo -e "${GREEN}${tag} test passed!${NC}"
+    echo ""
+}
+
 echo -e "${BLUE}=== Testing ht-docker-ai images ===${NC}"
 echo ""
 
-# Test CPU variant (doesn't require GPU)
+echo -e "${BLUE}--- MiniCPM-V Tests ---${NC}"
-test_image "minicpm45v-cpu" "test-minicpm-cpu" ""
+echo ""
 
-# Test GPU variant only if NVIDIA runtime is available
+# Test MiniCPM CPU variant (doesn't require GPU)
+test_minicpm_image "minicpm45v-cpu" "test-minicpm-cpu" ""
+
+# Test MiniCPM GPU variant only if NVIDIA runtime is available
 if docker info 2>/dev/null | grep -q "nvidia"; then
-    test_image "minicpm45v" "test-minicpm-gpu" "--gpus all"
+    test_minicpm_image "minicpm45v" "test-minicpm-gpu" "--gpus all"
 else
-    echo -e "${BLUE}Skipping GPU test (NVIDIA runtime not available)${NC}"
+    echo -e "${BLUE}Skipping MiniCPM GPU test (NVIDIA runtime not available)${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}--- PaddleOCR Tests ---${NC}"
+echo ""
+
+# Test PaddleOCR CPU variant (doesn't require GPU)
+test_paddleocr_image "paddleocr-cpu" "test-paddleocr-cpu" ""
+
+# Test PaddleOCR GPU variant only if NVIDIA runtime is available
+if docker info 2>/dev/null | grep -q "nvidia"; then
+    test_paddleocr_image "paddleocr" "test-paddleocr-gpu" "--gpus all"
+else
+    echo -e "${BLUE}Skipping PaddleOCR GPU test (NVIDIA runtime not available)${NC}"
 fi
 
 echo -e "${GREEN}=== All tests passed! ===${NC}"

test/helpers/docker.ts

@@ -0,0 +1,360 @@
+import { execSync } from 'child_process';
+
+// Project container names (only manage these)
+const PROJECT_CONTAINERS = [
+  'paddleocr-vl-test',
+  'paddleocr-vl-gpu-test',
+  'paddleocr-vl-cpu-test',
+  'paddleocr-vl-full-test',
+  'minicpm-test',
+];
+
+// Image configurations
+export interface IImageConfig {
+  name: string;
+  dockerfile: string;
+  buildContext: string;
+  containerName: string;
+  ports: string[];
+  volumes?: string[];
+  gpus?: boolean;
+  healthEndpoint?: string;
+  healthTimeout?: number;
+}
+
+export const IMAGES = {
+  paddleocrVlGpu: {
+    name: 'paddleocr-vl-gpu',
+    dockerfile: 'Dockerfile_paddleocr_vl_gpu',
+    buildContext: '.',
+    containerName: 'paddleocr-vl-test',
+    ports: ['8000:8000'],
+    volumes: ['ht-huggingface-cache:/root/.cache/huggingface'],
+    gpus: true,
+    healthEndpoint: 'http://localhost:8000/health',
+    healthTimeout: 300000, // 5 minutes for model loading
+  } as IImageConfig,
+
+  paddleocrVlCpu: {
+    name: 'paddleocr-vl-cpu',
+    dockerfile: 'Dockerfile_paddleocr_vl_cpu',
+    buildContext: '.',
+    containerName: 'paddleocr-vl-test',
+    ports: ['8000:8000'],
+    volumes: ['ht-huggingface-cache:/root/.cache/huggingface'],
+    gpus: false,
+    healthEndpoint: 'http://localhost:8000/health',
+    healthTimeout: 300000,
+  } as IImageConfig,
+
+  minicpm: {
+    name: 'minicpm45v',
+    dockerfile: 'Dockerfile_minicpm45v_gpu',
+    buildContext: '.',
+    containerName: 'minicpm-test',
+    ports: ['11434:11434'],
+    volumes: ['ht-ollama-models:/root/.ollama'],
+    gpus: true,
+    healthEndpoint: 'http://localhost:11434/api/tags',
+    healthTimeout: 120000,
+  } as IImageConfig,
+
+  // Full PaddleOCR-VL pipeline with PP-DocLayoutV2 + structured JSON output
+  paddleocrVlFull: {
+    name: 'paddleocr-vl-full',
+    dockerfile: 'Dockerfile_paddleocr_vl_full',
+    buildContext: '.',
+    containerName: 'paddleocr-vl-full-test',
+    ports: ['8000:8000'],
+    volumes: [
+      'ht-huggingface-cache:/root/.cache/huggingface',
+      'ht-paddleocr-cache:/root/.paddleocr',
+    ],
+    gpus: true,
+    healthEndpoint: 'http://localhost:8000/health',
+    healthTimeout: 600000, // 10 minutes for model loading (vLLM + PP-DocLayoutV2)
+  } as IImageConfig,
+};
+
+/**
+ * Execute a shell command and return output
+ */
+function exec(command: string, silent = false): string {
+  try {
+    return execSync(command, {
+      encoding: 'utf-8',
+      stdio: silent ? 'pipe' : 'inherit',
+    });
+  } catch (err: unknown) {
+    if (silent) return '';
+    throw err;
+  }
+}
+
+/**
+ * Check if a Docker image exists locally
+ */
+export function imageExists(imageName: string): boolean {
+  const result = exec(`docker images -q ${imageName}`, true);
+  return result.trim().length > 0;
+}
+
+/**
+ * Check if a container is running
+ */
+export function isContainerRunning(containerName: string): boolean {
+  const result = exec(`docker ps --filter "name=^${containerName}$" --format "{{.Names}}"`, true);
+  return result.trim() === containerName;
+}
+
+/**
+ * Check if a container exists (running or stopped)
+ */
+export function containerExists(containerName: string): boolean {
+  const result = exec(`docker ps -a --filter "name=^${containerName}$" --format "{{.Names}}"`, true);
+  return result.trim() === containerName;
+}
+
+/**
+ * Stop and remove a container
+ */
+export function removeContainer(containerName: string): void {
+  if (containerExists(containerName)) {
+    console.log(`[Docker] Removing container: ${containerName}`);
+    exec(`docker rm -f ${containerName}`, true);
+  }
+}
+
+/**
+ * Stop all project containers that conflict with the required one
+ */
+export function stopConflictingContainers(requiredContainer: string, requiredPort: string): void {
+  // Stop project containers using the same port
+  for (const container of PROJECT_CONTAINERS) {
+    if (container === requiredContainer) continue;
+
+    if (isContainerRunning(container)) {
+      // Check if this container uses the same port
+      const ports = exec(`docker port ${container} 2>/dev/null || true`, true);
+      if (ports.includes(requiredPort.split(':')[0])) {
+        console.log(`[Docker] Stopping conflicting container: ${container}`);
+        exec(`docker stop ${container}`, true);
+      }
+    }
+  }
+}
+
+/**
+ * Build a Docker image
+ */
+export function buildImage(config: IImageConfig): void {
+  console.log(`[Docker] Building image: ${config.name}`);
+  const cmd = `docker build --load -f ${config.dockerfile} -t ${config.name} ${config.buildContext}`;
+  exec(cmd);
+}
+
+/**
+ * Start a container from an image
+ */
+export function startContainer(config: IImageConfig): void {
+  // Remove existing container if it exists
+  removeContainer(config.containerName);
+
+  console.log(`[Docker] Starting container: ${config.containerName}`);
+
+  const portArgs = config.ports.map((p) => `-p ${p}`).join(' ');
+  const volumeArgs = config.volumes?.map((v) => `-v ${v}`).join(' ') || '';
+  const gpuArgs = config.gpus ? '--gpus all' : '';
+
+  const cmd = `docker run -d --name ${config.containerName} ${gpuArgs} ${portArgs} ${volumeArgs} ${config.name}`;
+  exec(cmd);
+}
+
+/**
+ * Wait for a container to become healthy
+ */
+export async function waitForHealth(
+  endpoint: string,
+  timeoutMs: number = 120000,
+  intervalMs: number = 5000
+): Promise<boolean> {
+  const startTime = Date.now();
+  console.log(`[Docker] Waiting for health: ${endpoint}`);
+
+  while (Date.now() - startTime < timeoutMs) {
+    try {
+      const response = await fetch(endpoint, {
+        method: 'GET',
+        signal: AbortSignal.timeout(5000),
+      });
+      if (response.ok) {
+        console.log(`[Docker] Service healthy!`);
+        return true;
+      }
+    } catch {
+      // Service not ready yet
+    }
+
+    const elapsed = Math.round((Date.now() - startTime) / 1000);
+    console.log(`[Docker] Waiting... (${elapsed}s)`);
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  console.log(`[Docker] Health check timeout after ${timeoutMs / 1000}s`);
+  return false;
+}
+
+/**
+ * Ensure a service is running and healthy
+ * - Builds image if missing
+ * - Stops conflicting project containers
+ * - Starts container if not running
+ * - Waits for health check
+ */
+export async function ensureService(config: IImageConfig): Promise<boolean> {
+  console.log(`\n[Docker] Ensuring service: ${config.name}`);
+
+  // Build image if it doesn't exist
+  if (!imageExists(config.name)) {
+    console.log(`[Docker] Image not found, building...`);
+    buildImage(config);
+  }
+
+  // Stop conflicting containers on the same port
+  const mainPort = config.ports[0];
+  stopConflictingContainers(config.containerName, mainPort);
+
+  // Start container if not running
+  if (!isContainerRunning(config.containerName)) {
+    startContainer(config);
+  } else {
+    console.log(`[Docker] Container already running: ${config.containerName}`);
+  }
+
+  // Wait for health
+  if (config.healthEndpoint) {
+    return waitForHealth(config.healthEndpoint, config.healthTimeout);
+  }
+
+  return true;
+}
+
+/**
+ * Ensure PaddleOCR-VL GPU service is running
+ */
+export async function ensurePaddleOcrVlGpu(): Promise<boolean> {
+  return ensureService(IMAGES.paddleocrVlGpu);
+}
+
+/**
+ * Ensure PaddleOCR-VL CPU service is running
+ */
+export async function ensurePaddleOcrVlCpu(): Promise<boolean> {
+  return ensureService(IMAGES.paddleocrVlCpu);
+}
+
+/**
+ * Ensure MiniCPM service is running
+ */
+export async function ensureMiniCpm(): Promise<boolean> {
+  return ensureService(IMAGES.minicpm);
+}
+
+/**
+ * Check if GPU is available
+ */
+export function isGpuAvailable(): boolean {
+  try {
+    const result = exec('nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null', true);
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure PaddleOCR-VL service (auto-detect GPU/CPU)
+ */
+export async function ensurePaddleOcrVl(): Promise<boolean> {
+  if (isGpuAvailable()) {
+    console.log('[Docker] GPU detected, using GPU image');
+    return ensurePaddleOcrVlGpu();
+  } else {
+    console.log('[Docker] No GPU detected, using CPU image');
+    return ensurePaddleOcrVlCpu();
+  }
+}
+
+/**
+ * Ensure PaddleOCR-VL Full Pipeline service (PP-DocLayoutV2 + structured output)
+ * This is the recommended service for production use - outputs structured JSON/Markdown
+ */
+export async function ensurePaddleOcrVlFull(): Promise<boolean> {
+  if (!isGpuAvailable()) {
+    console.log('[Docker] WARNING: Full pipeline requires GPU, but none detected');
+  }
+  return ensureService(IMAGES.paddleocrVlFull);
+}
+
+/**
+ * Ensure an Ollama model is pulled and available
+ * Uses the MiniCPM container (which runs Ollama) to pull the model
+ */
+export async function ensureOllamaModel(modelName: string): Promise<boolean> {
+  const OLLAMA_URL = 'http://localhost:11434';
+
+  console.log(`\n[Ollama] Ensuring model: ${modelName}`);
+
+  // Check if model exists
+  try {
+    const response = await fetch(`${OLLAMA_URL}/api/tags`);
+    if (response.ok) {
+      const data = await response.json();
+      const models = data.models || [];
+      const exists = models.some((m: { name: string }) =>
+        m.name === modelName || m.name.startsWith(modelName.split(':')[0])
+      );
+
+      if (exists) {
+        console.log(`[Ollama] Model already available: ${modelName}`);
+        return true;
+      }
+    }
+  } catch {
+    console.log(`[Ollama] Cannot check models, Ollama may not be running`);
+    return false;
+  }
+
+  // Pull the model
+  console.log(`[Ollama] Pulling model: ${modelName} (this may take a while)...`);
+  try {
+    const response = await fetch(`${OLLAMA_URL}/api/pull`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: modelName, stream: false }),
+    });
+
+    if (response.ok) {
+      console.log(`[Ollama] Model pulled successfully: ${modelName}`);
+      return true;
+    } else {
+      console.log(`[Ollama] Failed to pull model: ${response.status}`);
+      return false;
+    }
+  } catch (err) {
+    console.log(`[Ollama] Error pulling model: ${err}`);
+    return false;
+  }
+}
+
+/**
+ * Ensure Qwen2.5 7B model is available (for text-only JSON extraction)
+ */
+export async function ensureQwen25(): Promise<boolean> {
+  // First ensure the Ollama service (MiniCPM container) is running
+  const ollamaOk = await ensureMiniCpm();
+  if (!ollamaOk) return false;
+
+  // Then ensure the Qwen2.5 model is pulled
+  return ensureOllamaModel('qwen2.5:7b');
+}

test/test.bankstatements.combined.ts

@@ -0,0 +1,549 @@
+/**
+ * Bank statement extraction test using MiniCPM-V (visual) + PaddleOCR-VL (table recognition)
+ *
+ * This is the combined/dual-VLM approach that uses both models for consensus:
+ *   - MiniCPM-V for visual extraction
+ *   - PaddleOCR-VL for table recognition
+ */
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as os from 'os';
+import { ensurePaddleOcrVl, ensureMiniCpm } from './helpers/docker.js';
+
+// Service URLs
+const OLLAMA_URL = 'http://localhost:11434';
+const PADDLEOCR_VL_URL = 'http://localhost:8000';
+
+// Models
+const MINICPM_MODEL = 'minicpm-v:latest';
+const PADDLEOCR_VL_MODEL = 'paddleocr-vl';
+
+// Prompt for MiniCPM-V visual extraction
+const MINICPM_EXTRACT_PROMPT = `/nothink
+You are a bank statement parser. Extract EVERY transaction from the table.
+
+Read the Amount column carefully:
+- "- 21,47 €" means DEBIT, output as: -21.47
+- "+ 1.000,00 €" means CREDIT, output as: 1000.00
+- European format: comma = decimal point
+
+For each row output: {"date":"YYYY-MM-DD","counterparty":"NAME","amount":-21.47}
+
+Do not skip any rows. Return ONLY the JSON array, no explanation.`;
+
+// Prompt for PaddleOCR-VL table extraction
+const PADDLEOCR_VL_TABLE_PROMPT = `Table Recognition:`;
+
+// Post-processing prompt to convert PaddleOCR-VL output to JSON
+const PADDLEOCR_VL_CONVERT_PROMPT = `/nothink
+Convert the following bank statement table data to JSON.
+
+Read the Amount values carefully:
+- "- 21,47 €" means DEBIT, output as: -21.47
+- "+ 1.000,00 €" means CREDIT, output as: 1000.00
+- European format: comma = decimal point
+
+For each transaction output: {"date":"YYYY-MM-DD","counterparty":"NAME","amount":-21.47}
+
+Return ONLY the JSON array, no explanation.
+
+Table data:
+---
+{TABLE_DATA}
+---`;
+
+interface ITransaction {
+  date: string;
+  counterparty: string;
+  amount: number;
+}
+
+/**
+ * Convert PDF to PNG images using ImageMagick
+ */
+function convertPdfToImages(pdfPath: string): string[] {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdf-convert-'));
+  const outputPattern = path.join(tempDir, 'page-%d.png');
+
+  try {
+    execSync(
+      `convert -density 300 -quality 100 "${pdfPath}" -background white -alpha remove "${outputPattern}"`,
+      { stdio: 'pipe' }
+    );
+
+    const files = fs.readdirSync(tempDir).filter((f: string) => f.endsWith('.png')).sort();
+    const images: string[] = [];
+
+    for (const file of files) {
+      const imagePath = path.join(tempDir, file);
+      const imageData = fs.readFileSync(imagePath);
+      images.push(imageData.toString('base64'));
+    }
+
+    return images;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Extract using MiniCPM-V via Ollama
+ */
+async function extractWithMiniCPM(images: string[], passLabel: string): Promise<ITransaction[]> {
+  const payload = {
+    model: MINICPM_MODEL,
+    prompt: MINICPM_EXTRACT_PROMPT,
+    images,
+    stream: true,
+    options: {
+      num_predict: 16384,
+      temperature: 0.1,
+    },
+  };
+
+  const response = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error: ${response.status}`);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let fullText = '';
+  let lineBuffer = '';
+
+  console.log(`[${passLabel}] Extracting with MiniCPM-V...`);
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n').filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (json.response) {
+          fullText += json.response;
+          lineBuffer += json.response;
+
+          if (lineBuffer.includes('\n')) {
+            const parts = lineBuffer.split('\n');
+            for (let i = 0; i < parts.length - 1; i++) {
+              console.log(parts[i]);
+            }
+            lineBuffer = parts[parts.length - 1];
+          }
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  if (lineBuffer) {
+    console.log(lineBuffer);
+  }
+  console.log('');
+
+  const startIdx = fullText.indexOf('[');
+  const endIdx = fullText.lastIndexOf(']') + 1;
+
+  if (startIdx < 0 || endIdx <= startIdx) {
+    throw new Error('No JSON array found in response');
+  }
+
+  return JSON.parse(fullText.substring(startIdx, endIdx));
+}
+
+/**
+ * Extract table using PaddleOCR-VL via OpenAI-compatible API
+ */
+async function extractTableWithPaddleOCRVL(imageBase64: string): Promise<string> {
+  const payload = {
+    model: PADDLEOCR_VL_MODEL,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image_url',
+            image_url: { url: `data:image/png;base64,${imageBase64}` },
+          },
+          {
+            type: 'text',
+            text: PADDLEOCR_VL_TABLE_PROMPT,
+          },
+        ],
+      },
+    ],
+    temperature: 0.0,
+    max_tokens: 8192,
+  };
+
+  const response = await fetch(`${PADDLEOCR_VL_URL}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`PaddleOCR-VL API error: ${response.status} - ${text}`);
+  }
+
+  const data = await response.json();
+  return data.choices?.[0]?.message?.content || '';
+}
+
+/**
+ * Convert PaddleOCR-VL table output to transactions using MiniCPM-V
+ */
+async function convertTableToTransactions(
+  tableData: string,
+  passLabel: string
+): Promise<ITransaction[]> {
+  const prompt = PADDLEOCR_VL_CONVERT_PROMPT.replace('{TABLE_DATA}', tableData);
+
+  const payload = {
+    model: MINICPM_MODEL,
+    prompt,
+    stream: true,
+    options: {
+      num_predict: 16384,
+      temperature: 0.1,
+    },
+  };
+
+  const response = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error: ${response.status}`);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let fullText = '';
+
+  console.log(`[${passLabel}] Converting table data to JSON...`);
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n').filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (json.response) {
+          fullText += json.response;
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  const startIdx = fullText.indexOf('[');
+  const endIdx = fullText.lastIndexOf(']') + 1;
+
+  if (startIdx < 0 || endIdx <= startIdx) {
+    throw new Error('No JSON array found in response');
+  }
+
+  return JSON.parse(fullText.substring(startIdx, endIdx));
+}
+
+/**
+ * Extract using PaddleOCR-VL (table recognition) + conversion
+ */
+async function extractWithPaddleOCRVL(
+  images: string[],
+  passLabel: string
+): Promise<ITransaction[]> {
+  console.log(`[${passLabel}] Extracting tables with PaddleOCR-VL...`);
+
+  // Extract table data from each page
+  const tableDataParts: string[] = [];
+  for (let i = 0; i < images.length; i++) {
+    console.log(`[${passLabel}] Processing page ${i + 1}/${images.length}...`);
+    const tableData = await extractTableWithPaddleOCRVL(images[i]);
+    if (tableData.trim()) {
+      tableDataParts.push(`--- Page ${i + 1} ---\n${tableData}`);
+    }
+  }
+
+  const combinedTableData = tableDataParts.join('\n\n');
+  console.log(`[${passLabel}] Got ${combinedTableData.length} chars of table data`);
+
+  // Convert to transactions
+  return convertTableToTransactions(combinedTableData, passLabel);
+}
+
+/**
+ * Create a hash of transactions for comparison
+ */
+function hashTransactions(transactions: ITransaction[]): string {
+  return transactions
+    .map((t) => `${t.date}|${t.amount.toFixed(2)}`)
+    .sort()
+    .join(';');
+}
+
+/**
+ * Check if PaddleOCR-VL service is available
+ */
+async function isPaddleOCRVLAvailable(): Promise<boolean> {
+  try {
+    const response = await fetch(`${PADDLEOCR_VL_URL}/health`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(5000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract with dual-VLM consensus
+ * Strategy:
+ *   Pass 1 = MiniCPM-V visual extraction
+ *   Pass 2 = PaddleOCR-VL table recognition (if available)
+ *   Pass 3+ = MiniCPM-V visual (fallback)
+ */
+async function extractWithConsensus(
+  images: string[],
+  maxPasses: number = 5
+): Promise<ITransaction[]> {
+  const results: Array<{ transactions: ITransaction[]; hash: string }> = [];
+  const hashCounts: Map<string, number> = new Map();
+
+  const addResult = (transactions: ITransaction[], passLabel: string): number => {
+    const hash = hashTransactions(transactions);
+    results.push({ transactions, hash });
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+    console.log(
+      `[${passLabel}] Got ${transactions.length} transactions (hash: ${hash.substring(0, 20)}...)`
+    );
+    return hashCounts.get(hash)!;
+  };
+
+  // Check if PaddleOCR-VL is available
+  const paddleOCRVLAvailable = await isPaddleOCRVLAvailable();
+  if (paddleOCRVLAvailable) {
+    console.log('[Setup] PaddleOCR-VL service available - using dual-VLM consensus');
+  } else {
+    console.log('[Setup] PaddleOCR-VL not available - using MiniCPM-V only');
+  }
+
+  // Pass 1: MiniCPM-V visual extraction
+  try {
+    const pass1Result = await extractWithMiniCPM(images, 'Pass 1 MiniCPM-V');
+    addResult(pass1Result, 'Pass 1 MiniCPM-V');
+  } catch (err) {
+    console.log(`[Pass 1] Error: ${err}`);
+  }
+
+  // Pass 2: PaddleOCR-VL table recognition (if available)
+  if (paddleOCRVLAvailable) {
+    try {
+      const pass2Result = await extractWithPaddleOCRVL(images, 'Pass 2 PaddleOCR-VL');
+      const count = addResult(pass2Result, 'Pass 2 PaddleOCR-VL');
+      if (count >= 2) {
+        console.log('[Consensus] MiniCPM-V and PaddleOCR-VL extractions match!');
+        return pass2Result;
+      }
+    } catch (err) {
+      console.log(`[Pass 2 PaddleOCR-VL] Error: ${err}`);
+    }
+  }
+
+  // Pass 3+: Continue with MiniCPM-V visual passes
+  const startPass = paddleOCRVLAvailable ? 3 : 2;
+  for (let pass = startPass; pass <= maxPasses; pass++) {
+    try {
+      const transactions = await extractWithMiniCPM(images, `Pass ${pass} MiniCPM-V`);
+      const count = addResult(transactions, `Pass ${pass} MiniCPM-V`);
+
+      if (count >= 2) {
+        console.log(`[Consensus] Reached after ${pass} passes`);
+        return transactions;
+      }
+
+      console.log(`[Pass ${pass}] No consensus yet, trying again...`);
+    } catch (err) {
+      console.log(`[Pass ${pass}] Error: ${err}`);
+    }
+  }
+
+  // No consensus reached - return the most common result
+  let bestHash = '';
+  let bestCount = 0;
+  for (const [hash, count] of hashCounts) {
+    if (count > bestCount) {
+      bestCount = count;
+      bestHash = hash;
+    }
+  }
+
+  if (!bestHash) {
+    throw new Error('No valid results obtained');
+  }
+
+  const best = results.find((r) => r.hash === bestHash)!;
+  console.log(`[No consensus] Using most common result (${bestCount}/${maxPasses} passes)`);
+  return best.transactions;
+}
+
+/**
+ * Compare extracted transactions against expected
+ */
+function compareTransactions(
+  extracted: ITransaction[],
+  expected: ITransaction[]
+): { matches: number; total: number; errors: string[] } {
+  const errors: string[] = [];
+  let matches = 0;
+
+  for (let i = 0; i < expected.length; i++) {
+    const exp = expected[i];
+    const ext = extracted[i];
+
+    if (!ext) {
+      errors.push(`Missing transaction ${i}: ${exp.date} ${exp.counterparty}`);
+      continue;
+    }
+
+    const dateMatch = ext.date === exp.date;
+    const amountMatch = Math.abs(ext.amount - exp.amount) < 0.01;
+
+    if (dateMatch && amountMatch) {
+      matches++;
+    } else {
+      errors.push(
+        `Mismatch at ${i}: expected ${exp.date}/${exp.amount}, got ${ext.date}/${ext.amount}`
+      );
+    }
+  }
+
+  if (extracted.length > expected.length) {
+    errors.push(`Extra transactions: ${extracted.length - expected.length}`);
+  }
+
+  return { matches, total: expected.length, errors };
+}
+
+/**
+ * Find all test cases (PDF + JSON pairs) in .nogit/
+ */
+function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: string }> {
+  const testDir = path.join(process.cwd(), '.nogit');
+  if (!fs.existsSync(testDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(testDir);
+  const pdfFiles = files.filter((f: string) => f.endsWith('.pdf'));
+  const testCases: Array<{ name: string; pdfPath: string; jsonPath: string }> = [];
+
+  for (const pdf of pdfFiles) {
+    const baseName = pdf.replace('.pdf', '');
+    const jsonFile = `${baseName}.json`;
+    if (files.includes(jsonFile)) {
+      testCases.push({
+        name: baseName,
+        pdfPath: path.join(testDir, pdf),
+        jsonPath: path.join(testDir, jsonFile),
+      });
+    }
+  }
+
+  return testCases;
+}
+
+// Tests
+
+tap.test('setup: ensure Docker containers are running', async () => {
+  console.log('\n[Setup] Checking Docker containers...\n');
+
+  // Ensure PaddleOCR-VL is running (auto-detects GPU/CPU)
+  const paddleOk = await ensurePaddleOcrVl();
+  expect(paddleOk).toBeTrue();
+
+  // Ensure MiniCPM is running
+  const minicpmOk = await ensureMiniCpm();
+  expect(minicpmOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
+});
+
+tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
+  const response = await fetch(`${OLLAMA_URL}/api/tags`);
+  const data = await response.json();
+  const modelNames = data.models.map((m: { name: string }) => m.name);
+  expect(modelNames.some((name: string) => name.includes('minicpm-v4.5'))).toBeTrue();
+});
+
+tap.test('should check PaddleOCR-VL availability', async () => {
+  const available = await isPaddleOCRVLAvailable();
+  console.log(`PaddleOCR-VL available: ${available}`);
+  expect(available).toBeTrue();
+});
+
+// Dynamic test for each PDF/JSON pair
+const testCases = findTestCases();
+for (const testCase of testCases) {
+  tap.test(`should extract transactions from ${testCase.name}`, async () => {
+    // Load expected transactions
+    const expected: ITransaction[] = JSON.parse(fs.readFileSync(testCase.jsonPath, 'utf-8'));
+    console.log(`\n=== ${testCase.name} ===`);
+    console.log(`Expected: ${expected.length} transactions`);
+
+    // Convert PDF to images
+    console.log('Converting PDF to images...');
+    const images = convertPdfToImages(testCase.pdfPath);
+    console.log(`Converted: ${images.length} pages\n`);
+
+    // Extract with dual-VLM consensus
+    const extracted = await extractWithConsensus(images);
+    console.log(`\nFinal: ${extracted.length} transactions`);
+
+    // Compare results
+    const result = compareTransactions(extracted, expected);
+    console.log(`Accuracy: ${result.matches}/${result.total}`);
+
+    if (result.errors.length > 0) {
+      console.log('Errors:');
+      result.errors.forEach((e) => console.log(`  - ${e}`));
+    }
+
+    // Assert high accuracy
+    const accuracy = result.matches / result.total;
+    expect(accuracy).toBeGreaterThan(0.95);
+    expect(extracted.length).toEqual(expected.length);
+  });
+}
+
+export default tap.start();

test/test.bankstatements.minicpm.ts

@@ -1,13 +1,25 @@
+/**
+ * Bank statement extraction test using MiniCPM-V only (visual extraction)
+ *
+ * This tests MiniCPM-V's ability to extract bank transactions directly from images
+ * without any OCR augmentation.
+ */
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import * as os from 'os';
+import { ensureMiniCpm } from './helpers/docker.js';
 
+// Service URL
 const OLLAMA_URL = 'http://localhost:11434';
-const MODEL = 'openbmb/minicpm-v4.5:q8_0';
 
-const EXTRACT_PROMPT = `You are a bank statement parser. Extract EVERY transaction from the table.
+// Model
+const MINICPM_MODEL = 'minicpm-v:latest';
+
+// Prompt for MiniCPM-V visual extraction
+const MINICPM_EXTRACT_PROMPT = `/nothink
+You are a bank statement parser. Extract EVERY transaction from the table.
 
 Read the Amount column carefully:
 - "- 21,47 €" means DEBIT, output as: -21.47
@@ -37,7 +49,7 @@ function convertPdfToImages(pdfPath: string): string[] {
       { stdio: 'pipe' }
     );
 
-    const files = fs.readdirSync(tempDir).filter((f) => f.endsWith('.png')).sort();
+    const files = fs.readdirSync(tempDir).filter((f: string) => f.endsWith('.png')).sort();
     const images: string[] = [];
 
     for (const file of files) {
@@ -53,12 +65,12 @@ function convertPdfToImages(pdfPath: string): string[] {
 }
 
 /**
- * Single extraction pass
+ * Extract using MiniCPM-V via Ollama
  */
-async function extractOnce(images: string[], passNum: number): Promise<ITransaction[]> {
+async function extractWithMiniCPM(images: string[], passLabel: string): Promise<ITransaction[]> {
   const payload = {
-    model: MODEL,
+    model: MINICPM_MODEL,
-    prompt: EXTRACT_PROMPT,
+    prompt: MINICPM_EXTRACT_PROMPT,
     images,
     stream: true,
     options: {
@@ -86,7 +98,7 @@ async function extractOnce(images: string[], passNum: number): Promise<ITransact
   let fullText = '';
   let lineBuffer = '';
 
-  console.log(`[Pass ${passNum}] Extracting...`);
+  console.log(`[${passLabel}] Extracting with MiniCPM-V...`);
 
   while (true) {
     const { done, value } = await reader.read();
@@ -102,7 +114,6 @@ async function extractOnce(images: string[], passNum: number): Promise<ITransact
           fullText += json.response;
           lineBuffer += json.response;
 
-          // Print complete lines
           if (lineBuffer.includes('\n')) {
             const parts = lineBuffer.split('\n');
             for (let i = 0; i < parts.length - 1; i++) {
@@ -143,31 +154,40 @@ function hashTransactions(transactions: ITransaction[]): string {
 }
 
 /**
- * Extract with majority voting - run until 2 passes match
+ * Extract with consensus voting using MiniCPM-V only
  */
-async function extractWithConsensus(images: string[], maxPasses: number = 5): Promise<ITransaction[]> {
+async function extractWithConsensus(
+  images: string[],
+  maxPasses: number = 5
+): Promise<ITransaction[]> {
   const results: Array<{ transactions: ITransaction[]; hash: string }> = [];
   const hashCounts: Map<string, number> = new Map();
 
-  for (let pass = 1; pass <= maxPasses; pass++) {
+  const addResult = (transactions: ITransaction[], passLabel: string): number => {
-    const transactions = await extractOnce(images, pass);
     const hash = hashTransactions(transactions);
-
     results.push({ transactions, hash });
     hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+    console.log(
+      `[${passLabel}] Got ${transactions.length} transactions (hash: ${hash.substring(0, 20)}...)`
+    );
+    return hashCounts.get(hash)!;
+  };
 
-    console.log(`[Pass ${pass}] Got ${transactions.length} transactions (hash: ${hash.substring(0, 20)}...)`);
+  console.log('[Setup] Using MiniCPM-V only');
 
-    // Check if we have consensus (2+ matching)
+  for (let pass = 1; pass <= maxPasses; pass++) {
-    const count = hashCounts.get(hash)!;
+    try {
-    if (count >= 2) {
+      const transactions = await extractWithMiniCPM(images, `Pass ${pass} MiniCPM-V`);
-      console.log(`[Consensus] Reached after ${pass} passes (${count} matching results)`);
+      const count = addResult(transactions, `Pass ${pass} MiniCPM-V`);
-      return transactions;
+
-    }
+      if (count >= 2) {
+        console.log(`[Consensus] Reached after ${pass} passes`);
+        return transactions;
+      }
 
-    // After 2 passes, if no match yet, continue
-    if (pass >= 2) {
       console.log(`[Pass ${pass}] No consensus yet, trying again...`);
+    } catch (err) {
+      console.log(`[Pass ${pass}] Error: ${err}`);
     }
   }
 
@@ -181,6 +201,10 @@ async function extractWithConsensus(images: string[], maxPasses: number = 5): Pr
     }
   }
 
+  if (!bestHash) {
+    throw new Error('No valid results obtained');
+  }
+
   const best = results.find((r) => r.hash === bestHash)!;
   console.log(`[No consensus] Using most common result (${bestCount}/${maxPasses} passes)`);
   return best.transactions;
@@ -234,7 +258,7 @@ function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: strin
   }
 
   const files = fs.readdirSync(testDir);
-  const pdfFiles = files.filter((f) => f.endsWith('.pdf'));
+  const pdfFiles = files.filter((f: string) => f.endsWith('.pdf'));
   const testCases: Array<{ name: string; pdfPath: string; jsonPath: string }> = [];
 
   for (const pdf of pdfFiles) {
@@ -254,11 +278,14 @@ function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: strin
 
 // Tests
 
-tap.test('should connect to Ollama API', async () => {
+tap.test('setup: ensure Docker containers are running', async () => {
-  const response = await fetch(`${OLLAMA_URL}/api/tags`);
+  console.log('\n[Setup] Checking Docker containers...\n');
-  expect(response.ok).toBeTrue();
+
-  const data = await response.json();
+  // Ensure MiniCPM is running
-  expect(data.models).toBeArray();
+  const minicpmOk = await ensureMiniCpm();
+  expect(minicpmOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
 });
 
 tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
@@ -270,6 +297,8 @@ tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
 
 // Dynamic test for each PDF/JSON pair
 const testCases = findTestCases();
+console.log(`\nFound ${testCases.length} bank statement test cases (MiniCPM-V only)\n`);
+
 for (const testCase of testCases) {
   tap.test(`should extract transactions from ${testCase.name}`, async () => {
     // Load expected transactions
@@ -282,7 +311,7 @@ for (const testCase of testCases) {
     const images = convertPdfToImages(testCase.pdfPath);
     console.log(`Converted: ${images.length} pages\n`);
 
-    // Extract with consensus voting
+    // Extract with consensus (MiniCPM-V only)
     const extracted = await extractWithConsensus(images);
     console.log(`\nFinal: ${extracted.length} transactions`);
 

test/test.bankstatements.paddleocr-vl.ts

@@ -0,0 +1,346 @@
+/**
+ * Bank statement extraction test using PaddleOCR-VL Full Pipeline
+ *
+ * This tests the complete PaddleOCR-VL pipeline for bank statements:
+ *   1. PP-DocLayoutV2 for layout detection
+ *   2. PaddleOCR-VL for recognition (tables with proper structure)
+ *   3. Structured Markdown output with tables
+ *   4. MiniCPM extracts transactions from structured tables
+ *
+ * The structured Markdown has properly formatted tables,
+ * making it much easier for MiniCPM to extract transaction data.
+ */
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as os from 'os';
+import { ensurePaddleOcrVlFull, ensureMiniCpm } from './helpers/docker.js';
+
+const PADDLEOCR_VL_URL = 'http://localhost:8000';
+const OLLAMA_URL = 'http://localhost:11434';
+const MINICPM_MODEL = 'minicpm-v:latest';
+
+interface ITransaction {
+  date: string;
+  counterparty: string;
+  amount: number;
+}
+
+/**
+ * Convert PDF to PNG images using ImageMagick
+ */
+function convertPdfToImages(pdfPath: string): string[] {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdf-convert-'));
+  const outputPattern = path.join(tempDir, 'page-%d.png');
+
+  try {
+    execSync(
+      `convert -density 300 -quality 100 "${pdfPath}" -background white -alpha remove "${outputPattern}"`,
+      { stdio: 'pipe' }
+    );
+
+    const files = fs.readdirSync(tempDir).filter((f: string) => f.endsWith('.png')).sort();
+    const images: string[] = [];
+
+    for (const file of files) {
+      const imagePath = path.join(tempDir, file);
+      const imageData = fs.readFileSync(imagePath);
+      images.push(imageData.toString('base64'));
+    }
+
+    return images;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Parse document using PaddleOCR-VL Full Pipeline (returns structured Markdown)
+ */
+async function parseDocument(imageBase64: string): Promise<string> {
+  const response = await fetch(`${PADDLEOCR_VL_URL}/parse`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      image: imageBase64,
+      output_format: 'markdown',
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`PaddleOCR-VL API error: ${response.status} - ${text}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.success) {
+    throw new Error(`PaddleOCR-VL error: ${data.error}`);
+  }
+
+  return data.result?.markdown || '';
+}
+
+/**
+ * Extract transactions from structured Markdown using MiniCPM
+ */
+async function extractTransactionsFromMarkdown(markdown: string): Promise<ITransaction[]> {
+  console.log(`    [Extract] Processing ${markdown.length} chars of Markdown`);
+
+  const prompt = `/nothink
+Convert this bank statement to a JSON array of transactions.
+
+Read the Amount values carefully:
+- "- 21,47 €" means DEBIT, output as: -21.47
+- "+ 1.000,00 €" means CREDIT, output as: 1000.00
+- European format: comma = decimal point, dot = thousands
+
+For each transaction output: {"date":"YYYY-MM-DD","counterparty":"NAME","amount":-21.47}
+
+Return ONLY the JSON array, no explanation.
+
+Document:
+${markdown}`;
+
+  const payload = {
+    model: MINICPM_MODEL,
+    prompt,
+    stream: true,
+    options: {
+      num_predict: 16384,
+      temperature: 0.1,
+    },
+  };
+
+  const response = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error: ${response.status}`);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let fullText = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n').filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (json.response) {
+          fullText += json.response;
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  // Extract JSON array from response
+  const startIdx = fullText.indexOf('[');
+  const endIdx = fullText.lastIndexOf(']') + 1;
+
+  if (startIdx < 0 || endIdx <= startIdx) {
+    throw new Error(`No JSON array found in response: ${fullText.substring(0, 200)}`);
+  }
+
+  const jsonStr = fullText.substring(startIdx, endIdx);
+  return JSON.parse(jsonStr);
+}
+
+/**
+ * Extract transactions from all pages of a bank statement
+ */
+async function extractAllTransactions(images: string[]): Promise<ITransaction[]> {
+  const allTransactions: ITransaction[] = [];
+
+  for (let i = 0; i < images.length; i++) {
+    console.log(`  Processing page ${i + 1}/${images.length}...`);
+
+    // Parse with full pipeline
+    const markdown = await parseDocument(images[i]);
+    console.log(`    [Parse] Got ${markdown.split('\n').length} lines of Markdown`);
+
+    // Extract transactions
+    try {
+      const transactions = await extractTransactionsFromMarkdown(markdown);
+      console.log(`    [Extracted] ${transactions.length} transactions`);
+      allTransactions.push(...transactions);
+    } catch (err) {
+      console.log(`    [Error] ${err}`);
+    }
+  }
+
+  return allTransactions;
+}
+
+/**
+ * Compare transactions - find matching transaction in expected list
+ */
+function findMatchingTransaction(
+  tx: ITransaction,
+  expectedList: ITransaction[]
+): ITransaction | undefined {
+  return expectedList.find((exp) => {
+    const dateMatch = tx.date === exp.date;
+    const amountMatch = Math.abs(tx.amount - exp.amount) < 0.02;
+    const counterpartyMatch =
+      tx.counterparty?.toLowerCase().includes(exp.counterparty?.toLowerCase().slice(0, 10)) ||
+      exp.counterparty?.toLowerCase().includes(tx.counterparty?.toLowerCase().slice(0, 10));
+    return dateMatch && amountMatch && counterpartyMatch;
+  });
+}
+
+/**
+ * Calculate extraction accuracy
+ */
+function calculateAccuracy(
+  extracted: ITransaction[],
+  expected: ITransaction[]
+): { matched: number; total: number; accuracy: number } {
+  let matched = 0;
+  const usedExpected = new Set<number>();
+
+  for (const tx of extracted) {
+    for (let i = 0; i < expected.length; i++) {
+      if (usedExpected.has(i)) continue;
+
+      const exp = expected[i];
+      const dateMatch = tx.date === exp.date;
+      const amountMatch = Math.abs(tx.amount - exp.amount) < 0.02;
+
+      if (dateMatch && amountMatch) {
+        matched++;
+        usedExpected.add(i);
+        break;
+      }
+    }
+  }
+
+  return {
+    matched,
+    total: expected.length,
+    accuracy: expected.length > 0 ? (matched / expected.length) * 100 : 0,
+  };
+}
+
+/**
+ * Find all test cases (PDF + JSON pairs) in .nogit/bankstatements/
+ */
+function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: string }> {
+  const testDir = path.join(process.cwd(), '.nogit/bankstatements');
+  if (!fs.existsSync(testDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(testDir);
+  const pdfFiles = files.filter((f) => f.endsWith('.pdf'));
+  const testCases: Array<{ name: string; pdfPath: string; jsonPath: string }> = [];
+
+  for (const pdf of pdfFiles) {
+    const baseName = pdf.replace('.pdf', '');
+    const jsonFile = `${baseName}.json`;
+    if (files.includes(jsonFile)) {
+      testCases.push({
+        name: baseName,
+        pdfPath: path.join(testDir, pdf),
+        jsonPath: path.join(testDir, jsonFile),
+      });
+    }
+  }
+
+  testCases.sort((a, b) => a.name.localeCompare(b.name));
+  return testCases;
+}
+
+// Tests
+
+tap.test('setup: ensure Docker containers are running', async () => {
+  console.log('\n[Setup] Checking Docker containers...\n');
+
+  // Ensure PaddleOCR-VL Full Pipeline is running
+  const paddleOk = await ensurePaddleOcrVlFull();
+  expect(paddleOk).toBeTrue();
+
+  // Ensure MiniCPM is running (for field extraction from Markdown)
+  const minicpmOk = await ensureMiniCpm();
+  expect(minicpmOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
+});
+
+// Dynamic test for each PDF/JSON pair
+const testCases = findTestCases();
+console.log(`\nFound ${testCases.length} bank statement test cases (PaddleOCR-VL Full Pipeline)\n`);
+
+const results: Array<{ name: string; accuracy: number; matched: number; total: number }> = [];
+
+for (const testCase of testCases) {
+  tap.test(`should extract bank statement: ${testCase.name}`, async () => {
+    // Load expected data
+    const expected: ITransaction[] = JSON.parse(fs.readFileSync(testCase.jsonPath, 'utf-8'));
+    console.log(`\n=== ${testCase.name} ===`);
+    console.log(`Expected: ${expected.length} transactions`);
+
+    const startTime = Date.now();
+
+    // Convert PDF to images
+    const images = convertPdfToImages(testCase.pdfPath);
+    console.log(`  Pages: ${images.length}`);
+
+    // Extract all transactions
+    const extracted = await extractAllTransactions(images);
+
+    const endTime = Date.now();
+    const elapsedMs = endTime - startTime;
+
+    // Calculate accuracy
+    const accuracy = calculateAccuracy(extracted, expected);
+    results.push({
+      name: testCase.name,
+      accuracy: accuracy.accuracy,
+      matched: accuracy.matched,
+      total: accuracy.total,
+    });
+
+    console.log(`  Extracted: ${extracted.length} transactions`);
+    console.log(`  Matched: ${accuracy.matched}/${accuracy.total} (${accuracy.accuracy.toFixed(1)}%)`);
+    console.log(`  Time: ${(elapsedMs / 1000).toFixed(1)}s`);
+
+    // We expect at least 50% accuracy
+    expect(accuracy.accuracy).toBeGreaterThan(50);
+  });
+}
+
+tap.test('summary', async () => {
+  const totalStatements = results.length;
+  const avgAccuracy =
+    results.length > 0 ? results.reduce((a, b) => a + b.accuracy, 0) / results.length : 0;
+  const totalMatched = results.reduce((a, b) => a + b.matched, 0);
+  const totalExpected = results.reduce((a, b) => a + b.total, 0);
+
+  console.log(`\n======================================================`);
+  console.log(`  Bank Statement Extraction Summary (PaddleOCR-VL Full)`);
+  console.log(`======================================================`);
+  console.log(`  Method:      PaddleOCR-VL Full Pipeline -> MiniCPM`);
+  console.log(`  Statements:  ${totalStatements}`);
+  console.log(`  Transactions: ${totalMatched}/${totalExpected} matched`);
+  console.log(`  Avg accuracy: ${avgAccuracy.toFixed(1)}%`);
+  console.log(`======================================================\n`);
+});
+
+export default tap.start();

test/test.invoices.combined.ts

@@ -0,0 +1,455 @@
+/**
+ * Invoice extraction test using MiniCPM-V (visual) + PaddleOCR-VL (OCR augmentation)
+ *
+ * This is the combined approach that uses both models for best accuracy:
+ *   - MiniCPM-V for visual understanding
+ *   - PaddleOCR-VL for OCR text to augment prompts
+ */
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as os from 'os';
+import { ensurePaddleOcrVl, ensureMiniCpm } from './helpers/docker.js';
+
+const OLLAMA_URL = 'http://localhost:11434';
+const MODEL = 'minicpm-v:latest';
+const PADDLEOCR_VL_URL = 'http://localhost:8000';
+
+interface IInvoice {
+  invoice_number: string;
+  invoice_date: string;
+  vendor_name: string;
+  currency: string;
+  net_amount: number;
+  vat_amount: number;
+  total_amount: number;
+}
+
+/**
+ * Extract OCR text from an image using PaddleOCR-VL (OpenAI-compatible API)
+ */
+async function extractOcrText(imageBase64: string): Promise<string> {
+  try {
+    const response = await fetch(`${PADDLEOCR_VL_URL}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: 'paddleocr-vl',
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'image_url', image_url: { url: `data:image/png;base64,${imageBase64}` } },
+            { type: 'text', text: 'OCR:' }
+          ]
+        }],
+        temperature: 0.0,
+        max_tokens: 4096
+      }),
+    });
+
+    if (!response.ok) return '';
+
+    const data = await response.json();
+    return data.choices?.[0]?.message?.content || '';
+  } catch {
+    // PaddleOCR-VL unavailable
+  }
+  return '';
+}
+
+/**
+ * Build prompt with optional OCR text
+ */
+function buildPrompt(ocrText: string): string {
+  const base = `/nothink
+You are an invoice parser. Extract the following fields from this invoice:
+
+1. invoice_number: The invoice/receipt number
+2. invoice_date: Date in YYYY-MM-DD format
+3. vendor_name: Company that issued the invoice
+4. currency: EUR, USD, etc.
+5. net_amount: Amount before tax (if shown)
+6. vat_amount: Tax/VAT amount (if shown, 0 if reverse charge or no tax)
+7. total_amount: Final amount due
+
+Return ONLY valid JSON in this exact format:
+{"invoice_number":"XXX","invoice_date":"YYYY-MM-DD","vendor_name":"Company Name","currency":"EUR","net_amount":100.00,"vat_amount":19.00,"total_amount":119.00}
+
+If a field is not visible, use null for strings or 0 for numbers.
+No explanation, just the JSON object.`;
+
+  if (ocrText) {
+    // Limit OCR text to prevent context overflow
+    const maxOcrLength = 4000;
+    const truncatedOcr = ocrText.length > maxOcrLength
+      ? ocrText.substring(0, maxOcrLength) + '\n... (truncated)'
+      : ocrText;
+
+    return `${base}
+
+OCR text extracted from the invoice (use for reference):
+---
+${truncatedOcr}
+---
+
+Cross-reference the image with the OCR text above for accuracy.`;
+  }
+  return base;
+}
+
+/**
+ * Convert PDF to PNG images using ImageMagick
+ */
+function convertPdfToImages(pdfPath: string): string[] {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdf-convert-'));
+  const outputPattern = path.join(tempDir, 'page-%d.png');
+
+  try {
+    execSync(
+      `convert -density 200 -quality 90 "${pdfPath}" -background white -alpha remove "${outputPattern}"`,
+      { stdio: 'pipe' }
+    );
+
+    const files = fs.readdirSync(tempDir).filter((f) => f.endsWith('.png')).sort();
+    const images: string[] = [];
+
+    for (const file of files) {
+      const imagePath = path.join(tempDir, file);
+      const imageData = fs.readFileSync(imagePath);
+      images.push(imageData.toString('base64'));
+    }
+
+    return images;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Single extraction pass
+ */
+async function extractOnce(images: string[], passNum: number, ocrText: string = ''): Promise<IInvoice> {
+  const payload = {
+    model: MODEL,
+    prompt: buildPrompt(ocrText),
+    images,
+    stream: true,
+    options: {
+      num_predict: 2048,
+      temperature: 0.1,
+    },
+  };
+
+  const response = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error: ${response.status}`);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let fullText = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n').filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (json.response) {
+          fullText += json.response;
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  // Extract JSON from response
+  const startIdx = fullText.indexOf('{');
+  const endIdx = fullText.lastIndexOf('}') + 1;
+
+  if (startIdx < 0 || endIdx <= startIdx) {
+    throw new Error(`No JSON object found in response: ${fullText.substring(0, 200)}`);
+  }
+
+  const jsonStr = fullText.substring(startIdx, endIdx);
+  return JSON.parse(jsonStr);
+}
+
+/**
+ * Create a hash of invoice for comparison (using key fields)
+ */
+function hashInvoice(invoice: IInvoice): string {
+  return `${invoice.invoice_number}|${invoice.invoice_date}|${invoice.total_amount.toFixed(2)}`;
+}
+
+/**
+ * Extract with majority voting - run until 2 passes match
+ * Optimization: Run Pass 1, OCR, and Pass 2 (after OCR) in parallel
+ */
+async function extractWithConsensus(images: string[], invoiceName: string, maxPasses: number = 5): Promise<IInvoice> {
+  const results: Array<{ invoice: IInvoice; hash: string }> = [];
+  const hashCounts: Map<string, number> = new Map();
+
+  const addResult = (invoice: IInvoice, passLabel: string): number => {
+    const hash = hashInvoice(invoice);
+    results.push({ invoice, hash });
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+    console.log(`  [${passLabel}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
+    return hashCounts.get(hash)!;
+  };
+
+  // OPTIMIZATION: Run Pass 1 (no OCR) in parallel with OCR -> Pass 2 (with OCR)
+  let ocrText = '';
+  const pass1Promise = extractOnce(images, 1, '').catch((err) => ({ error: err }));
+
+  // OCR then immediately Pass 2
+  const ocrThenPass2Promise = (async () => {
+    ocrText = await extractOcrText(images[0]);
+    if (ocrText) {
+      console.log(`  [OCR] Extracted ${ocrText.split('\n').length} text lines`);
+    }
+    return extractOnce(images, 2, ocrText).catch((err) => ({ error: err }));
+  })();
+
+  // Wait for both to complete
+  const [pass1Result, pass2Result] = await Promise.all([pass1Promise, ocrThenPass2Promise]);
+
+  // Process Pass 1 result
+  if ('error' in pass1Result) {
+    console.log(`  [Pass 1] Error: ${(pass1Result as {error: unknown}).error}`);
+  } else {
+    const count = addResult(pass1Result as IInvoice, 'Pass 1');
+    if (count >= 2) {
+      console.log(`  [Consensus] Reached after parallel passes`);
+      return pass1Result as IInvoice;
+    }
+  }
+
+  // Process Pass 2 result
+  if ('error' in pass2Result) {
+    console.log(`  [Pass 2+OCR] Error: ${(pass2Result as {error: unknown}).error}`);
+  } else {
+    const count = addResult(pass2Result as IInvoice, 'Pass 2+OCR');
+    if (count >= 2) {
+      console.log(`  [Consensus] Reached after parallel passes`);
+      return pass2Result as IInvoice;
+    }
+  }
+
+  // Continue with passes 3+ using OCR text if no consensus yet
+  for (let pass = 3; pass <= maxPasses; pass++) {
+    try {
+      const invoice = await extractOnce(images, pass, ocrText);
+      const count = addResult(invoice, `Pass ${pass}+OCR`);
+
+      if (count >= 2) {
+        console.log(`  [Consensus] Reached after ${pass} passes`);
+        return invoice;
+      }
+    } catch (err) {
+      console.log(`  [Pass ${pass}] Error: ${err}`);
+    }
+  }
+
+  // No consensus reached - return the most common result
+  let bestHash = '';
+  let bestCount = 0;
+  for (const [hash, count] of hashCounts) {
+    if (count > bestCount) {
+      bestCount = count;
+      bestHash = hash;
+    }
+  }
+
+  if (!bestHash) {
+    throw new Error(`No valid results for ${invoiceName}`);
+  }
+
+  const best = results.find((r) => r.hash === bestHash)!;
+  console.log(`  [No consensus] Using most common result (${bestCount}/${maxPasses} passes)`);
+  return best.invoice;
+}
+
+/**
+ * Compare extracted invoice against expected
+ */
+function compareInvoice(
+  extracted: IInvoice,
+  expected: IInvoice
+): { match: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Compare invoice number (normalize by removing spaces and case)
+  const extNum = extracted.invoice_number?.replace(/\s/g, '').toLowerCase() || '';
+  const expNum = expected.invoice_number?.replace(/\s/g, '').toLowerCase() || '';
+  if (extNum !== expNum) {
+    errors.push(`invoice_number: expected "${expected.invoice_number}", got "${extracted.invoice_number}"`);
+  }
+
+  // Compare date
+  if (extracted.invoice_date !== expected.invoice_date) {
+    errors.push(`invoice_date: expected "${expected.invoice_date}", got "${extracted.invoice_date}"`);
+  }
+
+  // Compare total amount (with tolerance)
+  if (Math.abs(extracted.total_amount - expected.total_amount) > 0.02) {
+    errors.push(`total_amount: expected ${expected.total_amount}, got ${extracted.total_amount}`);
+  }
+
+  // Compare currency
+  if (extracted.currency?.toUpperCase() !== expected.currency?.toUpperCase()) {
+    errors.push(`currency: expected "${expected.currency}", got "${extracted.currency}"`);
+  }
+
+  return { match: errors.length === 0, errors };
+}
+
+/**
+ * Find all test cases (PDF + JSON pairs) in .nogit/invoices/
+ * Priority invoices (like vodafone) run first for quick feedback
+ */
+function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: string }> {
+  const testDir = path.join(process.cwd(), '.nogit/invoices');
+  if (!fs.existsSync(testDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(testDir);
+  const pdfFiles = files.filter((f) => f.endsWith('.pdf'));
+  const testCases: Array<{ name: string; pdfPath: string; jsonPath: string }> = [];
+
+  for (const pdf of pdfFiles) {
+    const baseName = pdf.replace('.pdf', '');
+    const jsonFile = `${baseName}.json`;
+    if (files.includes(jsonFile)) {
+      testCases.push({
+        name: baseName,
+        pdfPath: path.join(testDir, pdf),
+        jsonPath: path.join(testDir, jsonFile),
+      });
+    }
+  }
+
+  // Sort with priority invoices first, then alphabetically
+  const priorityPrefixes = ['vodafone'];
+  testCases.sort((a, b) => {
+    const aPriority = priorityPrefixes.findIndex((p) => a.name.startsWith(p));
+    const bPriority = priorityPrefixes.findIndex((p) => b.name.startsWith(p));
+
+    // Both have priority - sort by priority order
+    if (aPriority >= 0 && bPriority >= 0) return aPriority - bPriority;
+    // Only a has priority - a comes first
+    if (aPriority >= 0) return -1;
+    // Only b has priority - b comes first
+    if (bPriority >= 0) return 1;
+    // Neither has priority - alphabetical
+    return a.name.localeCompare(b.name);
+  });
+
+  return testCases;
+}
+
+// Tests
+
+tap.test('setup: ensure Docker containers are running', async () => {
+  console.log('\n[Setup] Checking Docker containers...\n');
+
+  // Ensure PaddleOCR-VL is running (auto-detects GPU/CPU)
+  const paddleOk = await ensurePaddleOcrVl();
+  expect(paddleOk).toBeTrue();
+
+  // Ensure MiniCPM is running
+  const minicpmOk = await ensureMiniCpm();
+  expect(minicpmOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
+});
+
+tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
+  const response = await fetch(`${OLLAMA_URL}/api/tags`);
+  const data = await response.json();
+  const modelNames = data.models.map((m: { name: string }) => m.name);
+  expect(modelNames.some((name: string) => name.includes('minicpm-v4.5'))).toBeTrue();
+});
+
+// Dynamic test for each PDF/JSON pair
+const testCases = findTestCases();
+console.log(`\nFound ${testCases.length} invoice test cases\n`);
+
+let passedCount = 0;
+let failedCount = 0;
+const processingTimes: number[] = [];
+
+for (const testCase of testCases) {
+  tap.test(`should extract invoice: ${testCase.name}`, async () => {
+    // Load expected data
+    const expected: IInvoice = JSON.parse(fs.readFileSync(testCase.jsonPath, 'utf-8'));
+    console.log(`\n=== ${testCase.name} ===`);
+    console.log(`Expected: ${expected.invoice_number} | ${expected.invoice_date} | ${expected.total_amount} ${expected.currency}`);
+
+    const startTime = Date.now();
+
+    // Convert PDF to images
+    const images = convertPdfToImages(testCase.pdfPath);
+    console.log(`  Pages: ${images.length}`);
+
+    // Extract with consensus voting
+    const extracted = await extractWithConsensus(images, testCase.name);
+
+    const endTime = Date.now();
+    const elapsedMs = endTime - startTime;
+    processingTimes.push(elapsedMs);
+
+    // Compare results
+    const result = compareInvoice(extracted, expected);
+
+    if (result.match) {
+      passedCount++;
+      console.log(`  Result: MATCH (${(elapsedMs / 1000).toFixed(1)}s)`);
+    } else {
+      failedCount++;
+      console.log(`  Result: MISMATCH (${(elapsedMs / 1000).toFixed(1)}s)`);
+      result.errors.forEach((e) => console.log(`    - ${e}`));
+    }
+
+    // Assert match
+    expect(result.match).toBeTrue();
+  });
+}
+
+tap.test('summary', async () => {
+  const totalInvoices = testCases.length;
+  const accuracy = totalInvoices > 0 ? (passedCount / totalInvoices) * 100 : 0;
+  const totalTimeMs = processingTimes.reduce((a, b) => a + b, 0);
+  const avgTimeMs = processingTimes.length > 0 ? totalTimeMs / processingTimes.length : 0;
+  const avgTimeSec = avgTimeMs / 1000;
+  const totalTimeSec = totalTimeMs / 1000;
+
+  console.log(`\n========================================`);
+  console.log(`        Invoice Extraction Summary`);
+  console.log(`========================================`);
+  console.log(`  Passed:    ${passedCount}/${totalInvoices}`);
+  console.log(`  Failed:    ${failedCount}/${totalInvoices}`);
+  console.log(`  Accuracy:  ${accuracy.toFixed(1)}%`);
+  console.log(`----------------------------------------`);
+  console.log(`  Total time:   ${totalTimeSec.toFixed(1)}s`);
+  console.log(`  Avg per inv:  ${avgTimeSec.toFixed(1)}s`);
+  console.log(`========================================\n`);
+});
+
+export default tap.start();

test/test.invoices.minicpm.ts

@@ -1,12 +1,18 @@
+/**
+ * Invoice extraction test using MiniCPM-V only (visual extraction)
+ *
+ * This tests MiniCPM-V's ability to extract invoice data directly from images
+ * without any OCR augmentation.
+ */
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import * as os from 'os';
+import { ensureMiniCpm } from './helpers/docker.js';
 
 const OLLAMA_URL = 'http://localhost:11434';
-const MODEL = 'openbmb/minicpm-v4.5:q8_0';
+const MODEL = 'minicpm-v:latest';
-const PADDLEOCR_URL = 'http://localhost:5000';
 
 interface IInvoice {
   invoice_number: string;
@@ -19,38 +25,11 @@ interface IInvoice {
 }
 
 /**
- * Extract OCR text from an image using PaddleOCR
+ * Build extraction prompt (MiniCPM-V only, no OCR augmentation)
  */
-async function extractOcrText(imageBase64: string): Promise<string> {
+function buildPrompt(): string {
-  const formData = new FormData();
+  return `/nothink
-  const imageBuffer = Buffer.from(imageBase64, 'base64');
+You are an invoice parser. Extract the following fields from this invoice:
-  const blob = new Blob([imageBuffer], { type: 'image/png' });
-  formData.append('img', blob, 'image.png');
-  formData.append('outtype', 'json');
-
-  try {
-    const response = await fetch(`${PADDLEOCR_URL}/ocr`, {
-      method: 'POST',
-      body: formData,
-    });
-
-    if (!response.ok) return '';
-
-    const data = await response.json();
-    if (data.success && data.results) {
-      return data.results.map((r: { text: string }) => r.text).join('\n');
-    }
-  } catch {
-    // PaddleOCR unavailable
-  }
-  return '';
-}
-
-/**
- * Build prompt with optional OCR text
- */
-function buildPrompt(ocrText: string): string {
-  const base = `You are an invoice parser. Extract the following fields from this invoice:
 
 1. invoice_number: The invoice/receipt number
 2. invoice_date: Date in YYYY-MM-DD format
@@ -65,18 +44,6 @@ Return ONLY valid JSON in this exact format:
 
 If a field is not visible, use null for strings or 0 for numbers.
 No explanation, just the JSON object.`;
-
-  if (ocrText) {
-    return `${base}
-
-OCR text extracted from the invoice:
----
-${ocrText}
----
-
-Cross-reference the image with the OCR text above for accuracy.`;
-  }
-  return base;
 }
 
 /**
@@ -108,12 +75,12 @@ function convertPdfToImages(pdfPath: string): string[] {
 }
 
 /**
- * Single extraction pass
+ * Single extraction pass with MiniCPM-V
  */
-async function extractOnce(images: string[], passNum: number, ocrText: string = ''): Promise<IInvoice> {
+async function extractOnce(images: string[], passNum: number): Promise<IInvoice> {
   const payload = {
     model: MODEL,
-    prompt: buildPrompt(ocrText),
+    prompt: buildPrompt(),
     images,
     stream: true,
     options: {
@@ -179,30 +146,25 @@ function hashInvoice(invoice: IInvoice): string {
 }
 
 /**
- * Extract with majority voting - run until 2 passes match
+ * Extract with consensus voting using MiniCPM-V only
  */
 async function extractWithConsensus(images: string[], invoiceName: string, maxPasses: number = 5): Promise<IInvoice> {
   const results: Array<{ invoice: IInvoice; hash: string }> = [];
   const hashCounts: Map<string, number> = new Map();
 
-  // Extract OCR text from first page
+  const addResult = (invoice: IInvoice, passLabel: string): number => {
-  const ocrText = await extractOcrText(images[0]);
+    const hash = hashInvoice(invoice);
-  if (ocrText) {
+    results.push({ invoice, hash });
-    console.log(`  [OCR] Extracted ${ocrText.split('\n').length} text lines`);
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
-  }
+    console.log(`  [${passLabel}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
+    return hashCounts.get(hash)!;
+  };
 
   for (let pass = 1; pass <= maxPasses; pass++) {
     try {
-      const invoice = await extractOnce(images, pass, ocrText);
+      const invoice = await extractOnce(images, pass);
-      const hash = hashInvoice(invoice);
+      const count = addResult(invoice, `Pass ${pass}`);
 
-      results.push({ invoice, hash });
-      hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
-
-      console.log(`  [Pass ${pass}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
-
-      // Check if we have consensus (2+ matching)
-      const count = hashCounts.get(hash)!;
       if (count >= 2) {
         console.log(`  [Consensus] Reached after ${pass} passes`);
         return invoice;
@@ -290,16 +252,22 @@ function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: strin
     }
   }
 
+  // Sort alphabetically
+  testCases.sort((a, b) => a.name.localeCompare(b.name));
+
   return testCases;
 }
 
 // Tests
 
-tap.test('should connect to Ollama API', async () => {
+tap.test('setup: ensure Docker containers are running', async () => {
-  const response = await fetch(`${OLLAMA_URL}/api/tags`);
+  console.log('\n[Setup] Checking Docker containers...\n');
-  expect(response.ok).toBeTrue();
+
-  const data = await response.json();
+  // Ensure MiniCPM is running
-  expect(data.models).toBeArray();
+  const minicpmOk = await ensureMiniCpm();
+  expect(minicpmOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
 });
 
 tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
@@ -311,7 +279,7 @@ tap.test('should have MiniCPM-V 4.5 model loaded', async () => {
 
 // Dynamic test for each PDF/JSON pair
 const testCases = findTestCases();
-console.log(`\nFound ${testCases.length} invoice test cases\n`);
+console.log(`\nFound ${testCases.length} invoice test cases (MiniCPM-V only)\n`);
 
 let passedCount = 0;
 let failedCount = 0;
@@ -330,7 +298,7 @@ for (const testCase of testCases) {
     const images = convertPdfToImages(testCase.pdfPath);
     console.log(`  Pages: ${images.length}`);
 
-    // Extract with consensus voting
+    // Extract with consensus voting (MiniCPM-V only)
     const extracted = await extractWithConsensus(images, testCase.name);
 
     const endTime = Date.now();
@@ -363,7 +331,7 @@ tap.test('summary', async () => {
   const totalTimeSec = totalTimeMs / 1000;
 
   console.log(`\n========================================`);
-  console.log(`        Invoice Extraction Summary`);
+  console.log(`   Invoice Extraction Summary (MiniCPM)`);
   console.log(`========================================`);
   console.log(`  Passed:    ${passedCount}/${totalInvoices}`);
   console.log(`  Failed:    ${failedCount}/${totalInvoices}`);

test/test.invoices.paddleocr-vl.ts

@@ -0,0 +1,451 @@
+/**
+ * Invoice extraction test using PaddleOCR-VL Full Pipeline
+ *
+ * This tests the complete PaddleOCR-VL pipeline:
+ *   1. PP-DocLayoutV2 for layout detection
+ *   2. PaddleOCR-VL for recognition
+ *   3. Structured Markdown output
+ *   4. MiniCPM extracts invoice fields from structured Markdown
+ *
+ * The structured Markdown has proper tables and formatting,
+ * making it much easier for MiniCPM to extract invoice data.
+ */
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as os from 'os';
+import { ensurePaddleOcrVlFull, ensureQwen25 } from './helpers/docker.js';
+
+const PADDLEOCR_VL_URL = 'http://localhost:8000';
+const OLLAMA_URL = 'http://localhost:11434';
+// Use Qwen2.5 for text-only JSON extraction (not MiniCPM which is vision-focused)
+const TEXT_MODEL = 'qwen2.5:7b';
+
+interface IInvoice {
+  invoice_number: string;
+  invoice_date: string;
+  vendor_name: string;
+  currency: string;
+  net_amount: number;
+  vat_amount: number;
+  total_amount: number;
+}
+
+/**
+ * Convert PDF to PNG images using ImageMagick
+ */
+function convertPdfToImages(pdfPath: string): string[] {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pdf-convert-'));
+  const outputPattern = path.join(tempDir, 'page-%d.png');
+
+  try {
+    execSync(
+      `convert -density 200 -quality 90 "${pdfPath}" -background white -alpha remove "${outputPattern}"`,
+      { stdio: 'pipe' }
+    );
+
+    const files = fs.readdirSync(tempDir).filter((f) => f.endsWith('.png')).sort();
+    const images: string[] = [];
+
+    for (const file of files) {
+      const imagePath = path.join(tempDir, file);
+      const imageData = fs.readFileSync(imagePath);
+      images.push(imageData.toString('base64'));
+    }
+
+    return images;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Parse document using PaddleOCR-VL Full Pipeline (returns structured Markdown)
+ */
+async function parseDocument(imageBase64: string): Promise<string> {
+  const response = await fetch(`${PADDLEOCR_VL_URL}/parse`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      image: imageBase64,
+      output_format: 'markdown',
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`PaddleOCR-VL API error: ${response.status} - ${text}`);
+  }
+
+  const data = await response.json();
+
+  if (!data.success) {
+    throw new Error(`PaddleOCR-VL error: ${data.error}`);
+  }
+
+  return data.result?.markdown || '';
+}
+
+/**
+ * Extract invoice fields from structured Markdown using Qwen2.5 (text-only model)
+ */
+async function extractInvoiceFromMarkdown(markdown: string): Promise<IInvoice> {
+  // Truncate if too long
+  const truncated = markdown.length > 12000 ? markdown.slice(0, 12000) : markdown;
+  console.log(`    [Extract] Processing ${truncated.length} chars of Markdown`);
+
+  const prompt = `You are an invoice data extractor. Extract the following fields from this OCR text and return ONLY a valid JSON object.
+
+Required fields:
+- invoice_number: The invoice/receipt/document number
+- invoice_date: Date in YYYY-MM-DD format (convert from any format)
+- vendor_name: Company that issued the invoice
+- currency: EUR, USD, GBP, etc.
+- net_amount: Amount before tax (number)
+- vat_amount: Tax/VAT amount (number, use 0 if reverse charge or not shown)
+- total_amount: Final total amount (number)
+
+Example output format:
+{"invoice_number":"INV-123","invoice_date":"2022-01-28","vendor_name":"Adobe","currency":"EUR","net_amount":24.99,"vat_amount":0,"total_amount":24.99}
+
+Rules:
+- Return ONLY the JSON object, no explanation or markdown
+- Use null for missing string fields
+- Use 0 for missing numeric fields
+- Convert dates to YYYY-MM-DD format (e.g., "28-JAN-2022" becomes "2022-01-28")
+- Extract numbers without currency symbols
+
+OCR Text:
+${truncated}
+
+JSON:`;
+
+  const payload = {
+    model: TEXT_MODEL,
+    prompt,
+    stream: true,
+    options: {
+      num_predict: 512,
+      temperature: 0.1,
+    },
+  };
+
+  const response = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error: ${response.status}`);
+  }
+
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new Error('No response body');
+  }
+
+  const decoder = new TextDecoder();
+  let fullText = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n').filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const json = JSON.parse(line);
+        if (json.response) {
+          fullText += json.response;
+        }
+      } catch {
+        // Skip invalid JSON lines
+      }
+    }
+  }
+
+  // Extract JSON from response
+  const startIdx = fullText.indexOf('{');
+  const endIdx = fullText.lastIndexOf('}') + 1;
+
+  if (startIdx < 0 || endIdx <= startIdx) {
+    throw new Error(`No JSON object found in response: ${fullText.substring(0, 200)}`);
+  }
+
+  const jsonStr = fullText.substring(startIdx, endIdx);
+  const parsed = JSON.parse(jsonStr);
+
+  // Ensure numeric fields are actually numbers
+  return {
+    invoice_number: parsed.invoice_number || null,
+    invoice_date: parsed.invoice_date || null,
+    vendor_name: parsed.vendor_name || null,
+    currency: parsed.currency || 'EUR',
+    net_amount: parseFloat(parsed.net_amount) || 0,
+    vat_amount: parseFloat(parsed.vat_amount) || 0,
+    total_amount: parseFloat(parsed.total_amount) || 0,
+  };
+}
+
+/**
+ * Single extraction pass: Parse with PaddleOCR-VL Full, extract with Qwen2.5 (text-only)
+ */
+async function extractOnce(images: string[], passNum: number): Promise<IInvoice> {
+  // Parse document with full pipeline (PaddleOCR-VL)
+  const markdown = await parseDocument(images[0]);
+  console.log(`    [Parse] Got ${markdown.split('\n').length} lines of Markdown`);
+
+  // Extract invoice fields from Markdown using text-only model (no images)
+  return extractInvoiceFromMarkdown(markdown);
+}
+
+/**
+ * Create a hash of invoice for comparison (using key fields)
+ */
+function hashInvoice(invoice: IInvoice): string {
+  // Ensure total_amount is a number
+  const amount = typeof invoice.total_amount === 'number'
+    ? invoice.total_amount.toFixed(2)
+    : String(invoice.total_amount || 0);
+  return `${invoice.invoice_number}|${invoice.invoice_date}|${amount}`;
+}
+
+/**
+ * Extract with consensus voting
+ */
+async function extractWithConsensus(images: string[], invoiceName: string, maxPasses: number = 5): Promise<IInvoice> {
+  const results: Array<{ invoice: IInvoice; hash: string }> = [];
+  const hashCounts: Map<string, number> = new Map();
+
+  const addResult = (invoice: IInvoice, passLabel: string): number => {
+    const hash = hashInvoice(invoice);
+    results.push({ invoice, hash });
+    hashCounts.set(hash, (hashCounts.get(hash) || 0) + 1);
+    console.log(`  [${passLabel}] ${invoice.invoice_number} | ${invoice.invoice_date} | ${invoice.total_amount} ${invoice.currency}`);
+    return hashCounts.get(hash)!;
+  };
+
+  for (let pass = 1; pass <= maxPasses; pass++) {
+    try {
+      const invoice = await extractOnce(images, pass);
+      const count = addResult(invoice, `Pass ${pass}`);
+
+      if (count >= 2) {
+        console.log(`  [Consensus] Reached after ${pass} passes`);
+        return invoice;
+      }
+    } catch (err) {
+      console.log(`  [Pass ${pass}] Error: ${err}`);
+    }
+  }
+
+  // No consensus reached - return the most common result
+  let bestHash = '';
+  let bestCount = 0;
+  for (const [hash, count] of hashCounts) {
+    if (count > bestCount) {
+      bestCount = count;
+      bestHash = hash;
+    }
+  }
+
+  if (!bestHash) {
+    throw new Error(`No valid results for ${invoiceName}`);
+  }
+
+  const best = results.find((r) => r.hash === bestHash)!;
+  console.log(`  [No consensus] Using most common result (${bestCount}/${maxPasses} passes)`);
+  return best.invoice;
+}
+
+/**
+ * Normalize date to YYYY-MM-DD format
+ */
+function normalizeDate(dateStr: string | null): string {
+  if (!dateStr) return '';
+
+  // Already in correct format
+  if (/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+    return dateStr;
+  }
+
+  // Handle DD-MMM-YYYY format (e.g., "28-JUN-2022")
+  const monthMap: Record<string, string> = {
+    JAN: '01', FEB: '02', MAR: '03', APR: '04', MAY: '05', JUN: '06',
+    JUL: '07', AUG: '08', SEP: '09', OCT: '10', NOV: '11', DEC: '12',
+  };
+
+  const match = dateStr.match(/^(\d{1,2})-([A-Z]{3})-(\d{4})$/i);
+  if (match) {
+    const day = match[1].padStart(2, '0');
+    const month = monthMap[match[2].toUpperCase()] || '01';
+    const year = match[3];
+    return `${year}-${month}-${day}`;
+  }
+
+  // Handle DD/MM/YYYY or DD.MM.YYYY
+  const match2 = dateStr.match(/^(\d{1,2})[\/.](\d{1,2})[\/.](\d{4})$/);
+  if (match2) {
+    const day = match2[1].padStart(2, '0');
+    const month = match2[2].padStart(2, '0');
+    const year = match2[3];
+    return `${year}-${month}-${day}`;
+  }
+
+  return dateStr;
+}
+
+/**
+ * Compare extracted invoice against expected
+ */
+function compareInvoice(
+  extracted: IInvoice,
+  expected: IInvoice
+): { match: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Compare invoice number (normalize by removing spaces and case)
+  const extNum = extracted.invoice_number?.replace(/\s/g, '').toLowerCase() || '';
+  const expNum = expected.invoice_number?.replace(/\s/g, '').toLowerCase() || '';
+  if (extNum !== expNum) {
+    errors.push(`invoice_number: expected "${expected.invoice_number}", got "${extracted.invoice_number}"`);
+  }
+
+  // Compare date (normalize format first)
+  const extDate = normalizeDate(extracted.invoice_date);
+  const expDate = normalizeDate(expected.invoice_date);
+  if (extDate !== expDate) {
+    errors.push(`invoice_date: expected "${expected.invoice_date}", got "${extracted.invoice_date}"`);
+  }
+
+  // Compare total amount (with tolerance)
+  if (Math.abs(extracted.total_amount - expected.total_amount) > 0.02) {
+    errors.push(`total_amount: expected ${expected.total_amount}, got ${extracted.total_amount}`);
+  }
+
+  // Compare currency
+  if (extracted.currency?.toUpperCase() !== expected.currency?.toUpperCase()) {
+    errors.push(`currency: expected "${expected.currency}", got "${extracted.currency}"`);
+  }
+
+  return { match: errors.length === 0, errors };
+}
+
+/**
+ * Find all test cases (PDF + JSON pairs) in .nogit/invoices/
+ */
+function findTestCases(): Array<{ name: string; pdfPath: string; jsonPath: string }> {
+  const testDir = path.join(process.cwd(), '.nogit/invoices');
+  if (!fs.existsSync(testDir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(testDir);
+  const pdfFiles = files.filter((f) => f.endsWith('.pdf'));
+  const testCases: Array<{ name: string; pdfPath: string; jsonPath: string }> = [];
+
+  for (const pdf of pdfFiles) {
+    const baseName = pdf.replace('.pdf', '');
+    const jsonFile = `${baseName}.json`;
+    if (files.includes(jsonFile)) {
+      testCases.push({
+        name: baseName,
+        pdfPath: path.join(testDir, pdf),
+        jsonPath: path.join(testDir, jsonFile),
+      });
+    }
+  }
+
+  // Sort alphabetically
+  testCases.sort((a, b) => a.name.localeCompare(b.name));
+
+  return testCases;
+}
+
+// Tests
+
+tap.test('setup: ensure Docker containers are running', async () => {
+  console.log('\n[Setup] Checking Docker containers...\n');
+
+  // Ensure PaddleOCR-VL Full Pipeline is running
+  const paddleOk = await ensurePaddleOcrVlFull();
+  expect(paddleOk).toBeTrue();
+
+  // Ensure Qwen2.5 is available (for text-only JSON extraction)
+  const qwenOk = await ensureQwen25();
+  expect(qwenOk).toBeTrue();
+
+  console.log('\n[Setup] All containers ready!\n');
+});
+
+// Dynamic test for each PDF/JSON pair
+const testCases = findTestCases();
+console.log(`\nFound ${testCases.length} invoice test cases (PaddleOCR-VL Full Pipeline)\n`);
+
+let passedCount = 0;
+let failedCount = 0;
+const processingTimes: number[] = [];
+
+for (const testCase of testCases) {
+  tap.test(`should extract invoice: ${testCase.name}`, async () => {
+    // Load expected data
+    const expected: IInvoice = JSON.parse(fs.readFileSync(testCase.jsonPath, 'utf-8'));
+    console.log(`\n=== ${testCase.name} ===`);
+    console.log(`Expected: ${expected.invoice_number} | ${expected.invoice_date} | ${expected.total_amount} ${expected.currency}`);
+
+    const startTime = Date.now();
+
+    // Convert PDF to images
+    const images = convertPdfToImages(testCase.pdfPath);
+    console.log(`  Pages: ${images.length}`);
+
+    // Extract with consensus voting (PaddleOCR-VL Full -> MiniCPM)
+    const extracted = await extractWithConsensus(images, testCase.name);
+
+    const endTime = Date.now();
+    const elapsedMs = endTime - startTime;
+    processingTimes.push(elapsedMs);
+
+    // Compare results
+    const result = compareInvoice(extracted, expected);
+
+    if (result.match) {
+      passedCount++;
+      console.log(`  Result: MATCH (${(elapsedMs / 1000).toFixed(1)}s)`);
+    } else {
+      failedCount++;
+      console.log(`  Result: MISMATCH (${(elapsedMs / 1000).toFixed(1)}s)`);
+      result.errors.forEach((e) => console.log(`    - ${e}`));
+    }
+
+    // Assert match
+    expect(result.match).toBeTrue();
+  });
+}
+
+tap.test('summary', async () => {
+  const totalInvoices = testCases.length;
+  const accuracy = totalInvoices > 0 ? (passedCount / totalInvoices) * 100 : 0;
+  const totalTimeMs = processingTimes.reduce((a, b) => a + b, 0);
+  const avgTimeMs = processingTimes.length > 0 ? totalTimeMs / processingTimes.length : 0;
+  const avgTimeSec = avgTimeMs / 1000;
+  const totalTimeSec = totalTimeMs / 1000;
+
+  console.log(`\n======================================================`);
+  console.log(`   Invoice Extraction Summary (PaddleOCR-VL Full)`);
+  console.log(`======================================================`);
+  console.log(`  Method:    PaddleOCR-VL Full Pipeline -> Qwen2.5 (text-only)`);
+  console.log(`  Passed:    ${passedCount}/${totalInvoices}`);
+  console.log(`  Failed:    ${failedCount}/${totalInvoices}`);
+  console.log(`  Accuracy:  ${accuracy.toFixed(1)}%`);
+  console.log(`------------------------------------------------------`);
+  console.log(`  Total time:   ${totalTimeSec.toFixed(1)}s`);
+  console.log(`  Avg per inv:  ${avgTimeSec.toFixed(1)}s`);
+  console.log(`======================================================\n`);
+});
+
+export default tap.start();