"""Type definitions for inference namespace."""

from typing import Literal, TypedDict


# Inference API parameter types
# Note: Using Literal | str pattern for forward compatibility with API evolution.
# This allows IDE autocomplete for known values while permitting new API values without SDK updates.

# Embed parameters
InputType = Literal["passage", "query"] | str
"""Input text type for embeddings.

Use "passage" for documents to be searched, "query" for search queries.
Additional values may be supported by specific models.
"""

TruncateMode = Literal["END", "NONE", "START"] | str
"""Text truncation strategy when exceeding model token limits.

"END" truncates at the end, "NONE" errors on overflow, "START" truncates at beginning.
Additional modes may be supported by specific models.
"""


class EmbedParameters(TypedDict, total=False):
    """Optional parameters for embedding generation.

    All fields are optional. Additional model-specific parameters not listed here
    can be passed and will be forwarded to the API.

    Attributes:
        input_type: Type of input text. Use "passage" for documents to be searched,
            "query" for search queries. Models may use this to optimize embeddings
            for retrieval tasks.
        truncate: How to handle text exceeding the model's token limit. "END"
            truncates at the end (default behavior), "NONE" returns an error on
            overflow, "START" truncates at the beginning.
    """

    input_type: InputType
    truncate: TruncateMode


# Note: RerankParameters is intentionally not defined as a TypedDict
# because rerank parameters are entirely model-specific with no common
# parameters across models. Use dict[str, Any] for maximum flexibility.
