from __future__ import annotations

from collections.abc import Sequence
from pathlib import Path
from typing import Any, Literal

import pandas as pd

from .flow_sentences.api import generate_sentences as _impl_generate_sentences

BalanceStrategy = Literal["none", "downsample", "cap"]


def generate_sentences(
    data: pd.DataFrame | str | bytes | Path,
    *,
    sep: str = ",",
    encoding: str | None = "utf-8",
    dtype: dict[str, Any] | None = None,
    parse_dates: list[str] | None = None,
    na_values: list[str] | None = None,
    nrows: int | None = None,
    # balancing
    balance: BalanceStrategy | bool = "none",
    balance_labels: Sequence[str] | None = None,
    per_class_cap: int | None = None,
    random_state: int = 42,
    # others
    max_items: int | None = None,
    show_progress: bool = False,
) -> pd.DataFrame:
    """
    One-shot CSV/DataFrame → sentences (English).
    Returns ONLY: sentence, description, label. 
    """
    return _impl_generate_sentences(
        data,
        sep=sep,
        encoding=encoding,
        dtype=dtype,
        parse_dates=parse_dates,
        na_values=na_values,
        nrows=nrows,
        # balancing
        balance=balance,
        balance_labels=balance_labels,
        per_class_cap=per_class_cap,
        random_state=random_state,
        # others
        max_items=max_items,
        show_progress=show_progress,
    )
