# @wix/ai

[![npm version](https://img.shields.io/npm/v/@wix/ai.svg)](https://www.npmjs.com/package/@wix/ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

Wix AI SDK for the [Vercel AI SDK](https://ai-sdk.dev/). Provides access to AI models through Wix infrastructure with automatic authentication.

> ⚠️ **Note**: This package depends on Vercel AI SDK v6 (currently in beta).

## Supported Providers

| Provider | Status | Capabilities |
|----------|--------|--------------|
| **OpenAI** | ✅ Available | Text generation, chat, embeddings |
| **Runware** | ✅ Available | Image generation |

## Installation

```bash
npm install @wix/ai
```

> **Requirements:**
> - `ai@>=6.0.27` (Vercel AI SDK v6)
> - `zod@^4.1.8`

## Quick Start

### Wix Environment (Blocks, Wix CLI Apps)

```typescript
import { generateText } from 'ai';
import { openai } from '@wix/ai';

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the capital of France?',
});
```

### Self-Hosted Apps

For apps running outside Wix, pass a WixClient configured with `AppStrategy` or `ApiKeyStrategy`:

```typescript
import { generateText } from 'ai';
import { createOpenAI } from '@wix/ai';
import { createClient, AppStrategy } from '@wix/sdk';

const wixClient = createClient({
  auth: AppStrategy({
    appId: 'YOUR_APP_ID',
    appSecret: 'YOUR_APP_SECRET',
    instanceId: 'YOUR_INSTANCE_ID',
  }),
});

const openai = createOpenAI({ client: wixClient });

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the capital of France?',
});
```

## Requirements

- ✅ Wix backend code (API routes, server functions)
- ✅ Self-hosted apps (with WixClient using AppStrategy or ApiKeyStrategy)
- ❌ Browser/client-side code

**Technical requirements:**
- Node.js 18+
- `ai` package v6.0.0+

## API Reference

### OpenAI Provider

#### Responses API (Default)

```typescript
import { generateText } from 'ai';
import { openai } from '@wix/ai';

const { text } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Explain quantum computing.',
});
```

Or explicitly:

```typescript
const model = openai.responses('gpt-4o');
```

#### Chat Completions

```typescript
import { generateText } from 'ai';
import { openai } from '@wix/ai';

const { text } = await generateText({
  model: openai.chat('gpt-4o'),
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is TypeScript?' },
  ],
});
```

#### Embeddings

```typescript
import { embed, cosineSimilarity } from 'ai';
import { openai } from '@wix/ai';

const { embedding } = await embed({
  model: openai.embeddingModel('text-embedding-3-small'),
  value: 'Hello world',
});

const similarity = cosineSimilarity(embedding1, embedding2);
```

**Batch embeddings:**

```typescript
import { embedMany } from 'ai';
import { openai } from '@wix/ai';

const { embeddings } = await embedMany({
  model: openai.embeddingModel('text-embedding-3-small'),
  values: ['Hello', 'World', 'Foo', 'Bar'],
});
```

#### OpenAI Provider Methods

| Method | Description |
|--------|-------------|
| `openai(modelId)` | Responses API (default) |
| `openai.responses(modelId)` | Responses API (explicit) |
| `openai.chat(modelId)` | Chat Completions API |
| `openai.embeddingModel(modelId)` | Text embeddings |

### Runware Provider

#### Image Generation

```typescript
import { generateImage } from 'ai';
import { runware } from '@wix/ai';

const result = await generateImage({
  model: runware.imageModel('runware:101@1'),
  prompt: 'A serene mountain landscape at sunset',
  n: 4, // Generate 4 images in one call
});
```

#### Using image() method

```typescript
import { generateImage } from 'ai';
import { runware } from '@wix/ai';

const result = await generateImage({
  model: runware.image('FLUX.1'),
  prompt: 'A futuristic cityscape at night with neon lights',
});
```

#### Self-Hosted Apps

For apps running outside Wix, use `createRunware` with a WixClient:

```typescript
import { generateImage } from 'ai';
import { createRunware } from '@wix/ai';
import { createClient, ApiKeyStrategy } from '@wix/sdk';

const wixClient = createClient({
  auth: ApiKeyStrategy({
    siteId: 'YOUR_SITE_ID',
    apiKey: 'YOUR_API_KEY',
  }),
});

const runware = createRunware({ client: wixClient });

const result = await generateImage({
  model: runware.imageModel('runware:101@1'),
  prompt: 'A beautiful sunset over mountains',
  n: 2,
});
```

#### Runware Provider Methods

| Method | Description |
|--------|-------------|
| `runware.image(modelId)` | Image generation (shortcut method) |
| `runware.imageModel(modelId)` | Image generation model |

## License

MIT