Skip to content

Fix: treat NumPy uint8 vectors as u8, not bit-packed binary - #780

Open
chakshu-dhannawat wants to merge 1 commit into
unum-cloud:main-devfrom
chakshu-dhannawat:fix/u8-vectors-misread-as-binary
Open

Fix: treat NumPy uint8 vectors as u8, not bit-packed binary#780
chakshu-dhannawat wants to merge 1 commit into
unum-cloud:main-devfrom
chakshu-dhannawat:fix/u8-vectors-misread-as-binary

Conversation

@chakshu-dhannawat

Copy link
Copy Markdown
Contributor

Closes #595.

The bug

A u8 index silently corrupts its vectors. Adding np.uint8 data zeros out
almost everything, so search results are meaningless. int8 works fine.

import numpy as np
from usearch.index import Index, ScalarKind

vec = np.zeros(8, dtype=np.uint8); vec[2] = 3; vec[5] = 7
idx = Index(ndim=8, metric="l2sq", dtype=ScalarKind.U8)
idx.add(0, vec)
print(idx.get(0, ScalarKind.U8))   # [0 0 0 0 0 0 0 0]  <- input was [0 0 3 0 0 7 0 0]

Root cause

A NumPy uint8 buffer is ambiguous: the same bytes back both bit-packed binary
vectors (b1x8) and unsigned byte vectors (u8). numpy_string_to_kind maps
uint8 to b1x8 for backwards compatibility. When no explicit dtype is passed
to add/search, the dispatch used that detected kind directly, so a u8 index
reinterpreted its data as packed bits and the values collapsed to (near-)zero.
int8 avoids this because it maps to i8 unambiguously.

The index already knows it is a u8 index, so that is enough to disambiguate.

The fix

When the caller gave no dtype and the buffer resolves to b1x8 but the index's
own scalar kind is u8, use u8. Binary indexes are untouched, so bit-packed
uint8 vectors keep working exactly as before. This is wired through a small
shared helper at the add, search, and cluster dispatch sites. The multi-shard
wrapper gains a scalar_kind() accessor (mirroring its existing scalar_words())
so the helper compiles for both index types.

Tests

Added test_u8_vectors_not_misread_as_binary: it stores sparse uint8 counts,
checks the round trip and search ranking, and confirms a binary index is
unaffected. It fails on the current code (vector stored as all zeros) and passes
with the fix. Full test_index.py suite is green (609 passed, 6 pre-existing skips).

A NumPy uint8 buffer is ambiguous: the same bytes back both bit-packed
binary vectors (b1x8) and unsigned byte vectors (u8). numpy_string_to_kind
maps uint8 to b1x8 for backwards compatibility, so when no explicit dtype
was passed to add/search, a u8 index reinterpreted its data as packed bits
and the vectors silently collapsed to (near-)zero. int8 worked because it
maps to i8 unambiguously.

Disambiguate against the index's own scalar kind: when the caller gave no
dtype and the buffer resolves to b1x8 but the index is u8, use u8. Binary
indexes are unaffected, so bit-packed uint8 vectors keep working. Applied
at the add, search, and cluster dispatch sites through a shared helper, and
added a scalar_kind() accessor to the multi-shard wrapper so it compiles for
both index types.

Adds a regression test that stores sparse uint8 counts, checks the round
trip and search ranking, and confirms the binary path is untouched. The
test fails on the current code (vector stored as all zeros) and passes with
the fix.

Closes unum-cloud#595
@chakshu-dhannawat

Copy link
Copy Markdown
Contributor Author

Heads up on the one red check (Ubuntu GCC 14): it's the C++ core test failing at cpp/test.cpp:433 in test_minimal_three_vectors (the std::abs(matched_distances[0]) < 0.01 self-match assertion after the serialize/reload roundtrip). That's flaky on the GCC 14 toolchain and unrelated to this PR:

  • This change only touches python/lib.cpp and python/scripts/test_index.py, neither of which is compiled into the test_cpp binary.
  • The same assertion at line 433 fails and passes nondeterministically on main-dev itself, e.g. run 29111716197 failed at line 433 while 29101749568 (a push about a minute earlier) passed.

The 22 other checks are green, including the Python suite that covers the actual fix. A rerun of just the GCC 14 job should clear it, but I don't have permissions to trigger one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant