OpenAI API Patterns

# OpenAI API Patterns

## Install
```bash
npm install openai
pip install openai
```

## Chat completions
```ts
import OpenAI from 'openai'
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

const res = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain async/await in one paragraph.' },
  ],
  temperature: 0.7,
  max_tokens: 500,
})
console.log(res.choices[0].message.content)
```

## Streaming
```ts
const stream = openai.chat.completions.stream({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a poem' }],
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}
const finalMessage = await stream.finalMessage()
```

## Function / Tool calling
```ts
const tools = [{
  type: 'function' as const,
  function: {
    name: 'get_weather',
    description: 'Get current weather for a city',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'City name' },
        unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
      },
      required: ['city'],
    },
  },
}]

const res = await openai.chat.completions.create({ model: 'gpt-4o', messages, tools })
const call = res.choices[0].message.tool_calls?.[0]
if (call) {
  const args = JSON.parse(call.function.arguments)
  const result = await getWeather(args.city, args.unit)
  // Feed result back into messages and call again
}
```

## Embeddings
```ts
const res = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'The quick brown fox',
})
const vector = res.data[0].embedding  // float[1536]

// Cosine similarity
const similarity = (a, b) =>
  a.reduce((sum, v, i) => sum + v * b[i], 0) /
  (Math.sqrt(a.reduce((s, v) => s + v*v, 0)) * Math.sqrt(b.reduce((s, v) => s + v*v, 0)))
```

## Vision
```ts
const res = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this image?' },
      { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } },
      // Or base64: { type: 'image_url', image_url: { url: 'data:image/jpeg;base64,...' } }
    ],
  }],
})
```

## Cost & rate limit tips
- `gpt-4o-mini` for most tasks (10x cheaper than gpt-4o).
- Cache identical prompts (same hash -> reuse response).
- Use `max_tokens` to cap output length.
- Batch embeddings: pass array of strings to single API call.
- Exponential backoff on 429: wait 2^n seconds before retry.