feat(python): add local cross-encoder reranker support

sdks/python/sdk/README.md

@@ -186,6 +186,31 @@ results = await client.query(
 
 For a complete runnable example, see [`examples/python/metadata_filtering.py`](../../examples/python/metadata_filtering.py).
 
+### Reranking (High Precision)
+
+If you need higher precision at the top of the result list than first-stage retrieval gives, you can enable the optional local cross-encoder reranker.
+
+When `rerank=True` is provided, Moss will fetch a larger pool of candidates (`rerank_top_k`, default 50) and locally re-score them using a `sentence-transformers` cross-encoder before returning the final `top_k` results.
+
+First, install the optional dependencies:
+```bash
+pip install 'moss[rerank]'
+```
+
+Then, enable it in your query:
+```python
+results = await client.query(
+    "my-docs",
+    "How to process a refund?",
+    QueryOptions(
+        top_k=5, 
+        rerank=True, 
+        rerank_top_k=50, # Optional: number of candidates to fetch for reranking
+        # rerank_model="cross-encoder/ms-marco-MiniLM-L-6-v2" # Optional override
+    ),
+)
+```
+
 ## 🧠 Providing custom embeddings
 
 Already using your own embedding model? Supply vectors directly when managing

sdks/python/sdk/pyproject.toml

@@ -32,6 +32,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+rerank = [
+    "sentence-transformers>=3.0.0",
+]
 dev = [
     "pytest>=8.4.2",
     "pytest-asyncio>=1.2.0",

sdks/python/sdk/src/moss/__init__.py

@@ -24,19 +24,18 @@
     IndexInfo,
     IndexStatus,
     IndexStatusValues,
-    ModelRef,
-    MutationOptions,
-    MutationResult,
-    JobStatus,
     JobPhase,
     JobProgress,
+    JobStatus,
     JobStatusResponse,
-    QueryOptions,
+    ModelRef,
+    MutationOptions,
+    MutationResult,
     QueryResultDocumentInfo,
     SearchResult,
 )
 
-from .client.moss_client import MossClient
+from .client.moss_client import MossClient, QueryOptions
 
 __version__ = "1.0.0b19"
 

sdks/python/sdk/src/moss/__init__.pyi

@@ -2,89 +2,73 @@ from __future__ import annotations
 
 from typing import ClassVar, Dict, List, Optional, Sequence
 
-
 class MossClient:
     """Semantic search client for vector similarity operations."""
 
     DEFAULT_MODEL_ID: ClassVar[str]
 
     def __init__(self, project_id: str, project_key: str) -> None: ...
-
     async def create_index(
         self,
         name: str,
         docs: List[DocumentInfo],
         model_id: Optional[str] = ...,
     ) -> MutationResult: ...
-
     async def add_docs(
         self,
         name: str,
         docs: List[DocumentInfo],
         options: Optional[MutationOptions] = None,
     ) -> MutationResult: ...
-
     async def delete_docs(
         self,
         name: str,
         doc_ids: List[str],
     ) -> MutationResult: ...
-
     async def get_job_status(self, job_id: str) -> JobStatusResponse: ...
-
     async def get_index(self, name: str) -> IndexInfo: ...
-
     async def list_indexes(self) -> List[IndexInfo]: ...
-
     async def delete_index(self, name: str) -> bool: ...
-
     async def get_docs(
         self,
         name: str,
         options: Optional[GetDocumentsOptions] = None,
     ) -> List[DocumentInfo]: ...
-
     async def load_index(
         self,
         name: str,
         auto_refresh: bool = False,
         polling_interval_in_seconds: int = 600,
     ) -> str: ...
-
     async def unload_index(self, name: str) -> None: ...
-
     async def query(
         self,
         name: str,
         query: str,
         options: Optional[QueryOptions] = None,
     ) -> SearchResult: ...
 
-
 class MutationResult:
     """Return value from create_index/add_docs/delete_docs."""
 
     job_id: str
     index_name: str
     doc_count: int
 
-
 class MutationOptions:
     """Options for add_docs (e.g. upsert behavior)."""
 
     upsert: Optional[bool]
 
     def __init__(self, upsert: Optional[bool] = None) -> None: ...
 
-
 class GetDocumentsOptions:
     """Options for get_docs (e.g. filter by document IDs)."""
 
     doc_ids: Optional[List[str]]
 
     def __init__(self, doc_ids: Optional[List[str]] = None) -> None: ...
 
-
 class JobStatus:
     """Enum-like class for job status values."""
 
@@ -96,7 +80,6 @@ class JobStatus:
 
     value: str
 
-
 class JobPhase:
     """Enum-like class for job phase values."""
 
@@ -109,7 +92,6 @@ class JobPhase:
 
     value: str
 
-
 class JobProgress:
     """Progress update for a job."""
 
@@ -118,7 +100,6 @@ class JobProgress:
     progress: float
     current_phase: Optional[JobPhase]
 
-
 class JobStatusResponse:
     """Full status response from get_job_status."""
 
@@ -131,13 +112,11 @@ class JobStatusResponse:
     updated_at: str
     completed_at: Optional[str]
 
-
 class ModelRef:
     id: str
     version: str
     def __init__(self, id: str, version: str) -> None: ...
 
-
 class QueryResultDocumentInfo:
     id: str
     text: str
@@ -151,7 +130,6 @@ class QueryResultDocumentInfo:
         score: float = ...,
     ) -> None: ...
 
-
 class DocumentInfo:
     id: str
     text: str
@@ -165,21 +143,25 @@ class DocumentInfo:
         embedding: Optional[Sequence[float]] = ...,
     ) -> None: ...
 
-
 class QueryOptions:
     embedding: Optional[Sequence[float]]
     top_k: Optional[int]
     alpha: Optional[float]
     filter: Optional[dict]
+    rerank: bool
+    rerank_top_k: Optional[int]
+    rerank_model: Optional[str]
     def __init__(
         self,
         embedding: Optional[Sequence[float]] = ...,
         top_k: Optional[int] = ...,
         alpha: Optional[float] = ...,
         filter: Optional[dict] = ...,
+        rerank: bool = ...,
+        rerank_top_k: Optional[int] = ...,
+        rerank_model: Optional[str] = ...,
     ) -> None: ...
 
-
 class IndexInfo:
     id: str
     name: str
@@ -201,7 +183,6 @@ class IndexInfo:
         model: ModelRef,
     ) -> None: ...
 
-
 class SearchResult:
     docs: List[QueryResultDocumentInfo]
     query: str
@@ -215,15 +196,13 @@ class SearchResult:
         time_taken_ms: Optional[int] = None,
     ) -> None: ...
 
-
 class IndexStatus:
     NotStarted: ClassVar[str]
     Building: ClassVar[str]
     Ready: ClassVar[str]
     Failed: ClassVar[str]
     def __init__(self, value: str) -> None: ...
 
-
 IndexStatusValues: Dict[str, str]
 
 __version__: str