From b539c1a497b02aab353991ae80ffdcd3a8729942 Mon Sep 17 00:00:00 2001
From: Dt8333 <lb0016@foxmail.com>
Date: Mon, 17 Nov 2025 17:36:40 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E8=A1=A5=E5=85=85faiss=E5=A3=B0?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 typings/faiss/__init__.pyi | 47 +++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/typings/faiss/__init__.pyi b/typings/faiss/__init__.pyi
index fc316dfea..6f2bace36 100644
--- a/typings/faiss/__init__.pyi
+++ b/typings/faiss/__init__.pyi
@@ -5,7 +5,7 @@ project uses, including the runtime-monkeypatched signatures such as
 `Index.add_with_ids` so Pyright/Pylance stops reporting false positives.
 """
 
-from typing import Any
+from typing import Any, overload
 
 import numpy as np
 
@@ -27,10 +27,20 @@ class Index:
         I: np.ndarray | None = ...,
     ) -> tuple[np.ndarray, np.ndarray]: ...
     def remove_ids(self, x: np.ndarray) -> int: ...
-    def reconstruct(self, key: int, x: np.ndarray | None = ...) -> np.ndarray: ...
+    @overload
+    def reconstruct(self, key: int) -> np.ndarray: ...
+    @overload
+    def reconstruct(self, key: int, x: np.ndarray) -> None: ...
+    def reconstruct(
+        self, key: int, x: np.ndarray | None = ...
+    ) -> np.ndarray | None: ...
+    @overload
+    def reconstruct_n(self, n0: int, ni: int) -> np.ndarray: ...
+    @overload
+    def reconstruct_n(self, n0: int, ni: int, x: np.ndarray) -> None: ...
     def reconstruct_n(
         self, n0: int = ..., ni: int = ..., x: np.ndarray | None = ...
-    ) -> np.ndarray: ...
+    ) -> np.ndarray | None: ...
     def range_search(
         self, x: np.ndarray, thresh: float, *, params: Any = ...
     ) -> tuple[np.ndarray, np.ndarray, np.ndarray]: ...
@@ -42,8 +52,39 @@ class IndexFlatL2(Index):
     def __init__(self, d: int) -> None: ...
 
 class IndexIDMap(Index):
+    index: Index
+
     def __init__(self, index: Index) -> None: ...
 
 def read_index(path: str) -> Index: ...
 def write_index(index: Index, path: str | None = ...) -> None: ...
 def normalize_L2(x: np.ndarray) -> None: ...
+
+# Additional concrete-ish classes exposed by some faiss builds (SWIG helpers
+# expose `downcast_*` helpers to convert generic objects to these concrete
+# types). We keep these minimal — only the names are important for typing.
+class IndexBinary(Index):
+    def __init__(self, d: int) -> None: ...
+
+class InvertedLists:
+    def __len__(self) -> int: ...
+
+class AdditiveQuantizer:
+    pass
+
+class Quantizer:
+    pass
+
+class VectorTransform:
+    pass
+
+# SWIG-provided downcast helpers (present in some faiss Python builds).
+def downcast_IndexBinary(obj: Any) -> IndexBinary: ...
+def downcast_InvertedLists(obj: Any) -> InvertedLists: ...
+def downcast_AdditiveQuantizer(obj: Any) -> AdditiveQuantizer: ...
+def downcast_Quantizer(obj: Any) -> Quantizer: ...
+def downcast_VectorTransform(obj: Any) -> VectorTransform: ...
+def downcast_index(obj: Any) -> Index: ...
+
+# version exposed by runtime
+__version__: str