Initial commit

references/migration-guide.md

@@ -0,0 +1,236 @@
+# Migration Guide: Chat Completions → Responses API
+
+**Last Updated**: 2025-10-25
+
+Quick guide for migrating from Chat Completions to Responses API.
+
+---
+
+## Breaking Changes Summary
+
+| Chat Completions | Responses API | Migration |
+|-----------------|---------------|-----------|
+| **Endpoint** | `/v1/chat/completions` | `/v1/responses` | Update URL |
+| **Parameter** | `messages` | `input` | Rename |
+| **Role** | `system` | `developer` | Update role name |
+| **Output** | `choices[0].message.content` | `output_text` | Update accessor |
+| **State** | Manual (messages array) | Automatic (conversation ID) | Use conversations |
+| **Tools** | `tools` array with functions | Built-in types + MCP | Update tool definitions |
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Update Endpoint
+
+**Before:**
+```typescript
+const response = await openai.chat.completions.create({...});
+```
+
+**After:**
+```typescript
+const response = await openai.responses.create({...});
+```
+
+### Step 2: Rename `messages` to `input`
+
+**Before:**
+```typescript
+{
+  messages: [
+    { role: 'system', content: '...' },
+    { role: 'user', content: '...' }
+  ]
+}
+```
+
+**After:**
+```typescript
+{
+  input: [
+    { role: 'developer', content: '...' },
+    { role: 'user', content: '...' }
+  ]
+}
+```
+
+### Step 3: Update Response Access
+
+**Before:**
+```typescript
+const text = response.choices[0].message.content;
+```
+
+**After:**
+```typescript
+const text = response.output_text;
+```
+
+### Step 4: Use Conversation IDs (Optional but Recommended)
+
+**Before (Manual History):**
+```typescript
+let messages = [...previousMessages, newMessage];
+const response = await openai.chat.completions.create({
+  model: 'gpt-5',
+  messages,
+});
+```
+
+**After (Automatic):**
+```typescript
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  conversation: conv.id, // ✅ Automatic state
+  input: newMessage,
+});
+```
+
+---
+
+## Complete Example
+
+**Before (Chat Completions):**
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+let messages = [
+  { role: 'system', content: 'You are a helpful assistant.' },
+];
+
+async function chat(userMessage: string) {
+  messages.push({ role: 'user', content: userMessage });
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-5',
+    messages,
+  });
+
+  const assistantMessage = response.choices[0].message;
+  messages.push(assistantMessage);
+
+  return assistantMessage.content;
+}
+
+// Usage
+await chat('Hello');
+await chat('Tell me a joke');
+```
+
+**After (Responses):**
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const conversation = await openai.conversations.create({
+  items: [
+    { type: 'message', role: 'developer', content: 'You are a helpful assistant.' },
+  ],
+});
+
+async function chat(userMessage: string) {
+  const response = await openai.responses.create({
+    model: 'gpt-5',
+    conversation: conversation.id,
+    input: userMessage,
+  });
+
+  return response.output_text;
+}
+
+// Usage
+await chat('Hello');
+await chat('Tell me a joke'); // Remembers previous turn automatically
+```
+
+---
+
+## Tool Migration
+
+### Chat Completions Functions → Responses Built-in Tools
+
+**Before (Custom Function):**
+```typescript
+{
+  tools: [
+    {
+      type: 'function',
+      function: {
+        name: 'get_weather',
+        description: 'Get weather',
+        parameters: { /* schema */ }
+      }
+    }
+  ]
+}
+```
+
+**After (Built-in or MCP):**
+```typescript
+{
+  tools: [
+    { type: 'web_search' },        // Built-in
+    { type: 'code_interpreter' },  // Built-in
+    {
+      type: 'mcp',                 // External tools
+      server_label: 'weather',
+      server_url: 'https://weather-mcp.example.com'
+    }
+  ]
+}
+```
+
+---
+
+## Streaming Migration
+
+**Before:**
+```typescript
+const stream = await openai.chat.completions.create({
+  model: 'gpt-5',
+  messages,
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+**After:**
+```typescript
+const stream = await openai.responses.create({
+  model: 'gpt-5',
+  input,
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  // Handle polymorphic outputs
+  if (chunk.type === 'message_delta') {
+    process.stdout.write(chunk.content || '');
+  }
+}
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Update all endpoint calls
+- [ ] Rename `messages` to `input`
+- [ ] Update `system` role to `developer`
+- [ ] Update response access (`choices[0]` → `output_text`)
+- [ ] Implement conversation management
+- [ ] Update tool definitions
+- [ ] Test multi-turn conversations
+- [ ] Verify streaming works
+- [ ] Check cost tracking (tool tokens)
+
+---
+
+**Official Docs**: https://platform.openai.com/docs/guides/responses