mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-06-22 15:21:14 +00:00
[AZ-341] C2 FAISS HNSW retrieve wiring (FaissBridge + AZ-507 cut)
Shared retrieve_topk plumbing for every concrete C2 VprStrategy:
- FaissBridge centralises the c6 search_topk → VprResult pipeline,
the defended-in-depth INV-4 check (exactly k, distance-ascending),
the WARN-threshold check on distances[0], optional per-frame DEBUG
log, and one `vpr.retrieve_topk` FDR record per call with latency
measurement.
- DescriptorIndexCut Protocol — consumer-side structural cut of c6
DescriptorIndex.search_topk (AZ-507); keeps c2_vpr c6-import-free.
- C2VprConfig gains warn_top1_threshold + debug_per_frame_distances
knobs with validators.
- KNOWN_PAYLOAD_KEYS registers vpr.retrieve_topk for the FDR record
schema with payload {frame_id, backbone_label, top10_distances,
latency_us}; companion fixture added to the AZ-272 roundtrip suite.
- 22 unit tests cover AC-1..AC-11 + NFR-perf microbench (p95 ≤ 0.5 ms)
+ constructor and retrieve-argument validation.
Verdict: PASS_WITH_WARNINGS (2 Low findings — duplicated ISO-ts
helper across c2/c5/c11/c12, captured in AZ-508 hygiene PBI;
spec-listed but unused `normaliser` parameter dropped — INV-3 makes
the embedding L2-normalised at the strategy's `embed_query`).
Tests: 1565 passed / 80 skipped (was 1543; +22 new tests).
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,676 @@
|
||||
"""AZ-341 FaissBridge unit tests.
|
||||
|
||||
Covers AC-1..AC-11 + the NFR-perf microbench against the bridge using
|
||||
fakes (no c6, c7, or live FAISS — c2_vpr stays AZ-507-clean).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import numpy as np
|
||||
import pytest
|
||||
|
||||
from gps_denied_onboard._types.vpr import VprQuery
|
||||
from gps_denied_onboard.components.c2_vpr._faiss_bridge import FaissBridge
|
||||
from gps_denied_onboard.components.c2_vpr.errors import IndexUnavailableError
|
||||
from gps_denied_onboard.fdr_client import FdrClient
|
||||
from gps_denied_onboard.fdr_client.records import (
|
||||
CURRENT_SCHEMA_VERSION,
|
||||
FdrRecord,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from gps_denied_onboard.components.c2_vpr.descriptor_index_cut import (
|
||||
TileIdTuple,
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Fakes
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class _FakeDescriptorIndex:
|
||||
"""Configurable :class:`DescriptorIndexCut` for the unit tests.
|
||||
|
||||
``results`` is the canned ``(tile_id_tuple, distance)`` list the
|
||||
fake returns from :meth:`search_topk`; ``raises``, when set, is
|
||||
raised instead. ``calls`` records every ``(query, k)`` invocation.
|
||||
"""
|
||||
|
||||
results: list[tuple[tuple[int, float, float], float]] = field(default_factory=list)
|
||||
raises: BaseException | None = None
|
||||
calls: list[tuple[np.ndarray, int]] = field(default_factory=list)
|
||||
|
||||
def search_topk(
|
||||
self, query: np.ndarray, k: int
|
||||
) -> list[tuple[tuple[int, float, float], float]]:
|
||||
self.calls.append((query, k))
|
||||
if self.raises is not None:
|
||||
raise self.raises
|
||||
return list(self.results)
|
||||
|
||||
|
||||
@dataclass
|
||||
class _StubClock:
|
||||
"""Deterministic Clock — ``monotonic_ns`` increments by ``step_ns``."""
|
||||
|
||||
next_monotonic_ns: int = 1_000_000_000
|
||||
step_ns: int = 5_000
|
||||
fixed_time_ns: int = 1_715_600_000_000_000_000
|
||||
|
||||
def monotonic_ns(self) -> int:
|
||||
v = self.next_monotonic_ns
|
||||
self.next_monotonic_ns += self.step_ns
|
||||
return v
|
||||
|
||||
def time_ns(self) -> int:
|
||||
return self.fixed_time_ns
|
||||
|
||||
def sleep_until_ns(self, target_ns: int) -> None:
|
||||
_ = target_ns
|
||||
|
||||
|
||||
def _make_fdr_client(*, force_overrun: bool = False) -> FdrClient:
|
||||
client = FdrClient(
|
||||
producer_id="c2_vpr",
|
||||
capacity=8,
|
||||
_emit_diag_log=False,
|
||||
)
|
||||
if force_overrun:
|
||||
filler = FdrRecord(
|
||||
schema_version=CURRENT_SCHEMA_VERSION,
|
||||
ts="2026-05-13T00:00:00.000000+00:00",
|
||||
producer_id=client.producer_id,
|
||||
kind="log",
|
||||
payload={
|
||||
"level": "INFO",
|
||||
"component": "test",
|
||||
"frame_id": "",
|
||||
"kind": "test",
|
||||
"msg": "filler",
|
||||
},
|
||||
)
|
||||
# `FdrClient._buffer` is the SPSC ring; its capacity is rounded
|
||||
# up to the next power of two from the constructor argument.
|
||||
# Filling to capacity makes the next enqueue return OVERRUN.
|
||||
while client.enqueue(filler) == "ok":
|
||||
pass
|
||||
return client
|
||||
|
||||
|
||||
def _make_query(*, frame_id: int = 4242, dim: int = 512) -> VprQuery:
|
||||
embedding = np.zeros((dim,), dtype=np.float32)
|
||||
embedding[0] = 1.0
|
||||
return VprQuery(frame_id=frame_id, embedding=embedding, produced_at=999)
|
||||
|
||||
|
||||
def _ten_canned_results(
|
||||
distances: list[float] | None = None,
|
||||
) -> list[tuple[tuple[int, float, float], float]]:
|
||||
distances = distances if distances is not None else [
|
||||
0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50,
|
||||
]
|
||||
return [
|
||||
((18, 49.0 + i * 0.001, 36.0 + i * 0.001), d)
|
||||
for i, d in enumerate(distances)
|
||||
]
|
||||
|
||||
|
||||
def _build_bridge(
|
||||
*,
|
||||
descriptor_index: _FakeDescriptorIndex,
|
||||
fdr_client: FdrClient,
|
||||
clock: _StubClock,
|
||||
descriptor_dim: int = 512,
|
||||
warn_top1_threshold: float = 0.30,
|
||||
debug_log_per_frame_distances: bool = False,
|
||||
logger_name: str = "c2.faiss_bridge.test",
|
||||
) -> FaissBridge:
|
||||
return FaissBridge(
|
||||
descriptor_index=descriptor_index,
|
||||
descriptor_dim=descriptor_dim,
|
||||
warn_top1_threshold=warn_top1_threshold,
|
||||
debug_log_per_frame_distances=debug_log_per_frame_distances,
|
||||
fdr_client=fdr_client,
|
||||
logger=logging.getLogger(logger_name),
|
||||
clock=clock,
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-1: happy-path retrieve → VprResult + FDR record
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_happy_path_returns_vpr_result_and_emits_fdr(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query(frame_id=4242)
|
||||
|
||||
# Act
|
||||
with caplog.at_level(logging.DEBUG, logger="c2.faiss_bridge.test"):
|
||||
result = bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
|
||||
# Assert — c6 cut was called exactly once with the correct args
|
||||
assert len(descriptor_index.calls) == 1
|
||||
sent_query, sent_k = descriptor_index.calls[0]
|
||||
assert sent_k == 10
|
||||
assert sent_query is query.embedding
|
||||
|
||||
# Assert — VprResult shape
|
||||
assert result.frame_id == 4242
|
||||
assert result.backbone_label == "ultra_vpr"
|
||||
assert len(result.candidates) == 10
|
||||
candidate_distances = [c.descriptor_distance for c in result.candidates]
|
||||
assert candidate_distances == sorted(candidate_distances)
|
||||
assert candidate_distances[0] == pytest.approx(0.05)
|
||||
assert all(c.descriptor_dim == 512 for c in result.candidates)
|
||||
assert result.retrieved_at > 0
|
||||
|
||||
# Assert — exactly one FDR record
|
||||
record = fdr_client.pop_one()
|
||||
assert record is not None
|
||||
assert record.kind == "vpr.retrieve_topk"
|
||||
assert record.payload["frame_id"] == 4242
|
||||
assert record.payload["backbone_label"] == "ultra_vpr"
|
||||
assert record.payload["top10_distances"] == pytest.approx(
|
||||
[0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50]
|
||||
)
|
||||
assert isinstance(record.payload["latency_us"], int)
|
||||
assert record.payload["latency_us"] > 0
|
||||
assert fdr_client.pop_one() is None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-2: INV-4 violation — undersized result → IndexUnavailableError
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_undersized_corpus_raises_index_unavailable_error(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(
|
||||
results=[((18, 49.0, 36.0), 0.05), ((18, 49.001, 36.001), 0.10)],
|
||||
)
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act + Assert
|
||||
with caplog.at_level(logging.ERROR, logger="c2.faiss_bridge.test"):
|
||||
with pytest.raises(IndexUnavailableError) as exc_info:
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
assert "corpus returned 2 candidates (expected 10)" in str(exc_info.value)
|
||||
|
||||
# Assert — ERROR log with the invariant_violation kind
|
||||
err_records = [
|
||||
r for r in caplog.records if getattr(r, "kind", None) == "c2.vpr.invariant_violation"
|
||||
]
|
||||
assert len(err_records) == 1
|
||||
assert err_records[0].kv["reason"] == "undersized"
|
||||
assert err_records[0].kv["returned_count"] == 2
|
||||
assert err_records[0].kv["expected_k"] == 10
|
||||
|
||||
# Assert — no FDR record emitted (failure is the corpus, not retrieval)
|
||||
assert fdr_client.pop_one() is None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-3: INV-4 violation — unordered distances
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_unordered_distances_raises_index_unavailable_error(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange — distances out of ascending order at idx 2
|
||||
bad_distances = [0.05, 0.20, 0.10, 0.15, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50]
|
||||
descriptor_index = _FakeDescriptorIndex(
|
||||
results=_ten_canned_results(distances=bad_distances),
|
||||
)
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act + Assert
|
||||
with caplog.at_level(logging.ERROR, logger="c2.faiss_bridge.test"):
|
||||
with pytest.raises(IndexUnavailableError) as exc_info:
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
assert "unordered distances" in str(exc_info.value)
|
||||
|
||||
err_records = [
|
||||
r for r in caplog.records if getattr(r, "kind", None) == "c2.vpr.invariant_violation"
|
||||
]
|
||||
assert len(err_records) == 1
|
||||
assert err_records[0].kv["reason"] == "unordered"
|
||||
|
||||
assert fdr_client.pop_one() is None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-4: c6 raises IndexUnavailableError → propagates UNCHANGED (no catch)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_propagates_index_unavailable_error_unchanged() -> None:
|
||||
# Arrange — the fake raises ON the search_topk call (mirroring c6's
|
||||
# stale-handle / sidecar / dim-mismatch defence)
|
||||
inner = IndexUnavailableError("stale handle")
|
||||
descriptor_index = _FakeDescriptorIndex(raises=inner)
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act + Assert — same exception, NOT wrapped
|
||||
with pytest.raises(IndexUnavailableError) as exc_info:
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
assert exc_info.value is inner
|
||||
assert str(exc_info.value) == "stale handle"
|
||||
|
||||
# Assert — no FDR record (retrieval never completed)
|
||||
assert fdr_client.pop_one() is None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-5: WARN-threshold trigger when distances[0] > threshold
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_emits_warn_log_when_top1_above_threshold(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
distances = [0.42, 0.45, 0.50, 0.55, 0.60, 0.65, 0.70, 0.75, 0.80, 0.85]
|
||||
descriptor_index = _FakeDescriptorIndex(
|
||||
results=_ten_canned_results(distances=distances),
|
||||
)
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index,
|
||||
fdr_client=fdr_client,
|
||||
clock=clock,
|
||||
warn_top1_threshold=0.30,
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act
|
||||
with caplog.at_level(logging.WARNING, logger="c2.faiss_bridge.test"):
|
||||
result = bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
|
||||
# Assert — VprResult still returned
|
||||
assert len(result.candidates) == 10
|
||||
|
||||
# Assert — exactly ONE WARN log with the expected kind + structured kv
|
||||
warn_records = [
|
||||
r for r in caplog.records
|
||||
if getattr(r, "kind", None) == "c2.vpr.top1_distance_above_threshold"
|
||||
]
|
||||
assert len(warn_records) == 1
|
||||
kv = warn_records[0].kv
|
||||
assert kv["distance"] == pytest.approx(0.42)
|
||||
assert kv["threshold"] == pytest.approx(0.30)
|
||||
assert kv["backbone_label"] == "ultra_vpr"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-6: WARN-threshold NOT triggered when top-1 below threshold
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_does_not_emit_warn_when_top1_below_threshold(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
distances = [0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50, 0.55, 0.60]
|
||||
descriptor_index = _FakeDescriptorIndex(
|
||||
results=_ten_canned_results(distances=distances),
|
||||
)
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index,
|
||||
fdr_client=fdr_client,
|
||||
clock=clock,
|
||||
warn_top1_threshold=0.30,
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act
|
||||
with caplog.at_level(logging.WARNING, logger="c2.faiss_bridge.test"):
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
|
||||
# Assert — no WARN log
|
||||
warn_records = [
|
||||
r for r in caplog.records
|
||||
if getattr(r, "kind", None) == "c2.vpr.top1_distance_above_threshold"
|
||||
]
|
||||
assert warn_records == []
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-7: DEBUG per-frame distances ON → DEBUG log emitted
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_emits_debug_log_when_per_frame_distances_on(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index,
|
||||
fdr_client=fdr_client,
|
||||
clock=clock,
|
||||
debug_log_per_frame_distances=True,
|
||||
)
|
||||
query = _make_query(frame_id=9999)
|
||||
|
||||
# Act
|
||||
with caplog.at_level(logging.DEBUG, logger="c2.faiss_bridge.test"):
|
||||
bridge.retrieve(query, k=10, backbone_label="net_vlad")
|
||||
|
||||
# Assert — exactly one DEBUG record
|
||||
debug_records = [
|
||||
r for r in caplog.records
|
||||
if getattr(r, "kind", None) == "c2.vpr.frame_distances"
|
||||
]
|
||||
assert len(debug_records) == 1
|
||||
kv = debug_records[0].kv
|
||||
assert kv["frame_id"] == 9999
|
||||
assert kv["top10_distances"] == pytest.approx(
|
||||
[0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50]
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-8: DEBUG per-frame distances OFF (default) → no DEBUG log
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_does_not_emit_debug_log_when_per_frame_distances_off(
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
) -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act
|
||||
with caplog.at_level(logging.DEBUG, logger="c2.faiss_bridge.test"):
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
|
||||
# Assert
|
||||
debug_records = [
|
||||
r for r in caplog.records
|
||||
if getattr(r, "kind", None) == "c2.vpr.frame_distances"
|
||||
]
|
||||
assert debug_records == []
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-9: FDR record carries {frame_id, backbone_label, top10_distances, latency_us > 0}
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_retrieve_fdr_record_fields_are_populated_with_positive_latency() -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock(step_ns=7_000)
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query(frame_id=12345)
|
||||
|
||||
# Act
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
|
||||
# Assert
|
||||
record = fdr_client.pop_one()
|
||||
assert record is not None
|
||||
assert record.kind == "vpr.retrieve_topk"
|
||||
payload = record.payload
|
||||
assert set(payload.keys()) == {
|
||||
"frame_id", "backbone_label", "top10_distances", "latency_us",
|
||||
}
|
||||
assert payload["frame_id"] == 12345
|
||||
assert payload["backbone_label"] == "ultra_vpr"
|
||||
assert payload["top10_distances"] == pytest.approx(
|
||||
[0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50]
|
||||
)
|
||||
assert payload["latency_us"] > 0
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-10: every concrete `VprStrategy.retrieve_topk` body is one return statement
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_every_concrete_strategy_retrieve_topk_body_is_one_return_statement() -> None:
|
||||
# Arrange — discover every concrete `VprStrategy` subclass via AST
|
||||
# inspection of `c2_vpr/*.py` modules whose filename matches a
|
||||
# ``KNOWN_STRATEGIES`` member. Strategies that don't exist yet
|
||||
# (AZ-337..AZ-340) trivially pass this check.
|
||||
import ast
|
||||
import pathlib
|
||||
|
||||
from gps_denied_onboard.components.c2_vpr.config import KNOWN_STRATEGIES
|
||||
|
||||
component_dir = pathlib.Path(__file__).resolve().parents[3] / (
|
||||
"src/gps_denied_onboard/components/c2_vpr"
|
||||
)
|
||||
|
||||
strategy_files = sorted(
|
||||
p for p in component_dir.iterdir()
|
||||
if p.is_file() and p.suffix == ".py" and p.stem in KNOWN_STRATEGIES
|
||||
)
|
||||
|
||||
# If no strategy files exist yet, the check still passes — AC-10 is
|
||||
# forward-looking; AZ-337/338/339/340 will be required to satisfy it
|
||||
# when they ship.
|
||||
for strategy_file in strategy_files:
|
||||
tree = ast.parse(strategy_file.read_text(encoding="utf-8"))
|
||||
# Find every class that defines a ``retrieve_topk`` method
|
||||
for node in ast.walk(tree):
|
||||
if not isinstance(node, ast.ClassDef):
|
||||
continue
|
||||
for member in node.body:
|
||||
if not isinstance(member, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
||||
continue
|
||||
if member.name != "retrieve_topk":
|
||||
continue
|
||||
# Drop optional docstring (Expr/Constant string) from
|
||||
# the body before counting statements.
|
||||
body = list(member.body)
|
||||
if (
|
||||
body
|
||||
and isinstance(body[0], ast.Expr)
|
||||
and isinstance(body[0].value, ast.Constant)
|
||||
and isinstance(body[0].value.value, str)
|
||||
):
|
||||
body = body[1:]
|
||||
# Assert
|
||||
assert len(body) == 1, (
|
||||
f"{strategy_file.name}::{node.name}.retrieve_topk "
|
||||
f"must have exactly one statement after docstring; "
|
||||
f"got {len(body)}"
|
||||
)
|
||||
assert isinstance(body[0], ast.Return), (
|
||||
f"{strategy_file.name}::{node.name}.retrieve_topk "
|
||||
f"single statement must be `return ...`; got "
|
||||
f"{type(body[0]).__name__}"
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# AC-11: per-strategy `descriptor_dim` carried through to candidates
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_descriptor_dim_carried_through_to_each_candidate() -> None:
|
||||
# Arrange — two bridges with different dims
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
clock = _StubClock()
|
||||
bridge_ultra = _build_bridge(
|
||||
descriptor_index=_FakeDescriptorIndex(results=_ten_canned_results()),
|
||||
fdr_client=_make_fdr_client(),
|
||||
clock=_StubClock(),
|
||||
descriptor_dim=512,
|
||||
)
|
||||
bridge_netvlad = _build_bridge(
|
||||
descriptor_index=_FakeDescriptorIndex(results=_ten_canned_results()),
|
||||
fdr_client=_make_fdr_client(),
|
||||
clock=_StubClock(),
|
||||
descriptor_dim=4096,
|
||||
)
|
||||
|
||||
# Act
|
||||
ultra = bridge_ultra.retrieve(
|
||||
_make_query(dim=512), k=10, backbone_label="ultra_vpr"
|
||||
)
|
||||
netvlad = bridge_netvlad.retrieve(
|
||||
_make_query(dim=4096), k=10, backbone_label="net_vlad"
|
||||
)
|
||||
|
||||
# Assert
|
||||
assert all(c.descriptor_dim == 512 for c in ultra.candidates)
|
||||
assert all(c.descriptor_dim == 4096 for c in netvlad.candidates)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# NFR-perf: bridge.retrieve overhead p95 ≤ 0.5 ms (excluding c6 time)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_bridge_retrieve_overhead_p95_under_500us() -> None:
|
||||
# Arrange
|
||||
descriptor_index = _FakeDescriptorIndex(results=_ten_canned_results())
|
||||
fdr_client = _make_fdr_client()
|
||||
# WallClock-equivalent fake — uses time.monotonic_ns so the
|
||||
# measured latency is realistic, not stub-step driven.
|
||||
@dataclass
|
||||
class _WallStubClock:
|
||||
fixed_time_ns: int = 1_715_600_000_000_000_000
|
||||
|
||||
def monotonic_ns(self) -> int:
|
||||
return time.monotonic_ns()
|
||||
|
||||
def time_ns(self) -> int:
|
||||
return self.fixed_time_ns
|
||||
|
||||
def sleep_until_ns(self, target_ns: int) -> None:
|
||||
_ = target_ns
|
||||
|
||||
clock = _WallStubClock()
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=descriptor_index, fdr_client=fdr_client, clock=clock
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
n = 1000
|
||||
timings_ns: list[int] = []
|
||||
|
||||
# Act — measure outside the bridge so we capture wrapper + INV-4 +
|
||||
# candidate construction + FDR enqueue + log emission overhead.
|
||||
for _ in range(n):
|
||||
# Drain the FDR queue so the next enqueue does not OVERRUN.
|
||||
while fdr_client.pop_one() is not None:
|
||||
pass
|
||||
t0 = time.monotonic_ns()
|
||||
bridge.retrieve(query, k=10, backbone_label="ultra_vpr")
|
||||
t1 = time.monotonic_ns()
|
||||
timings_ns.append(t1 - t0)
|
||||
|
||||
# Assert — p95 ≤ 500 µs
|
||||
timings_ns.sort()
|
||||
p95_us = timings_ns[int(n * 0.95)] / 1_000
|
||||
assert p95_us <= 500.0, f"bridge.retrieve p95 = {p95_us:.1f}µs > 500.0µs"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Constructor validation — descriptor_dim, threshold, debug flag types
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"kwargs, match",
|
||||
[
|
||||
({"descriptor_dim": "512"}, "descriptor_dim must be a non-bool int"),
|
||||
({"descriptor_dim": True}, "descriptor_dim must be a non-bool int"),
|
||||
({"descriptor_dim": 0}, "descriptor_dim must be > 0"),
|
||||
({"descriptor_dim": -1}, "descriptor_dim must be > 0"),
|
||||
({"warn_top1_threshold": "0.5"}, "warn_top1_threshold must be a float"),
|
||||
({"warn_top1_threshold": True}, "warn_top1_threshold must be a float"),
|
||||
({"warn_top1_threshold": -0.01}, "warn_top1_threshold must be >= 0"),
|
||||
({"debug_log_per_frame_distances": 1}, "debug_log_per_frame_distances must be a bool"),
|
||||
],
|
||||
)
|
||||
def test_constructor_rejects_invalid_arguments(
|
||||
kwargs: dict[str, object], match: str
|
||||
) -> None:
|
||||
base = {
|
||||
"descriptor_index": _FakeDescriptorIndex(results=_ten_canned_results()),
|
||||
"descriptor_dim": 512,
|
||||
"warn_top1_threshold": 0.30,
|
||||
"debug_log_per_frame_distances": False,
|
||||
"fdr_client": _make_fdr_client(),
|
||||
"logger": logging.getLogger("c2.faiss_bridge.test"),
|
||||
"clock": _StubClock(),
|
||||
}
|
||||
base.update(kwargs)
|
||||
expected_error: type[BaseException] = (
|
||||
ValueError
|
||||
if match.startswith(("descriptor_dim must be > 0", "warn_top1_threshold must be >= 0"))
|
||||
else TypeError
|
||||
)
|
||||
with pytest.raises(expected_error, match=match):
|
||||
FaissBridge(**base) # type: ignore[arg-type]
|
||||
|
||||
|
||||
def test_retrieve_rejects_non_positive_k_and_empty_backbone_label() -> None:
|
||||
# Arrange
|
||||
bridge = _build_bridge(
|
||||
descriptor_index=_FakeDescriptorIndex(results=_ten_canned_results()),
|
||||
fdr_client=_make_fdr_client(),
|
||||
clock=_StubClock(),
|
||||
)
|
||||
query = _make_query()
|
||||
|
||||
# Act + Assert
|
||||
with pytest.raises(ValueError, match="k must be > 0"):
|
||||
bridge.retrieve(query, k=0, backbone_label="ultra_vpr")
|
||||
with pytest.raises(TypeError, match="k must be a non-bool int"):
|
||||
bridge.retrieve(query, k=True, backbone_label="ultra_vpr") # type: ignore[arg-type]
|
||||
with pytest.raises(ValueError, match="backbone_label must be a non-empty"):
|
||||
bridge.retrieve(query, k=10, backbone_label="")
|
||||
@@ -268,6 +268,15 @@ def _kind_payload(kind: str) -> dict[str, object]:
|
||||
"failure_reason": None,
|
||||
"ts_monotonic_ns": 1_234_567_890_123,
|
||||
}
|
||||
if kind == "vpr.retrieve_topk":
|
||||
return {
|
||||
"frame_id": 4242,
|
||||
"backbone_label": "ultra_vpr",
|
||||
"top10_distances": [
|
||||
0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50,
|
||||
],
|
||||
"latency_us": 123,
|
||||
}
|
||||
raise AssertionError(f"unhandled kind in fixture: {kind!r}")
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user