Merge pull request #5 from r0m4k/feat/docker-space

.dockerignore

@@ -0,0 +1,14 @@
+# Keep the build context small; the model is downloaded inside the image, not copied in.
+.git/
+.venv/
+venv/
+models/
+__pycache__/
+**/__pycache__/
+*.pyc
+.pytest_cache/
+.gradio/
+flagged/
+train/data/
+eval/data/synth*
+.DS_Store

DEPLOY.md

@@ -0,0 +1,50 @@
+# Deploying the offline Space (Docker)
+
+The submission Space runs the model **on-device** via a Docker image: it builds current
+llama.cpp, **bakes the MiniCPM-V GGUF into the image at build time**, and launches
+`llama-server` + the Gradio app. No external API at runtime → **off-grid**.
+
+## 1. Make the Space a Docker Space (under the org)
+The Space `build-small-hackathon/blood-test-explainer` must use **`sdk: docker`**. Set its
+`README.md` frontmatter to exactly:
+
+```yaml
+---
+title: Blood Test Explainer
+emoji: 📊
+colorFrom: green
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+```
+
+## 2. Get these files into the Space repo
+The Space needs `Dockerfile`, `start.sh`, `.dockerignore`, `app.py`, and `src/` (plus the
+sample reports under `eval/data/real/`). If your Space mirrors this GitHub repo, push this
+branch's contents. If the Space is a separate HF git repo, copy these files into it and push.
+
+## 3. HF builds it
+First build takes ~10–15 min (compiles llama.cpp + downloads the ~1.6 GB model). When it's
+up, upload a report → it extracts fully offline.
+
+## 4. Ship the fine-tuned model (later)
+Once you've fine-tuned and converted to GGUF, upload it to an HF model repo, then rebuild the
+Space with the build-args pointing at it:
+
+```
+MODEL_REPO=<you>/minicpmv-lab-gguf  MODEL_FILE=<your-model>.Q4_K_M.gguf  MMPROJ_FILE=mmproj-model-f16.gguf
+```
+(In a Space, set these as build-time variables, or edit the `ARG` defaults in the Dockerfile.)
+
+## 5. Verify off-grid (badge)
+- Model is baked into the image at build time; `HF_HUB_OFFLINE=1` + `TRANSFORMERS_OFFLINE=1`.
+- The only network at runtime is `127.0.0.1:8080` (llama-server in the same container).
+- Grep check: nothing on the request path hits an external host — the API backend (the only
+  outbound HTTP) is disabled when `EXTRACTOR_BACKEND=local`.
+
+## Hardware
+Free **CPU** Space works (first inference is slower than your M3, ~30–60s). Upgrade the Space
+hardware if you want it snappier for live demos; the demo **video** should be recorded locally
+where it's fast.

Dockerfile

@@ -0,0 +1,46 @@
+# Offline Blood Test Explainer — MiniCPM-V 4.6 served on-device by llama.cpp, no external APIs.
+# HF Docker Space. The model is baked into the image at build time, so there is zero network
+# at runtime (off-grid badge). Swap MODEL_REPO to your fine-tuned GGUF repo when it's ready.
+FROM python:3.11-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git cmake build-essential curl ca-certificates libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# 1) Build current llama.cpp (its server supports MiniCPM-V 4.6). GGML_NATIVE=OFF for portability.
+WORKDIR /opt
+RUN git clone --depth 1 https://github.com/ggml-org/llama.cpp.git && \
+    cmake -S llama.cpp -B llama.cpp/build \
+        -DGGML_NATIVE=OFF -DLLAMA_CURL=OFF -DBUILD_SHARED_LIBS=OFF -DLLAMA_BUILD_TESTS=OFF && \
+    cmake --build llama.cpp/build --config Release -j --target llama-server && \
+    cp llama.cpp/build/bin/llama-server /usr/local/bin/llama-server && \
+    rm -rf /opt/llama.cpp
+
+# 2) Bake the model + vision projector into the image (no runtime download).
+#    Override these build-args to ship your fine-tuned model instead of the base.
+ARG MODEL_REPO=openbmb/MiniCPM-V-4.6-gguf
+ARG MODEL_FILE=MiniCPM-V-4_6-Q4_K_M.gguf
+ARG MMPROJ_FILE=mmproj-model-f16.gguf
+RUN pip install --no-cache-dir "huggingface_hub[cli]" && \
+    mkdir -p /models && \
+    hf download "$MODEL_REPO" "$MODEL_FILE" "$MMPROJ_FILE" --local-dir /models
+
+# 3) App + runtime deps (no llama-cpp-python: we use the llama-server backend).
+WORKDIR /app
+RUN pip install --no-cache-dir \
+        gradio==6.17.3 requests==2.32.5 pillow==12.0.0 pymupdf==1.26.6 json-repair==0.60.1
+COPY . /app
+
+ENV EXTRACTOR_BACKEND=local \
+    LLAMA_SERVER_URL=http://127.0.0.1:8080/v1/chat/completions \
+    LLAMA_SERVER_MODEL=minicpm-v \
+    LOCAL_MODEL_PATH=/models/MiniCPM-V-4_6-Q4_K_M.gguf \
+    LOCAL_MMPROJ_PATH=/models/mmproj-model-f16.gguf \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    HF_HUB_OFFLINE=1 \
+    TRANSFORMERS_OFFLINE=1
+
+EXPOSE 7860
+CMD ["bash", "start.sh"]

start.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Launch the on-device model server, wait for it, then start the Gradio UI.
+# Everything stays on localhost — no external network — so this is fully off-grid.
+set -euo pipefail
+
+echo "Starting llama-server (on-device MiniCPM-V)..."
+llama-server \
+  -m "${LOCAL_MODEL_PATH}" \
+  --mmproj "${LOCAL_MMPROJ_PATH}" \
+  --host 127.0.0.1 --port 8080 \
+  --ctx-size 4096 &
+
+# Wait until the model is loaded and the server answers /health (model load can take a while).
+echo "Waiting for llama-server to be ready..."
+for _ in $(seq 1 240); do
+  if curl -sf http://127.0.0.1:8080/health >/dev/null 2>&1; then
+    echo "llama-server is ready."
+    break
+  fi
+  sleep 2
+done
+
+echo "Starting Gradio app on port ${GRADIO_SERVER_PORT:-7860}..."
+exec python app.py