feat: Enable Filters in OpenAI Search API (#4471)

# What does this PR do?

Finishes #2435; i.e.,
adds support for OpenAI Search API typed filters for vector IO.

This PR adds support for OpenAI's typed metadata filter API across
vector IO providers, enabling callers to filter search results by
metadata fields using comparison operators (eq, ne, gt, gte, lt, lte,
in, nin) and compound logic (and, or).

Core changes:

- API & routing (core/routers/vector_io.py): Propagates filter
parameters from the query request through the provider dispatch layer.
- Filter type definitions (providers/utils/vector_io/filters.py):
Introduces ComparisonFilter, CompoundFilter, and Filter union type used
across all providers.
- Inline providers (faiss, sqlite-vec): Implement filter evaluation
in-memory (faiss) and via SQL WHERE clauses using JSON_EXTRACT
(sqlite-vec). Operator dispatch uses a module-level `COMPARISON_OPS` /
`SQL_OPS` dict instead of if/elif chains.
- Remote providers (Milvus, Chroma, Elasticsearch, pgvector, Qdrant,
Weaviate, OCI): Translate filters to each backend's native expression or
query language.
- OpenAI vector store mixin (openai_vector_store_mixin.py):
Post-retrieval Python-side filter evaluation using a shared
COMPARISON_OPERATORS dispatch dict, covering providers that don't
support server-side filtering natively.
- Milvus bug fix: filter parameter was not being passed to keyword
search — corrected.

## Test Plan
- New integration test suite:
tests/integration/vector_io/test_vector_io_filters.py — covers all 8
comparison operators and compound (and/or) logic
against faiss and sqlite-vec
- New integration test:
test_openai_vector_store_search_with_typed_filters in
test_openai_vector_stores.py — validates eq/lte/compound-or filters over
the OpenAI vector store path
- Run integration tests locally via:

### faiss
.venv/bin/python -m pytest
tests/integration/vector_io/test_vector_io_filters.py \

--stack-config="inference=inline::sentence-transformers,vector_io=inline::faiss,files=inline::localfs"
-v

### sqlite-vec
.venv/bin/python -m pytest
tests/integration/vector_io/test_vector_io_filters.py \

--stack-config="inference=inline::sentence-transformers,vector_io=inline::sqlite-vec,files=inline::localfs"
-v

#### OpenAI vector store filter (mixin path)
.venv/bin/python -m pytest
tests/integration/vector_io/test_openai_vector_stores.py::test_openai_vector_store_search_with_typed_filters
\

--stack-config="inference=inline::sentence-transformers,vector_io=inline::sqlite-vec,files=inline::localfs"
-v

---------

Signed-off-by: Francisco Javier Arceo <farceo@redhat.com>
Co-authored-by: Claude Sonnet 4 <noreply@anthropic.com>

Author: franciscojavierarceo

client-sdks/stainless/openapi.yml

@@ -15651,6 +15651,50 @@ components:
           nullable: true
       title: ProcessFileRequest
       type: object
+    ComparisonFilter:
+      description: A filter that compares a metadata field against a value.
+      properties:
+        type:
+          enum:
+          - eq
+          - ne
+          - gt
+          - gte
+          - lt
+          - lte
+          - in
+          - nin
+          title: Type
+          type: string
+        key:
+          title: Key
+          type: string
+        value:
+          title: Value
+      required:
+      - type
+      - key
+      - value
+      title: ComparisonFilter
+      type: object
+    CompoundFilter:
+      description: A filter that combines multiple filters with a logical operator.
+      properties:
+        type:
+          enum:
+          - and
+          - or
+          title: Type
+          type: string
+        filters:
+          items: {}
+          title: Filters
+          type: array
+      required:
+      - type
+      - filters
+      title: CompoundFilter
+      type: object
     ListFilesRequest:
       description: Request model for listing files.
       properties:

docs/static/deprecated-llama-stack-spec.yaml

@@ -12197,6 +12197,50 @@ components:
           nullable: true
       title: ProcessFileRequest
       type: object
+    ComparisonFilter:
+      description: A filter that compares a metadata field against a value.
+      properties:
+        type:
+          enum:
+          - eq
+          - ne
+          - gt
+          - gte
+          - lt
+          - lte
+          - in
+          - nin
+          title: Type
+          type: string
+        key:
+          title: Key
+          type: string
+        value:
+          title: Value
+      required:
+      - type
+      - key
+      - value
+      title: ComparisonFilter
+      type: object
+    CompoundFilter:
+      description: A filter that combines multiple filters with a logical operator.
+      properties:
+        type:
+          enum:
+          - and
+          - or
+          title: Type
+          type: string
+        filters:
+          items: {}
+          title: Filters
+          type: array
+      required:
+      - type
+      - filters
+      title: CompoundFilter
+      type: object
     ListFilesRequest:
       description: Request model for listing files.
       properties:

docs/static/experimental-llama-stack-spec.yaml

@@ -11935,6 +11935,50 @@ components:
           nullable: true
       title: ProcessFileRequest
       type: object
+    ComparisonFilter:
+      description: A filter that compares a metadata field against a value.
+      properties:
+        type:
+          enum:
+          - eq
+          - ne
+          - gt
+          - gte
+          - lt
+          - lte
+          - in
+          - nin
+          title: Type
+          type: string
+        key:
+          title: Key
+          type: string
+        value:
+          title: Value
+      required:
+      - type
+      - key
+      - value
+      title: ComparisonFilter
+      type: object
+    CompoundFilter:
+      description: A filter that combines multiple filters with a logical operator.
+      properties:
+        type:
+          enum:
+          - and
+          - or
+          title: Type
+          type: string
+        filters:
+          items: {}
+          title: Filters
+          type: array
+      required:
+      - type
+      - filters
+      title: CompoundFilter
+      type: object
     ListFilesRequest:
       description: Request model for listing files.
       properties:

docs/static/llama-stack-spec.yaml

@@ -14006,6 +14006,50 @@ components:
           nullable: true
       title: ProcessFileRequest
       type: object
+    ComparisonFilter:
+      description: A filter that compares a metadata field against a value.
+      properties:
+        type:
+          enum:
+          - eq
+          - ne
+          - gt
+          - gte
+          - lt
+          - lte
+          - in
+          - nin
+          title: Type
+          type: string
+        key:
+          title: Key
+          type: string
+        value:
+          title: Value
+      required:
+      - type
+      - key
+      - value
+      title: ComparisonFilter
+      type: object
+    CompoundFilter:
+      description: A filter that combines multiple filters with a logical operator.
+      properties:
+        type:
+          enum:
+          - and
+          - or
+          title: Type
+          type: string
+        filters:
+          items: {}
+          title: Filters
+          type: array
+      required:
+      - type
+      - filters
+      title: CompoundFilter
+      type: object
     ListFilesRequest:
       description: Request model for listing files.
       properties:

docs/static/stainless-llama-stack-spec.yaml

@@ -15651,6 +15651,50 @@ components:
           nullable: true
       title: ProcessFileRequest
       type: object
+    ComparisonFilter:
+      description: A filter that compares a metadata field against a value.
+      properties:
+        type:
+          enum:
+          - eq
+          - ne
+          - gt
+          - gte
+          - lt
+          - lte
+          - in
+          - nin
+          title: Type
+          type: string
+        key:
+          title: Key
+          type: string
+        value:
+          title: Value
+      required:
+      - type
+      - key
+      - value
+      title: ComparisonFilter
+      type: object
+    CompoundFilter:
+      description: A filter that combines multiple filters with a logical operator.
+      properties:
+        type:
+          enum:
+          - and
+          - or
+          title: Type
+          type: string
+        filters:
+          items: {}
+          title: Filters
+          type: array
+      required:
+      - type
+      - filters
+      title: CompoundFilter
+      type: object
     ListFilesRequest:
       description: Request model for listing files.
       properties:

src/llama_stack/core/routers/vector_io.py

@@ -12,6 +12,7 @@
 
 from llama_stack.core.datatypes import VectorStoresConfig
 from llama_stack.log import get_logger
+from llama_stack.providers.utils.vector_io.filters import parse_filter
 from llama_stack_api import (
     DEFAULT_CHUNK_OVERLAP_TOKENS,
     DEFAULT_CHUNK_SIZE_TOKENS,
@@ -142,7 +143,30 @@ async def query_chunks(
         request: QueryChunksRequest,
     ) -> QueryChunksResponse:
         logger.debug(f"VectorIORouter.query_chunks: {request.vector_store_id}")
-        return await self.routing_table.query_chunks(request)
+
+        # Handle the no-filters case early
+        if not request.params or "filters" not in request.params:
+            return await self.routing_table.query_chunks(request)
+
+        # Extract and parse filters from request params
+        # Create a shallow copy to avoid mutating the caller's request
+        params_copy = dict(request.params)
+        filter_data = params_copy.pop("filters")
+
+        try:
+            parsed_filters = parse_filter(filter_data)
+        except ValueError as e:
+            logger.error(f"Invalid filter data: {e}")
+            raise ValueError(f"Invalid filter: {e}") from e
+
+        # Create a new request with the modified params
+        # Add the parsed filters back to params for the provider
+        params_copy["filters"] = parsed_filters
+        modified_request = QueryChunksRequest(
+            vector_store_id=request.vector_store_id, query=request.query, params=params_copy
+        )
+
+        return await self.routing_table.query_chunks(modified_request)
 
     # OpenAI Vector Stores API endpoints
     async def openai_create_vector_store(