chore(backend): port house-scanning-server into the monorepo

backend/.dockerignore

@@ -0,0 +1,4 @@
+*
+!pyproject.toml
+!uv.lock
+!Dockerfile

backend/.gitignore

@@ -0,0 +1,55 @@
+# Base-provided prompt material and anything else that must not reach GitHub.
+private/
+
+.venv/
+__pycache__/
+.env
+.env.*
+.terraform/
+*.tfstate
+*.tfstate.*
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+.DS_Store
+runs/
+.fixtures/
+
+# data/ holds scripts and manifests only; frames, packets and videos live in the store or on disk.
+data/houses/
+data/packets/
+data/frames/
+data/**/*.jpg
+data/**/*.jpeg
+data/**/*.png
+data/**/*.heic
+data/**/*.mp4
+data/**/*.mov
+data/**/*.npz
+data/**/*.ply
+data/**/*.bin
+
+# Fetched tars, PLYs and extracts. Never commit them.
+.fixtures/
+
+# scripts/reads_gate.py --live --out. Holds real meter numbers (barcode payloads
+# and reader answers). The default is /tmp/reads-gate, outside the repo. Never
+# commit or upload this folder, including an in-repo copy such as reads-gate-live.
+reads-gate*/
+
+# Golden fixtures that are committed on purpose (coverage grids, mini-arkit stills).
+!data/fixtures/**/*.jpg
+!data/fixtures/**/*.jpeg
+!data/fixtures/**/*.npz
+!data/fixtures/**/*.bin
+
+# Reconstruction outputs. Small JSON results under breadth outputs/ folders are committed.
+*.ply
+*.splat
+# The build-plan reference set is the exception: ETH3D facade clouds for reviewers.
+!media/colmap-facade/point-clouds/*.ply
+
+# Terraform provider cache. Lock files stay committed.
+.terraform/

backend/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: hygiene
+        name: repo hygiene
+        entry: uv run --frozen python scripts/check_repo_hygiene.py
+        language: system
+        pass_filenames: false

backend/.python-version

@@ -0,0 +1 @@
+3.12

backend/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+## Branches and pull requests
+
+- `main` is protected by convention: nobody pushes to it directly after the initial import, and agents never merge.
+- **Breadth work lands on branches named `breadth/<path-id>`, opened as draft pull requests.** Path ids match the folders: `a1-classical`, `a2-feedforward`, `a3-depth-fusion`, `a4-gaussian-splatting`, `a5-world-models`, `a6-iphone-quality`, `a7-iphone-degradation`, `a8-scale-without-lidar`, `a9-no-tape-scale`, `a10-sparse-photo-flow`, `b1-detection`, `b2-equipment-reading`, `b3-cheap-gate`, `c1-rules-3d`, `c2-volumetric`, `c3-vlm`, `e2e-criteria-on-recon`.
+- Keep one writer per branch. Each breadth pull request ends with the standard one-page result: metrics, runtime, cost, failure modes, licence, and a go / no-go.
+- Other work uses a short descriptive branch name and a draft pull request.
+- Breadth agents that work in the Project store don't push themselves: `scripts/sync_breadth.sh <path-id>...` (or `--all`) copies `internal/breadth/<folder>/` and the path's result file (as `RESULTS.md`) onto `breadth/<path-id>` and pushes it. It skips photos, model outputs, weights, files over 5 MB, real meter numbers (`raw/meter/`, `labels/meter_numbers_hand.csv`), and Base SSR prompt text or a digest of it.
+
+## Snapshot folders
+
+These are copied from the team's Cursor Project store by `scripts/sync_from_store.sh`, and edits made here are overwritten on the next sync:
+
+- `packet/` (from `internal/packet-generator/`)
+- `eval/` (from `internal/eval-harness/`)
+- `criteria/spec/` (from `internal/criteria/`)
+- `data/scripts/` and `data/manifest.json` (from `internal/data/`)
+- `docs/capture-packet-spec.md`, `docs/criteria-spec.md`, `docs/scene-and-verdict-format.md`
+
+Change them in the store, then run `scripts/sync_from_store.sh`. It creates a `sync/store-<timestamp>` branch from `origin/main`, re-copies the folders, and leaves the changes uncommitted for review. Lint is relaxed for these folders until the store copies are cleaned up.
+
+## What never gets committed
+
+- Anything in `private/`, including the prompt material Base gave the team. The sync script puts it there locally.
+- Images, videos, packets, point clouds and other large binaries. The sync skips files over 5 MB; `data/` holds scripts and manifests only.
+- ML runs on Google Maps / Street View, Mapbox or Esri imagery, whose terms forbid it. Use StratMap or NAIP.
+
+## Checks
+
+CI runs `ruff check`, `ruff format --check` and `pytest` on every push to `main` and every pull request. Run them locally with `uv run ruff check . && uv run ruff format --check . && uv run pytest`.

backend/Dockerfile

@@ -0,0 +1,111 @@
+# GPU pipeline image. Application code is not copied here; Modal adds server/
+# with add_local_python_source. COLMAP 4.2.0 matches pycolmap==4.2.0 (SD-34).
+# linux/amd64 digest of nvidia/cuda:12.4.1-devel-ubuntu22.04.
+FROM nvidia/cuda:12.4.1-devel-ubuntu22.04@sha256:5645fec64549cc35930eee9d85aafd2b0006c0c3f22632be5a1d85e2604e9749
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    HF_HOME=/vol/hf \
+    HUGGINGFACE_HUB_CACHE=/vol/hf/hub \
+    TORCH_HOME=/vol/torch \
+    PYTHONUNBUFFERED=1 \
+    PATH=/app/.venv/bin:$PATH
+
+# Jammy's Ceres package is 1.14. COLMAP 4.2 needs Ceres >= 2.2, so that
+# package is not installed; Ceres 2.2.0 is built below. OpenImageIO's Ubuntu
+# CMake config looks for /usr/include/opencv4 even when OpenCV is unused.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git \
+        cmake \
+        ninja-build \
+        build-essential \
+        libboost-program-options-dev \
+        libboost-filesystem-dev \
+        libboost-graph-dev \
+        libboost-system-dev \
+        libeigen3-dev \
+        libopenimageio-dev \
+        openimageio-tools \
+        libmetis-dev \
+        libgoogle-glog-dev \
+        libgflags-dev \
+        libsqlite3-dev \
+        libsuitesparse-dev \
+        libcurl4-openssl-dev \
+        libssl-dev \
+        libglew-dev \
+        libgl1-mesa-dev \
+        libglu1-mesa-dev \
+        libcgal-dev \
+        libopenblas-dev \
+        liblapack-dev \
+        ca-certificates \
+    && mkdir -p /usr/include/opencv4 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN git clone --branch 2.2.0 --depth 1 https://github.com/ceres-solver/ceres-solver.git /tmp/ceres \
+    && cmake -S /tmp/ceres -B /tmp/ceres/build -GNinja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_INSTALL_PREFIX=/usr/local \
+        -DBUILD_TESTING=OFF \
+        -DBUILD_EXAMPLES=OFF \
+        -DBUILD_BENCHMARKS=OFF \
+    && ninja -C /tmp/ceres/build -j3 \
+    && ninja -C /tmp/ceres/build install \
+    && rm -rf /tmp/ceres
+
+# A 3.11.1 binary under a 4.x pycolmap wheel is forbidden. Tag 4.2.0 is the
+# COLMAP release pycolmap 4.2.0 is built against. The PyPI pycolmap wheel is
+# CPU-only (has_cuda is false). pycolmap-cuda12 is installed last: the Pi3,
+# MoGe, and Depth Anything archives depend on pycolmap and would replace an
+# earlier CUDA wheel with the CPU one. The NVIDIA CUDA 12.4 image is not
+# Ubuntu's CUDA package, so the jammy GCC 10 workaround does not apply.
+# OpenImageIO's CMake config requires the OpenEXR config, which is not pulled
+# in by libopenimageio-dev alone.
+# Jammy's CMake is 3.22. COLMAP 4.2 fetches faiss, which requires CMake >= 3.24.
+RUN apt-get update && apt-get install -y --no-install-recommends curl libopenexr-dev \
+    && curl -fsSL -o /tmp/cmake.tgz https://github.com/Kitware/CMake/releases/download/v3.31.8/cmake-3.31.8-linux-x86_64.tar.gz \
+    && echo "630615d8e98ac33eba7fbe472626dff5c899c85af3c024585ae109166a6909d0  /tmp/cmake.tgz" | sha256sum -c - \
+    && tar -C /usr/local --strip-components=1 -xzf /tmp/cmake.tgz \
+    && rm -rf /tmp/cmake.tgz /var/lib/apt/lists/* \
+    && git clone --branch 4.2.0 --depth 1 https://github.com/colmap/colmap.git /tmp/colmap \
+    && cmake -S /tmp/colmap -B /tmp/colmap/build -GNinja \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_CUDA_ARCHITECTURES="80;86;89;90" \
+        -DGUI_ENABLED=OFF \
+        -DTESTS_ENABLED=OFF \
+        -DCMAKE_INSTALL_PREFIX=/usr/local \
+    && ninja -C /tmp/colmap/build -j3 \
+    && ninja -C /tmp/colmap/build install \
+    && ldconfig \
+    && (colmap -h > /tmp/colmap-help.txt || true) \
+    && grep -q COLMAP /tmp/colmap-help.txt \
+    && rm -rf /tmp/colmap /tmp/colmap-help.txt
+
+# Tag 0.11.23, pinned by digest. Modal's builder rejects a reference that sets both.
+COPY --from=ghcr.io/astral-sh/uv@sha256:d0a0a753ab981624b49c97abc98821c1c09f4ca69d1ef5cee69c501be3d88479 /uv /uvx /bin/
+
+RUN uv python install 3.12
+
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+# libsm6/libice6/libx11/libxext are NEEDED by the CUDA wheel. --no-deps keeps
+# pip's cuda-toolkit meta-package off this image; CUDA 12.4 is already here.
+RUN apt-get update && apt-get install -y --no-install-recommends libsm6 libice6 libx11-6 libxext6 \
+    && rm -rf /var/lib/apt/lists/* \
+    && uv sync --frozen --no-install-project --no-dev --extra gpu \
+    && uv pip install --python /app/.venv/bin/python pip \
+    && curl -fsSL -o /tmp/pi3.tgz "https://github.com/yyfz/Pi3/archive/9fa3ddb3f8d53041f8b2738df404f62223bbaa7b.tar.gz" \
+    && echo "017c226430e69bd3508940f326bce3db6e3eb778d7efe088b7fe6374cd550431  /tmp/pi3.tgz" | sha256sum -c - \
+    && curl -fsSL -o /tmp/moge.tgz "https://github.com/microsoft/MoGe/archive/925b8ed835a7a9cdb7578ba15c658a0afc969030.tar.gz" \
+    && echo "c6d90b2564d643f0f3ae65b5ffe163abaea3b55d194c6e2ba9976d67f552bd26  /tmp/moge.tgz" | sha256sum -c - \
+    && curl -fsSL -o /tmp/da3.tgz "https://github.com/ByteDance-Seed/Depth-Anything-3/archive/3d835ec1a5802d64a8b8b15f817a1ab54809bfe4.tar.gz" \
+    && echo "98aa2dd53ab44b96cef5190ae4841c6ae51797d099b784e08e12a1a55bd3a69b  /tmp/da3.tgz" | sha256sum -c - \
+    && uv pip install --python /app/.venv/bin/python /tmp/pi3.tgz /tmp/moge.tgz /tmp/da3.tgz \
+    && rm -f /tmp/pi3.tgz /tmp/moge.tgz /tmp/da3.tgz \
+    && uv pip install --python /app/.venv/bin/python \
+        torch==2.5.1 torchvision==0.20.1 \
+        --index-url https://download.pytorch.org/whl/cu124 \
+    && uv pip uninstall --python /app/.venv/bin/python pycolmap pycolmap-cuda12 \
+    && uv pip install --python /app/.venv/bin/python --no-deps "pycolmap-cuda12==4.2.0"
+
+RUN python -c "import pycolmap; assert pycolmap.__version__.startswith('4.2'), pycolmap.__version__; assert pycolmap.has_cuda, pycolmap.has_cuda"

backend/Makefile

@@ -0,0 +1,137 @@
+# `ci` includes `validate` (committed fixtures only). Large PLYs and tars stay in `.fixtures/`.
+.PHONY: setup lint test schemas hygiene fixtures gt validate validate-full ci gates-offline gates-update e2e e2e-local lamar criteria-golden e2e-dev orchestrator-e2e ios-kit result-golden reads-gate reads-extra weights
+
+ONLY ?= small
+
+setup:
+	uv sync --frozen
+
+lint:
+	uv run --frozen ruff check .
+	uv run --frozen ruff format --check .
+	uv run --frozen lint-imports
+
+# api extra only. `--all-extras` installs the gpu torch pin, and the OWLv2
+# parity test then runs on agent-store B1 images and misses by one box.
+test:
+	uv run --frozen --extra api pytest -q
+
+schemas:
+	uv run --frozen python -m server.contracts.export_schemas --check
+
+hygiene:
+	uv run --frozen python scripts/check_repo_hygiene.py
+
+fixtures:
+	uv run --frozen python scripts/fetch_fixtures.py --only $(ONLY) $(if $(ITEM),--item $(ITEM),)
+
+# Public Hugging Face weights onto house-capture-pipeline:/vol/hf.
+# Local-dir <org>--<repo> and hub/models--<org>--<repo> (see server/weights/fetch.py).
+weights:
+	SMP_ENVIRONMENT=dev uv run modal run -e dev -m server.weights.fetch
+
+gt:
+	bash scripts/rebuild_gt.sh
+
+validate:
+	uv run --frozen python scripts/validate_fixtures.py
+
+validate-full:
+	uv run --frozen python scripts/validate_fixtures.py --full
+
+ci: lint test schemas hygiene validate
+
+# Scores the committed fixtures. Producers write under runs/ unless --update.
+gates-offline:
+	nice -n 10 uv run --frozen python -m server.eval.cli gates --config server/eval/gates.yaml --inputs data/fixtures --out runs/gates-offline/gates.json
+
+gates-update:
+	uv run --frozen python -m server.eval.producers --update --inputs data/fixtures
+	uv run --frozen python -m server.eval.cli gates --refresh-hashes --config server/eval/gates.yaml --inputs data/fixtures
+	$(MAKE) gates-offline
+
+e2e:
+	nice -n 10 uv run python -m server.eval.e2e --config server/eval/gates.yaml --inputs data/fixtures --out runs/e2e/latest
+
+e2e-local:
+	nice -n 10 uv run python -m server.eval.e2e --local --config server/eval/gates.yaml --inputs data/fixtures --out runs/e2e/local
+
+lamar:
+	nice -n 10 uv run python -m server.eval.lamar run --data $(HOME)/lamar --out runs/lamar
+
+# Unit suite, then verdicts for the three ETH3D laser sites at /tmp/crit/<site>/.
+# Laser PLYs come from `make fixtures ONLY=all`. C3 stays off.
+criteria-golden:
+	uv run --frozen pytest server/criteria/tests -q
+	HSS_CRITERIA_C3=off VISION_EXTERNAL_CALLS=off uv run --frozen python -m server.criteria.run --scene data/fixtures/scenes/eth3d-facade/gt-laser/scene.json --out /tmp/crit/facade --no-c3
+	HSS_CRITERIA_C3=off VISION_EXTERNAL_CALLS=off uv run --frozen python -m server.criteria.run --scene data/fixtures/scenes/eth3d-delivery/gt-laser/scene.json --out /tmp/crit/delivery --no-c3
+	HSS_CRITERIA_C3=off VISION_EXTERNAL_CALLS=off uv run --frozen python -m server.criteria.run --scene data/fixtures/scenes/eth3d-electro/gt-laser/scene.json --out /tmp/crit/electro --no-c3
+
+# SD-77: the live stack only (Modal dev capture-api, house-scanning bucket).
+# CAPTURE_API_URL must be https://huntertcarver-dev--capture-api.modal.run
+# SD-86: no CAPTURE_API_TOKEN. PACKET=path/to/packet.json (or its directory).
+e2e-dev:
+	PYTHONPATH=. uv run --frozen python scripts/e2e_dev.py --self-check
+	PYTHONPATH=. uv run --frozen python scripts/e2e_dev.py $(if $(PACKET),--packet $(PACKET),)
+
+orchestrator-e2e:
+	STATE_BACKEND=memory STORAGE_BACKEND=local HSS_ORCH_STAGE_STUBS=1 VISION_EXTERNAL_CALLS=off SMP_ENVIRONMENT=dev \
+		uv run --frozen pytest server/orchestrator/tests -q
+
+# Refresh the committed schema copies and pack the zip the iOS team installs.
+ios-kit:
+	cp server/contracts/schemas/capture-packet.v0.4.schema.json ios-kit/schemas/capture-packet.v0.4.schema.json
+	cp server/contracts/schemas/result.v0.schema.json ios-kit/schemas/result.v0.schema.json
+	cp server/contracts/schemas/api.v1.schema.json ios-kit/schemas/api.v1.schema.json
+	cp server/contracts/schemas/capture-packet.v0.4.schema.json ios-kit/schema/capture-packet.schema.json
+	cp data/fixtures/packets/examples/example-packet.json ios-kit/examples/packets/example-packet.json
+	cp data/fixtures/packets/examples/example-packet-photo-only.json ios-kit/examples/packets/example-packet-photo-only.json
+	cp data/fixtures/packets/mini-arkit/packet.json ios-kit/examples/packets/example-packet-meter-stills.json
+	rm -rf dist/ios-kit-stage dist/ios-kit-0.4.0.zip
+	mkdir -p dist/ios-kit-stage/spec dist/ios-kit-stage/schema dist/ios-kit-stage/fixtures
+	cp ios-kit/README.md ios-kit/VERSION ios-kit/CHANGELOG.md ios-kit/requirements.txt dist/ios-kit-stage/
+	cp docs/capture-packet-spec.md dist/ios-kit-stage/spec/capture-packet-spec.md
+	cp -R ios-kit/schemas ios-kit/examples ios-kit/prompts ios-kit/packetgen dist/ios-kit-stage/
+	cp ios-kit/schema/capture-packet.schema.json dist/ios-kit-stage/schema/
+	cp ios-kit/fixtures/LICENCE-NOTES.md dist/ios-kit-stage/fixtures/
+	cp -R ios-kit/fixtures/mini-arkit ios-kit/fixtures/mini-arkit-lidar ios-kit/fixtures/mini-photo-only dist/ios-kit-stage/fixtures/
+	cd dist/ios-kit-stage && zip -qr ../ios-kit-0.4.0.zip . -x '*__pycache__*'
+	rm -rf dist/ios-kit-stage
+	cmp server/contracts/schemas/capture-packet.v0.4.schema.json ios-kit/schemas/capture-packet.v0.4.schema.json
+
+# Compose the committed synthetic fixture. ETH3D rows wait on make fixtures and make criteria-golden.
+result-golden:
+	uv run --frozen --extra result python -m server.result.compose \
+	  --capture server/result/tests/data/capture.sample.json \
+	  --run server/result/tests/data/run.ok.json \
+	  --scene server/result/tests/data/synthetic \
+	  --verdicts server/result/tests/data/synthetic/verdicts \
+	  --out /tmp/res/synthetic \
+	  --reads server/result/tests/data/reads.auto_fill.json \
+	  --catalogue server/result/tests/data/prompts.en-US.json
+	uv run --frozen --extra result python -m server.result.compose \
+	  --capture server/result/tests/data/capture.sample.json \
+	  --run server/result/tests/data/run.ok.json \
+	  --scene server/result/tests/data/photo \
+	  --verdicts server/result/tests/data/photo/verdicts \
+	  --out /tmp/res/photo \
+	  --catalogue server/result/tests/data/prompts.en-US.json
+	uv run --frozen --extra result python -m server.result.compose \
+	  --capture server/result/tests/data/capture.sample.json \
+	  --run server/result/tests/data/run.ok.json \
+	  --scene server/result/tests/data/synthetic \
+	  --verdicts server/result/tests/data/reject/verdicts \
+	  --out /tmp/res/reject \
+	  --catalogue server/result/tests/data/prompts.en-US.json \
+	  --show-reject
+	uv run --frozen --extra result python -c "from server.contracts.result import ResultResponse; import json; \
+	[ResultResponse.model_validate(json.load(open(f'/tmp/res/{name}/result.json'))) for name in ('synthetic','photo','reject')]; print('ok synthetic photo reject')"
+
+reads-gate:
+	uv run --frozen python scripts/reads_gate.py --set meter --set panel --set extra --out /tmp/reads-gate
+
+reads-extra:
+	uv sync --frozen --extra reads
+	uv run --frozen --extra reads python -c "import openai, zxingcpp"
+
+include infra/deploy.mk