feat(search): add filter builder DSL and fix search payload for document-index

- Add pharia/filters.py with Filter, And, Or, Not, ModalityCondition
  for Pythonic operator-overloaded search filters
- Fix search_input_to_api to produce document-index format: query wrapped
  as [{"modality": "text", "text": ...}], limit renamed to maxResults
- Change search() return type to list[SearchResult] matching API response
- Export Filter DSL from pharia/__init__.py
- Add 34 unit tests in tests/test_filters.py
- Update integration tests and documentation

Author: alphamt

README.md

@@ -200,7 +200,7 @@ meta    = await client.v1.search_stores(ssid).documents("my-doc").get()
 content = await client.v1.search_stores(ssid).documents("my-doc").get_content()  # list[ContentDTO]
 
 # Search
-results = await client.v1.search_stores(ssid).search(query="hello", limit=5)
+results = await client.v1.search_stores(ssid).search(query="hello", max_results=5)
 
 # List, filter, batch
 docs = await client.v1.search_stores(ssid).documents.list(page=1, size=10, starts_with="my")
@@ -229,6 +229,51 @@ ss = await client.v1.search_stores.vllm.create(
 )
 ```
 
+### Search Filters (Filter DSL)
+
+The SDK provides a Pythonic filter builder using operator overloading:
+
+```python
+from pharia import Filter, And, Or, Not, ModalityCondition
+from datetime import datetime
+
+# Metadata comparisons
+Filter("category") == "science"          # equalTo
+Filter("category") == None               # isNull
+Filter("priority") > 5                   # greaterThan
+Filter("priority") >= 5                  # greaterThanOrEqualTo
+Filter("priority") < 10                  # lessThan
+Filter("priority") <= 10                 # lessThanOrEqualTo
+
+# Datetime comparisons (auto-detected)
+Filter("created") > datetime(2024, 1, 1) # after
+Filter("created") <= datetime(2024, 12, 31) # atOrBefore
+
+# Modality filters
+ModalityCondition.text()                 # {"modality": "text"}
+ModalityCondition.image()                # {"modality": "image"}
+
+# Combine with And / Or / Not
+results = await client.v1.search_stores(ssid).search(
+    query="machine learning",
+    max_results=10,
+    filters=[
+        And(Filter("category") == "science", ModalityCondition.text()),
+        Not(Filter("archived") == None),
+    ],
+)
+```
+
+Raw camelCase dicts are also accepted for backward compatibility:
+
+```python
+results = await client.v1.search_stores(ssid).search(
+    query="hello",
+    max_results=5,
+    filters=[{"with": [{"metadata": {"field": "category", "equalTo": "science"}}]}],
+)
+```
+
 ## Type Safety
 
 Full TypedDict support for type checking and IDE autocomplete:

examples/README.md

@@ -46,6 +46,21 @@ python create_stages.py
 
 ---
 
+### 🔍 Search Stores
+**File:** `search_stores_usage.py`
+
+Full search store lifecycle including the Filter DSL:
+- Create search stores (semantic, instruct)
+- Add documents and search with metadata filters
+- Use `Filter`, `And`, `Or`, `Not`, and `ModalityCondition` for Pythonic queries
+
+```bash
+cd pharia/examples
+python search_stores_usage.py
+```
+
+---
+
 ### 🛡️ Type-Safe Usage
 **File:** `typed_usage.py`
 

examples/search_stores_usage.py

@@ -7,14 +7,18 @@
 - Listing search stores
 - Getting a specific search store
 - Updating search store metadata
+- Searching with the Filter DSL
 - Deleting a search store
 """
 
 import asyncio
 import uuid
 
 from examples.helpers import ExamplePrinter
+from pharia import And
 from pharia import Client
+from pharia import Filter
+from pharia import ModalityCondition
 
 
 async def main():
@@ -95,8 +99,38 @@ async def main():
             {"Metadata keys": list(updated_store.get("metadata", {}).keys())},
         )
 
-        # Example 6: Delete the search stores (fluent API)
-        p.section(6, 6, "Deleting search stores")
+        # Example 6: Search with Filter DSL
+        p.section(6, 7, "Searching with Filter DSL")
+
+        # Add a document so there's something to search
+        doc_name = f"test-doc-{uuid.uuid4().hex[:8]}"
+        await (
+            client.v1.search_stores(semantic_store_id)
+            .documents(doc_name)
+            .create_or_update(
+                schema_version="V1",
+                contents=[{"modality": "text", "text": "Machine learning is a subset of AI."}],
+                metadata={"category": "science"},
+            )
+        )
+        p.info(f"Created document: {doc_name}", indent=1)
+
+        # Search using the Filter DSL
+        search_result = await client.v1.search_stores(semantic_store_id).search(
+            query="artificial intelligence",
+            max_results=5,
+            filters=[And(Filter("category") == "science", ModalityCondition.text())],
+        )
+        p.success(
+            f"Search returned {len(search_result)} results",
+            {"Query": "artificial intelligence", "Filter": 'category == "science"'},
+        )
+
+        # Clean up document
+        await client.v1.search_stores(semantic_store_id).documents(doc_name).delete()
+
+        # Example 7: Delete the search stores (fluent API)
+        p.section(7, 7, "Deleting search stores")
         await client.v1.search_stores(semantic_store_id).delete()
         p.success(f"Deleted semantic search store: {semantic_store_id}")
 

pharia/__init__.py

@@ -22,6 +22,11 @@
 """
 
 from pharia.client import Client
+from pharia.filters import And
+from pharia.filters import Filter
+from pharia.filters import ModalityCondition
+from pharia.filters import Not
+from pharia.filters import Or
 from pharia.models import ChunkingStrategy
 from pharia.models import Connector
 from pharia.models import ConnectorFile
@@ -104,15 +109,13 @@
 
 
 __all__ = [
+    "And",
     "ChunkingStrategy",
-    # Client
     "Client",
-    # Connector types
     "Connector",
     "ConnectorFile",
     "ConnectorFilesListResponse",
     "ConnectorListResponse",
-    # Enums
     "ConnectorType",
     "ContentDTO",
     "CreateConnectorInput",
@@ -125,62 +128,56 @@
     "Cursor",
     "DataObjectDTO",
     "DataStorage",
-    # Dataset types
     "Dataset",
     "DatasetListResponse",
     "DestinationConfig",
     "DestinationType",
-    # Document types
     "Document",
     "DocumentContentResponse",
     "DocumentListResponse",
     "DocumentSection",
     "DocumentWithContents",
-    # Other types
     "Download",
     "EmbeddingStrategy",
     "EmbeddingStrategyInstructConfig",
     "EmbeddingStrategySemanticConfig",
     "EmbeddingStrategyVLLMConfig",
-    # File types
     "File",
     "FileListResponse",
+    "Filter",
     "GoogleDriveSourceConfig",
     "IngestionContext",
     "MediaType",
     "Modality",
+    "ModalityCondition",
+    "Not",
+    "Or",
     "PaginationBase",
     "Parameter",
     "PresignedURL",
     "QueryEngineCloseSessionResult",
     "QueryEngineCommandResult",
     "QueryEngineDatabaseFile",
     "QueryEngineQueryResult",
-    # Query Engine types
     "QueryEngineSession",
-    # Repository types
     "Repository",
     "RepositoryListResponse",
     "RetentionPolicy",
     "Run",
     "RunListResponse",
     "SchemaVersion",
-    # Search types
     "SearchInput",
     "SearchResponse",
     "SearchResult",
-    # Search Store types
     "SearchStore",
     "SearchStoreListResponse",
     "SharepointSourceConfig",
     "SourceConfig",
-    # Stage types
     "Stage",
     "StageChunkingStrategy",
     "StageEmbeddingStrategy",
     "StageListResponse",
     "StageSearchStoreContext",
-    # Transformation & Run types
     "Transformation",
     "TransformationContext",
     "TransformationName",