betterdb-valkey-search-kit 0.1.0__tar.gz

betterdb_valkey_search_kit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/

betterdb_valkey_search_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-06-23
+
+### Added
+
+- Initial release. Python equivalent of the TypeScript `@betterdb/valkey-search-kit`.
+- `encode_float32` / `decode_float32` — little-endian Float32 vector encoding for embeddings.
+- `escape_tag` — TAG filter value escaping (including spaces).
+- `parse_ft_search_response` — bytes-aware FT.SEARCH reply parsing; never raises.
+- `parse_dimension_from_info` / `parse_ft_info_stats` — version-skew-tolerant FT.INFO parsing.
+- `is_index_not_found_error` — "index does not exist" error classification.

betterdb_valkey_search_kit-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: betterdb-valkey-search-kit
+Version: 0.1.0
+Summary: Shared Valkey Search (FT.*) helpers: float32 vector encoding, FT.SEARCH reply parsing, version-skew FT.INFO parsing, TAG escaping, and error classification.
+Project-URL: Repository, https://github.com/BetterDB-inc/monitor
+License: MIT
+Keywords: ft,redis,redisearch,valkey,valkey-search,vector-search
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# @betterdb/valkey-search-kit (Python)
+
+`betterdb-valkey-search-kit` — shared low-level helpers for working with Valkey
+Search (`FT.*`) from Python. This is the Python equivalent of the TypeScript
+`@betterdb/valkey-search-kit` package, and the shared foundation the
+`betterdb-retrieval` and `betterdb-agent-memory` packages build on.
+
+It has **no runtime dependencies** and exposes only pure functions, so it stays
+trivial to vendor and test.
+
+## Install
+
+```bash
+pip install betterdb-valkey-search-kit
+```
+
+## API
+
+### Vector encoding
+
+```python
+from betterdb_valkey_search_kit import encode_float32, decode_float32
+
+blob = encode_float32([0.1, 0.2, 0.3])   # little-endian Float32 bytes
+vec = decode_float32(blob)               # back to list[float]
+```
+
+Use `encode_float32` to store embeddings as binary `HSET` field values and as
+the `PARAMS` vector for a KNN `FT.SEARCH`.
+
+### TAG escaping
+
+```python
+from betterdb_valkey_search_kit import escape_tag
+
+f"@model:{{{escape_tag('gpt-4o')}}}"   # -> "@model:{gpt\\-4o}"
+```
+
+Escapes every character with special meaning in the TAG filter syntax,
+**including spaces** (unescaped spaces are treated as OR term separators).
+
+### FT.SEARCH reply parsing
+
+```python
+from betterdb_valkey_search_kit import parse_ft_search_response
+
+raw = await client.execute_command("FT.SEARCH", index, query, ...)
+hits = parse_ft_search_response(raw)
+# [{"key": "cache:entry:abc", "fields": {"prompt": "...", "__score": "0.05"}}]
+```
+
+Handles valkey-py's mixed `bytes`/`str` replies, `RETURN 0` mode (keys with no
+field list), and odd-length field lists. Binary field values that are not valid
+UTF-8 (e.g. raw embedding bytes) are skipped. **Never raises** — returns `[]` on
+any malformed input.
+
+### FT.INFO parsing (version-skew tolerant)
+
+```python
+from betterdb_valkey_search_kit import (
+    parse_dimension_from_info,
+    parse_ft_info_stats,
+)
+
+info = await client.execute_command("FT.INFO", index)
+dims = parse_dimension_from_info(info)        # 1536, or 0 if no vector field
+stats = parse_ft_info_stats(info)             # FtIndexStats(num_docs=..., indexing_state=...)
+```
+
+`parse_dimension_from_info` understands both the flat `DIM` attribute pair and
+the nested `index/dimensions` shape introduced in Valkey Search 1.2.
+
+### Error classification
+
+```python
+from betterdb_valkey_search_kit import is_index_not_found_error
+
+try:
+    await client.execute_command("FT.INFO", index)
+except Exception as err:
+    if is_index_not_found_error(err):
+        ...  # index does not exist yet
+    else:
+        raise
+```
+
+Matches the "index does not exist" message variants emitted across Valkey
+Search / RediSearch versions, case-insensitively.
+
+## Development
+
+```bash
+uv run --extra dev pytest tests -q
+```

betterdb_valkey_search_kit-0.1.0/README.md

@@ -0,0 +1,94 @@
+# @betterdb/valkey-search-kit (Python)
+
+`betterdb-valkey-search-kit` — shared low-level helpers for working with Valkey
+Search (`FT.*`) from Python. This is the Python equivalent of the TypeScript
+`@betterdb/valkey-search-kit` package, and the shared foundation the
+`betterdb-retrieval` and `betterdb-agent-memory` packages build on.
+
+It has **no runtime dependencies** and exposes only pure functions, so it stays
+trivial to vendor and test.
+
+## Install
+
+```bash
+pip install betterdb-valkey-search-kit
+```
+
+## API
+
+### Vector encoding
+
+```python
+from betterdb_valkey_search_kit import encode_float32, decode_float32
+
+blob = encode_float32([0.1, 0.2, 0.3])   # little-endian Float32 bytes
+vec = decode_float32(blob)               # back to list[float]
+```
+
+Use `encode_float32` to store embeddings as binary `HSET` field values and as
+the `PARAMS` vector for a KNN `FT.SEARCH`.
+
+### TAG escaping
+
+```python
+from betterdb_valkey_search_kit import escape_tag
+
+f"@model:{{{escape_tag('gpt-4o')}}}"   # -> "@model:{gpt\\-4o}"
+```
+
+Escapes every character with special meaning in the TAG filter syntax,
+**including spaces** (unescaped spaces are treated as OR term separators).
+
+### FT.SEARCH reply parsing
+
+```python
+from betterdb_valkey_search_kit import parse_ft_search_response
+
+raw = await client.execute_command("FT.SEARCH", index, query, ...)
+hits = parse_ft_search_response(raw)
+# [{"key": "cache:entry:abc", "fields": {"prompt": "...", "__score": "0.05"}}]
+```
+
+Handles valkey-py's mixed `bytes`/`str` replies, `RETURN 0` mode (keys with no
+field list), and odd-length field lists. Binary field values that are not valid
+UTF-8 (e.g. raw embedding bytes) are skipped. **Never raises** — returns `[]` on
+any malformed input.
+
+### FT.INFO parsing (version-skew tolerant)
+
+```python
+from betterdb_valkey_search_kit import (
+    parse_dimension_from_info,
+    parse_ft_info_stats,
+)
+
+info = await client.execute_command("FT.INFO", index)
+dims = parse_dimension_from_info(info)        # 1536, or 0 if no vector field
+stats = parse_ft_info_stats(info)             # FtIndexStats(num_docs=..., indexing_state=...)
+```
+
+`parse_dimension_from_info` understands both the flat `DIM` attribute pair and
+the nested `index/dimensions` shape introduced in Valkey Search 1.2.
+
+### Error classification
+
+```python
+from betterdb_valkey_search_kit import is_index_not_found_error
+
+try:
+    await client.execute_command("FT.INFO", index)
+except Exception as err:
+    if is_index_not_found_error(err):
+        ...  # index does not exist yet
+    else:
+        raise
+```
+
+Matches the "index does not exist" message variants emitted across Valkey
+Search / RediSearch versions, case-insensitively.
+
+## Development
+
+```bash
+uv run --extra dev pytest tests -q
+```

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/__init__.py

@@ -0,0 +1,26 @@
+"""Shared Valkey Search (FT.*) helpers for BetterDB packages.
+
+Mirrors the TypeScript ``@betterdb/valkey-search-kit`` package: float32 vector
+encoding, FT.SEARCH reply parsing, version-skew-tolerant FT.INFO parsing, TAG
+escaping, and "index does not exist" error classification.
+"""
+
+from __future__ import annotations
+
+from .encoding import decode_float32, encode_float32
+from .errors import is_index_not_found_error
+from .ft_info import FtIndexStats, parse_dimension_from_info, parse_ft_info_stats
+from .ft_search import FtSearchHit, parse_ft_search_response
+from .tags import escape_tag
+
+__all__ = [
+    "encode_float32",
+    "decode_float32",
+    "escape_tag",
+    "parse_ft_search_response",
+    "FtSearchHit",
+    "parse_dimension_from_info",
+    "parse_ft_info_stats",
+    "FtIndexStats",
+    "is_index_not_found_error",
+]

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/encoding.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import struct
+
+
+def encode_float32(vec: list[float]) -> bytes:
+    """Encode a float list as little-endian Float32 bytes.
+
+    Used to store embeddings as binary HSET field values for KNN search.
+    """
+    return struct.pack(f"<{len(vec)}f", *vec)
+
+
+def decode_float32(data: bytes) -> list[float]:
+    """Decode little-endian Float32 bytes into a float list."""
+    n = len(data) // 4
+    return list(struct.unpack_from(f"<{n}f", data))

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_index_not_found_error(err: Any) -> bool:
+    """Classify an error as a Valkey Search "index does not exist" error.
+
+    Matches the message variants emitted across Valkey Search / RediSearch
+    versions, case-insensitively. Non-exception values never match.
+    """
+    if not isinstance(err, BaseException):
+        return False
+    msg = str(err).lower()
+    return (
+        "unknown index name" in msg
+        or "no such index" in msg
+        or ("not found" in msg and "index" in msg)
+    )

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/ft_info.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _s(x: Any) -> str:
+    """Coerce a raw FT.INFO token (bytes from valkey-py, or str) to a string."""
+    if isinstance(x, bytes):
+        try:
+            return x.decode()
+        except UnicodeDecodeError:
+            return ""
+    return str(x)
+
+
+def _to_int(x: Any) -> int:
+    # Mirror TS ``parseInt(String(x), 10) || 0``: parse via float() so a
+    # float-formatted token (e.g. a RESP3 double rendered as "42.0") still
+    # yields its integer value instead of falling back to 0. OverflowError
+    # guards "inf"/"Infinity"; non-numeric tokens fall back to 0.
+    try:
+        return int(float(_s(x)))
+    except (ValueError, TypeError, OverflowError):
+        return 0
+
+
+def parse_dimension_from_info(info: list[Any]) -> int:
+    """Extract the vector field dimension from a raw FT.INFO reply.
+
+    Handles both reply shapes across Valkey Search versions:
+
+    - flat attribute pairs with a ``DIM`` key
+    - Valkey Search 1.2, which nests dimension inside an ``index`` sub-array
+      under a ``dimensions`` key
+
+    Returns 0 if no vector field with a positive dimension is found.
+    """
+    for i in range(0, len(info) - 1, 2):
+        key = _s(info[i])
+        if key not in ("attributes", "fields"):
+            continue
+
+        attributes = info[i + 1]
+        if not isinstance(attributes, (list, tuple)):
+            continue
+
+        for attr in attributes:
+            if not isinstance(attr, (list, tuple)):
+                continue
+
+            is_vector = False
+            dim = 0
+
+            j = 0
+            while j < len(attr) - 1:
+                attr_key = _s(attr[j])
+                if attr_key == "type" and _s(attr[j + 1]) == "VECTOR":
+                    is_vector = True
+                if attr_key.lower() == "dim":
+                    dim = _to_int(attr[j + 1])
+                if attr_key == "index" and isinstance(attr[j + 1], (list, tuple)):
+                    index_arr = attr[j + 1]
+                    k = 0
+                    while k < len(index_arr) - 1:
+                        if _s(index_arr[k]) == "dimensions":
+                            d = _to_int(index_arr[k + 1])
+                            if d > 0:
+                                dim = d
+                        k += 1
+                j += 1
+
+            if is_vector and dim > 0:
+                return dim
+
+    return 0
+
+
+@dataclass(frozen=True)
+class FtIndexStats:
+    num_docs: int
+    indexing_state: str
+
+
+def parse_ft_info_stats(info: list[Any]) -> FtIndexStats:
+    """Walk the flat key/value pairs of a raw FT.INFO reply and extract
+    ``num_docs`` and the indexing state.
+    """
+    num_docs = 0
+    indexing_state = "unknown"
+    for i in range(0, len(info) - 1, 2):
+        key = _s(info[i])
+        if key == "num_docs":
+            num_docs = _to_int(info[i + 1])
+        elif key == "indexing":
+            indexing_state = _s(info[i + 1])
+    return FtIndexStats(num_docs=num_docs, indexing_state=indexing_state)

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/ft_search.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class FtSearchHit(TypedDict):
+    """A single FT.SEARCH hit: the matched key and its returned fields."""
+
+    key: str
+    fields: dict[str, str]
+
+
+def parse_ft_search_response(raw: Any) -> list[FtSearchHit]:
+    """Parse a raw FT.SEARCH response from valkey-py's execute_command().
+
+    valkey-py returns FT.SEARCH results as a mixed bytes/str list::
+
+        [totalCount, key1, [field1, val1, ...], key2, [...], ...]
+
+    Returns a list of ``{"key": str, "fields": dict[str, str]}``.
+    Returns ``[]`` if totalCount is 0 or the response is empty/malformed.
+    Never raises: on any parse error, returns ``[]``. Binary field values
+    that cannot be decoded as UTF-8 (e.g. embedding bytes) are skipped.
+    """
+    try:
+        if not isinstance(raw, (list, tuple)) or len(raw) < 1:
+            return []
+
+        total_raw = raw[0]
+        if isinstance(total_raw, bytes):
+            total_raw = total_raw.decode()
+        # Parse via float() so a float-formatted total (e.g. "2.0" from a RESP3
+        # double) yields its integer value instead of raising and collapsing to
+        # no hits — matching TS parseInt and this package's FT.INFO _to_int.
+        total = int(float(total_raw))
+
+        if total <= 0:
+            return []
+
+        results: list[FtSearchHit] = []
+        i = 1
+        while i < len(raw):
+            key = raw[i]
+            if isinstance(key, bytes):
+                key = key.decode()
+            elif not isinstance(key, str):
+                i += 1
+                continue
+
+            if i + 1 >= len(raw):
+                results.append({"key": key, "fields": {}})
+                break
+
+            field_list = raw[i + 1]
+            fields: dict[str, str] = {}
+
+            if isinstance(field_list, (list, tuple)):
+                j = 0
+                while j < len(field_list) - 1:
+                    fname = field_list[j]
+                    fval = field_list[j + 1]
+                    if isinstance(fname, bytes):
+                        fname = fname.decode()
+                    else:
+                        fname = str(fname)
+                    if isinstance(fval, bytes):
+                        try:
+                            fval = fval.decode()
+                        except (UnicodeDecodeError, AttributeError):
+                            # Binary field (e.g. embedding bytes) — skip it.
+                            j += 2
+                            continue
+                    else:
+                        fval = str(fval)
+                    fields[fname] = fval
+                    j += 2
+                i += 2
+            else:
+                results.append({"key": key, "fields": {}})
+                i += 1
+                continue
+
+            results.append({"key": key, "fields": fields})
+
+        return results
+    except Exception:
+        return []

betterdb_valkey_search_kit-0.1.0/betterdb_valkey_search_kit/tags.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import re
+
+_TAG_ESCAPE_RE = re.compile(r'([,.<>{}\[\]"\'!@#$%^&*()\-+=~|/\\:; ])')
+
+
+def escape_tag(value: str) -> str:
+    """Escape a string for safe use as a Valkey Search TAG filter value.
+
+    Spaces are escaped because Valkey Search treats unescaped spaces in TAG
+    values as term separators (OR semantics), which would broaden the filter
+    unintentionally.
+    """
+    return _TAG_ESCAPE_RE.sub(r"\\\1", value)

betterdb_valkey_search_kit-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "betterdb-valkey-search-kit"
+version = "0.1.0"
+description = "Shared Valkey Search (FT.*) helpers: float32 vector encoding, FT.SEARCH reply parsing, version-skew FT.INFO parsing, TAG escaping, and error classification."
+keywords = ["valkey", "redis", "valkey-search", "vector-search", "ft", "redisearch"]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/BetterDB-inc/monitor"
+
+[tool.hatch.build.targets.wheel]
+packages = ["betterdb_valkey_search_kit"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

betterdb_valkey_search_kit-0.1.0/tests/test_encoding.py

@@ -0,0 +1,28 @@
+import struct
+
+from betterdb_valkey_search_kit import decode_float32, encode_float32
+
+
+def test_byte_length_is_four_per_element():
+    vec = [1.0, 2.0, 3.0, 4.0]
+    buf = encode_float32(vec)
+    assert len(buf) == len(vec) * 4
+
+
+def test_little_endian_float32_values():
+    vec = [0.5, -1.25, 3.75]
+    buf = encode_float32(vec)
+    assert struct.unpack_from("<f", buf, 0)[0] == 0.5
+    assert struct.unpack_from("<f", buf, 4)[0] == -1.25
+    assert struct.unpack_from("<f", buf, 8)[0] == 3.75
+
+
+def test_decode_inverts_encode():
+    # These values are exactly representable in float32, so equality holds.
+    vec = [0.5, -1.25, 3.75]
+    assert decode_float32(encode_float32(vec)) == vec
+
+
+def test_empty_vector():
+    assert len(encode_float32([])) == 0
+    assert decode_float32(b"") == []

betterdb_valkey_search_kit-0.1.0/tests/test_errors.py

@@ -0,0 +1,50 @@
+from betterdb_valkey_search_kit import is_index_not_found_error
+
+
+def test_matches_unknown_index_name_case_insensitively():
+    assert is_index_not_found_error(Exception("Unknown Index Name")) is True
+    assert is_index_not_found_error(Exception("UNKNOWN INDEX NAME sc:idx")) is True
+
+
+def test_matches_no_such_index_case_insensitively():
+    assert is_index_not_found_error(Exception("no such index")) is True
+    assert is_index_not_found_error(Exception("sc:idx: No Such Index")) is True
+
+
+def test_matches_redis8_ft_search_phrasing():
+    assert is_index_not_found_error(Exception("No such index nonexistent_idx_xyz")) is True
+
+
+def test_matches_index_scoped_not_found_phrasings():
+    assert is_index_not_found_error(Exception("Index sc:idx: not found")) is True
+    assert is_index_not_found_error(Exception("index not found")) is True
+    assert is_index_not_found_error(Exception("Index with name foo not found")) is True
+
+
+def test_matches_the_valkey_search_12_phrasing():
+    assert (
+        is_index_not_found_error(
+            Exception("Index with name 'nonexistent_idx_xyz' not found in database 0")
+        )
+        is True
+    )
+
+
+def test_rejects_not_found_messages_without_index_context():
+    assert is_index_not_found_error(Exception("key not found")) is False
+    assert is_index_not_found_error(Exception("function not found")) is False
+    assert is_index_not_found_error(Exception("ERR value not found")) is False
+
+
+def test_rejects_index_messages_without_not_found_context():
+    assert is_index_not_found_error(Exception("index is being created")) is False
+
+
+def test_rejects_unrelated_error_messages():
+    assert is_index_not_found_error(Exception("connection refused")) is False
+
+
+def test_rejects_non_exception_values():
+    assert is_index_not_found_error("index not found") is False
+    assert is_index_not_found_error(None) is False
+    assert is_index_not_found_error({"message": "index not found"}) is False

betterdb_valkey_search_kit-0.1.0/tests/test_ft_info.py

@@ -0,0 +1,76 @@
+from betterdb_valkey_search_kit import (
+    FtIndexStats,
+    parse_dimension_from_info,
+    parse_ft_info_stats,
+)
+
+
+def test_parses_the_flat_dim_pair_shape():
+    info = [
+        "index_name",
+        "sc:idx",
+        "attributes",
+        [["identifier", "embedding", "type", "VECTOR", "DIM", "1536"]],
+    ]
+    assert parse_dimension_from_info(info) == 1536
+
+
+def test_parses_the_nested_v12_index_dimensions_shape():
+    info = [
+        "index_name",
+        "sc:idx",
+        "attributes",
+        [["identifier", "embedding", "type", "VECTOR", "index", ["dimensions", "768"]]],
+    ]
+    assert parse_dimension_from_info(info) == 768
+
+
+def test_reads_attributes_under_the_legacy_fields_key():
+    info = ["fields", [["identifier", "embedding", "type", "VECTOR", "dim", "384"]]]
+    assert parse_dimension_from_info(info) == 384
+
+
+def test_ignores_non_vector_attributes_with_a_dim_pair():
+    info = ["attributes", [["identifier", "prompt", "type", "TEXT", "DIM", "99"]]]
+    assert parse_dimension_from_info(info) == 0
+
+
+def test_returns_zero_when_no_vector_attribute_exists():
+    info = ["index_name", "sc:idx", "num_docs", "5"]
+    assert parse_dimension_from_info(info) == 0
+
+
+def test_parses_bytes_info_from_valkey_py():
+    info = [
+        b"attributes",
+        [[b"identifier", b"embedding", b"type", b"VECTOR", b"DIM", b"1536"]],
+    ]
+    assert parse_dimension_from_info(info) == 1536
+
+
+def test_stats_extracts_num_docs_and_indexing_state():
+    info = ["index_name", "sc:idx", "num_docs", "42", "indexing", "0"]
+    assert parse_ft_info_stats(info) == FtIndexStats(num_docs=42, indexing_state="0")
+
+
+def test_stats_defaults_when_keys_absent():
+    assert parse_ft_info_stats(["index_name", "sc:idx"]) == FtIndexStats(
+        num_docs=0, indexing_state="unknown"
+    )
+
+
+def test_stats_coerces_unparseable_num_docs_to_zero():
+    assert parse_ft_info_stats(["num_docs", "garbage"]) == FtIndexStats(
+        num_docs=0, indexing_state="unknown"
+    )
+
+
+def test_stats_reads_a_float_formatted_num_docs():
+    # A RESP3 double may surface as "42.0"; match TS parseInt and read 42
+    # rather than strict int() falling back to 0.
+    assert parse_ft_info_stats(["num_docs", "42.0"]).num_docs == 42
+
+
+def test_parses_a_float_formatted_dim():
+    info = ["attributes", [["identifier", "embedding", "type", "VECTOR", "DIM", "1536.0"]]]
+    assert parse_dimension_from_info(info) == 1536

betterdb_valkey_search_kit-0.1.0/tests/test_ft_search.py

@@ -0,0 +1,107 @@
+from betterdb_valkey_search_kit import parse_ft_search_response
+
+
+def test_returns_empty_for_none():
+    assert parse_ft_search_response(None) == []
+
+
+def test_returns_empty_for_empty_list():
+    assert parse_ft_search_response([]) == []
+
+
+def test_returns_empty_for_zero_count():
+    assert parse_ft_search_response(["0"]) == []
+
+
+def test_parses_a_single_entry():
+    raw = [
+        "1",
+        "cache:entry:abc",
+        ["prompt", "hello", "response", "world", "__score", "0.05"],
+    ]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 1
+    assert result[0]["key"] == "cache:entry:abc"
+    assert result[0]["fields"]["prompt"] == "hello"
+    assert result[0]["fields"]["response"] == "world"
+    assert result[0]["fields"]["__score"] == "0.05"
+
+
+def test_parses_bytes_response_from_valkey_py():
+    raw = [b"1", b"cache:entry:abc", [b"prompt", b"hello", b"__score", b"0.05"]]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 1
+    assert result[0]["key"] == "cache:entry:abc"
+    assert result[0]["fields"]["prompt"] == "hello"
+    assert result[0]["fields"]["__score"] == "0.05"
+
+
+def test_skips_undecodable_binary_field_value():
+    raw = ["1", "k", ["embedding", b"\xff\xfe\x00\x01", "prompt", "hi"]]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 1
+    assert "embedding" not in result[0]["fields"]
+    assert result[0]["fields"]["prompt"] == "hi"
+
+
+def test_extracts_score_from_two_results():
+    raw = [
+        "2",
+        "sc:entry:111",
+        ["prompt", "q1", "response", "a1", "__score", "0.0234", "model", "gpt-4o"],
+        "sc:entry:222",
+        ["prompt", "q2", "response", "a2", "__score", "0.1500", "model", "gpt-4o"],
+    ]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 2
+    assert abs(float(result[0]["fields"]["__score"]) - 0.0234) < 1e-4
+    assert abs(float(result[1]["fields"]["__score"]) - 0.15) < 1e-4
+
+
+def test_malformed_odd_length_field_list_skips_orphan():
+    raw = ["1", "key1", ["field1", "val1", "orphan"]]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 1
+    assert result[0]["fields"]["field1"] == "val1"
+    assert len(result[0]["fields"]) == 1
+
+
+def test_two_result_response():
+    raw = ["2", "key:a", ["f1", "v1"], "key:b", ["f2", "v2"]]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 2
+    assert result[0]["key"] == "key:a"
+    assert result[0]["fields"]["f1"] == "v1"
+    assert result[1]["key"] == "key:b"
+    assert result[1]["fields"]["f2"] == "v2"
+
+
+def test_return_zero_mode_keys_without_field_list():
+    raw = ["2", "key:a", "key:b"]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 2
+    assert result[0] == {"key": "key:a", "fields": {}}
+    assert result[1] == {"key": "key:b", "fields": {}}
+
+
+def test_parses_a_float_formatted_total():
+    # A RESP3 double may surface the total as "2.0"; match TS parseInt and
+    # still return the hits instead of collapsing to [].
+    raw = ["2.0", "key:a", ["f1", "v1"], "key:b", ["f2", "v2"]]
+    result = parse_ft_search_response(raw)
+    assert len(result) == 2
+    assert result[0]["key"] == "key:a"
+    assert result[1]["key"] == "key:b"
+
+
+def test_parses_a_float_formatted_total_in_bytes():
+    raw = [b"1", b"key:a", [b"f1", b"v1"]]
+    raw[0] = b"1.0"
+    result = parse_ft_search_response(raw)
+    assert len(result) == 1
+    assert result[0]["key"] == "key:a"
+
+
+def test_never_raises_on_garbage():
+    assert parse_ft_search_response("garbage") == []
+    assert parse_ft_search_response(123) == []

betterdb_valkey_search_kit-0.1.0/tests/test_tags.py

@@ -0,0 +1,21 @@
+from betterdb_valkey_search_kit import escape_tag
+
+
+def test_escapes_tag_punctuation():
+    assert escape_tag("a,b") == "a\\,b"
+    assert escape_tag("a.b") == "a\\.b"
+    assert escape_tag("a{b}") == "a\\{b\\}"
+    assert escape_tag("a|b") == "a\\|b"
+
+
+def test_escapes_spaces_to_prevent_or_semantics():
+    assert escape_tag("gpt 4o") == "gpt\\ 4o"
+
+
+def test_escapes_hyphens_and_slashes():
+    assert escape_tag("gpt-4o") == "gpt\\-4o"
+    assert escape_tag("a/b\\c") == "a\\/b\\\\c"
+
+
+def test_leaves_alphanumerics_and_underscores_untouched():
+    assert escape_tag("model_v2") == "model_v2"