mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 14:21:14 +00:00
[AZ-336] C2 VprStrategy: Protocol + DTOs + factory + composition
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>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,214 @@
|
||||
"""C2 VPR strategy composition-root factory (AZ-336).
|
||||
|
||||
:func:`build_vpr_strategy` selects exactly one strategy by
|
||||
``config.components['c2_vpr'].strategy`` and respects compile-time
|
||||
``BUILD_VPR_<variant>`` gating: requesting a strategy whose flag is
|
||||
OFF raises :class:`StrategyNotAvailableError` at composition time
|
||||
(NOT at first frame).
|
||||
|
||||
Concrete strategy modules
|
||||
(``ultra_vpr``, ``net_vlad``, ``mega_loc``, ``mix_vpr``,
|
||||
``sela_vpr``, ``eigen_places``, ``salad``) are imported lazily —
|
||||
a Tier-0 workstation build with ``BUILD_VPR_ULTRA_VPR=OFF`` MUST
|
||||
NOT load ``c2_vpr.ultra_vpr`` (ADR-002 / I-5; verifiable via
|
||||
``sys.modules``).
|
||||
|
||||
Pre-flight validation: after constructing the strategy, the factory
|
||||
queries :meth:`VprStrategy.descriptor_dim` and asserts it matches
|
||||
the C6 ``DescriptorIndex`` sidecar's ``descriptor_dim()``. Mismatch
|
||||
→ :class:`ConfigurationError` at startup, NOT at first frame.
|
||||
|
||||
Factory signature deviates from the v1.0.0 contract draft in one
|
||||
place: the contract spec named the second parameter ``tile_store:
|
||||
TileStore``, but ``descriptor_dim()`` lives on
|
||||
:class:`DescriptorIndex` per C6's actual Public API. We inject
|
||||
``descriptor_index`` directly; the contract markdown is updated to
|
||||
match.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import os
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from gps_denied_onboard.config.schema import ConfigError
|
||||
from gps_denied_onboard.runtime_root.errors import StrategyNotAvailableError
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from gps_denied_onboard.components.c2_vpr import C2VprConfig, VprStrategy
|
||||
from gps_denied_onboard.components.c6_tile_cache import DescriptorIndex
|
||||
from gps_denied_onboard.components.c7_inference import InferenceRuntime
|
||||
from gps_denied_onboard.config.schema import Config
|
||||
|
||||
__all__ = ["build_vpr_strategy"]
|
||||
|
||||
|
||||
_LOG = logging.getLogger("gps_denied_onboard.c2_vpr")
|
||||
|
||||
|
||||
# Strategy resolution table — mirrors the contract's
|
||||
# ``vpr_strategy_protocol.md`` v1.0.0 § Composition-Root Factory table
|
||||
# verbatim. ANY mutation of this dict MUST be mirrored in the contract.
|
||||
_STRATEGY_TO_BUILD_FLAG: dict[str, str] = {
|
||||
"ultra_vpr": "BUILD_VPR_ULTRA_VPR",
|
||||
"net_vlad": "BUILD_VPR_NETVLAD",
|
||||
"mega_loc": "BUILD_VPR_MEGALOC",
|
||||
"mix_vpr": "BUILD_VPR_MIXVPR",
|
||||
"sela_vpr": "BUILD_VPR_SELAVPR",
|
||||
"eigen_places": "BUILD_VPR_EIGENPLACES",
|
||||
"salad": "BUILD_VPR_SALAD",
|
||||
}
|
||||
|
||||
_STRATEGY_TO_MODULE: dict[str, tuple[str, str]] = {
|
||||
"ultra_vpr": (
|
||||
"gps_denied_onboard.components.c2_vpr.ultra_vpr",
|
||||
"UltraVprStrategy",
|
||||
),
|
||||
"net_vlad": (
|
||||
"gps_denied_onboard.components.c2_vpr.net_vlad",
|
||||
"NetVladStrategy",
|
||||
),
|
||||
"mega_loc": (
|
||||
"gps_denied_onboard.components.c2_vpr.mega_loc",
|
||||
"MegaLocStrategy",
|
||||
),
|
||||
"mix_vpr": (
|
||||
"gps_denied_onboard.components.c2_vpr.mix_vpr",
|
||||
"MixVprStrategy",
|
||||
),
|
||||
"sela_vpr": (
|
||||
"gps_denied_onboard.components.c2_vpr.sela_vpr",
|
||||
"SelaVprStrategy",
|
||||
),
|
||||
"eigen_places": (
|
||||
"gps_denied_onboard.components.c2_vpr.eigen_places",
|
||||
"EigenPlacesStrategy",
|
||||
),
|
||||
"salad": (
|
||||
"gps_denied_onboard.components.c2_vpr.salad",
|
||||
"SaladStrategy",
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def _is_build_flag_on(flag_name: str) -> bool:
|
||||
"""Read a compile-time ``BUILD_*`` flag from the environment.
|
||||
|
||||
``ON`` / ``1`` / ``true`` / ``yes`` (case-insensitive) → ``True``;
|
||||
anything else (including unset) → ``False``. Defaults to OFF so
|
||||
test environments must opt-in explicitly per strategy.
|
||||
"""
|
||||
raw = os.environ.get(flag_name, "")
|
||||
return raw.strip().lower() in {"on", "1", "true", "yes"}
|
||||
|
||||
|
||||
def _c2_config(config: "Config") -> "C2VprConfig":
|
||||
"""Pull the registered C2 config block.
|
||||
|
||||
``c2_vpr.__init__`` registers it on import; a missing
|
||||
registration is a developer error and surfaces as ``KeyError``
|
||||
rather than a silent fallback.
|
||||
"""
|
||||
return config.components["c2_vpr"]
|
||||
|
||||
|
||||
def build_vpr_strategy(
|
||||
config: "Config",
|
||||
*,
|
||||
descriptor_index: "DescriptorIndex",
|
||||
inference_runtime: "InferenceRuntime",
|
||||
) -> "VprStrategy":
|
||||
"""Construct the :class:`VprStrategy` impl selected by config.
|
||||
|
||||
1. Reads ``config.components['c2_vpr'].strategy``.
|
||||
2. Checks the matching ``BUILD_VPR_<variant>`` flag — if OFF,
|
||||
raises :class:`StrategyNotAvailableError` BEFORE any import.
|
||||
3. Lazily imports the concrete strategy module.
|
||||
4. Constructs the strategy via its module-level
|
||||
``create(config, descriptor_index, inference_runtime)``
|
||||
factory function (each concrete strategy module exports
|
||||
``create`` as its public entry-point; concrete constructors
|
||||
stay private).
|
||||
5. Pre-flight ``descriptor_dim`` match: ``strategy.descriptor_dim()``
|
||||
vs ``descriptor_index.descriptor_dim()``. Mismatch raises
|
||||
:class:`ConfigError`; ONE ERROR log
|
||||
``kind="c2.vpr.dim_mismatch"`` is emitted; the strategy is
|
||||
NOT bound.
|
||||
6. On success, ONE INFO log ``kind="c2.vpr.strategy_loaded"``
|
||||
with ``strategy`` + ``descriptor_dim``.
|
||||
|
||||
Raises:
|
||||
StrategyNotAvailableError: compile-time flag OFF or
|
||||
concrete module not yet built (AZ-337..AZ-340 pending).
|
||||
ConfigError: ``descriptor_dim`` mismatch between strategy
|
||||
and corpus index.
|
||||
"""
|
||||
block = _c2_config(config)
|
||||
strategy = block.strategy
|
||||
flag_name = _STRATEGY_TO_BUILD_FLAG.get(strategy)
|
||||
module_info = _STRATEGY_TO_MODULE.get(strategy)
|
||||
if flag_name is None or module_info is None:
|
||||
# Defensive — config validation rejects unknown strategy labels
|
||||
# at load (C2VprConfig.__post_init__), so this branch is only
|
||||
# reachable if the resolution table and the validation set
|
||||
# drift apart.
|
||||
_LOG.error(
|
||||
"c2.vpr.build_flag_off",
|
||||
extra={"strategy": strategy, "reason": "unknown_strategy"},
|
||||
)
|
||||
raise StrategyNotAvailableError(
|
||||
f"VprStrategy {strategy!r} is not buildable in this binary."
|
||||
)
|
||||
if not _is_build_flag_on(flag_name):
|
||||
_LOG.error(
|
||||
"c2.vpr.build_flag_off",
|
||||
extra={"strategy": strategy, "flag": flag_name},
|
||||
)
|
||||
raise StrategyNotAvailableError(
|
||||
f"BUILD_VPR_{strategy.upper()} is OFF for this binary; "
|
||||
f"cannot select strategy={strategy}."
|
||||
)
|
||||
module_name, class_name = module_info
|
||||
try:
|
||||
module = __import__(module_name, fromlist=[class_name])
|
||||
except ModuleNotFoundError as exc:
|
||||
raise StrategyNotAvailableError(
|
||||
f"VprStrategy {strategy!r} is configured but its concrete impl "
|
||||
f"module {module_name!r} has not been built into this binary "
|
||||
"yet (AZ-337 / AZ-338 / AZ-339 / AZ-340 pending)."
|
||||
) from exc
|
||||
create_fn = getattr(module, "create", None)
|
||||
if create_fn is None:
|
||||
strategy_cls = getattr(module, class_name)
|
||||
instance = strategy_cls(
|
||||
config,
|
||||
descriptor_index=descriptor_index,
|
||||
inference_runtime=inference_runtime,
|
||||
)
|
||||
else:
|
||||
instance = create_fn(
|
||||
config,
|
||||
descriptor_index=descriptor_index,
|
||||
inference_runtime=inference_runtime,
|
||||
)
|
||||
strategy_dim = instance.descriptor_dim()
|
||||
corpus_dim = descriptor_index.descriptor_dim()
|
||||
if strategy_dim != corpus_dim:
|
||||
_LOG.error(
|
||||
"c2.vpr.dim_mismatch",
|
||||
extra={
|
||||
"strategy": strategy,
|
||||
"strategy_dim": strategy_dim,
|
||||
"corpus_dim": corpus_dim,
|
||||
},
|
||||
)
|
||||
raise ConfigError(
|
||||
f"descriptor_dim mismatch: strategy={strategy_dim}, "
|
||||
f"corpus={corpus_dim}"
|
||||
)
|
||||
_LOG.info(
|
||||
"c2.vpr.strategy_loaded",
|
||||
extra={"strategy": strategy, "descriptor_dim": strategy_dim},
|
||||
)
|
||||
return instance
|
||||
Reference in New Issue
Block a user