Initial commit

references/migration-from-v1.md

@@ -0,0 +1,188 @@
+# Migration from Assistants API v1 to v2
+
+**v1 Deprecated**: December 18, 2024 (no longer accessible)
+**v2 Status**: Production (Deprecated H1 2026 in favor of Responses API)
+
+---
+
+## Breaking Changes
+
+### 1. Retrieval Tool → File Search
+
+**v1:**
+```typescript
+{
+  tools: [{ type: "retrieval" }],
+  file_ids: ["file_abc123", "file_def456"]
+}
+```
+
+**v2:**
+```typescript
+{
+  tools: [{ type: "file_search" }],
+  tool_resources: {
+    file_search: {
+      vector_store_ids: ["vs_abc123"]
+    }
+  }
+}
+```
+
+**Action**: Create vector stores and migrate files.
+
+### 2. File Attachments
+
+**v1**: Files attached at assistant level
+**v2**: Files attached at message level
+
+**v1:**
+```typescript
+const assistant = await openai.beta.assistants.create({
+  file_ids: ["file_abc123"],
+});
+```
+
+**v2:**
+```typescript
+await openai.beta.threads.messages.create(thread.id, {
+  content: "...",
+  attachments: [{
+    file_id: "file_abc123",
+    tools: [{ type: "code_interpreter" }]
+  }],
+});
+```
+
+### 3. Instructions Character Limit
+
+- **v1**: 32,000 characters
+- **v2**: 256,000 characters (8x increase)
+
+---
+
+## Migration Steps
+
+### Step 1: Create Vector Stores
+
+```typescript
+// Old v1 approach
+const assistant = await openai.beta.assistants.create({
+  tools: [{ type: "retrieval" }],
+  file_ids: fileIds, // Direct attachment
+});
+
+// New v2 approach
+const vectorStore = await openai.beta.vectorStores.create({
+  name: "Knowledge Base",
+});
+
+await openai.beta.vectorStores.fileBatches.create(vectorStore.id, {
+  file_ids: fileIds,
+});
+
+const assistant = await openai.beta.assistants.create({
+  tools: [{ type: "file_search" }],
+  tool_resources: {
+    file_search: {
+      vector_store_ids: [vectorStore.id],
+    },
+  },
+});
+```
+
+### Step 2: Update File Attachments
+
+```typescript
+// Move file attachments from assistant to messages
+await openai.beta.threads.messages.create(thread.id, {
+  role: "user",
+  content: "Analyze this file",
+  attachments: [{
+    file_id: "file_abc123",
+    tools: [{ type: "code_interpreter" }],
+  }],
+});
+```
+
+### Step 3: Test Thoroughly
+
+- Verify file search returns expected results
+- Check Code Interpreter file handling
+- Test streaming if used
+- Validate function calling patterns
+
+---
+
+## New v2 Features
+
+### 1. Massive File Capacity
+
+- **v1**: ~20 files per assistant
+- **v2**: 10,000 files per assistant (500x increase)
+
+### 2. Better Search Performance
+
+- Vector + keyword search
+- Parallel query processing
+- Advanced reranking
+
+### 3. Auto-Expiration
+
+```typescript
+const vectorStore = await openai.beta.vectorStores.create({
+  expires_after: {
+    anchor: "last_active_at",
+    days: 30,
+  },
+});
+```
+
+### 4. Batch File Operations
+
+```typescript
+const batch = await openai.beta.vectorStores.fileBatches.create(vectorStoreId, {
+  file_ids: ["file_1", "file_2", "file_3"],
+});
+```
+
+---
+
+## Cost Implications
+
+### v1 (Deprecated)
+- No separate storage costs for retrieval
+
+### v2
+- **Storage**: $0.10/GB/day for vector stores
+- **Free tier**: First 1GB
+- **Optimization**: Use auto-expiration
+
+---
+
+## Recommended Path Forward
+
+**For existing v1 applications:**
+1. Migrate to v2 immediately (v1 no longer works)
+2. Plan migration to Responses API (v2 sunset in H1 2026)
+
+**For new applications:**
+- ✅ Use [Responses API](../../openai-responses/SKILL.md)
+- ❌ Don't use Assistants API (being deprecated)
+
+---
+
+## Migration Checklist
+
+- [ ] Update to openai SDK 6.7.0+
+- [ ] Create vector stores for file search
+- [ ] Migrate file attachments to message level
+- [ ] Test file search results
+- [ ] Update to `file_search` from `retrieval`
+- [ ] Implement vector store cleanup
+- [ ] Monitor storage costs
+- [ ] Plan migration to Responses API
+
+---
+
+**Last Updated**: 2025-10-25