Adds two research-only VprStrategy implementations for the IT-12
comparative-study matrix. MegaLocStrategy (D=2048, 322x322) and
MixVprStrategy (D=4096, 320x320), both via C7 TensorRT FP16 with
their own concrete BackbonePreprocessor. Single-stage global L2
normalisation; retrieval delegated to FaissBridge; FDR records +
structured logs identical to UltraVPR. BUILD_VPR_MEGALOC and
BUILD_VPR_MIXVPR ON for research/replay-cli only, OFF for airborne
and operator-tooling (fail-fast at composition root via existing
AZ-336 factory). Uses helpers.iso_ts_from_clock from day 1 — no
new timestamp helper duplicates introduced.
36 parametrised AC tests + 25 protocol-conformance + 18 helper
regression tests pass; 1690 / 1690 unit tests pass (excluding 1
pre-existing flaky cold-start subprocess test in c12). Verdict:
PASS_WITH_WARNINGS — one Medium follow-on (AZ-527 to consolidate
4-way _assert_engine_output_dim) + one Low AC wording drift.
Co-authored-by: Cursor <cursoragent@cursor.com>
UltraVPR is the Documentary Lead's PRIMARY backbone per
description.md § 1 and is wired by default
(config.c2_vpr.strategy = "ultra_vpr"). Runs on the C7 TensorRT
runtime (AZ-298) or ONNX-Runtime fallback (AZ-299); explicitly NOT
on the PyTorch FP16 runtime so a TRT engine compile bug can fall
back to NetVLAD without simultaneously breaking both strategies.
Production changes:
- c2_vpr/ultra_vpr.py - UltraVprStrategy + module-level create()
factory. embed_query pipeline: preprocess -> runtime.infer ->
single-stage L2 -> VprQuery. retrieve_topk delegates one-line to
FaissBridge. Engine load + output-shape assertion happen at
create() time (AC-6) so misconfiguration surfaces at startup,
not 17 minutes into a flight. UltraVPR has D=512 fixed (NOT a
config knob; AC-5 / AC-6 / AC-7 all assume 512). Single-stage L2
(no intra-cluster step like NetVLAD; spy-test enforces this so a
future refactor cannot silently regress recall).
- c2_vpr/_preprocessor_ultra_vpr.py - centre-crop using the camera
calibration's principal point (cx, cy from intrinsics_3x3),
falling back to geometric centre + WARN log when calibration is
absent (AC-9). Resize -> (384, 384) -> ImageNet mean/std ->
FP16 NCHW.
- No composition-root changes: UltraVPR consumes a pre-compiled
.trt engine (no PyTorch nn.Module), so the strategy module does
NOT expose MODEL_NAME / architecture_factory. The composition-
root _register_strategy_architecture helper no-ops cleanly for
this case (verified by test_create_does_not_register_pytorch_architecture).
Tests:
- tests/unit/c2_vpr/test_ultra_vpr.py - 29 tests covering all 12
ACs + preprocessor contract + constructor validation + FDR
record emission + single-stage L2 enforcement.
Full unit suite: 1637 passed / 80 env-skipped (+29 new tests).
Per-batch code review (batch_47_review.md): PASS_WITH_WARNINGS
(3 Low-severity findings; no Critical / High / Medium):
- F1: _iso_ts_from_clock is now the 7th copy (AZ-508 will close).
- F2: AZ-337 spec uses outdated C7 API names; affects upcoming
AZ-339 / AZ-340. Spec-hygiene PBI recommended.
- F3: principal-point fallback uses (0, 0) zero-detection for
missing calibration; safe but tightens when intrinsics become
Optional.
Architectural notes:
- AZ-507 layering clean. Imports only InferenceRuntimeCut,
DescriptorIndexCut, c2_vpr internals, _types, helpers,
clock, fdr_client. Architecture lint test passes.
- Pattern parity with NetVLAD (B46) where semantics permit;
UltraVPR-specific paths (single-stage L2, 'embedding' output
key, TRT runtime, no architecture registry, principal-point
crop) are clearly localised.
Co-authored-by: Cursor <cursoragent@cursor.com>
Foundational scaffolding for every concrete C2 backbone (UltraVPR,
NetVLAD, MegaLoc, MixVPR, SelaVPR, EigenPlaces, SALAD — AZ-337..AZ-340)
and the C2.5 ReRanker consumer side. No backbone is implemented here.
* VprStrategy Protocol (embed_query / retrieve_topk / descriptor_dim)
+ BackbonePreprocessor C2-internal Protocol (NOT in Public API per
description.md § 6).
* DTOs in L1 _types/vpr.py — VprQuery, VprCandidate, VprResult; all
frozen + slots; tuple-not-list for VprResult.candidates so the
immutability invariant truly holds.
* Error family: VprError + VprBackboneError + VprPreprocessError +
IndexUnavailableError; same-named but namespace-distinct from
c6_tile_cache.IndexUnavailableError (the c2 family is the closed
envelope C5 / C2.5 consume; concrete strategies rewrap the C6 form).
* C2VprConfig (strategy enum + backbone_weights_path + faiss_index_path)
with strict validation at load; registered into Config.components on
c2_vpr import.
* build_vpr_strategy factory with 7-strategy resolution table, lazy
import, BUILD_VPR_<variant> gating, ImportError→
StrategyNotAvailableError mapping, and pre-flight descriptor_dim
match against DescriptorIndex.descriptor_dim() — mismatch fires
ConfigError at startup, NOT at first frame.
Contract change vs the v1.0.0 draft: factory takes descriptor_index:
DescriptorIndex (not tile_store: TileStore) because descriptor_dim()
lives on DescriptorIndex per C6's Public API. The contract markdown
is updated to match.
Architecture: VprCandidate.tile_id is a plain (zoom, lat, lon) tuple,
keeping _types/ (L1) free of any c6_tile_cache (L3) import per
module-layout.md. Consumers reconstruct TileId at the C6 boundary.
Excluded per task spec:
* Concrete backbones (AZ-337..AZ-340).
* FAISS HNSW retrieve wiring (AZ-341).
* DescriptorNormaliser helper (AZ-283, already shipped).
* AC-9 single-thread binding — deferred per task spec Risk 4 until the
generic compose_root thread-binding registry is in place (today
each factory owns its own, e.g. fc_factory).
Tests: 45 ACs + NFRs in tests/unit/c2_vpr/test_protocol_conformance.py
covering AC-1..AC-8, the error family, the config validation, the
factory NFR (p99 ≤ 50 ms). The legacy smoke test is removed. Full
sweep 973 passed, 2 skipped (CI-only cmake / actionlint).
Co-authored-by: Cursor <cursoragent@cursor.com>
Oleksandr Bezdieniezhnykh