"""Score-by query models for document search."""

from msgspec import Struct


class SparseValues(Struct, kw_only=True):
    """Sparse vector representation.

    Attributes:
        indices: Non-zero dimension indices.
        values: Corresponding values for each index.

    Examples:
        >>> sparse = SparseValues(indices=[0, 5, 10, 100], values=[0.5, 0.3, 0.8, 0.2])
    """

    indices: list[int]
    values: list[float]


class DenseVectorQuery(Struct, kw_only=True):
    """Query documents by dense vector similarity.

    Searches for documents whose dense vector embeddings are most similar
    to the provided query vector.

    Attributes:
        type: Query type identifier (always "dense_vector").
        field: Name of the field containing dense vectors to search.
        values: Query vector as a list of floats.

    Examples:
        >>> query = DenseVectorQuery(field="_values", values=[0.1, 0.2, 0.3, 0.4, 0.5])
    """

    type: str = "dense_vector"
    field: str
    values: list[float]


class SparseVectorQuery(Struct, kw_only=True):
    """Query documents by sparse vector similarity.

    Searches for documents using sparse vector representations, useful for
    keyword-based search or high-dimensional vectors with few non-zero values.

    Attributes:
        type: Query type identifier (always "sparse_vector").
        field: Name of the field containing sparse vectors to search.
        sparse_values: Sparse vector with indices and values.

    Examples:
        >>> query = SparseVectorQuery(
        ...     field="_sparse_values",
        ...     sparse_values=SparseValues(indices=[0, 5, 10, 100], values=[0.5, 0.3, 0.8, 0.2]),
        ... )
    """

    type: str = "sparse_vector"
    field: str
    sparse_values: SparseValues


class TextQuery(Struct, kw_only=True):
    """Query documents using full-text search.

    Performs full-text search on the specified field using natural language queries.

    Attributes:
        type: Query type identifier (always "text").
        field: Name of the text field to search.
        query: Search query string.

    Examples:
        >>> query = TextQuery(field="text", query="action movie with robots")
    """

    type: str = "text"
    field: str
    query: str


class QueryStringQuery(Struct, kw_only=True):
    """Query documents using query string syntax.

    Supports advanced query string syntax with boolean operators (AND, OR, NOT)
    and field-specific queries.

    Attributes:
        type: Query type identifier (always "query_string").
        field: Name of the field to search.
        query: Query string with operators.

    Examples:
        >>> query = QueryStringQuery(field="text", query="robots AND (action OR adventure)")
    """

    type: str = "query_string"
    field: str
    query: str


# Union type for type hints
ScoreByQuery = DenseVectorQuery | SparseVectorQuery | TextQuery | QueryStringQuery
