Select llama.cpp GGUF on CPU Basic Spaces

Co-authored-by: Codex <chatgpt-codex-connector[bot]@users.noreply.github.com>

DEPLOY.md

@@ -1,17 +1,20 @@
-# Deploying the Space with ZeroGPU
+# Deploying the Space
 
-The active Hugging Face deployment is a **Gradio ZeroGPU Space** with **Transformers vision** as the default extraction backend.
+The active Hugging Face deployment is a **Gradio Space** with hardware-aware extraction:
+
+- **CPU Basic:** llama.cpp with the base MiniCPM-V GGUF model.
+- **ZeroGPU / GPU:** Transformers vision with the fine-tuned MiniCPM-V checkpoint.
 
 This workflow is intentionally fixed:
 
 1. The Space must stay a Gradio Space, not a Docker Space.
-2. Runtime extraction should use the Transformers backend on ZeroGPU by default.
-3. The extraction call must run behind `@spaces.GPU` so Hugging Face allocates ZeroGPU only while the model is needed.
+2. Runtime extraction should use `EXTRACTOR_BACKEND=auto` unless a lane is being forced for testing.
+3. ZeroGPU extraction calls must run behind `@spaces.GPU`; CPU Basic llama.cpp calls must not require ZeroGPU.
 4. Model files must not be committed to the Space git repo.
 5. When the fine-tuned model is ready, replace only the model variables for the active lanes.
-6. The llama.cpp lane is optional and must be enabled explicitly with environment variables.
+6. The llama.cpp lane is automatic on CPU Basic and can still be enabled explicitly with environment variables.
 
-Do not change this architecture unless the project intentionally gives up ZeroGPU. To swap models, change `ZEROGPU_MODEL_ID` (or `DEFAULT_HF_REPO` in `src/model_paths.py`) and optional `LLAMACPP_*` for the llama.cpp lane.
+Do not change this architecture unless the project intentionally gives up hardware-aware deployment. To swap models, change `ZEROGPU_MODEL_ID` (or `DEFAULT_HF_REPO` in `src/model_paths.py`) and optional `LLAMACPP_*` for the llama.cpp lane.
 
 ## 1. Space Metadata
 
@@ -33,12 +36,25 @@ pinned: false
 
 ZeroGPU is Gradio-only on Hugging Face. It is not available for Docker Spaces, which is why the previous Docker + `llama-server` deployment was replaced.
 
-## 2. Default Model Serving (Transformers)
+## 2. Default Model Serving
+
+Leave `EXTRACTOR_BACKEND` unset or set it to:
+
+```text
+EXTRACTOR_BACKEND=auto
+```
+
+On **CPU Basic**, `auto` detects `cpu-basic` and selects llama.cpp vision with the base GGUF model:
+
+```text
+LLAMACPP_GGUF_REPO=openbmb/MiniCPM-V-4.6-gguf
+LLAMACPP_MODEL_FILE=MiniCPM-V-4_6-Q4_K_M.gguf
+LLAMACPP_MMPROJ_FILE=mmproj-model-f16.gguf
+```
 
-The production Space path is the fine-tuned Transformers repo:
+On **ZeroGPU/GPU**, `auto` selects the fine-tuned Transformers repo:
 
 ```text
-EXTRACTOR_BACKEND=transformers
 ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
@@ -61,11 +77,11 @@ transformers.AutoModelForImageTextToText
 
 This is the correct runtime for PDF/image blood-test uploads on ZeroGPU because the GPU is allocated only inside the decorated worker.
 
-Aliases `auto`, `zerogpu`, and `zero-gpu` resolve to the same Transformers path in `src/extraction/factory.py`.
+Aliases `zerogpu` and `zero-gpu` force the Transformers path in `src/extraction/factory.py`; `auto` is hardware-aware.
 
-## 3. Optional llama.cpp Lane
+## 3. llama.cpp Lane
 
-The app ships a second extraction lane for hackathon badges and GGUF deployment experiments. It is **not enabled by default**.
+The app ships a second extraction lane for CPU Basic, hackathon badges, and GGUF deployment experiments. It is automatic on CPU Basic.
 
 ### Why it exists
 
@@ -73,9 +89,9 @@ The app ships a second extraction lane for hackathon badges and GGUF deployment
 - **Fine-tuned GGUF swap** — deploy a quantized model without changing the Gradio app structure.
 - **Text-only fallback** — lighter lane for plain-text lab exports when vision is not needed.
 
-For normal PDF/image uploads, keep `EXTRACTOR_BACKEND=transformers`.
+For normal CPU Basic PDF/image uploads, keep `EXTRACTOR_BACKEND=auto` and let the code select llama.cpp vision.
 
-### Enable vision llama.cpp on the Space
+### Force vision llama.cpp on the Space
 
 Set these variables in the Space settings:
 
@@ -127,9 +143,10 @@ The Docker path failed on free CPU hardware with `OOMKilled` during build. ZeroG
 This architecture keeps:
 
 - Free ZeroGPU eligibility.
+- A CPU Basic fallback that uses llama.cpp + base GGUF instead of Transformers.
 - No external hosted inference API calls.
 - The fine-tuned Transformers runtime on ZeroGPU for PDF/image lab reports.
-- An optional llama.cpp / GGUF lane for badges and fine-tuned GGUF deployment.
+- A llama.cpp / GGUF lane for CPU Basic, badges, and fine-tuned GGUF deployment.
 - A clean model swap by changing `ZEROGPU_MODEL_ID` / `DEFAULT_HF_REPO` and optional `LLAMACPP_*` variables.
 
 ## 6. Local Development

README.md

@@ -42,7 +42,7 @@ The breakthrough was to stop teaching the model our schema and teach it general
 
 ## 🦙 Llama Champion
 
-The app ships two interchangeable backends behind one interface. The default runs the model through Transformers, and a second backend runs the same MiniCPM-V through the **llama.cpp** runtime, selectable with a single environment variable. We install the prebuilt llama.cpp wheel so the Space builds without a slow source compile, which means the model can run through the llama.cpp runtime when we point it there, while Transformers stays the default for the hosted demo.
+The app ships two interchangeable backends behind one interface. On CPU Basic Spaces, the default `auto` backend runs the base MiniCPM-V 4.6 GGUF through **llama.cpp** on CPU. On ZeroGPU/GPU, the same `auto` setting uses the fine-tuned Transformers model. We install the prebuilt llama.cpp wheel so the Space builds without a slow source compile, and the operator can still force the GGUF lane explicitly with `EXTRACTOR_BACKEND=llamacpp-gpu` and `LLAMACPP_VISION=1`.
 
 ## 🎨 Off-Brand
 

RUNBOOK.md

@@ -1,6 +1,9 @@
 # Runbook — Extraction Backends + Fine-Tuned Model Swap
 
-The active deployment path is **Gradio with Transformers vision on ZeroGPU**.
+The active deployment path is **hardware-aware Gradio**:
+
+- **CPU Basic:** llama.cpp with the base MiniCPM-V GGUF model.
+- **ZeroGPU / GPU:** Transformers vision with the fine-tuned MiniCPM-V checkpoint.
 
 This replaced the Docker + `llama-server` path because ZeroGPU is only available for Gradio SDK Spaces. The Docker build was also failing on free CPU hardware with `OOMKilled`.
 
@@ -9,9 +12,9 @@ This replaced the Docker + `llama-server` path because ZeroGPU is only available
 | Area | Current choice |
 |---|---|
 | Space SDK | `gradio` |
-| Default extraction | Fine-tuned MiniCPM-V 4.6 (`build-small-hackathon/blood-test-minicpmv-4_6-medreason`) |
+| Default extraction | `auto`: CPU Basic uses base GGUF through llama.cpp; ZeroGPU/GPU uses fine-tuned Transformers |
 | ZeroGPU worker | `@spaces.GPU` in `src/extraction/zerogpu_transformers.py` |
-| Optional llama.cpp lane | `EXTRACTOR_BACKEND=llamacpp-gpu` (+ `LLAMACPP_VISION=1` for PDF/images) |
+| llama.cpp lane | Automatic on CPU Basic, or forced with `EXTRACTOR_BACKEND=llamacpp-gpu` (+ `LLAMACPP_VISION=1` for PDF/images) |
 | Transformers variables | `ZEROGPU_MODEL_ID`, `ZEROGPU_MAX_NEW_TOKENS`, `ZEROGPU_DOWNSAMPLE_MODE` |
 | llama.cpp variables | `LLAMACPP_GGUF_REPO`, `LLAMACPP_MODEL_FILE`, `LLAMACPP_MMPROJ_FILE`, `LLAMACPP_VISION` |
 | Extraction backends | `src/extraction/factory.py`, `src/extraction/zerogpu_transformers.py`, `src/extraction/llamacpp_gpu.py` |
@@ -25,8 +28,8 @@ Do not switch the Space back to Docker unless the project intentionally gives up
 
 | Value | Behavior |
 |---|---|
-| `transformers` (default) | Fine-tuned MiniCPM-V through Transformers vision |
-| `auto`, `zerogpu`, `zero-gpu` | Same as `transformers` |
+| unset / `auto` (default) | Hardware-aware: CPU Basic -> llama.cpp base GGUF; otherwise Transformers |
+| `transformers`, `zerogpu`, `zero-gpu` | Force fine-tuned MiniCPM-V through Transformers vision |
 | `llamacpp-gpu`, `llama-champion` | GGUF through `llama-cpp-python` |
 | `local`, `server` | Local `llama-server` HTTP backend |
 | `llamacpp` | In-process local GGUF + mmproj |
@@ -35,15 +38,23 @@ Do not switch the Space back to Docker unless the project intentionally gives up
 ### Default path (production)
 
 ```bash
-EXTRACTOR_BACKEND=transformers
-ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
+# Usually leave EXTRACTOR_BACKEND unset, or set:
+EXTRACTOR_BACKEND=auto
 ```
 
-This is what the HF Space should use for PDF/image blood-test uploads. The env var is optional when it matches `DEFAULT_HF_REPO` in `src/model_paths.py`.
+On the current CPU Basic Space, `auto` selects llama.cpp vision with the base GGUF defaults:
+
+```bash
+LLAMACPP_GGUF_REPO=openbmb/MiniCPM-V-4.6-gguf
+LLAMACPP_MODEL_FILE=MiniCPM-V-4_6-Q4_K_M.gguf
+LLAMACPP_MMPROJ_FILE=mmproj-model-f16.gguf
+```
+
+When the Space is moved to ZeroGPU/GPU, `auto` selects Transformers and uses `ZEROGPU_MODEL_ID` or the default fine-tuned repo in `src/model_paths.py`.
 
 ### Optional llama.cpp path
 
-The llama.cpp lane is **opt-in**. It is not selected automatically.
+The llama.cpp lane is selected automatically on CPU Basic. It can also be forced explicitly.
 
 **Why keep it:**
 
@@ -99,7 +110,7 @@ transformers[torch]==5.7.0
 llama-cpp-python
 ```
 
-Transformers runs on ZeroGPU through `@spaces.GPU(duration=120)` (or longer for cold starts). The optional llama.cpp lane uses `@spaces.GPU(duration=600)` because GGUF inference can be slower.
+Transformers runs on ZeroGPU through `@spaces.GPU(duration=120)` (or longer for cold starts). llama.cpp bypasses `@spaces.GPU` on CPU Basic and runs as CPU inference; when forced on GPU/ZeroGPU it uses `@spaces.GPU(duration=600)`.
 
 On Linux x86_64 Spaces, `llama-cpp-python` comes from the prebuilt CPU manylinux wheel:
 
@@ -111,10 +122,15 @@ This avoids both the CUDA runtime mismatch that was causing the Space to abort o
 
 ## Current Model Defaults
 
-Primary lane:
+Auto lane:
+
+```bash
+EXTRACTOR_BACKEND=auto
+```
+
+Transformers lane:
 
 ```bash
-EXTRACTOR_BACKEND=transformers
 ZEROGPU_MODEL_ID=build-small-hackathon/blood-test-minicpmv-4_6-medreason
 ```
 
@@ -181,4 +197,4 @@ python3 -m py_compile app.py src/*.py src/extraction/*.py
 .venv/bin/python -m pytest tests/test_report_pipeline.py tests/test_llamacpp_gpu.py
 ```
 
-Then verify the Space build uses Gradio, not Docker, and that the default backend extracts PDF/image uploads through Transformers.
+Then verify the Space build uses Gradio, not Docker. On CPU Basic, the default backend should report `llamacpp-cpu-vision`; on ZeroGPU/GPU it should report the Transformers backend.

requirements.txt

@@ -4,13 +4,13 @@ requests==2.32.5
 pillow==12.0.0
 pymupdf==1.26.6
 json-repair==0.60.1
-# Local Transformers vision path (Mac + Linux GPU). Default EXTRACTOR_BACKEND=transformers.
+# Transformers vision path (Mac + Linux GPU, and non-CPU-Basic Space auto mode).
 torch==2.9.1 ; sys_platform == "darwin" or (sys_platform == "linux" and platform_machine == "x86_64")
 transformers[torch]==5.7.0
 accelerate==1.12.0
 bitsandbytes==0.48.2 ; sys_platform == "linux" and platform_machine == "x86_64"
 torchvision==0.24.1 ; sys_platform == "darwin" or (sys_platform == "linux" and platform_machine == "x86_64")
 av==16.0.1 ; sys_platform == "linux" and platform_machine == "x86_64"
-# CPU fallback path: install the prebuilt manylinux wheel directly to avoid a source build on Spaces.
+# CPU Basic / llama.cpp path: install the prebuilt manylinux wheel directly to avoid a source build on Spaces.
 llama-cpp-python @ https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.28/llama_cpp_python-0.3.28-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl ; sys_platform == "linux" and platform_machine == "x86_64"
 llama-cpp-python==0.3.28 ; sys_platform != "linux"

src/extraction/__init__.py

@@ -1,8 +1,8 @@
 """Extraction backends behind one interface.
 
 `build_extractor()` returns the right backend for the environment:
-  - **transformers** (default): local OpenBMB MiniCPM-V through Transformers.
-  - **auto**: same as transformers.
+  - unset / **auto** (default): CPU Basic Spaces use llama.cpp + base GGUF; other runtimes use Transformers.
+  - **transformers**: force OpenBMB MiniCPM-V through Transformers.
   - **llamacpp-gpu** / **llama-champion**: force GGUF through llama.cpp. Set `LLAMACPP_VISION=1`
     to run the same PDF/image vision pipeline as Transformers (requires mmproj).
   - **local**: local llama-server / llama.cpp backends for local experimentation.

src/extraction/factory.py

@@ -1,8 +1,9 @@
 """Backend selection.
 
 `EXTRACTOR_BACKEND` env:
-  - `transformers` (default): local OpenBMB MiniCPM-V through Transformers.
-  - `auto`: same as `transformers`.
+  - unset / `auto` (default): hardware-aware Space selection.
+    CPU Basic Spaces use llama.cpp + base MiniCPM-V GGUF; other runtimes use Transformers.
+  - `transformers`: local/OpenBMB MiniCPM-V through Transformers.
   - `zerogpu` / `zero-gpu`: alias for `transformers`.
   - `llamacpp-gpu` / `llama-champion`: llama.cpp GGUF badge path. Add `LLAMACPP_VISION=1`
     for PDF/image vision via mmproj.
@@ -21,8 +22,9 @@ from src.extraction.auto import AutoExtractor
 from src.extraction.llamacpp_gpu import LlamaCppGPUExtractor
 from src.extraction.local_minicpmv import LocalMiniCPMVExtractor
 from src.extraction.local_server import LocalServerExtractor
+from src.space_runtime import configured_space_hardware, is_cpu_basic_space, is_huggingface_space
 
-_DEFAULT_BACKEND = "transformers"
+_DEFAULT_BACKEND = "auto"
 _DISABLED_BACKENDS = {"api", "openbmb", "hosted"}
 
 
@@ -35,7 +37,25 @@ def build_extractor(model: str | None = None) -> Extractor:
             "Use EXTRACTOR_BACKEND=transformers for local MiniCPM-V extraction."
         )
 
-    if backend in ("auto", "zerogpu", "zero-gpu", "transformers"):
+    if backend == "auto":
+        if is_cpu_basic_space():
+            hardware = configured_space_hardware()
+            if hardware:
+                os.environ.setdefault("BTE_SPACE_HARDWARE", hardware)
+            os.environ.setdefault("LLAMACPP_VISION", "1")
+            print(
+                "[Blood Test Explainer] CPU Basic Space detected; using llama.cpp "
+                "(base MiniCPM-V GGUF)",
+                flush=True,
+            )
+            return LlamaCppGPUExtractor()
+        if is_huggingface_space():
+            print(
+                "[Blood Test Explainer] non-CPU-Basic Space detected; using Transformers extractor",
+                flush=True,
+            )
+        return AutoExtractor(model_id=model)
+    if backend in ("zerogpu", "zero-gpu", "transformers"):
         return AutoExtractor(model_id=model)
     if backend in ("llamacpp-gpu", "gpu-llamacpp", "llama-champion"):
         from src.extraction.llamacpp_vision import llamacpp_vision_enabled

src/extraction/llamacpp_gpu.py

@@ -39,6 +39,7 @@ from src.openbmb_client import (
     _parse_json_response,
     summarize_document_parts,
 )
+from src.space_runtime import is_cpu_basic_space
 
 DEFAULT_GGUF_REPO = "openbmb/MiniCPM-V-4.6-gguf"
 DEFAULT_MODEL_FILE = "MiniCPM-V-4_6-Q4_K_M.gguf"
@@ -69,6 +70,7 @@ class LlamaCppGPUExtractor:
         self.n_ctx = int(os.getenv("LLAMACPP_N_CTX", "8192"))
         self.n_gpu_layers = int(os.getenv("LLAMACPP_N_GPU_LAYERS", "0"))
         self.vision_enabled = llamacpp_vision_enabled()
+        self.use_spaces_gpu = not is_cpu_basic_space()
         if self.vision_enabled and not self.mmproj_file:
             raise ValueError("LLAMACPP_VISION=1 requires LLAMACPP_MMPROJ_FILE.")
 
@@ -76,7 +78,12 @@ class LlamaCppGPUExtractor:
         parts = document_to_payload_parts(file_path, max_pages=max_pages)
         started = time.perf_counter()
         if self.vision_enabled:
-            raw = _run_llamacpp_vision_generation(
+            runner = (
+                _run_llamacpp_vision_generation
+                if self.use_spaces_gpu
+                else _run_llamacpp_vision_generation_cpu
+            )
+            raw = runner(
                 parts=parts,
                 repo=self.repo,
                 model_file=self.model_file,
@@ -86,11 +93,16 @@ class LlamaCppGPUExtractor:
                 n_ctx=self.n_ctx,
                 n_gpu_layers=self.n_gpu_layers,
             )
-            backend = "llamacpp-gpu-vision"
+            backend = "llamacpp-gpu-vision" if self.use_spaces_gpu else "llamacpp-cpu-vision"
             composed_prompt = None
         else:
             prompt_text = _compose_prompt(parts)
-            raw = _run_llamacpp_generation(
+            runner = (
+                _run_llamacpp_generation
+                if self.use_spaces_gpu
+                else _run_llamacpp_generation_cpu
+            )
+            raw = runner(
                 prompt_text=prompt_text,
                 repo=self.repo,
                 model_file=self.model_file,
@@ -98,7 +110,7 @@ class LlamaCppGPUExtractor:
                 n_ctx=self.n_ctx,
                 n_gpu_layers=self.n_gpu_layers,
             )
-            backend = "llamacpp-gpu"
+            backend = "llamacpp-gpu" if self.use_spaces_gpu else "llamacpp-cpu"
             composed_prompt = prompt_text
 
         duration_ms = int((time.perf_counter() - started) * 1000)
@@ -108,6 +120,7 @@ class LlamaCppGPUExtractor:
             "repo": self.repo,
             "model": self.model_file,
             "vision_enabled": self.vision_enabled,
+            "spaces_gpu": self.use_spaces_gpu,
             "document_parts": len(parts),
             "max_pages": max_pages,
             "extraction_prompt": EXTRACTION_PROMPT,
@@ -177,6 +190,28 @@ def _run_llamacpp_vision_generation(
     max_tokens: int,
     n_ctx: int,
     n_gpu_layers: int,
+) -> str:
+    return _run_llamacpp_vision_generation_cpu(
+        parts=parts,
+        repo=repo,
+        model_file=model_file,
+        mmproj_file=mmproj_file,
+        chat_handler=chat_handler,
+        max_tokens=max_tokens,
+        n_ctx=n_ctx,
+        n_gpu_layers=n_gpu_layers,
+    )
+
+
+def _run_llamacpp_vision_generation_cpu(
+    parts: list[dict[str, Any]],
+    repo: str,
+    model_file: str,
+    mmproj_file: str,
+    chat_handler: str,
+    max_tokens: int,
+    n_ctx: int,
+    n_gpu_layers: int,
 ) -> str:
     try:
         model_path = download_hf_file(repo, model_file)
@@ -217,6 +252,24 @@ def _run_llamacpp_generation(
     max_tokens: int,
     n_ctx: int,
     n_gpu_layers: int,
+) -> str:
+    return _run_llamacpp_generation_cpu(
+        prompt_text=prompt_text,
+        repo=repo,
+        model_file=model_file,
+        max_tokens=max_tokens,
+        n_ctx=n_ctx,
+        n_gpu_layers=n_gpu_layers,
+    )
+
+
+def _run_llamacpp_generation_cpu(
+    prompt_text: str,
+    repo: str,
+    model_file: str,
+    max_tokens: int,
+    n_ctx: int,
+    n_gpu_layers: int,
 ) -> str:
     try:
         model_path = download_hf_file(repo, model_file)

src/space_runtime.py

@@ -0,0 +1,47 @@
+"""Helpers for hardware-aware Hugging Face Space behavior."""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+
+_HARDWARE_ENV_KEYS = (
+    "BTE_SPACE_HARDWARE",
+    "SPACE_HARDWARE",
+    "HF_SPACE_HARDWARE",
+)
+
+
+def is_huggingface_space() -> bool:
+    return bool(os.getenv("SPACE_ID") or os.getenv("SPACE_HOST"))
+
+
+def configured_space_hardware() -> str | None:
+    for key in _HARDWARE_ENV_KEYS:
+        value = os.getenv(key, "").strip().lower()
+        if value:
+            return value
+    return _hub_space_hardware()
+
+
+def is_cpu_basic_space() -> bool:
+    return configured_space_hardware() == "cpu-basic"
+
+
+@lru_cache(maxsize=8)
+def _hub_space_hardware() -> str | None:
+    repo_id = os.getenv("SPACE_ID", "").strip()
+    if not repo_id:
+        return None
+    try:
+        from huggingface_hub import HfApi
+
+        info = HfApi().space_info(repo_id=repo_id)
+        runtime = getattr(info, "runtime", None)
+        hardware = getattr(runtime, "hardware", None)
+        if hardware:
+            return str(hardware).strip().lower()
+    except Exception:
+        return None
+    return None

tests/test_extraction_factory.py

@@ -0,0 +1,32 @@
+import sys
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.extraction.factory import build_extractor
+
+
+def test_auto_uses_llamacpp_on_cpu_basic_space(monkeypatch):
+    monkeypatch.delenv("EXTRACTOR_BACKEND", raising=False)
+    monkeypatch.delenv("LLAMACPP_VISION", raising=False)
+    monkeypatch.setenv("BTE_SPACE_HARDWARE", "cpu-basic")
+
+    with patch("src.extraction.factory.LlamaCppGPUExtractor") as llama_cls:
+        extractor = build_extractor()
+
+    llama_cls.assert_called_once_with()
+    assert extractor is llama_cls.return_value
+    assert os.environ["LLAMACPP_VISION"] == "1"
+
+
+def test_auto_uses_transformers_when_hardware_is_not_cpu_basic(monkeypatch):
+    monkeypatch.delenv("EXTRACTOR_BACKEND", raising=False)
+    monkeypatch.setenv("BTE_SPACE_HARDWARE", "zero-a10g")
+
+    with patch("src.extraction.factory.AutoExtractor") as auto_cls:
+        extractor = build_extractor(model="demo/model")
+
+    auto_cls.assert_called_once_with(model_id="demo/model")
+    assert extractor is auto_cls.return_value

tests/test_llamacpp_gpu.py

@@ -37,6 +37,7 @@ def test_compose_prompt_keeps_text_files():
 
 def test_extract_uses_vision_generation_when_enabled(monkeypatch):
     monkeypatch.setenv("LLAMACPP_VISION", "1")
+    monkeypatch.delenv("BTE_SPACE_HARDWARE", raising=False)
     image_parts = [{"type": "image_url", "image_url": {"url": "data:image/png;base64,abc"}}]
 
     with patch(
@@ -55,10 +56,34 @@ def test_extract_uses_vision_generation_when_enabled(monkeypatch):
     assert result.request_summary["backend"] == "llamacpp-gpu-vision"
     assert result.request_summary["vision_enabled"] is True
     assert result.request_summary["mmproj"]
+    assert result.request_summary["spaces_gpu"] is True
+
+
+def test_cpu_basic_uses_plain_cpu_vision_runner(monkeypatch):
+    monkeypatch.setenv("BTE_SPACE_HARDWARE", "cpu-basic")
+    monkeypatch.setenv("LLAMACPP_VISION", "1")
+    image_parts = [{"type": "image_url", "image_url": {"url": "data:image/png;base64,abc"}}]
+
+    with patch(
+        "src.extraction.llamacpp_gpu.document_to_payload_parts",
+        return_value=image_parts,
+    ), patch(
+        "src.extraction.llamacpp_gpu._run_llamacpp_vision_generation_cpu",
+        return_value='{"patient":{},"tests":[],"notes":[]}',
+    ) as cpu_run, patch(
+        "src.extraction.llamacpp_gpu._run_llamacpp_vision_generation",
+    ) as gpu_run:
+        result = LlamaCppGPUExtractor().extract("/tmp/report.pdf")
+
+    cpu_run.assert_called_once()
+    gpu_run.assert_not_called()
+    assert result.request_summary["backend"] == "llamacpp-cpu-vision"
+    assert result.request_summary["spaces_gpu"] is False
 
 
 def test_extract_uses_text_generation_when_vision_disabled(monkeypatch):
     monkeypatch.delenv("LLAMACPP_VISION", raising=False)
+    monkeypatch.delenv("BTE_SPACE_HARDWARE", raising=False)
     text_parts = [{"type": "text", "text": "WBC 6.5"}]
 
     with patch(