feat: add Client.search for vector, keyword, and hybrid search

[lukekim]

What

Adds Client.search(), wrapping the runtime's POST /v1/search — vector similarity, keyword, and hybrid search over datasets with an embedding column.

response = client.search("tickets to Tokyo", datasets=["app_messages"], limit=3)

for match in response:
    print(match.dataset, match.score, match.matches)

text is the only positional argument; datasets, limit, where, additional_columns and keywords are keyword-only. Setting keywords pre-filters the embedding column with a lexical search before the vector search runs, making the search hybrid.

New public exports: SearchResponse and SearchMatch, with the implementation in a private _search module.

Why

/v1/search works on a default spice run and is a distinctive Spice capability, but Python users had no way to reach it short of hand-rolling the HTTP call. spice.js is currently the only SDK that exposes it.

Two wire-format details SearchMatch handles so callers don't have to:

• the similarity score is serialized as _score, not score
• data, primary_key and metadata are omitted entirely when empty, so they default to {} rather than None — readable without a guard

Part of aligning search support across the SDKs.

Verification

• Unit tests pass — 16 new tests in tests/test_search.py covering body construction, wire-format decoding, and client wiring. Full unit run: 395 passed.
• make lint — ruff clean; pylint 9.23/10 against the repo's --fail-under=8.0 gate
• make type-check — mypy reports no issues
• ruff format clean on the new module
• Verified against a live spice run: the search request reaches /v1/search, and a failure
  surfaces the runtime's own message rather than a bare 400 Client Error
• A search returning matches was not exercised end to end — that needs a dataset with an embedding
  column and a loaded embedding model, which this environment has no credentials for. The 8
  tests/test_main.py failures in a full run are refused Flight connections and are unrelated.

Note: make format-check fails on 15 files on trunk already; this branch does not add to that set.

[Copilot]

Pull request overview

Adds first-class Python SDK support for the runtime’s /v1/search endpoint by introducing Client.search() plus public response/match types, aligning search capabilities with other SDKs.

Changes:

• Introduces spicepy._search with SearchResponse, SearchMatch, and build_search_body() for request/response handling.
• Adds Client.search() to POST /v1/search and decode results into SearchResponse.
• Exposes new types from spicepy.__init__, adds README usage docs, and adds a dedicated unit test suite.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_search.py	Adds unit tests for request body construction, wire-format decoding, and Client.search wiring.
spicepy/_search.py	Implements search request builder and response/match decoding types.
spicepy/_client.py	Adds Client.search() method that calls /v1/search and returns a decoded SearchResponse.
spicepy/init.py	Exports SearchMatch and SearchResponse as public SDK symbols.
README.md	Documents search() usage, parameters, and returned match structure.

Comments suppressed due to low confidence (1)

spicepy/_search.py:70

• SearchResponse.from_dict currently assumes results is a list of dicts; if the runtime returns an unexpected shape (e.g. results is a dict/string), the list comprehension will throw an AttributeError from inside SearchMatch.from_dict, which is harder for callers to understand/handle. Validating results (and normalizing duration_ms) lets you raise a clear SpiceAIError consistently.

        if not isinstance(payload, dict):
            raise SpiceAIError(f"unexpected search response from the runtime: {payload!r}")

        return cls(
            results=[SearchMatch.from_dict(m) for m in payload.get("results") or []],

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

spicepy/_search.py:51

• SearchMatch.from_dict assumes payload is a dict and will raise an AttributeError if the runtime ever returns a non-dict match item (or if callers pass through unvalidated data). Since these helpers are public exports, it’s better to validate the wire shape and raise SpiceAIError with a clear message instead of failing with an unrelated attribute error.

    @classmethod
    def from_dict(cls, payload: dict[str, Any]) -> SearchMatch:
        """Build a match from the runtime's wire format.

        The wire format names the similarity score ``_score``.
        """
        return cls(
            dataset=payload.get("dataset", ""),
            score=payload.get("_score", 0.0),
            matches=payload.get("matches") or {},
            primary_key=payload.get("primary_key") or {},
            data=payload.get("data") or {},
            metadata=payload.get("metadata") or {},
        )

spicepy/_search.py:73

• SearchResponse.from_dict can currently crash with AttributeError/TypeError if results is present but not a list (e.g. a dict due to a server-side change) because the list-comprehension will iterate unexpected values and pass them into SearchMatch.from_dict. Consider validating the results field type and raising SpiceAIError with the same “unexpected search response” message to keep failures actionable.

    @classmethod
    def from_dict(cls, payload: dict[str, Any]) -> SearchResponse:
        """Build a response from the runtime's wire format."""
        if not isinstance(payload, dict):
            raise SpiceAIError(f"unexpected search response from the runtime: {payload!r}")

        return cls(
            results=[SearchMatch.from_dict(m) for m in payload.get("results") or []],
            duration_ms=payload.get("duration_ms", 0),
        )

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

spicepy/_search.py:43

• SearchMatch.from_dict assumes payload is a dict and will raise an AttributeError (not SpiceAIError) if the runtime returns an unexpected item type in results. Consider accepting Any and validating the payload type up front so callers always get a consistent, actionable exception.

    def from_dict(cls, payload: dict[str, Any]) -> SearchMatch:
        """Build a match from the runtime's wire format.

        The wire format names the similarity score ``_score``.
        """

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

spicepy/_search.py:41

• Defensive decoding: SearchMatch.from_dict assumes payload and the matches/primary_key/data/metadata fields are dicts. If the runtime (or a proxy) returns an unexpected shape, this will raise AttributeError/TypeError instead of a consistent SpiceAIError.

    @classmethod
    def from_dict(cls, payload: dict[str, Any]) -> SearchMatch:
        """Build a match from the runtime's wire format.

spicepy/_search.py:75

• Defensive decoding: SearchResponse.from_dict assumes results is a list of dicts. If results is present but not a list (or contains non-dicts), iteration will fail with a non-SpiceAIError exception; validating the shape makes failures clearer.

        return cls(
            results=[SearchMatch.from_dict(m) for m in payload.get("results") or []],
            duration_ms=payload.get("duration_ms", 0),
        )

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

spicepy/_search.py:43

• SearchMatch.from_dict() assumes payload is a dict; if the runtime returns a malformed element inside results (e.g., a string/null), this will raise an AttributeError (.get) rather than a consistent SpiceAIError message.

    def from_dict(cls, payload: dict[str, Any]) -> SearchMatch:
        """Build a match from the runtime's wire format.

        The wire format names the similarity score ``_score``.
        """

spicepy/_search.py:71

• SearchResponse.from_dict() iterates over payload.get("results") without validating its type. If the runtime sends results as a dict/string by mistake, the list-comprehension will iterate keys/characters and fail with a confusing downstream error.

        if not isinstance(payload, dict):
            raise SpiceAIError(
                f"unexpected search response from the runtime: {payload!r}"
            )

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

.github/workflows/test.yml:163

• The non-Windows readiness loop breaks when the dataset becomes queryable, but if it never does, the step still succeeds and the workflow proceeds to tests without emitting the spice log. This makes failures harder to diagnose and can produce misleading test errors. Consider failing explicitly after the loop (mirroring the Windows step) and printing spice.log.

          for i in {1..120}; do
            if curl -s -X POST http://localhost:8090/v1/sql \
                 -d 'SELECT count(*) AS n FROM taxi_trips' 2>/dev/null | grep -q '"n"'; then
              echo "Spice runtime is ready and taxi_trips is queryable"
              break

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

spicepy/_search.py:67

• SearchMatch.from_dict() assigns _score directly to score without coercion. If the runtime/proxy returns null, a string, or a boolean, this produces a non-float score despite the declared type and can break callers later.

        return cls(
            dataset=payload.get("dataset", ""),
            score=payload.get("_score", 0.0),

.github/workflows/test.yml:163

• In the non-Windows job, the readiness loop breaks on success but never fails the step on timeout. If taxi_trips never becomes queryable, the workflow will continue and fail later in a less actionable way (or flake).

          for i in {1..120}; do
            if curl -s -X POST http://localhost:8090/v1/sql \
                 -d 'SELECT count(*) AS n FROM taxi_trips' 2>/dev/null | grep -q '"n"'; then
              echo "Spice runtime is ready and taxi_trips is queryable"
              break

spicepy/_search.py:99

• SearchResponse.from_dict() uses payload.get("results") or [], which silently converts falsy non-list values (e.g., {}) into an empty list and skips the shape validation. That contradicts the goal of failing loudly on malformed responses.

        results = payload.get("results") or []
        if not isinstance(results, list):
            raise SpiceAIError(
                f"unexpected search results from the runtime: {results!r}"
            )