polars-llm 0.1.0__tar.gz

polars_llm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Garcia Lozano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polars_llm-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: polars-llm
+Version: 0.1.0
+Summary: Call LLMs and embedding models from a Polars DataFrame, one row at a time, using native Polars expressions. Powered by LangChain.
+Author-email: Diego Garcia Lozano <diegoglozano96@gmail.com>
+Project-URL: Homepage, https://diegoglozano.github.io/polars-ai/
+Project-URL: Repository, https://github.com/diegoglozano/polars-ai
+Project-URL: Documentation, https://diegoglozano.github.io/polars-ai/
+Keywords: polars,polars-llm,polars-ai,langchain,llm,openai,anthropic,gemini,embeddings,dataframe,etl,python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polars>=1.0.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: nest-asyncio>=1.6.0
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.2.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=0.2.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: langchain-google-genai>=2.0.0; extra == "gemini"
+Provides-Extra: all
+Requires-Dist: langchain-openai>=0.2.0; extra == "all"
+Requires-Dist: langchain-anthropic>=0.2.0; extra == "all"
+Requires-Dist: langchain-google-genai>=2.0.0; extra == "all"
+Dynamic: license-file
+
+# polars-llm
+
+[![PyPI version](https://img.shields.io/pypi/v/polars-llm.svg)](https://pypi.org/project/polars-llm/)
+[![Python versions](https://img.shields.io/pypi/pyversions/polars-llm.svg)](https://pypi.org/project/polars-llm/)
+[![Build status](https://img.shields.io/github/actions/workflow/status/diegoglozano/polars-ai/main.yml?branch=main)](https://github.com/diegoglozano/polars-ai/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/diegoglozano/polars-ai/branch/main/graph/badge.svg)](https://codecov.io/gh/diegoglozano/polars-ai)
+[![License](https://img.shields.io/github/license/diegoglozano/polars-ai)](https://github.com/diegoglozano/polars-ai/blob/main/LICENSE)
+
+**Call OpenAI, Anthropic, and Gemini models from a [Polars](https://pola.rs) DataFrame, one row at a time, using native Polars expressions.**
+
+`polars-llm` registers an `.llm` namespace on Polars expressions so you can call any [LangChain](https://python.langchain.com/)-supported chat model or embedding model on every row of a DataFrame — synchronously or asynchronously — and pipe the responses straight back into your data pipeline.
+
+```python
+import polars as pl
+import polars_llm  # noqa: F401  — registers the `.llm` namespace
+
+(
+    pl.DataFrame({"user_prompt": ["Summarise polars in one sentence."]})
+      .with_columns(
+          pl.col("user_prompt").llm.openai(model="gpt-4o-mini").alias("answer")
+      )
+)
+```
+
+- **Repository**: <https://github.com/diegoglozano/polars-ai>
+- **Documentation**: <https://diegoglozano.github.io/polars-ai/>
+- **PyPI**: <https://pypi.org/project/polars-llm/>
+
+---
+
+## Why polars-llm?
+
+- **Expression-native** — works inside `with_columns`, `select`, and any other Polars expression context. No Python `for` loops over rows, no notebook glue.
+- **Sync and async** — every provider verb has an `a`-prefixed async sibling that fans out concurrently with `asyncio.gather` and an optional `max_concurrency` cap.
+- **Per-row prompts and system messages** — both the prompt and the system message can be Polars expressions, so you can build them from other columns.
+- **Structured outputs** — pass a Pydantic model as `schema=` to get a struct column back, parsed via LangChain's `with_structured_output`.
+- **Embeddings, too** — `openai_embed` and `gemini_embed` return `List[Float64]` columns ready for vector search.
+- **Powered by [LangChain](https://python.langchain.com/)** — you get the same retries, batching, and observability primitives the rest of the LangChain ecosystem uses, plumbed straight into a DataFrame.
+
+Common use cases:
+
+- Summarise, classify, translate, or extract structured fields from a column of text.
+- Score rows against a custom rubric using an LLM-as-judge.
+- Build embeddings for a corpus directly from a DataFrame, ready to write to a vector database.
+- Mix LLM calls with the rest of your pipeline (joins, filters, group-bys) without leaving Polars.
+
+## Installation
+
+`polars-llm` keeps its base install light. Pick the providers you need as extras:
+
+```sh
+# Just one provider
+pip install "polars-llm[openai]"
+pip install "polars-llm[anthropic]"
+pip install "polars-llm[gemini]"
+
+# Or all of them
+pip install "polars-llm[all]"
+
+# uv
+uv add "polars-llm[all]"
+```
+
+Requires Python 3.9+ and Polars 1.0+.
+
+Authentication follows LangChain conventions — set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` in your environment before importing.
+
+## Quickstart
+
+### 1. Chat completion per row
+
+```python
+import polars as pl
+import polars_llm  # noqa: F401
+
+df = (
+    pl.DataFrame({"user_prompt": [
+        "What is the capital of Spain?",
+        "What is the capital of France?",
+    ]})
+    .with_columns(
+        pl.col("user_prompt").llm.openai(model="gpt-4o-mini").alias("answer")
+    )
+)
+```
+
+### 2. System prompt — literal or per-row
+
+```python
+# Same system prompt for every row
+pl.col("user_prompt").llm.anthropic(
+    model="claude-sonnet-4-6",
+    system="Answer in fewer than 10 words.",
+)
+
+# Per-row system prompt from another column
+pl.col("user_prompt").llm.gemini(
+    model="gemini-2.5-pro",
+    system=pl.col("system_prompt"),
+)
+```
+
+### 3. Async for throughput
+
+The `a`-prefixed verbs run concurrently across the batch, capped at `max_concurrency`:
+
+```python
+df.with_columns(
+    pl.col("user_prompt").llm.aopenai(
+        model="gpt-4o-mini",
+        max_concurrency=20,
+    ).alias("answer")
+)
+```
+
+### 4. Structured output with Pydantic
+
+```python
+from pydantic import BaseModel
+
+class Sentiment(BaseModel):
+    label: str  # "positive" | "neutral" | "negative"
+    confidence: float
+
+df.with_columns(
+    pl.col("review").llm.openai(
+        model="gpt-4o-mini",
+        schema=Sentiment,
+    ).alias("sentiment")
+).unnest("sentiment")
+```
+
+### 5. Embeddings
+
+```python
+df.with_columns(
+    pl.col("text").llm.openai_embed(
+        model="text-embedding-3-small",
+    ).alias("vector")
+)
+```
+
+### 6. Retries, caching, metadata
+
+```python
+pl.col("user_prompt").llm.aanthropic(
+    model="claude-sonnet-4-6",
+    retries=3,
+    backoff=0.5,
+    max_concurrency=10,
+    cache=True,            # dedupe identical prompts within a batch
+    with_metadata=True,    # struct {content, elapsed_ms, error}
+)
+```
+
+## API reference
+
+All methods live under the `.llm` namespace on any Polars expression that resolves to a string column.
+
+### Chat verbs
+
+| Method                     | Provider      | Mode         |
+| -------------------------- | ------------- | ------------ |
+| `openai` / `aopenai`       | OpenAI        | sync / async |
+| `anthropic` / `aanthropic` | Anthropic     | sync / async |
+| `gemini` / `agemini`       | Google Gemini | sync / async |
+
+### Embedding verbs
+
+| Method                           | Provider          | Mode         |
+| -------------------------------- | ----------------- | ------------ |
+| `openai_embed` / `aopenai_embed` | OpenAI Embeddings | sync / async |
+| `gemini_embed` / `agemini_embed` | Google Gemini     | sync / async |
+
+> Anthropic does not currently offer a first-party embeddings API.
+
+### Common arguments
+
+All verbs are keyword-only and accept:
+
+- **`model`** _(str)_ — model name forwarded to LangChain (e.g. `"gpt-4o-mini"`, `"claude-sonnet-4-6"`, `"gemini-2.5-pro"`).
+- **`system`** _(chat only)_ — literal string or `pl.Expr` for a per-row system prompt.
+- **`schema`** _(chat only)_ — a Pydantic model class. Returns a struct column with the schema fields, via `with_structured_output`.
+- **`client`** — a pre-configured LangChain chat or embeddings instance (skips the in-tree constructor and is handy for advanced configuration like custom base URLs).
+- **`retries`** _(int, default 0)_ — retry on any exception raised by the provider call.
+- **`backoff`** _(float, default 0.0)_ — exponential backoff base (seconds).
+- **`max_concurrency`** _(async only, int)_ — cap on in-flight requests via `asyncio.Semaphore`.
+- **`cache`** _(bool, default False)_ — memoise identical inputs within a batch.
+- **`with_metadata`** _(bool, default False)_ — return a struct column with timing and error metadata instead of just the content / vector.
+- **`on_error`** _("null" | "raise", default "null")_ — when `with_metadata=False`, what to do on errors. `"null"` replaces failures with `None` and emits a warning; `"raise"` re-raises immediately.
+- **`**model_kwargs`** — any additional keyword arguments forwarded to the underlying LangChain class (e.g. `temperature=`, `max_tokens=`, `timeout=`).
+
+### Return types
+
+| Mode                 | Default dtype                             | With `with_metadata=True`                                                     |
+| -------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
+| Chat (no `schema`)   | `Utf8`                                    | `Struct{content: Utf8, elapsed_ms: Float64, error: Utf8}`                     |
+| Chat (with `schema`) | `Struct{...}` matching the Pydantic model | Same struct; content JSON-serialised under `content`                          |
+| Embeddings           | `List[Float64]`                           | `Struct{vector: List[Float64], dim: Int64, elapsed_ms: Float64, error: Utf8}` |
+
+## Tips and patterns
+
+- **Build prompts from columns** with `pl.format("Translate to {}: {}", pl.col("language"), pl.col("text"))`.
+- **Bring your own client** to share a single `ChatOpenAI` (with custom `base_url`, `organization`, etc.) across many calls — pass it as `client=`.
+- **Watch the warning** — when a request fails and is silently nulled, polars-llm emits a `UserWarning` so you don't ship a column of nulls by accident. Pass `with_metadata=True` to inspect per-row errors instead.
+- **Combine with lazy frames** — every verb is an expression, so it composes inside `LazyFrame.with_columns(...)`.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Please open an issue before starting on larger changes.
+
+## License
+
+[MIT](./LICENSE) © Diego Garcia Lozano
+
+---
+
+Inspired by and patterned after [polars-api](https://github.com/diegoglozano/polars-api).

polars_llm-0.1.0/README.md

@@ -0,0 +1,218 @@
+# polars-llm
+
+[![PyPI version](https://img.shields.io/pypi/v/polars-llm.svg)](https://pypi.org/project/polars-llm/)
+[![Python versions](https://img.shields.io/pypi/pyversions/polars-llm.svg)](https://pypi.org/project/polars-llm/)
+[![Build status](https://img.shields.io/github/actions/workflow/status/diegoglozano/polars-ai/main.yml?branch=main)](https://github.com/diegoglozano/polars-ai/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/diegoglozano/polars-ai/branch/main/graph/badge.svg)](https://codecov.io/gh/diegoglozano/polars-ai)
+[![License](https://img.shields.io/github/license/diegoglozano/polars-ai)](https://github.com/diegoglozano/polars-ai/blob/main/LICENSE)
+
+**Call OpenAI, Anthropic, and Gemini models from a [Polars](https://pola.rs) DataFrame, one row at a time, using native Polars expressions.**
+
+`polars-llm` registers an `.llm` namespace on Polars expressions so you can call any [LangChain](https://python.langchain.com/)-supported chat model or embedding model on every row of a DataFrame — synchronously or asynchronously — and pipe the responses straight back into your data pipeline.
+
+```python
+import polars as pl
+import polars_llm  # noqa: F401  — registers the `.llm` namespace
+
+(
+    pl.DataFrame({"user_prompt": ["Summarise polars in one sentence."]})
+      .with_columns(
+          pl.col("user_prompt").llm.openai(model="gpt-4o-mini").alias("answer")
+      )
+)
+```
+
+- **Repository**: <https://github.com/diegoglozano/polars-ai>
+- **Documentation**: <https://diegoglozano.github.io/polars-ai/>
+- **PyPI**: <https://pypi.org/project/polars-llm/>
+
+---
+
+## Why polars-llm?
+
+- **Expression-native** — works inside `with_columns`, `select`, and any other Polars expression context. No Python `for` loops over rows, no notebook glue.
+- **Sync and async** — every provider verb has an `a`-prefixed async sibling that fans out concurrently with `asyncio.gather` and an optional `max_concurrency` cap.
+- **Per-row prompts and system messages** — both the prompt and the system message can be Polars expressions, so you can build them from other columns.
+- **Structured outputs** — pass a Pydantic model as `schema=` to get a struct column back, parsed via LangChain's `with_structured_output`.
+- **Embeddings, too** — `openai_embed` and `gemini_embed` return `List[Float64]` columns ready for vector search.
+- **Powered by [LangChain](https://python.langchain.com/)** — you get the same retries, batching, and observability primitives the rest of the LangChain ecosystem uses, plumbed straight into a DataFrame.
+
+Common use cases:
+
+- Summarise, classify, translate, or extract structured fields from a column of text.
+- Score rows against a custom rubric using an LLM-as-judge.
+- Build embeddings for a corpus directly from a DataFrame, ready to write to a vector database.
+- Mix LLM calls with the rest of your pipeline (joins, filters, group-bys) without leaving Polars.
+
+## Installation
+
+`polars-llm` keeps its base install light. Pick the providers you need as extras:
+
+```sh
+# Just one provider
+pip install "polars-llm[openai]"
+pip install "polars-llm[anthropic]"
+pip install "polars-llm[gemini]"
+
+# Or all of them
+pip install "polars-llm[all]"
+
+# uv
+uv add "polars-llm[all]"
+```
+
+Requires Python 3.9+ and Polars 1.0+.
+
+Authentication follows LangChain conventions — set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` in your environment before importing.
+
+## Quickstart
+
+### 1. Chat completion per row
+
+```python
+import polars as pl
+import polars_llm  # noqa: F401
+
+df = (
+    pl.DataFrame({"user_prompt": [
+        "What is the capital of Spain?",
+        "What is the capital of France?",
+    ]})
+    .with_columns(
+        pl.col("user_prompt").llm.openai(model="gpt-4o-mini").alias("answer")
+    )
+)
+```
+
+### 2. System prompt — literal or per-row
+
+```python
+# Same system prompt for every row
+pl.col("user_prompt").llm.anthropic(
+    model="claude-sonnet-4-6",
+    system="Answer in fewer than 10 words.",
+)
+
+# Per-row system prompt from another column
+pl.col("user_prompt").llm.gemini(
+    model="gemini-2.5-pro",
+    system=pl.col("system_prompt"),
+)
+```
+
+### 3. Async for throughput
+
+The `a`-prefixed verbs run concurrently across the batch, capped at `max_concurrency`:
+
+```python
+df.with_columns(
+    pl.col("user_prompt").llm.aopenai(
+        model="gpt-4o-mini",
+        max_concurrency=20,
+    ).alias("answer")
+)
+```
+
+### 4. Structured output with Pydantic
+
+```python
+from pydantic import BaseModel
+
+class Sentiment(BaseModel):
+    label: str  # "positive" | "neutral" | "negative"
+    confidence: float
+
+df.with_columns(
+    pl.col("review").llm.openai(
+        model="gpt-4o-mini",
+        schema=Sentiment,
+    ).alias("sentiment")
+).unnest("sentiment")
+```
+
+### 5. Embeddings
+
+```python
+df.with_columns(
+    pl.col("text").llm.openai_embed(
+        model="text-embedding-3-small",
+    ).alias("vector")
+)
+```
+
+### 6. Retries, caching, metadata
+
+```python
+pl.col("user_prompt").llm.aanthropic(
+    model="claude-sonnet-4-6",
+    retries=3,
+    backoff=0.5,
+    max_concurrency=10,
+    cache=True,            # dedupe identical prompts within a batch
+    with_metadata=True,    # struct {content, elapsed_ms, error}
+)
+```
+
+## API reference
+
+All methods live under the `.llm` namespace on any Polars expression that resolves to a string column.
+
+### Chat verbs
+
+| Method                     | Provider      | Mode         |
+| -------------------------- | ------------- | ------------ |
+| `openai` / `aopenai`       | OpenAI        | sync / async |
+| `anthropic` / `aanthropic` | Anthropic     | sync / async |
+| `gemini` / `agemini`       | Google Gemini | sync / async |
+
+### Embedding verbs
+
+| Method                           | Provider          | Mode         |
+| -------------------------------- | ----------------- | ------------ |
+| `openai_embed` / `aopenai_embed` | OpenAI Embeddings | sync / async |
+| `gemini_embed` / `agemini_embed` | Google Gemini     | sync / async |
+
+> Anthropic does not currently offer a first-party embeddings API.
+
+### Common arguments
+
+All verbs are keyword-only and accept:
+
+- **`model`** _(str)_ — model name forwarded to LangChain (e.g. `"gpt-4o-mini"`, `"claude-sonnet-4-6"`, `"gemini-2.5-pro"`).
+- **`system`** _(chat only)_ — literal string or `pl.Expr` for a per-row system prompt.
+- **`schema`** _(chat only)_ — a Pydantic model class. Returns a struct column with the schema fields, via `with_structured_output`.
+- **`client`** — a pre-configured LangChain chat or embeddings instance (skips the in-tree constructor and is handy for advanced configuration like custom base URLs).
+- **`retries`** _(int, default 0)_ — retry on any exception raised by the provider call.
+- **`backoff`** _(float, default 0.0)_ — exponential backoff base (seconds).
+- **`max_concurrency`** _(async only, int)_ — cap on in-flight requests via `asyncio.Semaphore`.
+- **`cache`** _(bool, default False)_ — memoise identical inputs within a batch.
+- **`with_metadata`** _(bool, default False)_ — return a struct column with timing and error metadata instead of just the content / vector.
+- **`on_error`** _("null" | "raise", default "null")_ — when `with_metadata=False`, what to do on errors. `"null"` replaces failures with `None` and emits a warning; `"raise"` re-raises immediately.
+- **`**model_kwargs`** — any additional keyword arguments forwarded to the underlying LangChain class (e.g. `temperature=`, `max_tokens=`, `timeout=`).
+
+### Return types
+
+| Mode                 | Default dtype                             | With `with_metadata=True`                                                     |
+| -------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
+| Chat (no `schema`)   | `Utf8`                                    | `Struct{content: Utf8, elapsed_ms: Float64, error: Utf8}`                     |
+| Chat (with `schema`) | `Struct{...}` matching the Pydantic model | Same struct; content JSON-serialised under `content`                          |
+| Embeddings           | `List[Float64]`                           | `Struct{vector: List[Float64], dim: Int64, elapsed_ms: Float64, error: Utf8}` |
+
+## Tips and patterns
+
+- **Build prompts from columns** with `pl.format("Translate to {}: {}", pl.col("language"), pl.col("text"))`.
+- **Bring your own client** to share a single `ChatOpenAI` (with custom `base_url`, `organization`, etc.) across many calls — pass it as `client=`.
+- **Watch the warning** — when a request fails and is silently nulled, polars-llm emits a `UserWarning` so you don't ship a column of nulls by accident. Pass `with_metadata=True` to inspect per-row errors instead.
+- **Combine with lazy frames** — every verb is an expression, so it composes inside `LazyFrame.with_columns(...)`.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Please open an issue before starting on larger changes.
+
+## License
+
+[MIT](./LICENSE) © Diego Garcia Lozano
+
+---
+
+Inspired by and patterned after [polars-api](https://github.com/diegoglozano/polars-api).

polars_llm-0.1.0/polars_llm/__init__.py

@@ -0,0 +1,3 @@
+from .llm import Llm
+
+__all__ = ["Llm"]