Update Python type stubs (__init__.pyi) to match current API (#4998)

Summary:
Pull Request resolved: https://github.com/facebookresearch/faiss/pull/4998

🤖 This diff was automatically generated by myclaw_faiss_monitor

Updates the PEP 561 type stubs for the faiss Python package to reflect
API changes since the initial stubs were added in D94139717.

Changes:
- Fix wrong RaBitQ constructor signatures (IndexRaBitQ, IndexIVFRaBitQ)
  to match actual C++ constructors (removed nonexistent M, nbit, trained
  params, renamed attribute from rq to rabitq)
- Add missing Panorama index classes: IndexFlatPanorama,
  IndexFlatL2Panorama, IndexFlatIPPanorama, IndexHNSWFlatPanorama,
  IndexIVFFlatPanorama, IndexRefinePanorama
- Add RaBitQ FastScan classes: IndexRaBitQFastScan,
  IndexIVFRaBitQFastScan
- Add RaBitQ search parameter classes: RaBitQSearchParameters,
  IVFRaBitQSearchParameters
- Add HadamardRotation VectorTransform
- Add IndexQINCo class, fix IndexNeuralNetCodec constructor signature
- Fix IndexRandom constructor (add missing ntotal, metric params)
- Add new ClusteringParameters fields (init_method,
  afkmc2_chain_length, early_stop_threshold)
- Add deserialization safety functions (get/set_deserialization_loop_limit,
  get/set_deserialization_vector_byte_limit)

Reviewed By: mnorris11

Differential Revision: D98439353

fbshipit-source-id: c6b8908d85bb3edaae30613e7e89074034678a7b

faiss/python/__init__.pyi

@@ -492,6 +492,17 @@ class RandomRotationMatrix(LinearTransform):
     def __init__(self, d_in: int, d_out: int) -> None: ...
     def init(self, seed: int) -> None: ...
 
+class HadamardRotation(VectorTransform):
+    """Three rounds of random sign-flip + Fast Walsh-Hadamard Transform.
+    Produces a pseudo-random rotation in O(d log d) time.
+    d_out is the smallest power of 2 >= d_in (zero-padded as needed).
+    """
+
+    seed: int
+
+    def __init__(self, d: int, seed: int = 12345) -> None: ...
+    def init(self, seed: int) -> None: ...
+
 class PCAMatrix(LinearTransform):
     eigen_power: float
     epsilon: float
@@ -638,6 +649,31 @@ class IndexFlat1D(IndexFlatL2):
     def update_permutation(self) -> None: ...
     def reset(self) -> None: ...
 
+class IndexFlatPanorama(IndexFlat):
+    """Panorama implementation of IndexFlat following https://arxiv.org/abs/2510.00566"""
+
+    batch_size: int
+    n_levels: int
+
+    def __init__(
+        self,
+        d: int,
+        metric: MetricType,
+        n_levels: int,
+        batch_size: int,
+    ) -> None: ...
+    def permute_entries(self, perm: npt.NDArray[np.int64]) -> None: ...
+
+class IndexFlatL2Panorama(IndexFlatPanorama):
+    def __init__(
+        self, d: int, n_levels: int, batch_size: int = 512
+    ) -> None: ...
+
+class IndexFlatIPPanorama(IndexFlatPanorama):
+    def __init__(
+        self, d: int, n_levels: int, batch_size: int = 512
+    ) -> None: ...
+
 class IndexPreTransform(Index):
     chain: list[VectorTransform]  # std::vector<VectorTransform*> chain
     index: Index
@@ -1617,6 +1653,21 @@ class IndexIVFFlat(IndexIVF):
         self, quantizer: Index, d: int, nlist: int, metric: MetricType = METRIC_L2
     ) -> None: ...
 
+class IndexIVFFlatPanorama(IndexIVFFlat):
+    """Panorama adaptation of IndexIVFFlat following https://arxiv.org/abs/2510.00566"""
+
+    n_levels: int
+
+    def __init__(
+        self,
+        quantizer: Index,
+        d: int,
+        nlist: int,
+        n_levels: int,
+        metric: MetricType = METRIC_L2,
+        own_invlists: bool = True,
+    ) -> None: ...
+
 class IndexIVFPQ(IndexIVF):
     pq: ProductQuantizer
     code_size: int
@@ -1744,6 +1795,21 @@ class IndexHNSW(Index):
 class IndexHNSWFlat(IndexHNSW):
     def __init__(self, d: int, M: int, metric: MetricType = METRIC_L2) -> None: ...
 
+class IndexHNSWFlatPanorama(IndexHNSWFlat):
+    """Panorama implementation of IndexHNSWFlat.
+    Uses progressive distance refinement to prune candidates early.
+    """
+
+    num_panorama_levels: int
+
+    def __init__(
+        self,
+        d: int,
+        M: int,
+        num_panorama_levels: int,
+        metric: MetricType = METRIC_L2,
+    ) -> None: ...
+
 class IndexHNSWPQ(IndexHNSW):
     pq: ProductQuantizer
 
@@ -1997,6 +2063,15 @@ class IndexRefineFlat(IndexRefine):
         self, base_index: Index | None = None, xb: npt.NDArray[np.float32] | None = None
     ) -> None: ...
 
+class IndexRefinePanorama(IndexRefine):
+    """Version where the search calls search_subset, allowing for Panorama refinement."""
+
+    def __init__(
+        self,
+        base_index: Index | None = None,
+        refine_index: Index | None = None,
+    ) -> None: ...
+
 # FastScan base class
 class IndexFastScan(Index):
     M: int
@@ -2088,6 +2163,12 @@ def read_VectorTransform(fname: str) -> VectorTransform: ...
 def write_InvertedLists(invlists: InvertedLists, writer: IOWriter) -> None: ...
 def read_InvertedLists(reader: IOReader, io_flags: int = 0) -> InvertedLists: ...
 
+# Deserialization safety limits
+def get_deserialization_loop_limit() -> int: ...
+def set_deserialization_loop_limit(value: int) -> None: ...
+def get_deserialization_vector_byte_limit() -> int: ...
+def set_deserialization_vector_byte_limit(value: int) -> None: ...
+
 # Search with parameters functions
 @overload
 def search_with_parameters(
@@ -2278,6 +2359,9 @@ class ClusteringParameters:
     decode_block_size: int
     check_input_data_for_NaNs: bool
     use_faster_subsampling: bool
+    init_method: int  # ClusteringInitMethod enum (RANDOM=0, KMEANS_PLUS_PLUS=1, AFK_MC2=2)
+    afkmc2_chain_length: int  # chain length for AFK-MC² initialization
+    early_stop_threshold: float  # early stop threshold [0, 1]
 
     def __init__(self) -> None: ...
 
@@ -3063,9 +3147,15 @@ class IndexRowwiseMinMaxFP16(Index):
 
 # IndexRandom for testing
 class IndexRandom(Index):
-    d: int
+    seed: int
 
-    def __init__(self, d: int, seed: int = 1234) -> None: ...
+    def __init__(
+        self,
+        d: int,
+        ntotal: int = 0,
+        seed: int = 1234,
+        metric: MetricType = METRIC_L2,
+    ) -> None: ...
 
 # IndexShards and IndexReplicas (already templated in SWIG)
 class IndexShardsIVF(Index):
@@ -3269,40 +3359,108 @@ class LocalSearchCoarseQuantizer(Index):
 
 # NeuralNet index
 class IndexNeuralNetCodec(Index):
-    d: int
+    M: int
+    nbits: int
 
-    def __init__(self, d: int, filename: str) -> None: ...
-
-# RaBitQ indices
-class IndexRaBitQ(Index):
-    rq: RaBitQuantizer
-    codes: UInt8Vector
+    def __init__(
+        self,
+        d: int = 0,
+        M: int = 0,
+        nbits: int = 0,
+        metric: MetricType = METRIC_L2,
+    ) -> None: ...
 
+class IndexQINCo(IndexNeuralNetCodec):
     def __init__(
         self,
         d: int,
         M: int,
-        nbit: int = 1,
+        nbits: int,
+        L: int,
+        h: int,
         metric: MetricType = METRIC_L2,
-        trained: bool = True,
     ) -> None: ...
 
+# RaBitQ indices
+class RaBitQSearchParameters(SearchParameters):
+    qb: int  # number of bits to quantize a query with (0 = raw fp32)
+    centered: bool  # quantize with zero-centered scalar quantizer
+
+    def __init__(self) -> None: ...
+
+class IndexRaBitQ(Index):
+    rabitq: RaBitQuantizer
+    center: Float32Vector
+    qb: int  # default number of bits to quantize a query with
+    centered: bool
+
+    def __init__(
+        self,
+        d: int,
+        metric: MetricType = METRIC_L2,
+        nb_bits: int = 1,
+    ) -> None: ...
+
+class IVFRaBitQSearchParameters(IVFSearchParameters):
+    qb: int
+    centered: bool
+
+    def __init__(self) -> None: ...
+
 class IndexIVFRaBitQ(IndexIVF):
-    rq: RaBitQuantizer
-    code_size: int
-    by_residual: bool
+    rabitq: RaBitQuantizer
+    qb: int
 
     def __init__(
         self,
         quantizer: Index,
         d: int,
         nlist: int,
-        M: int,
-        nbit: int = 1,
         metric: MetricType = METRIC_L2,
-        encode_residual: bool = True,
+        own_invlists: bool = True,
+        nb_bits: int = 1,
     ) -> None: ...
 
+class IndexRaBitQFastScan(IndexFastScan):
+    """Fast-scan version of RaBitQ that processes 32 database vectors at a time using SIMD."""
+
+    rabitq: RaBitQuantizer
+    center: Float32Vector
+    qb: int
+    centered: bool
+
+    @overload
+    def __init__(
+        self,
+        d: int,
+        metric: MetricType = METRIC_L2,
+        bbs: int = 32,
+        nb_bits: int = 1,
+    ) -> None: ...
+    @overload
+    def __init__(self, orig: IndexRaBitQ, bbs: int = 32) -> None: ...
+
+class IndexIVFRaBitQFastScan(IndexIVFFastScan):
+    """Fast-scan version of IndexIVFRaBitQ that processes vectors in batches using SIMD."""
+
+    rabitq: RaBitQuantizer
+    qb: int
+    centered: bool
+
+    @overload
+    def __init__(
+        self,
+        quantizer: Index,
+        d: int,
+        nlist: int,
+        metric: MetricType = METRIC_L2,
+        bbs: int = 32,
+        own_invlists: bool = True,
+        nb_bits: int = 1,
+    ) -> None: ...
+    @overload
+    def __init__(self, orig: IndexIVFRaBitQ, bbs: int = 32) -> None: ...
+
 # Independent quantizer
 class IndexIVFIndependentQuantizer(Index):
     quantizer: Index