fix(python): name the rejected rrf_k value and accept numpy integers (#1096)

AD
2h ago
+824-53

What

#1096 was filed against #1066's earlier head, where build_query did int(retrieval.rrf_k): -0.5 became a legal-looking 0, 2.5 became 2, and nan raised a bare ValueError from protobuf. #1048 (0f89c2a3d) already replaced that with a check that rejects non-integers before serializing. This PR closes the remaining gaps the issue names:

  • The error names the value the caller passed (... rrf_k must be an int, got -0.5, 2.5, nan) instead of its type, so nobody is told about a laundered 0.
  • Integral types are accepted, numpy integers included (numpy is a package dependency), via numbers.Integral, then cast.
  • Range stays in commons. A negative integer such as -5 is not coerced; it reaches the native validator, which rejects it naming rrf_k. Bounds are not duplicated in the binding, the same split the other SDKs use.

Tests

bindings/python/tests/test_rag.py: -0.5, 2.5, nan, int32 overflow and an unknown vector_store each raise an SDKException whose message names the field and value, and nothing is sent. A numpy.int64 rrf_k reaches the proto. Local: RAG tests 26 passed; whole Python suite 467 passed (the only failure, test_version_string, needs the package installed).

Stacking

Stacked on #1048 (the Python validation lives there), so the diff includes its commits until it merges.

Closes #1096

Summary by cubic

Fixes Python RAG rrf_k handling so rejected values are named correctly and numpy integers are accepted. Previously int() laundered -0.5 into 0, 2.5 into 2, and let nan surface as a bare protobuf ValueError; now non-integral or non-finite values are rejected before serialization with the value the caller passed in the error, and integral types including numpy integers are accepted. Range checks stay in commons, the same split the other SDKs use.

The diff also includes commits from the stacked branches this PR sits on (#1048, #913, #1019), which add the BM25, RRF, and vector-store retrieval knobs to the core backend and all bindings.

Summary by CodeRabbit

  • New Features
    • Added per-query controls for BM25 ranking parameters and reciprocal rank fusion across Kotlin, Python, Swift, and web SDKs.
    • Added USearch vector-store selection for retrieval. Omitted options continue to use session defaults.
    • Custom retrieval settings now affect BM25 scoring and rank-fusion results.
  • Bug Fixes
    • Added validation for retrieval settings, including numeric ranges and vector-store selections, so invalid or unsupported inputs are rejected.