# OpenAI Cookbook — Administrator & Developer Guide

This guide covers the architecture, repository structure, tooling internals, configuration reference, and contribution workflow for `openai/openai-cookbook`. It is written for maintainers, contributors, fork operators, and developers mining the cookbook for reusable patterns.

For everyday usage of the examples, see the User Guide.

## 1. Architecture Overview

### What This Repository Is

The OpenAI Cookbook is a flat collection of runnable examples — primarily Jupyter notebooks and Python scripts — organized by topic under `examples/`. There is no application to deploy, no server to run, and no build system. The repository exists to teach the OpenAI API through working code.

The only executable Python programs (beyond notebooks) are:

1. **`examples/api_request_parallel_processor.py`** — a standalone async script for rate-limited parallel API requests
2. **`examples/agents_sdk/sandboxed-code-migration/src/run_migration_agent.py`** — a CLI-driven code migration agent using the Agents SDK

Everything else is notebook-based, designed to be run cell-by-cell in Jupyter.

### Repository Layout

```text
openai-cookbook/
├── articles/                    # Markdown articles and GPT-OSS tutorials
│   └── gpt-oss/                 # Open-source model guides (Ollama, vLLM, etc.)
├── examples/                    # 80+ Jupyter notebooks and scripts
│   ├── agents_sdk/              # Agents SDK examples
│   │   ├── sandboxed-code-migration/  # Full migration agent with sandboxes
│   │   ├── multi-agent-portfolio-collaboration/  # Investment analysis agents
│   │   ├── computer_use_with_daytona/  # Computer use example
│   │   └── voice_agents_*/      # Voice agent assets
│   ├── azure/                   # Azure OpenAI examples
│   │   └── archive/             # Deprecated Azure notebooks
│   ├── chatgpt/                 # ChatGPT integrations
│   │   ├── gpt_actions_library/ # 25+ GPT Action recipes
│   │   ├── rag-quickstart/      # RAG on Azure and GCP
│   │   ├── sharepoint_azure_function/  # SharePoint integration
│   │   └── compliance_api/      # Compliance logging
│   ├── codex/                   # Codex examples
│   ├── dalle/                   # DALL-E examples
│   ├── book_translation/        # LaTeX book translation
│   ├── building_w_rt_mini/      # Realtime API mini model
│   ├── agentkit/                # AgentKit walkthrough
│   ├── data/                    # Sample datasets (CSV, JSONL, PDF, audio, DB)
│   └── *.ipynb                  # Top-level notebooks (embeddings, fine-tuning, etc.)
├── authors.yaml                 # Contributor metadata for cookbook.openai.com
├── AGENTS.md                    # Agent instructions
├── CONTRIBUTING.md              # Contribution guidelines
└── LICENSE                      # MIT License
```

> [!NOTE]
> The repository has no `setup.py`, `pyproject.toml`, or package configuration. Each example is self-contained — there is no shared library code beyond what individual examples provide in their own subdirectories.

### Technology Stack

| Layer | Technology |
|---|---|
| Language | Python 3.8+ (notebooks), JavaScript/Node.js (SharePoint examples) |
| Notebooks | Jupyter (`.ipynb`) |
| Primary SDK | `openai` (Python), `openai-agents` (Agents SDK examples) |
| Token counting | `tiktoken` |
| Data processing | `pandas`, `numpy`, `matplotlib`, `seaborn` |
| Async HTTP | `aiohttp` (parallel processor) |
| Sandbox runtimes | Docker, Cloudflare Workers, E2B |
| MCP servers | `mcp` (FastMCP), `MCPServerStdio`, `MCPServerStreamableHttp` |
| Financial data | `yfinance`, `fredapi` |
| Cloud platforms | Azure Functions, Google Cloud Functions |

### Component Inventory

| Component | Path | Role |
|---|---|---|
| Parallel API processor | `examples/api_request_parallel_processor.py` | Rate-limited batch API calls |
| Migration agent | `examples/agents_sdk/sandboxed-code-migration/src/run_migration_agent.py` | Sandboxed code migration CLI |
| Migration evals | `examples/agents_sdk/sandboxed-code-migration/evals.py` | Artifact validation |
| Migration fixtures | `examples/agents_sdk/sandboxed-code-migration/repo_fixtures/` | Test repos for migration |
| Portfolio agents | `examples/agents_sdk/multi-agent-portfolio-collaboration/` | Multi-agent investment analysis |
| Yahoo Finance MCP | `examples/agents_sdk/multi-agent-portfolio-collaboration/mcp/yahoo_finance_server.py` | MCP server for financial data |
| RAG function (GCP) | `examples/chatgpt/rag-quickstart/gcp/main.py` | BigQuery vector search endpoint |
| RAG function (Azure) | `examples/chatgpt/rag-quickstart/azure/function_app.py` | Azure AI Search endpoint |
| SharePoint retrieval | `examples/chatgpt/sharepoint_azure_function/solution_one_file_retrieval.js` | File retrieval from SharePoint |
| SharePoint preprocessing | `examples/chatgpt/sharepoint_azure_function/solution_two_preprocessing.js` | SharePoint content with OpenAI summarization |
| Author registry | `authors.yaml` | Contributor display info for website |

## 2. System Requirements

### Development Environment

| Requirement | Details |
|---|---|
| Python | 3.8+ (3.11+ recommended) |
| Node.js | 14+ (for SharePoint Azure Function examples only) |
| Docker | Required for sandboxed migration agent (Docker backend) |
| Git | For cloning the repository |
| Jupyter | Notebook or JupyterLab |
| Disk space | ~1 GB including datasets and audio files |

### API Keys and Accounts

| Service | Variable | Required For |
|---|---|---|
| OpenAI | `OPENAI_API_KEY` | All Python examples |
| FRED | `FRED_API_KEY` | Multi-agent portfolio (`get_fred_series` tool) |
| Cloudflare | `CLOUDFLARE_SANDBOX_WORKER_URL`, `CLOUDFLARE_SANDBOX_API_KEY` | Migration agent (Cloudflare backend) |
| E2B | `E2B_API_KEY` | Migration agent (E2B backend) |
| OpenAI Docs MCP | `OPENAI_DOCS_MCP_URL` | Migration agent (optional docs server) |
| Azure | `SEARCH_SERVICE_API_KEY`, `OPENAI_API_KEY` | RAG quickstart (Azure) |
| Azure AD | `TENANT_ID`, `CLIENT_ID`, `MICROSOFT_PROVIDER_AUTHENTICATION_SECRET` | SharePoint integration |
| GCP | `PROJECT_ID`, `DATASET_ID`, `TABLE_ID`, `EMBEDDINGS_MODEL` | RAG quickstart (GCP) |

## 3. Configuration Reference

### Environment Variables — Complete List

| Variable | Type | Default | Description | Required? |
|---|---|---|---|---|
| `OPENAI_API_KEY` | string | — | OpenAI API authentication key | Yes (all examples) |
| `FRED_API_KEY` | string | — | Federal Reserve Economic Data API key | Portfolio agents only |
| `CLOUDFLARE_SANDBOX_WORKER_URL` | string | — | Cloudflare sandbox worker endpoint URL | Migration agent (Cloudflare) |
| `CLOUDFLARE_SANDBOX_API_KEY` | string | — | Cloudflare sandbox authentication key | Migration agent (Cloudflare) |
| `E2B_API_KEY` | string | — | E2B sandbox platform API key | Migration agent (E2B) |
| `OPENAI_DOCS_MCP_URL` | string | — | URL for OpenAI docs MCP server | Migration agent (optional) |
| `SEARCH_SERVICE_API_KEY` | string | — | Azure AI Search service key | Azure RAG quickstart |
| `EMBEDDINGS_MODEL` | string | — | Embedding model name for GCP RAG | GCP RAG quickstart |
| `PROJECT_ID` | string | — | GCP project identifier | GCP RAG quickstart |
| `DATASET_ID` | string | — | BigQuery dataset identifier | GCP RAG quickstart |
| `TABLE_ID` | string | — | BigQuery table identifier | GCP RAG quickstart |
| `TENANT_ID` | string | — | Azure AD tenant identifier | SharePoint integration |
| `CLIENT_ID` | string | — | Azure AD client identifier | SharePoint integration |
| `MICROSOFT_PROVIDER_AUTHENTICATION_SECRET` | string | — | Azure AD client secret | SharePoint integration |

> [!IMPORTANT]
> The parallel processor reads `OPENAI_API_KEY` from the environment if `--api_key` is not provided on the command line. For Azure deployments, use the `--api_key` flag or set the environment variable to your Azure API key.

### CLI Flags — Parallel Processor (`api_request_parallel_processor.py`)

| Flag | Type | Default | Description |
|---|---|---|---|
| `--requests_filepath` | string | — | Path to JSONL file containing API requests |
| `--save_filepath` | string | `{requests_filepath}_results.jsonl` | Output path for results |
| `--request_url` | string | `https://api.openai.com/v1/embeddings` | API endpoint URL |
| `--api_key` | string | `$OPENAI_API_KEY` | API key for authentication |
| `--max_requests_per_minute` | int | `1500` | Rate limit for requests per minute |
| `--max_tokens_per_minute` | int | `125000` | Rate limit for tokens per minute |
| `--token_encoding_name` | string | `cl100k_base` | Tiktoken encoding name |
| `--max_attempts` | int | `5` | Maximum retry attempts per request |
| `--logging_level` | int | `20` (INFO) | Python logging level (10=DEBUG, 20=INFO, 30=WARNING, 40=ERROR) |

### CLI Flags — Migration Agent (`run_migration_agent.py`)

| Flag | Type | Default | Description |
|---|---|---|---|
| `--backend` | choice | `docker` | Sandbox backend: `docker`, `cloudflare`, or `e2b` |
| `--model` | string | `gpt-5.4` | Model to use for the migration agent |
| `--prompt` | string | (built-in migration prompt) | Custom prompt for the agent |
| `--docker-image` | string | `python:3.14-slim` | Docker image for sandbox container |
| `--output-dir` | path | `<example_root>/outputs` | Output directory for artifacts |
| `--task` | append | all tasks | Migration task to run (repeatable); choices: `support_reply_service`, `case_summary_service` |
| `--enable-hosted-tracing` | flag | `false` | Enable OpenAI hosted tracing |

## 4. Deployment & Scaling

### This Repository Does Not Deploy

The cookbook is a collection of examples, not a deployable application. However, some examples contain deployable components:

### Azure Functions (RAG Quickstart)

The `examples/chatgpt/rag-quickstart/azure/` directory contains an Azure Function for vector similarity search:

- **Entry point**: `function_app.py`
- **Route**: `GET /api/vector_similarity_search` (anonymous auth)
- **Configuration**: `host.json`, `requirements.txt`
- **Deploy**: Standard Azure Functions deployment (`func azure functionapp publish`)

The function accepts JSON requests with `search_service_endpoint`, `index_name`, `query`, `k_nearest_neighbors`, `search_column`, and `use_hybrid_query` fields.

### Google Cloud Functions (RAG Quickstart)

The `examples/chatgpt/rag-quickstart/gcp/main.py` implements a Cloud Function for BigQuery vector search:

- **Entry point**: `openai_docs_search`
- **Framework**: `functions-framework`
- **Deploy**: `gcloud functions deploy openai_docs_search --runtime python311 --trigger-http`

The function accepts JSON with `query` (required), `top_k` (default 3), and `category` (optional filter) fields.

> [!NOTE]
> Both RAG quickstart deployments require their respective cloud platforms to be configured separately. The notebooks in the same directories walk through the full setup process.

### SharePoint Azure Functions

Two JavaScript Azure Function implementations in `examples/chatgpt/sharepoint_azure_function/`:

1. **`solution_one_file_retrieval.js`** — searches SharePoint via Microsoft Graph, returns raw file content as base64 (suitable for OpenAI file processing)
2. **`solution_two_preprocessing.js`** — searches SharePoint, extracts PDF text, then uses `gpt-4o-mini` to extract relevant passages before returning results

Both require Azure AD OAuth (OBO flow) with `TENANT_ID`, `CLIENT_ID`, and `MICROSOFT_PROVIDER_AUTHENTICATION_SECRET`.

## 5. Operations

### Running the Migration Agent in Production

The sandboxed code migration agent (`run_migration_agent.py`) is the most operationally complex example in the cookbook.

#### Docker Backend (Recommended for Local Use)

```bash
# Ensure Docker is running
docker info

# Run all migration tasks
python -m src.run_migration_agent --backend docker

# Run specific task
python -m src.run_migration_agent --backend docker --task support_reply_service
```

The agent creates a Docker container with `python:3.14-slim`, mounts the fixture repo and migration instructions, runs baseline tests, applies patches, runs final tests, and produces structured output.

#### Cloudflare Backend (Cloud Sandbox)

```bash
export CLOUDFLARE_SANDBOX_WORKER_URL="https://your-worker.workers.dev"
export CLOUDFLARE_SANDBOX_API_KEY="your-key"
python -m src.run_migration_agent --backend cloudflare
```

> [!WARNING]
> Cloudflare sandbox support requires the `cloudflare` extra: `pip install openai-agents[cloudflare]`. If not installed, the agent exits with a clear error message.

#### E2B Backend (Cloud Sandbox)

```bash
export E2B_API_KEY="your-key"
python -m src.run_migration_agent --backend e2b
```

#### Monitoring and Auditing

Every migration run produces an audit log at `outputs/<task>/migration_audit.jsonl`. Events logged:

| Event | Description |
|---|---|
| `host_mcp_connected` | MCP server connected (if `OPENAI_DOCS_MCP_URL` set) |
| `tool_called` | Agent invoked a sandbox tool |
| `tool_output` | Tool returned output (truncated to 4000 chars) |
| `host_artifacts_written` | Final artifacts written to disk |

> [!TIP]
> Enable `--enable-hosted-tracing` for detailed run traces in the OpenAI dashboard. This is useful for debugging agent behavior but adds latency.

### Artifact Validation

Run the evaluation script to validate migration output:

```bash
python evals.py --output-dir outputs/
```

The validator checks:
- All expected files exist: `migration_report.md`, `migration.patch`, `migration_result.json`, `migration_audit.jsonl`
- Result JSON contains valid `baseline_test_command`, `check_command`, `final_test_command`
- `final_test_result` indicates passing tests
- Patch contains `responses.create` and `output_text` markers (proving the migration happened)
- Patch modifies the expected files for each task
- Audit log contains a `host_artifacts_written` event

### Yahoo Finance MCP Server

The multi-agent portfolio example includes a FastMCP server for Yahoo Finance data:

```bash
python examples/agents_sdk/multi-agent-portfolio-collaboration/mcp/yahoo_finance_server.py
```

This runs as an MCP stdio server with tools for:
- Historical stock prices
- Stock info and financials
- News
- Stock actions (dividends, splits)
- Financial statements (income, balance sheet, cashflow)
- Holder information
- Options chains
- Analyst recommendations

Files are saved to `outputs/` as CSV or JSON. The server has a 30-second timeout per tool call.

## 6. Performance

### Parallel Processor Throughput

The `api_request_parallel_processor.py` script uses an async event loop with adaptive rate limiting:

- **Main loop frequency**: 1ms sleep between iterations (max ~1000 requests/second dispatch rate)
- **Rate limit cooldown**: 15 seconds after receiving a rate limit error
- **Capacity tracking**: Sliding window for both requests/minute and tokens/minute
- **Token estimation**: Pre-computed from request JSON using `tiktoken` before dispatch

> [!NOTE]
> The script defaults to 1,500 requests/minute and 125,000 tokens/minute (50% of typical tier limits). Adjust based on your actual rate limits. The defaults are set at `3_000 * 0.5` and `250_000 * 0.5` in the argument parser.

### Migration Agent Limits

- Maximum 30 turns per migration task
- Docker containers use `python:3.14-slim` by default
- MCP server timeout: 30 seconds per session
- Model tool choice: `required` (agent must use a tool every turn)

## 7. Security

### API Key Handling

All examples read API keys from environment variables or function arguments. No API keys are hardcoded in the repository.

> [!CAUTION]
> The parallel processor accepts `--api_key` as a CLI argument, which means the key appears in shell history. For production use, prefer the `OPENAI_API_KEY` environment variable.

### Azure AD OAuth (SharePoint Examples)

The SharePoint integration uses the OAuth 2.0 On-Behalf-Of (OBO) flow:
1. Client passes a bearer token scoped to the Azure Function
2. Function exchanges it for a Graph API token via the OBO grant
3. Graph API token is used to search and retrieve SharePoint documents

Required secrets: `TENANT_ID`, `CLIENT_ID`, `MICROSOFT_PROVIDER_AUTHENTICATION_SECRET`.

### Sandbox Isolation

The migration agent isolates code execution in sandboxes:

| Backend | Isolation Level |
|---|---|
| Docker | Container-level isolation, no network access (agent instructions say "do not use network access") |
| Cloudflare | Worker-level isolation in Cloudflare's V8 runtime |
| E2B | VM-level isolation in E2B's cloud environment |

Agent instructions explicitly state: "Do not use network access or real API credentials. Keep tests offline."

### SQL Injection Risk in GCP RAG Example

The GCP RAG quickstart (`main.py`) constructs SQL queries using f-strings:

```python
sql_query = f"""
SELECT ... FROM `{project_id}.{dataset_id}.{table_id}` ...
WHERE ed.category = '{category}'
"""
```

> [!WARNING]
> The `category` parameter is inserted directly into SQL without parameterization. In a production deployment, use parameterized queries or validate/sanitize the `category` input to prevent SQL injection.

### No Credential Files in Repository

The repository includes `.gitignore` rules and no credential files are present in source. All `requirements.txt` files are dependency lists only.

## 8. Developer Internals

### Module Reference

#### `api_request_parallel_processor.py` (490 lines)

Production-grade async API request processor. Key components:

| Component | Type | Purpose |
|---|---|---|
| `process_api_requests_from_file()` | async function | Main loop: reads requests, manages capacity, dispatches calls |
| `StatusTracker` | dataclass | Tracks counts: started, in-progress, succeeded, failed, rate-limit errors |
| `APIRequest` | dataclass | Stores request state, metadata, retry count; has `call_api()` method |
| `api_endpoint_from_url()` | function | Extracts endpoint name from URL (supports OpenAI and Azure patterns) |
| `num_tokens_consumed_from_request()` | function | Estimates token usage from request JSON (completions + embeddings) |
| `append_to_jsonl()` | function | Atomic JSONL append for results |
| `task_id_generator_function()` | generator | Sequential integer IDs |

**Supported endpoints**: `chat/completions`, `completions`, `embeddings`. Other endpoints raise `NotImplementedError`.

**Azure support**: Detects `/deployments` in URL and switches from `Authorization: Bearer` to `api-key` header.

**Retry logic**: Failed requests are re-queued with `attempts_left - 1`. After all attempts exhausted, errors are logged to the save file alongside the original request.

#### `run_migration_agent.py` (472 lines)

Sandboxed code migration agent using the OpenAI Agents SDK. Key components:

| Component | Type | Purpose |
|---|---|---|
| `MigrationTask` | frozen dataclass | Represents a migration task (name + repo path) |
| `MigrationResult` | Pydantic model | Structured output: test results, changed files, patch, report |
| `MigrationTaskSummary` | Pydantic model | Per-task summary for campaign output |
| `MigrationCampaignResult` | Pydantic model | Aggregates task summaries |
| `build_manifest()` | function | Creates sandbox filesystem manifest (mounts repo + AGENTS.md) |
| `build_agent()` | function | Constructs `SandboxAgent` with Shell + ApplyPatch capabilities |
| `create_sandbox()` | async function | Factory for Docker/Cloudflare/E2B sandbox backends |
| `run_migration_task()` | async function | Runs one task: create sandbox → run agent → write artifacts |
| `run_migration_campaign()` | async function | Runs all tasks sequentially, writes batch summary |
| `write_host_artifacts()` | function | Writes report, patch, and result JSON to disk |
| `append_audit_event()` | function | Appends JSONL audit entry |
| `configure_host_mcp_servers()` | async function | Sets up OpenAI docs MCP server if URL provided |

**Default tasks**: `support_reply_service` and `case_summary_service` (both in `repo_fixtures/`).

**Agent configuration**:
- Model: `gpt-5.4` (configurable via `--model`)
- Instructions: "You are a careful code-migration agent" with explicit rules about AGENTS.md, test execution, and offline operation
- Capabilities: `Shell()` + `ApplyPatch()`
- Tool choice: `required`
- Output type: `MigrationResult` (Pydantic)

**Sandbox lifecycle**: Client creates session → agent runs in session → client deletes session in `finally` block (cleanup guaranteed).

#### Multi-Agent Portfolio Collaboration

A five-agent system for investment analysis:

| Module | Path | Role |
|---|---|---|
| `pm.py` | `investment_agents/pm.py` | Head Portfolio Manager — orchestrates specialists |
| `fundamental.py` | `investment_agents/fundamental.py` | Fundamental analysis with Yahoo Finance MCP + web search |
| `macro.py` | `investment_agents/macro.py` | Macro analysis with FRED data + web search |
| `quant.py` | `investment_agents/quant.py` | Quantitative analysis with code interpreter + Yahoo Finance |
| `editor.py` | `investment_agents/editor.py` | Memo editor — compiles final Markdown report |
| `tools.py` | `tools.py` | Shared tools: `run_code_interpreter`, `write_markdown`, `read_file`, `get_fred_series`, `list_output_files` |
| `utils.py` | `utils.py` | Shared utilities: paths, prompt loading, `FileSpanExporter` for local tracing |
| `yahoo_finance_server.py` | `mcp/yahoo_finance_server.py` | FastMCP server with 9 Yahoo Finance tools |

**Agent orchestration pattern**: The PM agent has `function_tool` wrappers that delegate to specialist agents via `Runner.run()`. A `run_all_specialists_parallel` tool dispatches all three specialists concurrently using `asyncio.gather()`.

**All agents use**: `gpt-4.1` model, `temperature=0`, `parallel_tool_calls=True`.

**Code interpreter tool**: Uses `client.responses.create()` with `code_interpreter` tool type. Uploads input files, downloads generated files (plots, CSVs) from the container.

**Prompt management**: Prompts live in `prompts/` as Markdown files. Loaded via `load_prompt()` which substitutes `<PLACEHOLDER>` patterns.

**Local tracing**: `FileSpanExporter` writes agent traces to `logs/agent_traces.jsonl`.

#### Migration Fixture Repos

Two small Python packages used as test targets for the migration agent:

**`support_reply_service`**:
- `customer_support_bot/client.py` — wraps `client.chat.completions.create()`
- `customer_support_bot/replies.py` — drafts support replies using the wrapper
- Tests use `FakeOpenAIClient` / `FakeChatCompletions` — fully offline

**`case_summary_service`**:
- `case_summary_service/client.py` — wraps `client.chat.completions.create()`
- `case_summary_service/summaries.py` — summarizes case notes using the wrapper
- Tests use the same fake pattern — fully offline

Both repos follow the migration target: Chat Completions → Responses API (`client.responses.create()`, `response.output_text`).

#### Evaluation Script (`evals.py`)

Validates migration artifacts without re-running the agent:

| Function | Purpose |
|---|---|
| `validate_migration_artifacts()` | Checks one task's output: files exist, result contains expected values, patch has correct markers |
| `validate_output_root()` | Dispatches to single-task or batch validation based on `batch_summary.json` presence |
| `require_output()` | Asserts file exists and is non-empty |
| `require_contains()` | Asserts text contains a substring |
| `require_result_value()` | Asserts a JSON result field contains a substring |

### Code Patterns and Conventions

#### Notebook Organization

- Each notebook is self-contained — imports, API calls, and outputs in one file
- Notebooks are named descriptively: `How_to_<verb>_<noun>.ipynb`
- Related notebooks share the `examples/` directory; complex examples get subdirectories
- Sample data lives in `examples/data/` and is referenced by relative path

#### Python Script Patterns

- Scripts use `argparse` for CLI interfaces
- `asyncio.run()` at the module level for async entry points
- `dataclass` for internal state tracking
- `Pydantic BaseModel` for structured agent outputs
- `@function_tool` decorator from `openai-agents` for agent tools

#### Agent Architecture Pattern

The cookbook demonstrates a consistent multi-agent pattern:
1. Define specialist agents with `Agent()` — each has instructions, tools, and model settings
2. Wrap each specialist in a `@function_tool` so the orchestrator can delegate
3. Use `Runner.run()` for sub-agent execution
4. Use `asyncio.gather()` for parallel specialist execution
5. Collect structured outputs via Pydantic models

#### MCP Server Pattern

MCP servers use `FastMCP` from the `mcp` package:
1. Define sync functions for blocking I/O (e.g., `yfinance` calls)
2. Wrap in async using `loop.run_in_executor()` with 30-second timeout
3. Save outputs to CSV/JSON and return metadata (file path, schema, preview)

### Testing Strategy

#### Migration Agent Tests (`tests/`)

| Test | What It Validates |
|---|---|
| `test_repo_fixtures_start_with_passing_legacy_tests` | Fixture repos have passing tests before migration |
| `test_repo_fixtures_pass_compile_check` | Fixture repos compile cleanly |
| `test_migration_manifest_mounts_repo_and_agent_instructions` | Manifest correctly mounts `/workspace/repo` and `AGENTS.md` |

Tests use `subprocess.run()` to execute `unittest discover` and `compileall` against fixture repos.

#### Migration Evals (`evals.py`)

Post-run artifact validation (see Operations section above). Run with:

```bash
python evals.py --output-dir outputs/
```

#### No Global Test Suite

The cookbook has no repository-wide test runner. Individual examples may have tests in their subdirectories.

> [!NOTE]
> The fixture repo tests are specifically designed to pass in their pre-migration (Chat Completions) state. The migration agent is expected to update them to pass in the post-migration (Responses API) state.

### Repository Files

#### `authors.yaml`

YAML file mapping contributor GitHub usernames to display metadata for `cookbook.openai.com`:

```yaml
username:
  name: "Display Name"
  website: "https://..."
  avatar: "https://..."
```

Schema defined by `.github/authors_schema.json`. If a contributor is not listed, their info is pulled from their GitHub profile.

#### `AGENTS.md`

Top-level agent instructions file (content not extracted in briefing — exists at repo root).

#### `CONTRIBUTING.md`

Contribution guidelines (content not extracted in briefing — exists at repo root).

### Sample Datasets

| File | Format | Size | Used By |
|---|---|---|---|
| `fine_food_reviews_1k.csv` | CSV | 1K rows | Embedding examples |
| `fine_food_reviews_with_embeddings_1k.csv` | CSV | 1K rows | Pre-computed embeddings |
| `AG_news_samples.csv` | CSV | News samples | Classification examples |
| `amazon_furniture_dataset.csv` | CSV | Product data | Classification examples |
| `25000_spend_dataset_current.csv` | CSV | Transaction data | Transaction classification |
| `cookbook_recipes_nlg_10k.csv` | CSV | 10K rows | NLG examples |
| `helpcenter_articles.csv` | CSV | Help articles | RAG examples |
| `Chinook.db` | SQLite | Database | SQL examples |
| `NotRealCorp_financial_data.json` | JSON | Financial data | Data extraction examples |
| `example_requests_to_parallel_process.jsonl` | JSONL | 10K requests | Parallel processor demo |
| `example_events_openapi.json` | OpenAPI spec | Event management API | Function calling examples |
| `dbpedia_samples.jsonl` | JSONL | DBpedia entries | Embedding examples |
| `drone_training.jsonl` | JSONL | Training data | Fine-tuning examples |
| `created_slides.pptx` | PPTX | Presentation | Assistants API example |
| `fia_f1_power_unit_financial_regulations_issue_1_-_2022-08-16.pdf` | PDF | F1 regulations | PDF parsing examples |
| `examples/data/audio/*.mp3` / `.wav` | Audio | Various | Whisper examples |

### Potential Improvements

1. **Global requirements file** — the repository lacks a top-level `requirements.txt` or `pyproject.toml`. Adding one with common dependencies would simplify onboarding.

2. **Parameterized SQL in GCP RAG** — `examples/chatgpt/rag-quickstart/gcp/main.py` uses f-string SQL construction. Should use parameterized queries.

3. **Token estimation coverage** — the parallel processor only estimates tokens for completions and embeddings endpoints. Other endpoints raise `NotImplementedError`.

4. **Azure archive cleanup** — `examples/azure/archive/` contains 7 deprecated notebooks that duplicate functionality in the parent directory.

5. **Fixture repo expansion** — the migration agent has only 2 fixture repos. Additional fixtures would improve coverage of edge cases.

## 9. Integration Points

### OpenAI API

All examples integrate with the OpenAI API via the `openai` Python SDK:

| API Surface | Example Coverage |
|---|---|
| Chat Completions | Extensive (20+ notebooks) |
| Embeddings | Extensive (15+ notebooks) |
| Fine-tuning | 7 notebooks |
| Assistants | 3 notebooks |
| Responses API | Migration agent, File Search |
| DALL-E / GPT Image | 7 notebooks |
| Whisper | 4 notebooks |
| Realtime API | 6 notebooks |
| Moderation | 2 notebooks |
| Batch API | 1 notebook |
| Code Interpreter | Portfolio collaboration tools |

### Azure OpenAI

The `examples/azure/` directory provides direct equivalents for Azure OpenAI Service. Authentication differs (uses `api-key` header), and deployment URLs follow the `/openai/deployments/<name>/` pattern.

### MCP (Model Context Protocol)

Two MCP integrations:

1. **Yahoo Finance MCP Server** (`yahoo_finance_server.py`): FastMCP stdio server with 9 tools for stock data. Used by fundamental and quantitative analysis agents.

2. **OpenAI Docs MCP Server**: Optional `MCPServerStreamableHttp` connection for the migration agent. Fetches Responses API migration documentation at runtime.

### Cloud Platform Functions

| Platform | Implementation | Purpose |
|---|---|---|
| Azure Functions | `function_app.py`, `solution_*.js` | Vector search, SharePoint retrieval |
| Google Cloud Functions | `main.py` | BigQuery vector search |

### Third-Party Data Services

| Service | Package | Used By |
|---|---|---|
| Yahoo Finance | `yfinance` | Portfolio agents (stock data, financials, options) |
| FRED | `fredapi` | Portfolio agents (economic indicators) |
| Microsoft Graph | `@microsoft/microsoft-graph-client` | SharePoint integration |

---

_Generated May 2026 from openai/openai-cookbook at 564a630. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._