API reference¶

polars-llm registers an llm namespace on every Polars expression. Import the package once and the namespace becomes available on any expression that resolves to a string column (the prompt).

import polars as pl
import polars_llm  # noqa: F401  — registers the `.llm` namespace

Chat verbs¶

Method	Provider	Mode
`chat`	Any compatible client	sync
`achat`	Any compatible client	async
`openai`	OpenAI	sync
`aopenai`	OpenAI	async
`anthropic`	Anthropic	sync
`aanthropic`	Anthropic	async
`gemini`	Google Gemini	sync
`agemini`	Google Gemini	async

Chat verbs return a Utf8 column with the model's response. With schema=, they return a struct column matching the Pydantic model.

Embedding verbs¶

Method	Provider	Mode
`embed`	Any compatible client	sync
`aembed`	Any compatible client	async
`openai_embed`	OpenAI Embeddings	sync
`aopenai_embed`	OpenAI Embeddings	async
`gemini_embed`	Google Gemini	sync
`agemini_embed`	Google Gemini	async

Embedding verbs return a List[Float64] column.

TypeSafe decision verbs¶

Method	Provider	Mode
`typesafe`	TypeSafe System One	sync
`atypesafe`	TypeSafe System One	async

The source expression is evaluated as TypeSafe state. Pass questions= with any mix of Choice, Score, and Noul questions. These methods return a nested struct with one answer field per question; with_metadata=True also includes the model, token usage, elapsed time, and error. Install them with pip install "polars-llm[typesafe]" on Python 3.10 or newer.

Vector helpers¶

Method	Description
`cosine`	Compute cosine similarity with another vector expression or a literal vector. No provider call is made.

Nearest-neighbor joins¶

polars_llm also registers an .ann namespace on DataFrames. Use df.ann.knn(other, ...) to return the closest rows from another DataFrame. Both vector columns must have matching dimensions and use List[Float32/64] or Array[Float32/64, dim] values.

`polars_llm._ann.Ann` ¶

DataFrame namespace for approximate / exact nearest-neighbour joins.

Source code in polars_llm/_ann.py

@pl.api.register_dataframe_namespace("ann")
class Ann:
    """DataFrame namespace for approximate / exact nearest-neighbour joins."""

    def __init__(self, df: pl.DataFrame) -> None:
        self._df = df

    def knn(
        self,
        other: pl.DataFrame,
        *,
        on: str | None = None,
        left_on: str | None = None,
        right_on: str | None = None,
        k: int = 5,
        metric: Metric = "cosine",
        backend: Backend = "auto",
        flat: bool = True,
        suffix: str = "_right",
        rank_name: str = "rank",
        score_name: str = "score",
        **backend_kwargs: Any,
    ) -> pl.DataFrame:
        """Top-K nearest-neighbour join against ``other``.

        Each row in ``self`` is matched against ``other`` using the chosen
        ``metric``; the result holds the ``k`` closest neighbours per row.

        Parameters
        ----------
        other:
            The right-hand DataFrame to search.
        on, left_on, right_on:
            Vector column name(s). Use ``on="vector"`` when both DataFrames
            share the column name, otherwise pass ``left_on`` and ``right_on``.
        k:
            Number of neighbours to return. Clamped to ``len(other)``.
        metric:
            ``"cosine"`` (default), ``"ip"``, or ``"l2"``. Lower score = closer.
        backend:
            ``"auto"`` (brute force up to a few x 10^4 right rows, otherwise
            usearch when installed), ``"brute"``, or ``"usearch"``.
        flat:
            ``True`` (default) returns a flat join of ``len(self) * k`` rows
            with all columns from both sides plus ``rank`` / ``score``.
            ``False`` returns ``len(self)`` rows with a ``neighbors``
            ``List[Struct]`` column carrying the right-side rows.
        suffix:
            Collision suffix for right-side columns (only used when ``flat``).
        rank_name, score_name:
            Names of the rank/score columns added to the output.
        **backend_kwargs:
            Forwarded to ``usearch.index.Index`` (e.g. ``connectivity``,
            ``expansion_add``, ``expansion_search``, ``dtype``).
        """
        import numpy as np  # noqa: F401  -- ensures numpy is installed

        left_col, right_col = _resolve_keys(on, left_on, right_on)
        left_vec = _to_matrix(self._df, left_col)
        right_vec = _to_matrix(other, right_col)
        if left_vec.shape[1] != right_vec.shape[1]:
            raise ValueError(
                f"polars-llm: vector dim mismatch: left {left_vec.shape[1]} != right {right_vec.shape[1]}.",
            )
        if other.height == 0:
            raise ValueError("polars-llm: `other` is empty; cannot run knn.")
        if k < 1:
            raise ValueError(f"polars-llm: `k` must be >= 1, got {k}.")

        chosen = _pick_backend(backend, other.height)
        if chosen == "brute":
            indices, scores = _brute_search(left_vec, right_vec, k, metric)
        else:
            indices, scores = _usearch_search(left_vec, right_vec, k, metric, **backend_kwargs)

        return _assemble(
            self._df,
            other,
            indices,
            scores,
            flat=flat,
            suffix=suffix,
            rank_name=rank_name,
            score_name=score_name,
        )

`knn(other, *, on=None, left_on=None, right_on=None, k=5, metric='cosine', backend='auto', flat=True, suffix='_right', rank_name='rank', score_name='score', **backend_kwargs)` ¶

Top-K nearest-neighbour join against other.

Each row in self is matched against other using the chosen metric; the result holds the k closest neighbours per row.

Parameters:

Name	Type	Description	Default
`other`	`DataFrame`	The right-hand DataFrame to search.	required
`on`	`str \| None`	Vector column name(s). Use `on="vector"` when both DataFrames share the column name, otherwise pass `left_on` and `right_on`.	`None`
`left_on`	`str \| None`	Vector column name(s). Use `on="vector"` when both DataFrames share the column name, otherwise pass `left_on` and `right_on`.	`None`
`right_on`	`str \| None`	Vector column name(s). Use `on="vector"` when both DataFrames share the column name, otherwise pass `left_on` and `right_on`.	`None`
`k`	`int`	Number of neighbours to return. Clamped to `len(other)`.	`5`
`metric`	`Metric`	`"cosine"` (default), `"ip"`, or `"l2"`. Lower score = closer.	`'cosine'`
`backend`	`Backend`	`"auto"` (brute force up to a few x 10^4 right rows, otherwise usearch when installed), `"brute"`, or `"usearch"`.	`'auto'`
`flat`	`bool`	`True` (default) returns a flat join of `len(self) * k` rows with all columns from both sides plus `rank` / `score`. `False` returns `len(self)` rows with a `neighbors` `List[Struct]` column carrying the right-side rows.	`True`
`suffix`	`str`	Collision suffix for right-side columns (only used when `flat`).	`'_right'`
`rank_name`	`str`	Names of the rank/score columns added to the output.	`'rank'`
`score_name`	`str`	Names of the rank/score columns added to the output.	`'rank'`
`**backend_kwargs`	`Any`	Forwarded to `usearch.index.Index` (e.g. `connectivity`, `expansion_add`, `expansion_search`, `dtype`).	`{}`

Source code in polars_llm/_ann.py

def knn(
    self,
    other: pl.DataFrame,
    *,
    on: str | None = None,
    left_on: str | None = None,
    right_on: str | None = None,
    k: int = 5,
    metric: Metric = "cosine",
    backend: Backend = "auto",
    flat: bool = True,
    suffix: str = "_right",
    rank_name: str = "rank",
    score_name: str = "score",
    **backend_kwargs: Any,
) -> pl.DataFrame:
    """Top-K nearest-neighbour join against ``other``.

    Each row in ``self`` is matched against ``other`` using the chosen
    ``metric``; the result holds the ``k`` closest neighbours per row.

    Parameters
    ----------
    other:
        The right-hand DataFrame to search.
    on, left_on, right_on:
        Vector column name(s). Use ``on="vector"`` when both DataFrames
        share the column name, otherwise pass ``left_on`` and ``right_on``.
    k:
        Number of neighbours to return. Clamped to ``len(other)``.
    metric:
        ``"cosine"`` (default), ``"ip"``, or ``"l2"``. Lower score = closer.
    backend:
        ``"auto"`` (brute force up to a few x 10^4 right rows, otherwise
        usearch when installed), ``"brute"``, or ``"usearch"``.
    flat:
        ``True`` (default) returns a flat join of ``len(self) * k`` rows
        with all columns from both sides plus ``rank`` / ``score``.
        ``False`` returns ``len(self)`` rows with a ``neighbors``
        ``List[Struct]`` column carrying the right-side rows.
    suffix:
        Collision suffix for right-side columns (only used when ``flat``).
    rank_name, score_name:
        Names of the rank/score columns added to the output.
    **backend_kwargs:
        Forwarded to ``usearch.index.Index`` (e.g. ``connectivity``,
        ``expansion_add``, ``expansion_search``, ``dtype``).
    """
    import numpy as np  # noqa: F401  -- ensures numpy is installed

    left_col, right_col = _resolve_keys(on, left_on, right_on)
    left_vec = _to_matrix(self._df, left_col)
    right_vec = _to_matrix(other, right_col)
    if left_vec.shape[1] != right_vec.shape[1]:
        raise ValueError(
            f"polars-llm: vector dim mismatch: left {left_vec.shape[1]} != right {right_vec.shape[1]}.",
        )
    if other.height == 0:
        raise ValueError("polars-llm: `other` is empty; cannot run knn.")
    if k < 1:
        raise ValueError(f"polars-llm: `k` must be >= 1, got {k}.")

    chosen = _pick_backend(backend, other.height)
    if chosen == "brute":
        indices, scores = _brute_search(left_vec, right_vec, k, metric)
    else:
        indices, scores = _usearch_search(left_vec, right_vec, k, metric, **backend_kwargs)

    return _assemble(
        self._df,
        other,
        indices,
        scores,
        flat=flat,
        suffix=suffix,
        rank_name=rank_name,
        score_name=score_name,
    )