"""Describe-index-stats method for Index."""

from __future__ import annotations

from typing import Any

import msgspec

from pinecone.models.index.describe_index_stats import DescribeIndexStatsResponse


_DECODER = msgspec.json.Decoder(DescribeIndexStatsResponse)


def describe_index_stats(
    self: Any,
    *,
    filter: dict[str, Any] | None = None,
) -> DescribeIndexStatsResponse:
    """Get index statistics.

    Args:
        filter: Optional metadata filter for filtered stats.

    Returns:
        DescribeIndexStatsResponse with index statistics.

    Example:
        >>> stats = index.describe_index_stats()
        >>> print(f"Total vectors: {stats.total_vector_count}")
        >>> print(f"Dimension: {stats.dimension}")
        >>> print(f"Fullness: {stats.index_fullness:.2%}")
    """
    body: dict[str, Any] = {}
    if filter is not None:
        body["filter"] = filter

    data = self._make_data_plane_request("POST", "/describe_index_stats", body=body)
    return _DECODER.decode(data)
