pandas_ext Basics¶

This notebook explains the core pandas_ext flow in order: input, outputs, and practical benefits.

These OpenAI API examples use gpt-6-luna with explicit reasoning={"effort": "none"}. Omitting reasoning uses the model's medium default. For Azure OpenAI, replace the model name with your deployment name and use settings supported by that deployment. See the GPT-6 migration guide. Saved outputs retained from earlier runs are illustrative and are not GPT-6 measurements.

1. Setup¶

Configure authentication and set a default responses model.

In [ ]:

import os

import pandas as pd
from pydantic import BaseModel, Field

import openaivec
from openaivec import pandas_ext

assert os.getenv("OPENAI_API_KEY") or os.getenv("AZURE_OPENAI_BASE_URL"), (
    "Set OPENAI_API_KEY or Azure OpenAI environment variables before running this notebook."
)

openaivec.set_responses_model("gpt-6-luna")

import os import pandas as pd from pydantic import BaseModel, Field import openaivec from openaivec import pandas_ext assert os.getenv("OPENAI_API_KEY") or os.getenv("AZURE_OPENAI_BASE_URL"), ( "Set OPENAI_API_KEY or Azure OpenAI environment variables before running this notebook." ) openaivec.set_responses_model("gpt-6-luna")

2. Input: pandas DataFrame¶

The main input is a normal DataFrame or Series.

In [2]:

fruits_df = pd.DataFrame({
    "name": ["apple", "banana", "cherry", "orange"],
    "price_usd": [1.2, 0.8, 2.5, 1.1],
})

fruits_df

fruits_df = pd.DataFrame({ "name": ["apple", "banana", "cherry", "orange"], "price_usd": [1.2, 0.8, 2.5, 1.1], }) fruits_df

Out[2]:

	name	price_usd
0	apple	1.2
1	banana	0.8
2	cherry	2.5
3	orange	1.1

3. Output A: plain-text responses¶

Use .ai.responses() when you want one text output per row.

In [ ]:

name_fr = fruits_df["name"].ai.responses(
    "Translate this fruit name to French.",
    reasoning={"effort": "none"},
    batch_size=16,
    show_progress=True,
)

fruits_df.assign(name_fr=name_fr)

name_fr = fruits_df["name"].ai.responses( "Translate this fruit name to French.", reasoning={"effort": "none"}, batch_size=16, show_progress=True, ) fruits_df.assign(name_fr=name_fr)

4. Output B: structured responses¶

Use response_format when you want typed, structured output.

In [ ]:

class FruitFacts(BaseModel):
    family: str = Field(description="Botanical family name")
    color: str = Field(description="Typical fruit color")
    short_note: str = Field(description="Short one-line note")


facts = fruits_df["name"].ai.responses(
    "Return botanical family, typical color, and a short note for this fruit.",
    reasoning={"effort": "none"},
    response_format=FruitFacts,
    batch_size=16,
    show_progress=True,
)

facts.head()

class FruitFacts(BaseModel): family: str = Field(description="Botanical family name") color: str = Field(description="Typical fruit color") short_note: str = Field(description="Short one-line note") facts = fruits_df["name"].ai.responses( "Return botanical family, typical color, and a short note for this fruit.", reasoning={"effort": "none"}, response_format=FruitFacts, batch_size=16, show_progress=True, ) facts.head()

5. Expand structured output into columns¶

In [5]:

facts_df = facts.rename("facts").ai.extract()
fruits_df.join(facts_df)

facts_df = facts.rename("facts").ai.extract() fruits_df.join(facts_df)

Out[5]:

	name	price_usd	facts_family	facts_color	facts_short_note
0	apple	1.2	Rosaceae	Red	A common pomaceous fruit with many cultivated ...
1	banana	0.8	Musaceae	Yellow	A tropical elongated fruit with soft, sweet fl...
2	cherry	2.5	Rosaceae	Red	A small stone fruit often sweet or tart depend...
3	orange	1.1	Rutaceae	Orange	A citrus fruit known for its juicy segments an...

6. Benefits¶

Main input

• A pandas Series or DataFrame
• One prompt, optionally with a response_format schema

Main outputs

• Plain-text outputs (.ai.responses)
• Structured typed outputs (response_format=...)
• Expandable columns via .ai.extract()

Why this is useful

• Keeps LLM processing inside familiar pandas workflows
• Supports structured validation with Pydantic models
• Provides batching controls (batch_size) for larger datasets