Prompt Builder Basics¶

This notebook explains FewShotPromptBuilder in order: main input, generated output, 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. Input: purpose, cautions, and examples¶

Define what you want, constraints, and a few representative examples.

In [ ]:

import os

import openaivec
from openaivec import FewShotPromptBuilder


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")

base_prompt = (
    FewShotPromptBuilder()
    .purpose("Classify fruit names into color and taste notes.")
    .caution("Return concise English.")
    .caution("Use one sentence.")
    .example(
        input_value="apple",
        output_value="Red or green fruit with a sweet-tart taste.",
    )
    .example(
        input_value="lemon",
        output_value="Yellow citrus fruit with a sour taste.",
    )
    .build()
)

import os import openaivec from openaivec import FewShotPromptBuilder 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") base_prompt = ( FewShotPromptBuilder() .purpose("Classify fruit names into color and taste notes.") .caution("Return concise English.") .caution("Use one sentence.") .example( input_value="apple", output_value="Red or green fruit with a sweet-tart taste.", ) .example( input_value="lemon", output_value="Yellow citrus fruit with a sour taste.", ) .build() )

2. Output: reusable prompt string¶

build() returns a prompt string you can pass to response APIs.

In [2]:

print(base_prompt)

print(base_prompt)

<Prompt>
  <Purpose>Classify fruit names into color and taste notes.</Purpose>
  <Cautions>
    <Caution>Return concise English.</Caution>
    <Caution>Use one sentence.</Caution>
  </Cautions>
  <Examples>
    <Example>
      <Input>apple</Input>
      <Output>Red or green fruit with a sweet-tart taste.</Output>
    </Example>
    <Example>
      <Input>lemon</Input>
      <Output>Yellow citrus fruit with a sour taste.</Output>
    </Example>
  </Examples>
</Prompt>

3. Structured examples (optional)¶

When output shape matters, provide Pydantic models as examples.

In [3]:

from pydantic import BaseModel, Field


class FruitProfile(BaseModel):
    color: str = Field(description="Main color")
    taste: str = Field(description="Primary taste")


structured_prompt = (
    FewShotPromptBuilder()
    .purpose("Extract fruit profile with fixed fields.")
    .caution("taste must be one of: sweet, sour, bitter, umami.")
    .example(
        input_value="banana",
        output_value=FruitProfile(color="yellow", taste="sweet"),
    )
    .example(
        input_value="grapefruit",
        output_value=FruitProfile(color="orange", taste="bitter"),
    )
    .build()
)

print(structured_prompt)

from pydantic import BaseModel, Field class FruitProfile(BaseModel): color: str = Field(description="Main color") taste: str = Field(description="Primary taste") structured_prompt = ( FewShotPromptBuilder() .purpose("Extract fruit profile with fixed fields.") .caution("taste must be one of: sweet, sour, bitter, umami.") .example( input_value="banana", output_value=FruitProfile(color="yellow", taste="sweet"), ) .example( input_value="grapefruit", output_value=FruitProfile(color="orange", taste="bitter"), ) .build() ) print(structured_prompt)

<Prompt>
  <Purpose>Extract fruit profile with fixed fields.</Purpose>
  <Cautions>
    <Caution>taste must be one of: sweet, sour, bitter, umami.</Caution>
  </Cautions>
  <Examples>
    <Example>
      <Input>banana</Input>
      <Output>{"color":"yellow","taste":"sweet"}</Output>
    </Example>
    <Example>
      <Input>grapefruit</Input>
      <Output>{"color":"orange","taste":"bitter"}</Output>
    </Example>
  </Examples>
</Prompt>

4. Improve and explain (optional)¶

improve() refines your prompt with an LLM, and explain() shows each improvement step as a diff. This example uses gpt-6-luna with reasoning disabled.

In [ ]:

improved_builder = (
    FewShotPromptBuilder()
    .purpose("Classify fruit names into color and taste notes.")
    .caution("Return concise English.")
    .caution("Use one sentence.")
    .example(
        input_value="apple",
        output_value="Red or green fruit with a sweet-tart taste.",
    )
    .example(
        input_value="lemon",
        output_value="Yellow citrus fruit with a sour taste.",
    )
    .improve(reasoning={"effort": "none"})
)
improved_builder.explain()
improved_prompt = improved_builder.build()

improved_builder = ( FewShotPromptBuilder() .purpose("Classify fruit names into color and taste notes.") .caution("Return concise English.") .caution("Use one sentence.") .example( input_value="apple", output_value="Red or green fruit with a sweet-tart taste.", ) .example( input_value="lemon", output_value="Yellow citrus fruit with a sour taste.", ) .improve(reasoning={"effort": "none"}) ) improved_builder.explain() improved_prompt = improved_builder.build()

In [5]:

print(improved_prompt)

print(improved_prompt)

<Prompt>
  <Purpose>Classify fruit names by providing their typical color and taste notes in one concise English sentence.</Purpose>
  <Cautions>
    <Caution>Return concise English.</Caution>
    <Caution>Use one sentence.</Caution>
    <Caution>Use typical color and taste notes rather than rare varieties.</Caution>
    <Caution>If a fruit commonly has multiple colors, include the main ones concisely.</Caution>
  </Cautions>
  <Examples>
    <Example>
      <Input>apple</Input>
      <Output>Red or green fruit with a sweet-tart taste.</Output>
    </Example>
    <Example>
      <Input>lemon</Input>
      <Output>Yellow citrus fruit with a sour taste.</Output>
    </Example>
    <Example>
      <Input>banana</Input>
      <Output>Yellow fruit with a sweet taste.</Output>
    </Example>
    <Example>
      <Input>lime</Input>
      <Output>Green citrus fruit with a sour taste.</Output>
    </Example>
    <Example>
      <Input>grape</Input>
      <Output>Green or purple fruit with a sweet taste.</Output>
    </Example>
    <Example>
      <Input>orange</Input>
      <Output>Orange citrus fruit with a sweet-tart taste.</Output>
    </Example>
  </Examples>
</Prompt>

5. Benefits¶

Main input

• Prompt purpose (purpose)
• Constraints (caution)
• Example pairs (example)

Main output

• Reusable prompt string (build)
• Optionally refined prompt and diff history (improve + explain)

Why this helps

• Makes prompt design explicit and reviewable
• Reduces ambiguity by encoding examples in code
• Reuses the same prompt across notebooks and production paths