"""
This type stub file was generated by pyright.
"""

from typing import Any, Dict, List, Optional, Protocol, Literal, Self

import mlx.nn as nn
from mlx.core import array
import mlx.core as mx

class Cache(Protocol):
    keys: mx.array
    values: mx.array
    def update_and_fetch(self, keys: mx.array, values: mx.array) -> None: ...
    @property
    def state(self) -> tuple[mx.array, mx.array]: ...
    @state.setter
    def state(self, v) -> None: ...

def make_prompt_cache(
    model: nn.Module, max_kv_size: Optional[int] = ...
) -> List[Cache | Any]:
    """
    Construct the model's cache for use in generation.

    This function will defer the cache construction to the model if it has a
    ``make_cache`` method, otherwise it will make a default KV cache.

    Args:
        model (nn.Module): The language model.
        max_kv_size (Optional[int]): If provided and the model does not have a
            ``make_cache`` method, a ``RotatingKVCache`` is used with a maximum
            size of ``max_kv_size``
    """

def save_prompt_cache(
    file_name: str, cache: List[Cache], metadata: Dict[str, str] = ...
) -> None:
    """
    Save a pre-computed prompt cache to a file.

    Args:
        file_name (str): The ``.safetensors`` file name.
        cache (List[Any]): The model state.
        metadata (Dict[str, str]): Optional metadata to save along with model
            state.
    """

def load_prompt_cache(file_name: str, return_metadata=...) -> array:
    """
    Load a prompt cache from a file.

    Args:
        file_name (str): The ``.safetensors`` file name.
        return_metadata (bool): Whether or not to return metadata.
            Default: ``False``.

    Returns:
        List[Any] or Tuple[List[Any], Dict[str, str]]: The prompt cache and
            the metadata if requested.
    """

def can_trim_prompt_cache(cache: List[Cache]) -> bool:
    """
    Check if model's cache can be trimmed.
    """

def trim_prompt_cache(cache: List[Cache], num_tokens: int) -> List[Cache]:
    """
    Trim the model's cache by the given number of tokens.

    This function will trim the cache if possible (in-place) and return the
    number of tokens that were trimmed.

    Args:
        cache (List[Any]): The model's cache.
        num_tokens (int): The number of tokens to trim.

    Returns:
        (int): The number of tokens that were trimmed.
    """

def create_attention_mask(
    N: int, offset: int, return_array: bool, window_size: Optional[int]
) -> array | Literal["causal"] | None: ...

class _BaseCache(Cache):
    keys: mx.array
    values: mx.array
    @property
    def state(self) -> tuple[mx.array, mx.array]: ...
    @state.setter
    def state(self, v) -> None: ...
    @property
    def meta_state(self) -> Literal[""]: ...
    @meta_state.setter
    def meta_state(self, v) -> None: ...
    def is_trimmable(self) -> Literal[False]: ...
    @classmethod
    def from_state(cls, state, meta_state) -> Self: ...

class ConcatenateKVCache(_BaseCache):
    """ConcatenateKVCache the simplest KV cache implementation.

    Can be used as a mock KV cache or when large blocks are being processed at
    a time in which case KVCache isn't necessarily faster. Consider using the
    KVCache with a larger step size before using this cache.
    """
    def __init__(self) -> None: ...
    def update_and_fetch(self, keys, values):  # -> tuple[Any | array, Any | array]:
        ...
    @property
    def state(self):  # -> tuple[Any | array | None, Any | array | None]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
    def trim(self, n):  # -> int:
        ...
    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
        ...

class QuantizedKVCache(_BaseCache):
    step = ...
    def __init__(self, group_size: int = ..., bits: int = ...) -> None: ...
    def update_and_fetch(self, keys, values):  # -> Any:
        ...
    @property
    def state(
        self,
    ):  # -> tuple[Any | tuple[array, array, array] | None, Any | tuple[array, array, array] | None] | Any:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    @property
    def meta_state(self):  # -> tuple[str, ...]:
        ...
    @meta_state.setter
    def meta_state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
    def trim(self, n):  # -> int:
        ...
    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
        ...

class KVCache(_BaseCache):
    step = ...
    def __init__(self) -> None: ...
    def update_and_fetch(self, keys, values):  # -> tuple[array | Any, array | Any]:
        ...
    @property
    def state(
        self,
    ) -> tuple[array, array]: ...
    @state.setter
    def state(self, v) -> None: ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
    def trim(self, n):  # -> int:
        ...
    def to_quantized(
        self, group_size: int = ..., bits: int = ...
    ) -> QuantizedKVCache: ...
    def make_mask(self, *args, **kwargs):  # -> array | Literal['causal'] | None:
        ...

class RotatingKVCache(_BaseCache):
    step = ...
    def __init__(self, max_size, keep=...) -> None: ...
    def update_and_fetch(
        self, keys, values
    ):  # -> tuple[array | Any, array | Any] | tuple[array | Any, array | Any | None]:
        ...
    @property
    def state(
        self,
    ):  # -> tuple[Any | array, Any | array] | tuple[Any | array | None, Any | array | None]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    @property
    def meta_state(self):  # -> tuple[str, ...]:
        ...
    @meta_state.setter
    def meta_state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> bool:
        ...
    def trim(self, n):  # -> int:
        ...
    def to_quantized(
        self, group_size: int = ..., bits: int = ...
    ) -> QuantizedKVCache: ...
    def make_mask(
        self, N: int, window_size: Optional[int] = ..., return_array: bool = ...
    ):  # -> array | Literal['causal'] | None:
        ...

class ArraysCache(_BaseCache):
    def __init__(self, size, left_padding: Optional[List[int]] = ...) -> None: ...
    def __setitem__(self, idx, value):  # -> None:
        ...
    def __getitem__(self, idx): ...
    @property
    def state(self):  # -> list[Any | array] | list[array]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    def filter(self, batch_indices):  # -> None:
        """
        In-place filter to keep just the given indices in the cache.
        """

    def extend(self, other):  # -> None:
        """
        In-place extend this cache with the other cache.
        """

    def make_mask(self, N: int):  # -> array | None:
        ...

class MambaCache(ArraysCache):
    def __init__(self, left_padding: Optional[List[int]] = ...) -> None: ...

class ChunkedKVCache(KVCache):
    def __init__(self, chunk_size) -> None: ...
    def maybe_trim_front(self):  # -> None:
        ...
    def update_and_fetch(self, keys, values):  # -> tuple[array, array]:
        ...
    def trim(self, n):  # -> int:
        ...
    @property
    def meta_state(self):  # -> tuple[str, ...]:
        ...
    @meta_state.setter
    def meta_state(self, v):  # -> None:
        ...

class CacheList(_BaseCache):
    def __init__(self, *caches) -> None: ...
    def __getitem__(self, idx): ...
    def is_trimmable(self):  # -> bool:
        ...
    def trim(self, n): ...
    @property
    def state(self):  # -> list[Any]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    def filter(self, batch_indices):  # -> None:
        """
        In-place filter to keep just the given indices in the cache.
        """

    def extend(self, other):  # -> None:
        """
        In-place extend this cache with the other cache.
        """

class BatchKVCache(_BaseCache):
    step = ...
    def __init__(self, left_padding: List[int]) -> None:
        """
        The BatchKV cache expects inputs to be left-padded.

        E.g. the following prompts:

            [1, 3, 5]
            [7]
            [2, 6, 8, 9]

        Should be padded like so:

            [0, 1, 3, 5]
            [0, 0, 0, 7]
            [2, 6, 8, 9]

        And ``left_padding`` specifies the amount of padding for each.
        In this case, ``left_padding = [1, 3, 0]``.
        """

    def update_and_fetch(self, keys, values):  # -> tuple[array | Any, array | Any]:
        ...
    @property
    def state(
        self,
    ):  # -> tuple[Any | array | None, Any | array | None, array | Any, array | Any]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> Literal[True]:
        ...
    def trim(self, n):  # -> int | float:
        ...
    def make_mask(self, N: int, return_array: bool = ..., **kwargs):  # -> array:
        ...
    def filter(self, batch_indices):  # -> None:
        """
        In-place filter to keep just the given indices in the cache.
        """

    def extend(self, other):  # -> None:
        """
        In-place extend this cache with the other cache.
        """

class BatchRotatingKVCache(_BaseCache):
    step = ...
    def __init__(self, max_size, left_padding: List[int]) -> None: ...
    def update_and_fetch(
        self, keys, values
    ):  # -> tuple[array | Any, array | Any] | tuple[array | Any, array | Any | None]:
        ...
    @property
    def state(
        self,
    ):  # -> tuple[Any | array | None, Any | array | None, array | Any, array | Any]:
        ...
    @state.setter
    def state(self, v):  # -> None:
        ...
    @property
    def meta_state(self):  # -> tuple[str, ...]:
        ...
    @meta_state.setter
    def meta_state(self, v):  # -> None:
        ...
    def is_trimmable(self):  # -> bool:
        ...
    def trim(self, n):  # -> int:
        ...
    def to_quantized(
        self, group_size: int = ..., bits: int = ...
    ) -> QuantizedKVCache: ...
    def make_mask(
        self, N: int, window_size: Optional[int] = ..., return_array: bool = ...
    ):  # -> array:
        ...
    def filter(self, batch_indices):  # -> None:
        """
        In-place filter to keep just the given indices in the cache.
        """

    def extend(self, other):  # -> None:
        """
        In-place extend this cache with the other cache.
        """
