### Install Dependencies and Run Example

Source: https://github.com/openai/openai-cookbook/blob/main/examples/building_w_rt_mini/building_w_rt_mini.ipynb

Install necessary npm dependencies and run the realtime-next example to set up the development environment. This step verifies the initial setup.

```bash
npm install @openai/agents zod@3
pnpm examples:realtime-next
```

--------------------------------

### Install Dependencies and Setup Environment

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/realtime_translation_guide/twilio-translation-demo/README.md

Navigate to the demo directory, install Node.js dependencies, and copy the example environment file. Set your API keys and configuration variables in the `.env` file.

```bash
cd examples/voice_solutions/realtime_translation_guide/twilio-translation-demo
npm install
cp .env.example .env
```

--------------------------------

### Install Dependencies and Run Demo

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/realtime_translation_guide/browser-translation-demo/README.md

Install project dependencies and start the development server for the browser translation demo.

```bash
cd examples/voice_solutions/realtime_translation_guide/browser-translation-demo
npm install
npm run dev
```

--------------------------------

### Install Frontend Dependencies and Run Dev Server

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/running_realtime_api_speech_on_esp32_arduino_edge_runtime_elatoai.md

Navigate to the frontend-nextjs directory, install npm dependencies, and start the development server.

```bash
cd frontend-nextjs
npm install

# Run the development server
npm run dev
```

--------------------------------

### Start Local Supabase Server

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/running_realtime_api_speech_on_esp32_arduino_edge_runtime_elatoai.md

Install the Supabase CLI and start your local Supabase server using this command.

```bash
brew install supabase/tap/supabase
supabase start
```

--------------------------------

### Install Dependencies and Run Demo

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/realtime_translation_guide/livekit-translation-demo/README.md

Install project dependencies using pnpm and start the Next.js development server. Open the provided local URL in two browser windows to join the same LiveKit room.

```bash
cd examples/voice_solutions/realtime_translation_guide/livekit-translation-demo
pnpm install
pnpm dev
```

--------------------------------

### Start React Frontend

Source: https://github.com/openai/openai-cookbook/blob/main/examples/mcp/building-a-supply-chain-copilot-with-agent-sdk-and-databricks-mcp/README.md

Starts the React development server for the chat UI. Navigate to the `ui` directory and run `npm install` before starting the development server. The application will be available at http://localhost:5173.

```bash
cd ui
npm install
npm run dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/openai/openai-cookbook/blob/main/AGENTS.md

Install the necessary Python packages for a specific example or topic within the cookbook. Ensure you are in the correct directory.

```bash
pip install -r examples/<topic>/requirements.txt
```

--------------------------------

### Setup OpenAI Client and Image Utilities

Source: https://github.com/openai/openai-cookbook/blob/main/examples/multimodal/image-gen-models-prompting-guide.ipynb

Initializes the OpenAI client, creates necessary output directories, and defines a helper function to save base64 encoded images. This setup is required before running image generation or editing examples.

```python
import os
import base64
from openai import OpenAI

client = OpenAI()

os.makedirs("../../images/input_images", exist_ok=True)
os.makedirs("../../images/output_images", exist_ok=True)

def save_image(result, filename: str) -> None:
    """
    Saves the first returned image to the given filename inside the output_images folder.
    """
    image_base64 = result.data[0].b64_json
    out_path = os.path.join("../../images/output_images", filename)
    with open(out_path, "wb") as f:
        f.write(base64.b64decode(image_base64))

from IPython.display import HTML, Image, display

def display_image_grid(items, width=240):
    cards = []
    for item in items:
        title = item.get("title", "")
        label = f'<div style="font-weight:600;margin-bottom:8px">{title}</div>' if title else ""
        cards.append(
            '<div style="text-align:center">'
            + label
            + f'<img src="{item["path"]}" width="{width}" style="max-width:100%;height:auto;" />'
            + '</div>'
        )
    display(HTML('<div style="display:flex;flex-wrap:wrap;gap:16px;align-items:flex-start">' + ''.join(cards) + '</div>'))
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/openai/openai-cookbook/blob/main/examples/agents_sdk/agent_improvement_loop.ipynb

Installs the necessary Python packages for the example, including openai and openai-agents. Ensure Node.js and npx are available for Promptfoo.

```bash
python -m venv .venv
source .venv/bin/activate
pip install openai openai-agents halo-engine
```

--------------------------------

### Setup paths and directories

Source: https://github.com/openai/openai-cookbook/blob/main/examples/codex/Build_iterative_repair_loops_with_Codex.ipynb

Configures necessary paths for example directories and a directory for storing repair loop outputs. It raises an error if the required data directory is not found.

```python
import concurrent.futures
import json
import os
import shlex
import shutil
import subprocess
import tempfile
from pathlib import Path
from typing import Any

CANDIDATE_EXAMPLE_DIRS = [Path("."), Path("examples/codex")]
EXAMPLE_DIR = next((base for base in CANDIDATE_EXAMPLE_DIRS if (base / "data" / "docs").exists()), None)

if EXAMPLE_DIR is None:
    raise RuntimeError(
        "This notebook needs its companion sample notebooks. "
        "Download the data folder that ships with this example and place it next to "
        "this notebook as ./data/docs, or run from a checkout where examples/codex/data/docs exists."
    )

DATA_DIR = EXAMPLE_DIR / "data" / "docs"
DEFAULT_RUNS_DIR = Path(tempfile.gettempdir()) / "codex_iterative_repair_loop_outputs"
RUNS_DIR = Path(os.getenv("CODEX_REPAIR_RUNS_DIR", str(DEFAULT_RUNS_DIR))).expanduser()
RUNS_DIR.mkdir(parents=True, exist_ok=True)

```

--------------------------------

### Environment Setup and Dependency Installation

Source: https://github.com/openai/openai-cookbook/blob/main/examples/partners/schemaflow_design_guide/schemaflow_cookbook.ipynb

Ensures necessary packages like neo4j, fastapi, and uvicorn are installed. It loads Neo4j connection details from environment variables or prompts the user if they are missing. If any required package fails to install or credentials are not provided, the section is disabled.

```python
import os
import subprocess
import sys
from getpass import getpass
from urllib.parse import urlparse

NEO4J_SECTION_ENABLED = True


def _ensure_pkg(pkg, import_name=None):
    name = import_name or pkg
    try:
        __import__(name)
        return True
    except Exception:
        print(f"Installing {pkg} (only needed for Section 11)...", flush=True)
        rc = subprocess.call([sys.executable, "-m", "pip", "install", "-q", pkg])
        if rc != 0:
            print(f"  pip install {pkg} failed (rc={rc}); Section 11 will be skipped.")
            return False
        try:
            __import__(name)
            return True
        except Exception as e:
            print(f"  Import still failing after install of {pkg}: {e}")
            return False


for _pkg, _imp in [("neo4j", "neo4j"), ("fastapi", "fastapi"), ("uvicorn", "uvicorn")]:
    if not _ensure_pkg(_pkg, _imp):
        NEO4J_SECTION_ENABLED = False

if not os.getenv("NEO4J_URI"):
    os.environ["NEO4J_URI"] = getpass("Enter NEO4J_URI (e.g. neo4j://127.0.0.1:7687) or press Enter to skip: ")
if not os.getenv("NEO4J_USER"):
    os.environ["NEO4J_USER"] = getpass("Enter NEO4J_USER (default 'neo4j') or press Enter to skip: ") or "neo4j"
if not os.getenv("NEO4J_PASSWORD"):
    os.environ["NEO4J_PASSWORD"] = getpass("Enter NEO4J_PASSWORD or press Enter to skip: ")

NEO4J_URI = (os.getenv("NEO4J_URI") or "").strip()
NEO4J_USER = (os.getenv("NEO4J_USER") or "").strip()
NEO4J_PASSWORD = os.getenv("NEO4J_PASSWORD") or ""

def _normalize_neo4j_uri(uri):
    parsed = urlparse(uri)
    if parsed.scheme in {"bolt", "bolt+ssc", "bolt+s", "neo4j", "neo4j+ssc", "neo4j+s"}:
        return uri
    if parsed.scheme in {"http", "https"} and parsed.hostname in {"127.0.0.1", "localhost", "::1"}:
        return f"neo4j://{parsed.hostname}:7687"
    return uri

_normalized_neo4j_uri = _normalize_neo4j_uri(NEO4J_URI)
if _normalized_neo4j_uri != NEO4J_URI:
    print(f"Converted Neo4j browser URL {NEO4J_URI!r} to driver URI {_normalized_neo4j_uri!r}.")
    NEO4J_URI = _normalized_neo4j_uri
    os.environ["NEO4J_URI"] = NEO4J_URI

if not (NEO4J_URI and NEO4J_USER and NEO4J_PASSWORD):
    print("Neo4j credentials not fully provided. Section 11 will be skipped (other cells will short-circuit safely).")
    NEO4J_SECTION_ENABLED = False
else:
    print(f"Neo4j configured: {NEO4J_USER}@{NEO4J_URI}")

print(f"NEO4J_SECTION_ENABLED = {NEO4J_SECTION_ENABLED}")
```

--------------------------------

### Chat Completions API Example

Source: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_build_an_agent_with_the_node_sdk.mdx

Demonstrates a basic call to the Chat Completions API to get a response based on a user's prompt. Ensure you have the 'openai' library installed and your API key configured.

```javascript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function main() {
  const completion = await openai.chat.completions.create({
    messages: [
      {
        "role": "system",
        "content": "You are a helpful assistant.",
      },
      {
        "role": "user",
        "content": "Please suggest some activities based on my location and the weather."
      }
    ],
    model: "gpt-3.5-turbo",
  });

  console.log(completion.choices[0].message);
}

main();
```

--------------------------------

### Initialize Project Setup and Configuration

Source: https://github.com/openai/openai-cookbook/blob/main/examples/agents_sdk/agent_improvement_loop.ipynb

Sets up the project environment by finding the project root, validating the API key, checking for necessary tools like npx, and configuring model names and artifact directories. It also creates necessary directories and cleans up previous runs.

```python
from __future__ import annotations

import asyncio
import hashlib
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
import time
import textwrap
import threading
from contextlib import contextmanager
from dataclasses import asdict, dataclass, field
from datetime import datetime, timezone
from importlib.metadata import version
from pathlib import Path
from typing import Any, Iterable, Iterator, Mapping

from IPython.display import Markdown, display
from openai import OpenAI

def find_project_root(start: Path | None = None) -> Path:
    current = (start or Path.cwd()).resolve()
    for candidate in [current, *current.parents]:
        if (candidate / "registry.yaml").exists():
            return candidate
    return current


PROJECT_ROOT = find_project_root()

if not os.getenv("OPENAI_API_KEY"):
    raise RuntimeError("Set OPENAI_API_KEY before running this live notebook.")
if shutil.which("npx") is None:
    raise RuntimeError("Install Node.js with npx before running the Promptfoo eval gate.")

# Edit these in one place if you want to use lower-cost models for part of the loop.
AGENT_MODEL = os.getenv("OPENAI_AGENT_MODEL", "gpt-5.5")
ANALYSIS_MODEL = os.getenv("OPENAI_ANALYSIS_MODEL", "gpt-5.5")
EVAL_GENERATION_MODEL = os.getenv("OPENAI_EVAL_GENERATION_MODEL", ANALYSIS_MODEL)
JUDGE_MODEL = os.getenv("OPENAI_JUDGE_MODEL", ANALYSIS_MODEL)
HALO_MODEL = os.getenv("OPENAI_HALO_MODEL", ANALYSIS_MODEL)
PROMPTFOO_VERSION = os.getenv("PROMPTFOO_VERSION", "0.121.9")

client = OpenAI()


def format_duration(seconds: float) -> str:
    minutes, remainder = divmod(int(round(seconds)), 60)
    return f"{minutes}m {remainder:02d}s" if minutes else f"{remainder}s"


ARTIFACT_DIR = PROJECT_ROOT / "examples" / "agents_sdk" / "agent_improvement_loop_artifacts"
TRACE_DIR = ARTIFACT_DIR / "traces"
HALO_TRACE_PATH = ARTIFACT_DIR / "halo_traces" / "traces.jsonl"
if ARTIFACT_DIR.exists():
    shutil.rmtree(ARTIFACT_DIR)
ARTIFACT_DIR.mkdir(exist_ok=True)
TRACE_DIR.mkdir(exist_ok=True)
HALO_TRACE_PATH.parent.mkdir(exist_ok=True)

print("Project root detected.")
print("Models:", {
    "agent": AGENT_MODEL,
    "analysis": ANALYSIS_MODEL,
    "eval_generation": EVAL_GENERATION_MODEL,
    "judge": JUDGE_MODEL,
    "halo": HALO_MODEL,
    "promptfoo": PROMPTFOO_VERSION,
})

```

```text
Output:
Project root detected.
Models: {'agent': 'gpt-5.5', 'analysis': 'gpt-5.5', 'eval_generation': 'gpt-5.5', 'judge': 'gpt-5.5', 'halo': 'gpt-5.5', 'promptfoo': '0.121.9'}


```

--------------------------------

### Run the Demo Server

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/realtime_translation_guide/twilio-translation-demo/README.md

Start the real-time translation demo server using npm. Ensure your public URL and port are correctly configured.

```bash
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/openai/openai-cookbook/blob/main/examples/codex/codex_mcp_agents_sdk/building_consistent_workflows_codex_cli_agents_sdk.ipynb

Installs the necessary openai-agents and openai libraries using pip. This is a prerequisite for running the agent examples.

```python
%pip install openai-agents openai ## install dependencies
```

--------------------------------

### Install and Check Codex Version

Source: https://github.com/openai/openai-cookbook/blob/main/examples/codex/using_goals_in_codex.ipynb

Install or update Codex to the latest version using npm and verify the installation by checking the version. Goals are available starting in Codex 0.128.0.

```bash
npm install -g @openai/codex@latest
codex --version
```

```bash
brew update
brew upgrade --cask codex
codex --version
```

--------------------------------

### Install vLLM and Serve Model

Source: https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss-safeguard-guide.md

Install vLLM using uv for dependency management and then start serving the gpt-oss-safeguard 120B model. This command installs vLLM and automatically downloads the model.

```shell
uv pip install vllm==0.10.2 --torch-backend=auto

vllm serve openai/gpt-oss-safeguard-120b
```

--------------------------------

### Initialize OpenAI Client and Create Images Directory

Source: https://github.com/openai/openai-cookbook/blob/main/examples/multimodal/image_evals.ipynb

Run this once to set up the API client and create the necessary directory for storing images. Ensure the `openai` library is installed.

```python
import os
from openai import OpenAI

client = OpenAI()

os.makedirs("../../images", exist_ok=True)
```

--------------------------------

### Start Deno Server

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/running_realtime_api_speech_on_esp32_arduino_edge_runtime_elatoai.md

Navigate to the server-deno directory and run the Deno server using the provided command, ensuring the .env file is present.

```bash
# Navigate to the server directory
cd server-deno

# Run the server at port 8000
den run -A --env-file=.env main.ts
```

--------------------------------

### TypeScript: Install LM Studio SDK

Source: https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss/run-locally-lmstudio.md

Installs the LM Studio SDK using npm. This is a prerequisite for using the TypeScript examples.

```shell
npm install @lmstudio/sdk
```

--------------------------------

### Install Qdrant Client

Source: https://github.com/openai/openai-cookbook/blob/main/examples/vector_databases/qdrant/Using_Qdrant_for_embeddings_search.ipynb

Install the Qdrant client library for Python. This is a necessary first step before interacting with the Qdrant database.

```python
# We'll need to install Qdrant client
!pip install qdrant-client
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/openai/openai-cookbook/blob/main/examples/data/oai_docs/crawl-website-embeddings.txt

Set up a virtual environment and install required packages for the project.

```bash
python -m venv env

source env/bin/activate

pip install -r requirements.txt
```

--------------------------------

### Clone simple-evals and Install Dependencies

Source: https://github.com/openai/openai-cookbook/blob/main/examples/fine-tuned_qa/reinforcement_finetuning_healthbench.ipynb

Clone the simple-evals repository and install necessary Python packages. This setup is required before running evaluations.

```bash
git clone https://github.com/openai/simple-evals.git
pip install openai human-eval
```

--------------------------------

### Start Mirror Server

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/one_way_translation_using_realtime_api/README.md

In a separate terminal, navigate to the project directory and run this command to start the mirror server.

```bash
node mirror-server/mirror-server.mjs
```

--------------------------------

### Python Example: Using Responses API with Reasoning Items

Source: https://github.com/openai/openai-cookbook/blob/main/examples/o-series/o3o4-mini_prompting_guide.ipynb

This Python script demonstrates how to leverage the Responses API to maintain a chain of thought between tool calls. It includes a function to get weather information and uses `encrypted_content` to pass reasoning back to the model for improved performance. Ensure you have the `openai` and `requests` libraries installed.

```python
from openai import OpenAI
import requests
import json
client = OpenAI()


def get_weather(latitude, longitude):
    response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m")
    data = response.json()
    return data['current']['temperature_2m']


tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get current temperature for provided coordinates in celsius.",
    "parameters": {
        "type": "object",
        "properties": {
            "latitude": {"type": "number"},
            "longitude": {"type": "number"}
        },
        "required": ["latitude", "longitude"],
        "additionalProperties": False
    },
    "strict": True
}]

context = [{"role": "user", "content": "What's the weather like in Paris today?"}]

response = client.responses.create(
    model="o3",
    input=context,
    tools=tools,
    store=False,
    include=["reasoning.encrypted_content"] # Encrypted chain of thought is passed back in the response
)


context += response.output # Add the response to the context (including the encrypted chain of thought)
tool_call = response.output[1]
args = json.loads(tool_call.arguments)



result = get_weather(args["latitude"], args["longitude"])

context.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,
    "output": str(result)
})

response_2 = client.responses.create(
    model="o3",
    input=context,
    tools=tools,
    store=False,
    include=["reasoning.encrypted_content"]
)

print(response_2.output_text)

```

--------------------------------

### Example Hyperparameter Search

Source: https://github.com/openai/openai-cookbook/blob/main/examples/Customizing_embeddings.ipynb

Provides a basic example of how to initiate a hyperparameter search. This snippet serves as a starting point for more complex optimization strategies.

```python
# example hyperparameter search
```

--------------------------------

### Start Qdrant Server with Docker Compose

Source: https://github.com/openai/openai-cookbook/blob/main/examples/vector_databases/qdrant/QA_with_Langchain_Qdrant_and_OpenAI.ipynb

Launches a local Qdrant instance using Docker Compose. Ensure you have Docker and the docker-compose.yaml file.

```bash
! docker-compose up -d
```

--------------------------------

### Few-Shot Examples for Vision Fine-Tuning

Source: https://github.com/openai/openai-cookbook/blob/main/examples/multimodal/Vision_Fine_tuning_on_GPT4o_for_Visual_Question_Answering.ipynb

Demonstrates how to structure few-shot examples for a vision fine-tuning task. Includes user prompts with text and image URLs, and assistant responses with reasoning and conclusions. These examples guide the model's understanding and response generation.

```python
FEW_SHOT_EXAMPLES = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "**Example 1:**\n\n**Question:** Who wrote this book?"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(ds_train.iloc[286]['image'], quality=50)}"}}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "**Reasoning:** The cover clearly displays two authors' names, 'Evelyn M. Thomson' and 'Orlen N. Johnson,' at the bottom of the cover, with Evelyn M. Thomson listed first. Typically, the first-listed author is considered the primary author or main contributor.\n\n**Conclusion:** Evelyn Thomson"}
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "**Example 2:**\n\n**Question:** What is the title of this book?"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(ds_train.iloc[22]['image'], quality=50)}"}}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "**Answer:**\n\n**Reasoning:** The cover prominently displays the title across the top and center of the image. The full title reads, 'Computer Systems: An Integrated Approach to Architecture and Operating Systems,' with each component of the title clearly separated and formatted to stand out.\n\n**Conclusion:** Computer Systems: An Integrated Approach to Architecture and Operating Systems"}
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "**Example 3:**\n\n**Question:** Is this book related to Children's Books?"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(ds_train.iloc[492]['image'], quality=50)}"}}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "**Answer:**\n\n**Reasoning:** The cover illustration features a whimsical mermaid holding a red shoe, with gentle, child-friendly artwork that suggests it is targeted toward a young audience. Additionally, the style and imagery are typical of children's literature.\n\n**Conclusion:** Yes"}
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "**Example 4:**\n\n**Question:** Is this book related to History?"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(ds_train.iloc[68]['image'], quality=50)}"}}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "**Answer:**\n\n**Reasoning:** The title 'Oliver Wendell Holmes, Jr.: Civil War Soldier, Supreme Court Justice' clearly indicates that this book focuses on the life of Oliver Wendell Holmes, Jr., providing a biographical account rather than a general historical analysis. Although it references historical elements (Civil War, Supreme Court), the primary focus is on the individual rather than historical events as a whole.\n\n**Conclusion:** No"}
        ]
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "**Example 5:**\n\n**Question:** What is the genre of this book?"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{encode_image(ds_train.iloc[42]['image'], quality=50)}"}}
        ]
    },
    {
        "role": "assistant",
        "content": [

```

--------------------------------

### Create Assistant Example

Source: https://github.com/openai/openai-cookbook/blob/main/examples/third_party/GPT_finetuning_with_wandb.ipynb

Shows how to create an Assistant with specific instructions and tools. Replace 'YOUR_MODEL_ID' with the desired model (e.g., 'gpt-4-turbo').

```python
import os
import openai

openai.api_key = os.getenv("OPENAI_API_KEY")

assistant = openai.Assistant.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Write and run code to answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="YOUR_MODEL_ID"
)

print(assistant.id)
```

--------------------------------

### Run Realtime Translation Demo (Bash)

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/realtime_translation_guide.mdx

Commands to install dependencies and run the Twilio translation demo application. This includes navigating to the demo directory, installing npm packages, and starting the development server.

```bash
cd examples/voice_solutions/realtime_translation_guide/twilio-translation-demo
npm install
npm run dev
```

--------------------------------

### Install and Initialize shadcn/ui

Source: https://github.com/openai/openai-cookbook/blob/main/examples/Build_a_coding_agent_with_GPT-5.1.ipynb

Install shadcn/ui and its dependencies, then initialize it within your Next.js project. This prepares the project to use shadcn/ui components.

```bash
# shadcn/ui & dependencies
npm install shadcn-ui class-variance-authority clsx tailwind-merge lucide-react

# Initialize shadcn/ui
npx shadcn@latest init
```

--------------------------------

### Initialize OpenAI Client

Source: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_handle_rate_limits.ipynb

Set up the OpenAI client with your API key. It's recommended to use environment variables for security.

```python
import openai
import os

client = openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY", "<your OpenAI API key if not set as env var>"))
```

--------------------------------

### Example Conversation State Instruction

Source: https://github.com/openai/openai-cookbook/blob/main/examples/Realtime_prompting_guide.ipynb

This JSON structure defines instructions for a conversational agent, including descriptions, steps, examples, and transitions. It's used to guide agent behavior in specific conversational flows.

```json
{
    "id": "3_get_and_verify_phone",
    "description": "Request phone number and verify by repeating it back.",
    "instructions": [
      "Politely request the user’s phone number.",
      "Once provided, confirm it by repeating each digit and ask if it’s correct.",
      "If the user corrects you, confirm AGAIN to make sure you understand."
    ],
    "examples": [
      "I'll need some more information to access your account if that's okay. May I have your phone number, please?",
      "You said 0-2-1-5-5-5-1-2-3-4, correct?",
      "You said 4-5-6-7-8-9-0-1-2-3, correct?"
    ],
    "transitions": [{
      "next_step": "4_authentication_DOB",
      "condition": "Once phone number is confirmed"
    }]
}
```

--------------------------------

### Prepare and Start Fine-Tuning Job

Source: https://github.com/openai/openai-cookbook/blob/main/examples/Fine-tuned_classification.ipynb

Upload training and validation files, then create a fine-tuning job. Specify the training and validation files by their IDs and choose a base model for fine-tuning.

```python
train_file = client.files.create(file=open("sport2_prepared_train.jsonl", "rb"), purpose="fine-tune")
valid_file = client.files.create(file=open("sport2_prepared_valid.jsonl", "rb"), purpose="fine-tune")

fine_tuning_job = client.fine_tuning.jobs.create(training_file=train_file.id, validation_file=valid_file.id, model="babbage-002")

print(fine_tuning_job)
```

--------------------------------

### Create Directory and Navigate

Source: https://github.com/openai/openai-cookbook/blob/main/examples/chatgpt/gpt_actions_library/gpt_middleware_google_cloud_function.md

Use these commands to create a new directory for your project and navigate into it. This is a prerequisite for setting up a Node.js environment.

```bash
mkdir <directory_name>
cd <directory_name>
```

--------------------------------

### Iterate and Analyze Example Images

Source: https://github.com/openai/openai-cookbook/blob/main/examples/Tag_caption_images_with_GPT4V.ipynb

Loops through the selected example data, displays each image, calls the `analyze_image` function to get tags, and prints the resulting tags. This snippet is used for demonstrating the image tagging functionality with sample data.

```python
for index, ex in examples.iterrows():
    url = ex['primary_image']
    img = Image(url=url)
    display(img)
    result = analyze_image(url, ex['title'])
    print(result)
    print("\n\n")
```

--------------------------------

### Create a Fine-tuned Model with All Options Specified

Source: https://github.com/openai/openai-cookbook/blob/main/examples/third_party/GPT_finetuning_with_wandb.ipynb

This example shows how to create a fine-tuned model with all major options specified: training file, model, suffix, hyperparameters, prompt loss weight, use prompt format, and truncation length. This provides maximum control over the fine-tuning process.

```python
import openai

openai.api_key = "YOUR_API_KEY"

response = openai.FineTuningJob.create(
  training_file="file-xxxxxxxxxxxxxxxxx",
  model="gpt-3.5-turbo",
  suffix="full-config-v1",
  hyperparameters={
    "n_epochs": 7,
    "batch_size": 12,
    "learning_rate_multiplier": 0.4
  },
  prompt_loss_weight=0.002,
  use_prompt_format=True,
  truncation_length=1500
)

print(response.id)
```

--------------------------------

### Initialize OpenAI Client

Source: https://github.com/openai/openai-cookbook/blob/main/examples/batch_processing.ipynb

Initialize the OpenAI client to authenticate and interact with the API. Refer to the OpenAI quickstart guide for more details.

```python
# Initializing OpenAI client - see https://platform.openai.com/docs/quickstart?context=python
client = OpenAI()
```

--------------------------------

### Virtual Try-On Harness Setup

Source: https://github.com/openai/openai-cookbook/blob/main/examples/multimodal/image_evals.ipynb

Sets up the necessary paths, prompts, criteria, and configurations for a Virtual Try-On image editing task. This includes defining the input images, the desired outcome, and the model parameters for execution.

```python
vto_person_path = Path("../../images/base_woman.png")
vto_garment_path = Path("../../images/jacket.png")

vto_prompt = """Put the person in the first image into the jacket shown in the second image.
Keep the person's face, pose, body shape, and background unchanged.
Preserve the garment's color, pattern, and key details.
Do not add extra accessories, text, or new elements."""

vto_criteria = """The output preserves the same person and background.
The jacket matches the reference garment closely.
Body shape and pose remain consistent outside normal garment effects.
The result looks physically plausible."""

vto_case = TestCase(
    id="vto_jacket_tryon",
    task_type="image_editing",
    prompt=vto_prompt,
    criteria=vto_criteria,
    image_inputs=ImageInputs(image_paths=[vto_person_path, vto_garment_path]),
)

vto_run = ModelRun(
    label="gpt-image-1.5-vto",
    task_type="image_editing",
    params={
        "model": "gpt-image-1.5",
        "n": 1,
    },
)

vto_store = OutputStore(root=Path("../../images"))

```

--------------------------------

### Translate Business Jargon with Example Messages

Source: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_format_inputs_to_ChatGPT_models.ipynb

Use example user and assistant messages within the system prompt to guide the model in translating corporate jargon into plain English. This method helps condition the model for specific translation tasks.

```python
response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "You are a helpful, pattern-following assistant that translates corporate jargon into plain English."},
        {"role": "system", "name":"example_user", "content": "New synergies will help drive top-line growth."},
        {"role": "system", "name": "example_assistant", "content": "Things working well together will increase revenue."},
        {"role": "system", "name":"example_user", "content": "Let's circle back when we have more bandwidth to touch base on opportunities for increased leverage."},
        {"role": "system", "name": "example_assistant", "content": "Let's talk later when we're less busy about how to do better."},
        {"role": "user", "content": "This late pivot means we don't have time to boil the ocean for the client deliverable."},
    ],
    temperature=0,
)

print(response.choices[0].message.content)
```

--------------------------------

### Activate Python Virtual Environment (Windows)

Source: https://github.com/openai/openai-cookbook/blob/main/examples/data/oai_docs/python-setup.txt

Activate the created virtual environment on Windows to start using its isolated Python installation and packages.

```bash
openai-env\Scripts\activate
```

--------------------------------

### List Run Steps Example

Source: https://github.com/openai/openai-cookbook/blob/main/examples/third_party/GPT_finetuning_with_wandb.ipynb

Shows how to list all steps for a specific run. This provides detailed information about the execution process. Replace 'THREAD_ID' and 'RUN_ID'.

```python
import os
import openai

openai.api_key = os.getenv("OPENAI_API_KEY")

steps = openai.Thread.runs.steps.list("THREAD_ID", "RUN_ID")

print(steps.data)
```

--------------------------------

### Milvus Service Startup Output

Source: https://github.com/openai/openai-cookbook/blob/main/examples/vector_databases/milvus/Filtered_search_with_Milvus_and_OpenAI.ipynb

Example output indicating the Milvus service is starting up. This may vary based on your Docker and Milvus configuration.

```text
E0317 14:06:38.344884000 140704629352640 fork_posix.cc:76]             Other threads are currently calling into gRPC, skipping fork() handlers\n
```

```text
[?25l[+] Running 1/0\n  ⠿ Network milvus          Created                                         0.1s\n  ⠋ Container milvus-etcd   Creating                                        0.0s\n  ⠋ Container milvus-minio  Creating                                        0.0s\n[?25h[?25l[+] Running 1/3\n  ⠿ Network milvus          Created                                         0.1s\n  ⠙ Container milvus-etcd   Creating                                        0.1s\n  ⠙ Container milvus-minio  Creating                                        0.1s\n[?25h[?25l[+] Running 2/3\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.2s\n  ⠿ Container milvus-minio       Starting                                   0.2s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.3s\n  ⠿ Container milvus-minio       Starting                                   0.3s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.4s\n  ⠿ Container milvus-minio       Starting                                   0.4s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.5s\n  ⠿ Container milvus-minio       Starting                                   0.5s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.6s\n  ⠿ Container milvus-minio       Starting                                   0.6s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.7s\n  ⠿ Container milvus-minio       Starting                                   0.7s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.8s\n  ⠿ Container milvus-minio       Starting                                   0.8s\n  ⠿ Container milvus-standalone  Created                                    0.1s\n[?25h[?25l[+] Running 2/4\n  ⠿ Network milvus               Created                                    0.1s\n  ⠿ Container milvus-etcd        Starting                                   0.9s\n
```

--------------------------------

### Environment Setup and Initialization

Source: https://github.com/openai/openai-cookbook/blob/main/examples/partners/schemaflow_design_guide/schemaflow_cookbook.ipynb

Sets up the Python environment by importing necessary libraries, checking and configuring OpenAI SDK versions, and initializing the OpenAI client. It also configures environment variables for API keys, organization ID, model, trace settings, and a unique trace group ID.

```python
import os
import json
import re
import uuid
from datetime import datetime, timezone
from getpass import getpass
from importlib.metadata import PackageNotFoundError, version

try:
    from openai import OpenAI
except Exception as e:
    raise RuntimeError("Install dependency first: pip install -U openai") from e

MIN_AGENTS_SDK_VERSION = "0.17.0"
try:
    from agents import (
        Agent,
        AgentOutputSchema,
        FileSearchTool,
        Runner,
        RunConfig,
        custom_span,
        flush_traces,
        function_span,
        guardrail_span,
        trace,
    )
except Exception as e:
    raise RuntimeError(
        'Install or upgrade the OpenAI Agents SDK first: pip install -U "openai-agents>=0.17.0"'
    ) from e


def _version_tuple(value):
    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", str(value or ""))
    return tuple(int(part) for part in match.groups()) if match else (0, 0, 0)


try:
    AGENTS_SDK_VERSION = version("openai-agents")
except PackageNotFoundError as e:
    raise RuntimeError('Install the OpenAI Agents SDK first: pip install -U "openai-agents>=0.17.0"') from e

if _version_tuple(AGENTS_SDK_VERSION) < _version_tuple(MIN_AGENTS_SDK_VERSION):
    raise RuntimeError(
        f'OpenAI Agents SDK {MIN_AGENTS_SDK_VERSION}+ is required; found {AGENTS_SDK_VERSION}. '
        'Upgrade with: pip install -U "openai-agents>=0.17.0"'
    )

def _clean_openai_api_key(value):
    key = (value or "").strip()
    if not key:
        raise RuntimeError("OPENAI_API_KEY is required.")
    return key


if not os.getenv("OPENAI_API_KEY", "").strip():
    os.environ["OPENAI_API_KEY"] = getpass("Enter your OpenAI API key: ")
os.environ["OPENAI_API_KEY"] = _clean_openai_api_key(os.getenv("OPENAI_API_KEY"))
OPENAI_ORG_ID = os.getenv("OPENAI_ORG_ID", "").strip()
if OPENAI_ORG_ID:
    os.environ["OPENAI_ORG_ID"] = OPENAI_ORG_ID

MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")
TRACE_INCLUDE_SENSITIVE_DATA = os.getenv("OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA", "false").lower() in {"1", "true", "yes", "on"}
os.environ["OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA"] = "true" if TRACE_INCLUDE_SENSITIVE_DATA else "false"
SCHEMAFLOW_TRACE_GROUP_ID = os.getenv("SCHEMAFLOW_TRACE_GROUP_ID") or (
    "schemaflow-cookbook-" + datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-" + uuid.uuid4().hex[:8]
)
os.environ["SCHEMAFLOW_TRACE_GROUP_ID"] = SCHEMAFLOW_TRACE_GROUP_ID
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
print("Using model:", MODEL)
print("OpenAI Agents SDK:", AGENTS_SDK_VERSION)
print("OpenAI organization:", os.getenv("OPENAI_ORG_ID") or "(default for API key)")
print("Trace group:", SCHEMAFLOW_TRACE_GROUP_ID)
print("Trace payloads include prompts/outputs:", TRACE_INCLUDE_SENSITIVE_DATA)

```

--------------------------------

### Select Training Data Subset

Source: https://github.com/openai/openai-cookbook/blob/main/examples/How_to_finetune_chat_models.ipynb

Python code to select a subset of the dataset for training. It's recommended to start with 30-50 examples and scale up.

```python
# use the first 100 rows of the dataset for training
training_df = recipe_df.loc[0:100]

```

--------------------------------

### Initialize RealtimeClient Instances

Source: https://github.com/openai/openai-cookbook/blob/main/examples/voice_solutions/one_way_translation_using_realtime_api.mdx

Sets up a map of RealtimeClient instances, one for each language configuration. Ensure to use ephemeral API keys in production instead of hardcoding.

```javascript
const clientRefs = useRef(
    languageConfigs.reduce((acc, { code }) => {
      acc[code] = new RealtimeClient({
        apiKey: OPENAI_API_KEY,
        dangerouslyAllowAPIKeyInBrowser: true,
      });
      return acc;
    }, {} as Record<string, RealtimeClient>)
  ).current;

  // Update languageConfigs to include client references
  const updatedLanguageConfigs = languageConfigs.map(config => ({
    ...config,
    clientRef: { current: clientRefs[config.code] }
  }));
```

--------------------------------

### Python Dependencies and Setup

Source: https://github.com/openai/openai-cookbook/blob/main/examples/partners/macro_evals_for_agentic_systems/macro_evals_for_agentic_systems.ipynb

Installs necessary dependencies and sets up the environment by defining helper functions and paths.

```python
from __future__ import annotations

import json
import os
import sqlite3
import sys
import warnings
import zipfile
from pathlib import Path
from time import perf_counter
from typing import Any

import numpy as np
import pandas as pd
import plotly.express as px
import plotly.graph_objects as go
from IPython.display import Markdown, display

pd.set_option("display.max_colwidth", 180)
pd.set_option("display.max_rows", 100)
warnings.filterwarnings("ignore", message="n_jobs value 1 overridden.*")


def find_example_root(start: Path | None = None) -> Path:
    start = (start or Path.cwd()).resolve()
    candidates = [start, *start.parents, start / "examples/partners/macro_evals_for_agentic_systems"]
    for candidate in candidates:
        if (candidate / "helpers/data_prep.py").is_file() and (candidate / "helpers/macro_eval_pipeline.py").is_file():
            return candidate
    raise FileNotFoundError("Could not locate the macro evals example root.")


EXAMPLE_ROOT = find_example_root()
HELPERS_ROOT = EXAMPLE_ROOT / "helpers"
if str(HELPERS_ROOT) not in sys.path:
    sys.path.insert(0, str(HELPERS_ROOT))

from data_prep import add_public_label_columns, build_trace_documents, load_promptfoo_label_rows, normalize_bundle
from macro_eval_pipeline import (
    drill_down_topic_root_causes,
    pick_focus_topic,
    plot_root_cause_story,
    plot_suspect_leaderboard,
    plot_topic_heatmap,
    plot_topic_leaderboard,
    plot_topic_scatter,
    plot_trace_swimlane,
    run_macro_discovery,
    slice_topics_by_metadata,
)


def display_path(path: Path | None) -> str:
    if path is None:
        return "not found"
    try:
        return str(path.resolve().relative_to(EXAMPLE_ROOT))
    except ValueError:
        return str(path)


def as_path(value: str | Path) -> Path:
    path = Path(value).expanduser()
    return path if path.is_absolute() else EXAMPLE_ROOT / path


def unique_paths(paths: list[Path]) -> list[Path]:
    seen: set[Path] = set()
    unique: list[Path] = []
    for path in paths:
        resolved = path.resolve()
        if resolved not in seen:
            seen.add(resolved)
            unique.append(resolved)
    return unique


def find_material(label: str, names: list[str], *, kind: str = "file", required: bool = True) -> Path | None:
    checked: list[Path] = []
    for root in DATA_ROOTS:
        for name in names:
            if not name:
                continue
            candidate = as_path(name) if Path(name).expanduser().is_absolute() else root / name
            checked.append(candidate)
            if kind == "dir":
                exists = candidate.is_dir() and any(candidate.glob("*.json"))
            else:
                exists = candidate.is_file()
            if exists:
                return candidate.resolve()
    if required:
        checked_text = "\n".join(f"- {display_path(path)}" for path in checked)
        raise FileNotFoundError(f"Missing {label}. Checked:\n{checked_text}")
    return None

def ensure_trace_bundle_dir(bundle_dir: Path | None, bundle_zip: Path | None) -> Path:
    if bundle_dir is not None:
        return bundle_dir
    if bundle_zip is None:
        raise FileNotFoundError("Missing trace bundles. Expected data/trace_bundles/ or data/trace_bundles.zip.")
    cache_dir = bundle_zip.parent / ".macro_eval_cache" / "trace_bundles"
    marker = cache_dir / ".extracted_from_trace_bundles_zip"
    if not marker.is_file() or not any(cache_dir.glob("*.json")):
        cache_dir.mkdir(parents=True, exist_ok=True)
        with zipfile.ZipFile(bundle_zip) as archive:
            for member in archive.infolist():
                if member.is_dir() or not member.filename.endswith(".json"):
                    continue
                (cache_dir / Path(member.filename).name).write_bytes(archive.read(member))
        marker.write_text(str(bundle_zip.stat().st_mtime_ns), encoding="utf-8")
    return cache_dir.resolve()

env_data_root = os.environ.get("MACRO_EVALS_DATA_ROOT")
DATA_ROOTS = unique_paths(
    ([as_path(env_data_root)] if env_data_root else [])
    + [
        EXAMPLE_ROOT / "data",
    ]
)

```