# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
import typing
__all__ = [
    "BM25Scoring",
    "BOWIndexBuilder",
    "BmpSearcher",
    "BuilderOptions",
    "CompressionTransform",
    "DocMetadata",
    "Document",
    "DocumentStore",
    "DocumentStoreBuilder",
    "EliasFanoCompressor",
    "GlobalImpactQuantizer",
    "ImpactCompressor",
    "ImpactQuantizer",
    "Index",
    "IndexBuilder",
    "IndexView",
    "PyDocIdCompressor",
    "PyScoredDocument",
    "PyTransform",
    "ScoredIndex",
    "SparseIndexIterator",
    "SplitIndexTransform",
    "TermImpact",
]

@typing.final
class BM25Scoring:
    r"""
    BM25 scoring model.
    """
    def __new__(cls, k1: builtins.float = 1.2000000476837158, b: builtins.float = 0.75) -> BM25Scoring: ...

@typing.final
class BOWIndexBuilder:
    r"""
    Bag-of-words index builder for traditional IR (BM25, TF-IDF, etc.).

    Example:

    ```python,ignore
    builder = impact_index.BOWIndexBuilder("/path/to/index", dtype="int32")
    builder.add(0, terms, tf_values)
    index, doc_meta = builder.build(in_memory=True)
    scored = index.with_scoring(impact_index.BM25Scoring(), doc_meta)
    results = scored.search_wand(query, top_k=10)
    ```
    """
    ...

@typing.final
class BmpSearcher:
    r"""
    BMP (Block-Max Pruning) Searcher for fast approximate search
    """
    def __new__(cls, path: builtins.str) -> BmpSearcher: ...
    def search(self, query: typing.Mapping[builtins.str, builtins.float], k: builtins.int, alpha: builtins.float = 1.0, beta: builtins.float = 1.0) -> tuple[builtins.list[builtins.str], builtins.list[builtins.float]]: ...
    def num_documents(self) -> builtins.int: ...

@typing.final
class BuilderOptions:
    r"""
    Configuration options for IndexBuilder.
    """
    @property
    def checkpoint_frequency(self) -> builtins.int: ...
    @checkpoint_frequency.setter
    def checkpoint_frequency(self, value: builtins.int) -> None: ...
    @property
    def in_memory_threshold(self) -> builtins.int: ...
    @in_memory_threshold.setter
    def in_memory_threshold(self, value: builtins.int) -> None: ...
    def __new__(cls) -> BuilderOptions: ...

@typing.final
class CompressionTransform(impactindex.PyTransform):
    r"""
    Transform that compresses an index using block-based encoding.
    """
    ...

@typing.final
class DocMetadata:
    r"""
    Document metadata (document lengths) for use with scoring models.
    """
    @staticmethod
    def load(folder: builtins.str) -> DocMetadata: ...
    def num_docs(self) -> builtins.int: ...
    def avg_dl(self) -> builtins.float: ...
    def min_dl(self) -> builtins.int: ...
    @staticmethod
    def copy_files(src: builtins.str, dst: builtins.str) -> None: ...

@typing.final
class Document:
    ...

@typing.final
class DocumentStore:
    ...

@typing.final
class DocumentStoreBuilder:
    ...

@typing.final
class EliasFanoCompressor(impactindex.PyDocIdCompressor):
    r"""
    Elias-Fano encoding for document ID compression.
    """
    ...

@typing.final
class GlobalImpactQuantizer(impactindex.ImpactCompressor):
    r"""
    Auto-ranging quantizer that determines min/max from the index.
    """
    ...

class ImpactCompressor:
    r"""
    Base class for impact value compressors.
    """
    ...

@typing.final
class ImpactQuantizer(impactindex.ImpactCompressor):
    r"""
    Fixed-range quantizer for impact values.
    """
    ...

@typing.final
class Index(impactindex.IndexView):
    r"""
    A loaded sparse index that supports searching and iteration.

    Use ``Index.load(folder, in_memory)`` to load an existing index,
    or build one with ``IndexBuilder``.

    Example:

    ```python,ignore
    import impact_index
    index = impact_index.Index.load("/path/to/index", in_memory=True)
    results = index.search_wand({42: 1.5, 100: 0.8}, top_k=10)
    for doc in results:
        print(doc.docid, doc.score)
    ```
    """
    def postings(self, term: builtins.int) -> SparseIndexIterator:
        r"""
        Returns an iterator over the posting list for the given term index.
        """
    def num_postings(self) -> builtins.int:
        r"""
        Returns the number of distinct terms in the index.
        """
    def search(self, py_query: dict, top_k: builtins.int) -> typing.Any:
        r"""
        Search the index (deprecated, use search_wand instead).
        """
    def search_wand(self, py_query: dict, top_k: builtins.int) -> typing.Any:
        r"""
        Search using the WAND algorithm.
        """
    def search_maxscore(self, py_query: dict, top_k: builtins.int) -> typing.Any:
        r"""
        Search using the MaxScore algorithm.
        """
    def aio_search_wand(self, py_query: dict, top_k: builtins.int) -> typing.Any:
        r"""
        Async version of search_wand.
        """
    def aio_search_maxscore(self, py_query: dict, top_k: builtins.int) -> typing.Any:
        r"""
        Async version of search_maxscore.
        """
    def to_bmp(self, output: builtins.str, bsize: builtins.int, compress_range: builtins.bool) -> None:
        r"""
        Convert the index into BMP format.
        """
    def to_bmp_streaming(self, output: builtins.str, bsize: builtins.int, compress_range: builtins.bool) -> None:
        r"""
        Convert into a BMP index using streaming (memory-efficient) method.
        """
    def with_scoring(self, scoring: BM25Scoring, doc_meta: DocMetadata) -> typing.Any:
        r"""
        Create a scored index that applies a scoring model to raw postings.
        """
    @staticmethod
    def load(folder: builtins.str, in_memory: builtins.bool) -> typing.Any:
        r"""
        Load an index from a directory.
        """

@typing.final
class IndexBuilder:
    r"""
    Builds a sparse index from document impact vectors.
    """
    ...

class IndexView:
    r"""
    Base class for index views.
    """
    ...

class PyDocIdCompressor:
    r"""
    Base class for document ID compressors.
    """
    ...

@typing.final
class PyScoredDocument:
    r"""
    A document with its retrieval score, returned by search methods.
    """
    @property
    def score(self) -> builtins.float:
        r"""
        The relevance score.
        """
    @property
    def docid(self) -> builtins.int:
        r"""
        The document identifier.
        """

class PyTransform:
    r"""
    Base class for index transforms.
    """
    def process(self, path: builtins.str, index: Index) -> None:
        r"""
        Apply this transform to an index, writing the result to path.
        """

@typing.final
class ScoredIndex(impactindex.IndexView):
    r"""
    A scored index that applies a scoring model to raw postings.
    """
    def search_wand(self, py_query: dict, top_k: builtins.int) -> typing.Any: ...
    def search_maxscore(self, py_query: dict, top_k: builtins.int) -> typing.Any: ...

@typing.final
class SparseIndexIterator:
    r"""
    Iterator over term impacts in a posting list.

    Yields TermImpact objects with (docid, value) pairs.
    Also provides metadata: length(), max_value(), max_doc_id().
    """
    def __next__(self) -> typing.Optional[TermImpact]: ...
    def __iter__(self) -> SparseIndexIterator: ...
    def length(self) -> builtins.int:
        r"""
        Returns the total number of postings for this term.
        """
    def max_value(self) -> builtins.float:
        r"""
        Returns the maximum impact value for this term.
        """
    def max_doc_id(self) -> builtins.int:
        r"""
        Returns the maximum document ID in this posting list.
        """

@typing.final
class SplitIndexTransform(impactindex.PyTransform):
    r"""
    Transform that splits posting lists by impact quantiles.
    """
    ...

@typing.final
class TermImpact:
    r"""
    A single term impact: a (document ID, impact value) pair.
    """
    @property
    def value(self) -> builtins.float:
        r"""
        The impact value.
        """
    @property
    def docid(self) -> builtins.int:
        r"""
        The document identifier.
        """
