feat(vectorstore): cross-adapter filter fail-loud + score normalization (task #61 P0-A + P0-B)

[earayu]

Summary

Closes the two task #61 vector-adapter contract gaps PM @不穷 dispatched to me (msg=a387a81e) and architect @符炫炜 ratified (msg=7646eb4f), per Weston contract-matrix scope (msg=8beffab5) + spec PR #1928 § 2.2 / § 5.3 lock.

• P0-A: filter fail-loud — qdrant_connector._normalize_filter_input no longer logs warning + returns None (silent unfiltered scan); both adapters now raise the new cross-adapter UnsupportedFilterError (subclass of TypeError → existing except TypeError callers keep working)
• P0-B: score normalization — SearchHit.score is now uniformly in [0, 1] higher=better across PGVector × Qdrant × cosine/L2/dot, with score_threshold on the same scale (pushdown via inverse + Python belt-and-braces)

P0-V1 (Qdrant legacy retrieve cross-tenant filter) intentionally NOT in scope — first-principles verify (msg=23a2f514) confirmed legacy mode is tenant-isolated by physical collection name (qdrant_connector.py:442-446), not query filter, so no leak. Architect ratified the reframe to P1-V4 defense-in-depth (msg=7646eb4f).

Changes

aperag/vectorstore/base.py

• New UnsupportedFilterError(TypeError) cross-adapter exception
• New normalize_score(metric, raw) + inverse denormalize_threshold_to_native
  • cosine: clamp to [0, 1]
  • euclid: 1 / (1 + L2) onto (0, 1]
  • dot: numerically-stable sigmoid onto (0, 1)
  • all monotone → top-k ordering preserved
• VectorStoreConnector.search() docstring + class-level invariants spell out §5 / §6 contract

aperag/vectorstore/dto.py

• SearchHit.__post_init__ validates 0.0 <= score <= 1.0 (Pydantic-Field-equivalent for the frozen dataclass)

aperag/vectorstore/pgvector_connector.py

• _SqlFilter._walk raises UnsupportedFilterError
• search() pushes threshold down via denormalize_threshold_to_native + applies normalize_score post-query + Python belt-and-braces

aperag/vectorstore/qdrant_connector.py

• _normalize_filter_input raises UnsupportedFilterError instead of fail-silent return None
• search() pushes threshold down + applies normalize_score + handles +inf / -inf pushdown edge cases

Tests

• New tests/unit_test/vectorstore/test_score_normalization.py (33 cases): range invariants × 14 raw scores, ordering preservation × 4 metric pairs, denormalize→normalize roundtrip × 15 (3 metric × 5 thresholds), endpoint behaviour, UnsupportedFilterError isinstance TypeError
• tests/unit_test/vectorstore/test_pgvector_translator.py + test_qdrant_filter_translation.py updated to assert UnsupportedFilterError while keeping TypeError back-compat assertion
• tests/integration/compat/test_vector_compat.py extended with 4 new cross-backend cases:
  • test_search_unsupported_filter_raises_unsupported_filter_error
  • test_search_score_in_unit_interval
  • test_search_score_threshold_filters_low_scores
  • test_search_top_k_ranking_higher_is_better

Local: uv run pytest tests/unit_test/vectorstore/ tests/unit_test/indexing/ tests/unit_test/graph_curation/ → 518 passed, 10 skipped.

Test plan

• Local unit tests pass (vectorstore / indexing / graph_curation)
• ruff check + ruff format --check clean
• CI lint-and-unit green
• Backend-Compat-Test green (PR ci(compat): trigger Backend-Compat-Test on real graph_storage path #1926 merged → compat-test now triggers on aperag/vectorstore/**)
• @huangheng CR (per msg=7d4fbcf2 + msg=05203d11 4-point checklist: base.py contract Pydantic-equivalent / cross-metric enum coverage / cross-adapter parametrize / legacy follow-up)
• @符炫炜 ratify (standing per msg=7646eb4f)

Spec / scope alignment

• task [Features] add API /api/v1/kbclusters to list KubeBlocks clusters #61 spec PR docs(task-61): DB adapter compat spec v1 — vector + graph cross-impl audit #1928 § 2.2 P0-A + P0-B locked
• P0-B score normalization onto [0, 1] per Weston msg=8beffab5 P0 hard layer 3 ("score 方向必须统一")
• cuiwenbo task [Features] add a chatbot to the kubeblocks.io website to answer user questions about KubeBlocks.  #70 P0 (FE displays raw score, PGVector cosine_distance vs Qdrant cosine_similarity) folded into P0-B (same root cause)

Follow-ups (NOT in this PR)

• huangheng boundary-test sub-PR extending compat fixture to full PGVector × Qdrant × {cosine, euclid, dot} 6-cell grid (current fixture exercises cosine only)
• legacy mode deprecation + delete (Lesson feat: socket debug #14 multi-cycle pattern, P1-V4 task [Features] add API /api/v1/kbclusters to list KubeBlocks clusters #61 cleanup queue)
• cr-checklist follow-up sub-PR Lesson #12 v9 first-application sediment (huangheng standby per msg=6ca63ae4)

🤖 Generated with Claude Code