docs: modernize openai python sdk tutorial for responses era (#56)

Author: johnxie

tutorials/openai-python-sdk-tutorial/01-getting-started.md

@@ -7,14 +7,7 @@ parent: OpenAI Python SDK Tutorial
 
 # Chapter 1: Getting Started
 
-This chapter sets up the OpenAI Python SDK and walks through your first successful API call.
-
-## Goals
-
-- Install the SDK in an isolated environment.
-- Configure authentication safely.
-- Make your first text-generation request.
-- Understand response objects and common errors.
+This chapter gets you to a stable baseline with Responses API-first code.
 
 ## Install and Configure
 
@@ -23,24 +16,19 @@ python3 -m venv .venv
 source .venv/bin/activate
 pip install --upgrade pip
 pip install openai
-```
-
-Set your API key through environment variables:
-
-```bash
 export OPENAI_API_KEY="your_api_key_here"
 ```
 
-## First Request
+## First Responses API Call
 
 ```python
 from openai import OpenAI
 
 client = OpenAI()
 
 response = client.responses.create(
-    model="gpt-4.1-mini",
-    input="Write a one-sentence summary of why typed APIs help in production."
+    model="gpt-5.2",
+    input="Summarize why idempotency matters in API design in 3 bullets."
 )
 
 print(response.output_text)
@@ -52,54 +40,26 @@ print(response.output_text)
 import asyncio
 from openai import AsyncOpenAI
 
-async def main() -> None:
+async def main():
     client = AsyncOpenAI()
-    response = await client.responses.create(
-        model="gpt-4.1-mini",
-        input="Give three short tips for robust API clients."
+    resp = await client.responses.create(
+        model="gpt-5.2",
+        input="Give 3 tips for reliable background jobs."
     )
-    print(response.output_text)
+    print(resp.output_text)
 
 asyncio.run(main())
 ```
 
-## Response Basics
-
-- `response.output_text`: convenient flattened text output.
-- `response.id`: request identifier useful for support/debugging.
-- `response.usage`: token usage metadata for cost tracking.
-
-## Security and Ops Basics
-
-- Never hardcode API keys in source files.
-- Rotate keys and use environment-specific credentials.
-- Add request logging with redaction for sensitive content.
-- Use timeouts and retries in production paths.
+## Baseline Production Controls
 
-## Common Errors
-
-| Error | Cause | Fix |
-|:------|:------|:----|
-| `401 Unauthorized` | Missing/invalid API key | Re-export key and retry |
-| `429 Too Many Requests` | Rate limit exceeded | Backoff + retry policy |
-| `400 Bad Request` | Invalid request shape | Validate payload and model name |
-
-## Quick Troubleshooting
-
-```python
-from openai import OpenAI
-
-client = OpenAI(timeout=30.0)
-
-try:
-    r = client.responses.create(model="gpt-4.1-mini", input="health check")
-    print(r.id)
-except Exception as exc:
-    print(type(exc).__name__, str(exc))
-```
+- set explicit client timeouts
+- capture request IDs in logs
+- keep secrets out of source control
+- fail fast on invalid configuration
 
 ## Summary
 
-You now have a working SDK installation, secure key loading, and both sync and async first calls.
+You now have a working SDK setup with both sync and async Responses API calls.
 
 Next: [Chapter 2: Chat Completions](02-chat-completions.md)

tutorials/openai-python-sdk-tutorial/02-chat-completions.md

@@ -7,101 +7,55 @@ parent: OpenAI Python SDK Tutorial
 
 # Chapter 2: Chat Completions
 
-This chapter covers message-based interactions, streaming output, and tool/function calling patterns.
+Chat Completions remains important for existing systems even as new builds move to Responses-first flows.
 
-## Message-Based Requests
+## Basic Message-Based Request
 
 ```python
 from openai import OpenAI
 
 client = OpenAI()
 
-messages = [
-    {"role": "system", "content": "You are a concise assistant."},
-    {"role": "user", "content": "Explain exponential backoff in two bullets."},
-]
-
-response = client.chat.completions.create(
-    model="gpt-4.1-mini",
-    messages=messages,
-    temperature=0.2,
+completion = client.chat.completions.create(
+    model="gpt-5.2",
+    messages=[
+        {"role": "developer", "content": "Be concise and structured."},
+        {"role": "user", "content": "Explain exponential backoff in 2 bullets."}
+    ]
 )
 
-print(response.choices[0].message.content)
+print(completion.choices[0].message.content)
 ```
 
-## Streaming
+## Streaming Pattern
 
 ```python
-from openai import OpenAI
-
-client = OpenAI()
-
 stream = client.chat.completions.create(
-    model="gpt-4.1-mini",
-    messages=[{"role": "user", "content": "List five API reliability checks."}],
-    stream=True,
+    model="gpt-5.2",
+    messages=[{"role": "user", "content": "List 5 SRE runbook checks."}],
+    stream=True
 )
 
 for chunk in stream:
     delta = chunk.choices[0].delta
     if delta and delta.content:
         print(delta.content, end="", flush=True)
-print()
-```
-
-## Tool Calling Pattern
-
-```python
-import json
-from openai import OpenAI
-
-client = OpenAI()
-
-tools = [{
-    "type": "function",
-    "function": {
-        "name": "get_weather",
-        "description": "Get weather by city",
-        "parameters": {
-            "type": "object",
-            "properties": {"city": {"type": "string"}},
-            "required": ["city"],
-        },
-    },
-}]
-
-resp = client.chat.completions.create(
-    model="gpt-4.1-mini",
-    messages=[{"role": "user", "content": "What is the weather in Seattle?"}],
-    tools=tools,
-    tool_choice="auto",
-)
-
-choice = resp.choices[0].message
-if choice.tool_calls:
-    call = choice.tool_calls[0]
-    args = json.loads(call.function.arguments)
-    print("Tool requested:", call.function.name, args)
 ```
 
-## Recommended Practices
+## When to Keep Chat Completions
 
-- Keep system prompts short and explicit.
-- Validate tool arguments before execution.
-- Keep tool responses structured and bounded.
-- Capture request IDs for incident triage.
+- existing production systems with stable message middleware
+- deeply integrated toolchains using current message schemas
+- migration phases where Responses API adoption is incremental
 
-## Common Pitfalls
+## When to Prefer Responses
 
-| Pitfall | Symptom | Fix |
-|:--------|:--------|:----|
-| Overlong prompts | Higher cost/latency | Summarize and chunk context |
-| Missing tool schema validation | Runtime errors | Strict JSON schema checks |
-| No streaming backpressure handling | UI freezes | Buffer and throttle rendering |
+- new services
+- multimodal and unified response flows
+- systems that need cleaner forward compatibility with current OpenAI platform direction
 
 ## Summary
 
-You can now implement chat flows with streaming and function calls.
+You can now support legacy/interoperable message workflows while planning Responses-first migration.
 
 Next: [Chapter 3: Embeddings and Search](03-embeddings-search.md)

tutorials/openai-python-sdk-tutorial/03-embeddings-search.md

@@ -7,7 +7,7 @@ parent: OpenAI Python SDK Tutorial
 
 # Chapter 3: Embeddings and Search
 
-Embeddings convert text into vectors so you can perform semantic retrieval for RAG and search.
+Embeddings power retrieval quality in most production RAG systems.
 
 ## Create Embeddings
 
@@ -16,71 +16,37 @@ from openai import OpenAI
 
 client = OpenAI()
 
-texts = [
-    "How to rotate API keys safely",
-    "Rate limits and retry policies",
-    "How to design a deployment checklist",
+docs = [
+    "Retry transient failures with exponential backoff.",
+    "Use idempotency keys for side-effecting writes.",
+    "Track p95 and p99 latency separately."
 ]
 
 emb = client.embeddings.create(
     model="text-embedding-3-small",
-    input=texts,
+    input=docs,
 )
 
 vectors = [row.embedding for row in emb.data]
 print(len(vectors), len(vectors[0]))
 ```
 
-## Simple Similarity Search
-
-```python
-import math
-from openai import OpenAI
-
-
-def cosine(a, b):
-    dot = sum(x * y for x, y in zip(a, b))
-    na = math.sqrt(sum(x * x for x in a))
-    nb = math.sqrt(sum(y * y for y in b))
-    return dot / (na * nb + 1e-12)
-
-client = OpenAI()
-
-docs = [
-    "Use exponential backoff for transient failures",
-    "Store credentials in env vars and rotate them",
-    "Benchmark latency and tail percentiles",
-]
-
-query = "How should I handle temporary API errors?"
-
-all_vectors = client.embeddings.create(model="text-embedding-3-small", input=docs + [query]).data
-
-doc_vectors = [x.embedding for x in all_vectors[:-1]]
-query_vec = all_vectors[-1].embedding
-
-scores = [(i, cosine(query_vec, dv)) for i, dv in enumerate(doc_vectors)]
-for i, s in sorted(scores, key=lambda t: t[1], reverse=True):
-    print(round(s, 4), docs[i])
-```
-
-## Retrieval Pipeline Notes
+## Retrieval Pipeline Blueprint
 
-- Chunk by meaning, not fixed bytes only.
-- Store metadata (source, timestamp, section).
-- Re-rank top candidates when quality matters.
-- Track retrieval hit quality over time.
+1. chunk source docs with semantic boundaries
+2. generate embeddings and store vectors + metadata
+3. retrieve top-k candidates by similarity
+4. re-rank or filter by business constraints
+5. pass compact context to generation layer
 
-## Troubleshooting
+## Quality Controls
 
-| Issue | Cause | Fix |
-|:------|:------|:----|
-| Poor matches | Bad chunking or noisy docs | Improve segmentation and cleaning |
-| High cost | Embedding everything repeatedly | Cache vectors and incremental updates |
-| Slow retrieval | No ANN index | Use a vector DB or optimized index |
+- maintain versioned chunking strategy
+- keep source timestamps for freshness checks
+- evaluate retrieval quality with labeled benchmark queries
 
 ## Summary
 
-You can now generate embeddings and implement semantic retrieval.
+You now have the core pieces to build and evaluate a robust embeddings-backed retrieval system.
 
-Next: [Chapter 4: Assistants API](04-assistants-api.md)
+Next: [Chapter 4: Agents and Assistants](04-assistants-api.md)