# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

from __future__ import annotations

from typing import Dict, List, Union, Iterable
from typing_extensions import Literal, Required, Annotated, TypeAlias, TypedDict

from ..._types import SequenceNotStr
from ..._utils import PropertyInfo

__all__ = [
    "WidgetCreateParams",
    "Query",
    "QuerySeriesQuery",
    "QuerySeriesQuerySelect",
    "QuerySeriesQuerySelectExpression",
    "QuerySeriesQuerySelectExpressionColumn",
    "QuerySeriesQuerySelectExpressionAggregation",
    "QuerySeriesQueryFilter",
    "QuerySeriesQueryFilterCondition",
    "QuerySeriesQueryOrderBy",
    "QueryMetricQuery",
    "QueryMetricQuerySelect",
    "QueryMetricQuerySelectExpression",
    "QueryMetricQuerySelectExpressionColumn",
    "QueryMetricQuerySelectExpressionAggregation",
    "QueryMetricQueryFilter",
    "QueryMetricQueryFilterCondition",
]


class WidgetCreateParams(TypedDict, total=False):
    title: Required[str]
    """Widget title"""

    type: Required[Literal["bar", "histogram", "metric", "table", "markdown", "heading"]]
    """Widget type"""

    config: Dict[str, object]
    """Chart-specific display configuration"""

    query: Query
    """Structured query AST for metric computation (SeriesQuery or MetricQuery)"""


class QuerySeriesQuerySelectExpressionColumn(TypedDict, total=False):
    """Reference to a column from evaluation_items.data

    Example:
        {"type": "COLUMN", "column": "category"}
    """

    column: Required[str]
    """Column name from evaluation_items.data"""

    source: str
    """Column source: 'data' or 'task_result_cache'"""

    type: Literal["COLUMN"]


class QuerySeriesQuerySelectExpressionAggregation(TypedDict, total=False):
    """Aggregation function to apply

    Examples:
        {"type": "AGGREGATION", "function": "AVG", "column": "score"}
        {"type": "AGGREGATION", "function": "COUNT", "column": "*"}
        {"type": "AGGREGATION", "function": "PERCENTILE", "column": "score", "params": {"percentile": 95}}
    """

    column: Required[str]
    """Column to aggregate, or '_' for COUNT(_)"""

    function: Required[
        Literal["COUNT", "SUM", "AVG", "MIN", "MAX", "STDDEV", "VARIANCE", "PERCENTILE", "COUNT_DISTINCT", "PERCENTAGE"]
    ]
    """Supported aggregation functions"""

    params: Dict[str, object]
    """
    Function parameters (e.g., {'percentile': 95} for PERCENTILE,
    {'percentage_filters': Filter} for PERCENTAGE)
    """

    source: str
    """Column source: 'data' or 'task_result_cache'"""

    type: Literal["AGGREGATION"]


QuerySeriesQuerySelectExpression: TypeAlias = Union[
    QuerySeriesQuerySelectExpressionColumn, QuerySeriesQuerySelectExpressionAggregation
]


class QuerySeriesQuerySelect(TypedDict, total=False):
    """Column in SELECT clause"""

    expression: Required[QuerySeriesQuerySelectExpression]
    """Reference to a column from evaluation_items.data

    Example: {"type": "COLUMN", "column": "category"}
    """

    alias: str
    """Optional alias for the selected item"""


class QuerySeriesQueryFilterCondition(TypedDict, total=False):
    """Single filter condition comparing a column to a value.

    Example:
        {"column": "score", "operator": ">", "value": 0.5}
        {"column": "category", "operator": "=", "value": "test"}
    """

    column: Required[str]
    """Column name to filter on"""

    operator: Required[Literal["=", "!=", ">", "<", ">=", "<=", "IN", "NOT IN", "LIKE", "NOT LIKE"]]
    """Comparison operator"""

    value: Required[object]
    """Value to compare against"""

    source: str
    """Column source: 'data' or 'task_result_cache'"""


class QuerySeriesQueryFilter(TypedDict, total=False):
    """Filter conditions (WHERE clause)"""

    conditions: Required[Iterable[QuerySeriesQueryFilterCondition]]

    logical_operators: Annotated[List[Literal["AND", "OR"]], PropertyInfo(alias="logicalOperators")]
    """Logical operators connecting conditions. Length must be len(conditions) - 1"""


class QuerySeriesQueryOrderBy(TypedDict, total=False):
    """Column in ORDER BY clause"""

    column: Required[str]
    """Column name to sort by"""

    direction: Literal["ASC", "DESC"]
    """Sort direction"""

    source: str
    """Column source: 'data' or 'task_result_cache'"""


class QuerySeriesQuery(TypedDict, total=False):
    """Query that returns a series of records (used for table/bar/histogram widgets).

    Used for widget types: table, bar, histogram.
    Returns: {"type": "series", "data": [...]}

    Example SQL equivalent:
        SELECT category, AVG(score) as avg_score, COUNT(*) as count
        FROM evaluation_items
        WHERE score > 0.5 AND category = 'test'
        GROUP BY category
        ORDER BY avg_score DESC
        LIMIT 100
    """

    select: Required[Iterable[QuerySeriesQuerySelect]]

    filter: QuerySeriesQueryFilter
    """Filter conditions (WHERE clause)"""

    group_by: Annotated[SequenceNotStr[str], PropertyInfo(alias="groupBy")]
    """Columns to group by"""

    limit: int
    """Max rows to return"""

    order_by: Annotated[Iterable[QuerySeriesQueryOrderBy], PropertyInfo(alias="orderBy")]
    """Sort order"""


class QueryMetricQuerySelectExpressionColumn(TypedDict, total=False):
    """Reference to a column from evaluation_items.data

    Example:
        {"type": "COLUMN", "column": "category"}
    """

    column: Required[str]
    """Column name from evaluation_items.data"""

    source: str
    """Column source: 'data' or 'task_result_cache'"""

    type: Literal["COLUMN"]


class QueryMetricQuerySelectExpressionAggregation(TypedDict, total=False):
    """Aggregation function to apply

    Examples:
        {"type": "AGGREGATION", "function": "AVG", "column": "score"}
        {"type": "AGGREGATION", "function": "COUNT", "column": "*"}
        {"type": "AGGREGATION", "function": "PERCENTILE", "column": "score", "params": {"percentile": 95}}
    """

    column: Required[str]
    """Column to aggregate, or '_' for COUNT(_)"""

    function: Required[
        Literal["COUNT", "SUM", "AVG", "MIN", "MAX", "STDDEV", "VARIANCE", "PERCENTILE", "COUNT_DISTINCT", "PERCENTAGE"]
    ]
    """Supported aggregation functions"""

    params: Dict[str, object]
    """
    Function parameters (e.g., {'percentile': 95} for PERCENTILE,
    {'percentage_filters': Filter} for PERCENTAGE)
    """

    source: str
    """Column source: 'data' or 'task_result_cache'"""

    type: Literal["AGGREGATION"]


QueryMetricQuerySelectExpression: TypeAlias = Union[
    QueryMetricQuerySelectExpressionColumn, QueryMetricQuerySelectExpressionAggregation
]


class QueryMetricQuerySelect(TypedDict, total=False):
    """Column in SELECT clause"""

    expression: Required[QueryMetricQuerySelectExpression]
    """Reference to a column from evaluation_items.data

    Example: {"type": "COLUMN", "column": "category"}
    """

    alias: str
    """Optional alias for the selected item"""


class QueryMetricQueryFilterCondition(TypedDict, total=False):
    """Single filter condition comparing a column to a value.

    Example:
        {"column": "score", "operator": ">", "value": 0.5}
        {"column": "category", "operator": "=", "value": "test"}
    """

    column: Required[str]
    """Column name to filter on"""

    operator: Required[Literal["=", "!=", ">", "<", ">=", "<=", "IN", "NOT IN", "LIKE", "NOT LIKE"]]
    """Comparison operator"""

    value: Required[object]
    """Value to compare against"""

    source: str
    """Column source: 'data' or 'task_result_cache'"""


class QueryMetricQueryFilter(TypedDict, total=False):
    """Filter conditions (WHERE clause)"""

    conditions: Required[Iterable[QueryMetricQueryFilterCondition]]

    logical_operators: Annotated[List[Literal["AND", "OR"]], PropertyInfo(alias="logicalOperators")]
    """Logical operators connecting conditions. Length must be len(conditions) - 1"""


class QueryMetricQuery(TypedDict, total=False):
    """Query that returns a single metric value (used for metric widgets).

    Used for widget type: metric.
    Enforces exactly 1 aggregation in select.
    Returns: {"type": "metric", "data": ...}

    Example SQL equivalent:
        SELECT AVG(score) as average_score
        FROM evaluation_items
    """

    select: Required[Iterable[QueryMetricQuerySelect]]

    filter: QueryMetricQueryFilter
    """Filter conditions (WHERE clause)"""


Query: TypeAlias = Union[QuerySeriesQuery, QueryMetricQuery]
