daft.functions.jev_score#

def jev_score(
    row: Expression,
    question: str,
    levels: list[str],
    *,
    model: str | None = None,
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: float = 60.0,
) -> Expression:
    """Where each row falls on an ordered rubric, as a probability-weighted level index.

    Args:
        row (Expression): The value to score. Pass `to_struct(...)` to score on several columns.
        question (str): A plain-English question, e.g. "how luxurious is this product?".
        levels (list[str]): Between 2 and 10 rubric levels, lowest first.
        model (str | None): The Jev model. Defaults to `TYPESAFE_DEFAULT_MODEL`, else `jev-latest`.
        api_key (str | None): TypeSafe API key. Defaults to `TYPESAFE_API_KEY`.
        base_url (str | None): API root, e.g. to route through a proxy. Defaults to `TYPESAFE_BASE_URL`, else `https://api.typesafe.ai`.
        timeout (float): Seconds allowed for each request, which carries up to 25 rows. Defaults to 60.

    Returns:
        Expression: A Float64 in [0, len(levels) - 1] that may fall between levels, or null where `row` is null.

    Examples:
        >>> import daft
        >>> from daft.functions import jev_score
        >>> df = daft.from_pydict({"product": ["Plastic stool", "Hand-stitched leather armchair"]})
        >>> levels = ["budget", "mid-range", "premium", "luxury"]
        >>> df = df.with_column(
        ...     "tier", jev_score(df["product"], "how luxurious is this product?", levels)
        ... )  # doctest: +SKIP
        >>> df.sort("tier", desc=True).show()  # doctest: +SKIP
    """
    if not 2 <= len(levels) <= 10:
        raise ValueError(f"jev_score requires between 2 and 10 levels, got {len(levels)}")
    return _client(api_key, model, base_url, timeout).score(serialize(row, format="json"), question, list(levels))