Working with PreparedTask¶

This notebook shows how to define your own PreparedTask, run it with BatchResponses, and apply it to pandas data with .ai.task.

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¶

Make sure OPENAI_API_KEY (or Azure equivalents) is configured before running API calls.

In [ ]:

import os

from openai import OpenAI
from pydantic import BaseModel, Field

import openaivec
from openaivec import BatchResponses, PreparedTask, 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 from openai import OpenAI from pydantic import BaseModel, Field import openaivec from openaivec import BatchResponses, PreparedTask, 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. Define a custom PreparedTask¶

A PreparedTask[T] combines instructions and structured response schema (T).

In [2]:

class FruitProfile(BaseModel):
    fruit: str = Field(description="Fruit name from input")
    color: str = Field(description="Typical fruit color")
    taste: str = Field(description="Short taste description")

fruit_profile_task = PreparedTask[FruitProfile](
    instructions=(
        "Return a compact fruit profile with name, typical color, and taste. "
        "Keep answers short and factual."
    ),
    response_format=FruitProfile,
)

fruit_profile_task

class FruitProfile(BaseModel): fruit: str = Field(description="Fruit name from input") color: str = Field(description="Typical fruit color") taste: str = Field(description="Short taste description") fruit_profile_task = PreparedTask[FruitProfile]( instructions=( "Return a compact fruit profile with name, typical color, and taste. " "Keep answers short and factual." ), response_format=FruitProfile, ) fruit_profile_task

Out[2]:

PreparedTask(instructions='Return a compact fruit profile with name, typical color, and taste. Keep answers short and factual.', response_format=<class '__main__.FruitProfile'>)

3. Run with BatchResponses.of_task¶

API options (for example temperature) are passed at call site.

In [ ]:

client = OpenAI()

batch = BatchResponses.of_task(
    reasoning={"effort": "none"},
    client=client,
    model_name="gpt-6-luna",
    task=fruit_profile_task,
    temperature=0.0,
)

batch.parse(["apple", "banana", "grape"])

client = OpenAI() batch = BatchResponses.of_task( reasoning={"effort": "none"}, client=client, model_name="gpt-6-luna", task=fruit_profile_task, temperature=0.0, ) batch.parse(["apple", "banana", "grape"])

4. Apply the same task to pandas¶

In [ ]:

import openaivec
import pandas as pd

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

fruits = pd.Series(["apple", "orange", "strawberry"], name="fruit")
profiles = fruits.ai.task(fruit_profile_task, reasoning={"effort": "none"}, temperature=0.0)
profiles

import openaivec import pandas as pd openaivec.set_client(client) openaivec.set_responses_model("gpt-6-luna") fruits = pd.Series(["apple", "orange", "strawberry"], name="fruit") profiles = fruits.ai.task(fruit_profile_task, reasoning={"effort": "none"}, temperature=0.0) profiles

5. Discover prebuilt tasks from the registry¶

In [5]:

from openaivec.task import get_task, list_tasks

list_tasks("nlp")[:6]

sentiment_task = get_task("nlp.sentiment_analysis")
sentiment_task

from openaivec.task import get_task, list_tasks list_tasks("nlp")[:6] sentiment_task = get_task("nlp.sentiment_analysis") sentiment_task

Out[5]:

PreparedTask(instructions='Analyze sentiment and emotions in the input text.\n\nReturn sentiment class, sentiment confidence, emotions, emotion scores, polarity, and subjectivity.\n\nProvide natural-language fields in the same language as the input text. Do not switch explanation language unless the task explicitly requires translation.\n\nIMPORTANT: Keep predefined categorical values in exact English tokens. The following fields must use English values only: sentiment, emotions.', response_format=<class 'openaivec.task.nlp.sentiment_analysis.SentimentAnalysis'>)