Edit

Share via

Use ai.generate_response with pandas

The ai.generate_response function uses generative AI to generate custom text responses that are based on your own instructions, with a single line of code.

Note

Overview

The ai.generate_response function can extend the pandas DataFrame class and the pandas Series class.

You may either call this function on a pandas series or an entire pandas DataFrame.

If calling the function on an entire pandas DataFrame, your prompt can be a literal string, and the function considers all columns of the DataFrame while generating responses. Your prompt can also be a format string, where the function considers only those column values that appear between curly braces in the prompt.

The function returns a pandas Series that contains custom text responses for each row of input. The text responses can be stored in a new DataFrame column.

Tip

Learn how to craft more effective prompts to get higher-quality responses by following OpenAI's prompting tips for gpt-4.1.

Syntax

df["response"] = df.ai.generate_response(
    prompt="Instructions for a custom response based on all column values",
)

Parameters

Name Description
prompt
Required		 A string that contains prompt instructions to apply to input text values for custom responses.
is_prompt_template
Optional		 A Boolean that indicates whether the prompt is a format string or a literal string. If this parameter is set to True, then the function considers only the specific row values from each column name that appears in the format string. In this case, those column names must appear between curly braces, and other columns are ignored. If this parameter is set to its default value of False, then the function considers all column values as context for each input row.
response_format
Optional		 None, a dictionary, a string, or a class based on Pydantic's BaseModel that specifies the expected structure of the model's response. See Response Format Options for details on all available formats.

Returns

The function returns a pandas DataFrame that contains custom text responses to the prompt for each input text row.

Response format options

The response_format parameter accepts different formats to control how the LLM structures its responses. This parameter corresponds to OpenAI's Structured Outputs feature. The following options are available:

Format Description
None (default) Let the LLM decide response format based on the instructions and input data, which can vary per row. Responses can be plain text or JSON dict with varying fields.
"text" or {"type": "text"} Forces plain text responses for all rows.
"json_object" or {"type": "json_object"} Returns a JSON dictionary in text form where the LLM decides the fields. Requires the word "json" in your prompt.
{"type": "json_schema", ...} Returns a JSON dictionary that conforms to your custom JSON Schema. Provides precise control over response structure.
Class based on Pydantic's BaseModel Returns a JSON string that conforms to your Pydantic model definition. Pydantic is a dependency of the openai package. Under the hood, the Pydantic BaseModel is automatically converted to a JSON schema and functions equivalently to the json_schema option.

Note

The json_schema and Pydantic BaseModel options are functionally equivalent. The Pydantic BaseModel approach provides better developer experience with Python's type system and validation, while being automatically converted to the verbose JSON schema under the hood.

Examples

# This code uses AI. Always review output for mistakes.

df = pd.DataFrame([
        ("Scarves"),
        ("Snow pants"),
        ("Ski goggles")
    ], columns=["product"])

df["response"] = df.ai.generate_response("Write a short, punchy email subject line for a winter sale.")
display(df)

This example code cell provides the following output:

Screenshot showing a data frame with columns 'product' and 'response'. The 'response' column contains a punchy subject line for the product.

Response Format example

The following example shows how to use the response_format parameter to specify different response formats, including plain text, a JSON object, and a custom JSON schema.

# This code uses AI. Always review output for mistakes.

df = pd.DataFrame([
        ("Alex Rivera is a 24-year-old soccer midfielder from Barcelona who scored 12 goals last season."),
        ("Jordan Smith, a 29-year-old basketball guard from Chicago, averaged 22 points per game."),
        ("William O'Connor is a 22-year-old tennis player from Dublin who won 3 ATP titles this year.")
    ], columns=["bio"])

# response_format : text
df["card_text"] = df.ai.generate_response(
    "Create a player card with the player's details and a motivational quote", 
    response_format={"type": "text"},
)

# response_format : json object
df["card_json_object"] = df.ai.generate_response(
    "Create a player card with the player's details and a motivational quote in JSON", 
    response_format={"type": "json_object"},  # Requires word "json" in the prompt
)

# response_format : specified json schema
df["card_json_schema"] = df.ai.generate_response(
    "Create a player card with the player's details and a motivational quote", 
    response_format={
        "type": "json_schema",
            "json_schema": {
            "name": "player_card_schema",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "sport": {"type": "string"},
                    "position": {"type": "string"},
                    "hometown": {"type": "string"},
                    "stats": {"type": "string", "description": "Key performance metrics or achievements"},
                    "motivational_quote": {"type": "string"}
                },
                "required": ["name", "age", "sport", "position", "hometown", "stats", "motivational_quote"],
                "additionalProperties": False,
            },
        },
    },
)

# Pydantic is a dependency of the openai package, so it's available when openai is installed.
# Pydantic may also be installed via `%pip install pydantic` if not already present.
from pydantic import BaseModel, Field

class PlayerCardSchema(BaseModel):
    name: str
    age: int
    sport: str
    position: str
    hometown: str
    stats: str = Field(description="Key performance metrics or achievements")
    motivational_quote: str

# response_format : pydantic BaseModel
df["card_pydantic"] = df.ai.generate_response(
    "Create a player card with the player's details and a motivational quote",
    response_format=PlayerCardSchema,
)

display(df)

This example code cell provides the following output:

Screenshot showing a data frame with a 'bio' column, and a new column for each specified format, with its corresponding formatted output.

Related content

  • Last updated on