> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fallom.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI (TypeScript)

> Trace OpenAI API calls in TypeScript

## Installation

```bash theme={null}
npm install @fallom/trace openai
```

## Quick Start

```typescript theme={null}
import fallom from "@fallom/trace";
import OpenAI from "openai";

// Initialize Fallom once at app startup
await fallom.init({ apiKey: process.env.FALLOM_API_KEY });

// Create a session for this conversation/request
const session = fallom.session({
  configKey: "my-app",
  sessionId: "session-123",
  customerId: "user-456",
});

// Wrap your OpenAI client
const openai = session.wrapOpenAI(new OpenAI());

// Use as normal - automatically traced!
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
```

## Streaming

Streaming responses are also traced with time-to-first-token:

```typescript theme={null}
const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a poem about coding." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
```

## With Azure OpenAI

```typescript theme={null}
import fallom from "@fallom/trace";
import { AzureOpenAI } from "openai";

await fallom.init({ apiKey: "your-fallom-api-key" });

const session = fallom.session({
  configKey: "my-agent",
  sessionId: "session-123",
});

const azure = session.wrapOpenAI(
  new AzureOpenAI({
    apiKey: process.env.AZURE_OPENAI_API_KEY,
    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
    apiVersion: "2024-02-01",
  })
);

const response = await azure.chat.completions.create({
  model: "gpt-4o", // Your deployment name
  messages: [{ role: "user", content: "Hello!" }],
});
```

## Multimodal (Images)

Image inputs are automatically handled:

```typescript theme={null}
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What's in this image?" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/image.jpg" },
        },
      ],
    },
  ],
});
```

## Model A/B Testing

```typescript theme={null}
import fallom from "@fallom/trace";
import OpenAI from "openai";

await fallom.init({ apiKey: "your-fallom-api-key" });

const session = fallom.session({
  configKey: "my-experiment",
  sessionId: "session-123",
});

const openai = session.wrapOpenAI(new OpenAI());

// Get assigned model for this session
const modelId = await session.getModel({ fallback: "gpt-4o-mini" });

const response = await openai.chat.completions.create({
  model: modelId, // Uses A/B test assigned model
  messages: [{ role: "user", content: "Hello!" }],
});
```

## What Gets Traced

| Field       | Description                       |
| ----------- | --------------------------------- |
| Model       | `gpt-4o`, `gpt-4o-mini`, etc.     |
| Duration    | Total request time (ms)           |
| Tokens      | Prompt, completion, cached tokens |
| Cost        | Calculated from token usage       |
| Prompts     | All input messages                |
| Completions | Model response                    |
| Session     | Your config key + session ID      |

## Next Steps

<CardGroup cols={2}>
  <Card title="Model A/B Testing" icon="flask" href="/model-testing">
    Test different models in production.
  </Card>

  <Card title="Prompt Management" icon="pen-fancy" href="/prompt-testing">
    Manage and version your prompts.
  </Card>
</CardGroup>