npm package: @mantey/saia-ai-sdk
Description: Vercel AI SDK provider for GWDG's SAIA (Scalable Artificial Intelligence Accelerator) API
Author: Daniel Mantey
Latest version: 0.1.0

# @mantey/saia-ai-sdk

Vercel AI SDK provider for GWDG's SAIA (Scalable Artificial Intelligence Accelerator) API. This package provides an OpenAI-compatible interface for the SAIA API, allowing seamless integration with the Vercel AI SDK.

## Installation

```bash
npm install @mantey/saia-ai-sdk
```

```bash
pnpm add @mantey/saia-ai-sdk
```

```bash
yarn add @mantey/saia-ai-sdk
```

## Setup

### 1. Get your SAIA API Key

To use SAIA, you need access to the GWDG SAIA service:

1. Visit the [GWDG SAIA Documentation](https://docs.hpc.gwdg.de/services/saia/index.html#api-request)
2. Request access to the SAIA service if you're affiliated with a GWDG member institution
3. Obtain your API key

### 2. Install Dependencies

This package requires the Vercel AI SDK:

```bash
npm install ai @mantey/saia-ai-sdk
```

**Note:**
- `ai` - The Vercel AI SDK (required for using any of vercel's core AI SDK)
- `@ai-sdk/openai-compatible`, `@ai-sdk/provider`, and `@ai-sdk/provider-utils` are regular dependencies and will be installed automatically

## Usage

### Basic Setup

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';
import { generateText } from 'ai';

const saia = createSaia({
  apiKey: process.env.SAIA_API_KEY,
});

const { text } = await generateText({
  model: saia('meta-llama-3.1-8b-instruct'),
  prompt: 'Explain quantum computing in simple terms',
});

console.log(text);
```

### Using the Default Instance

```typescript
import { saia } from '@mantey/saia-ai-sdk';
import { generateText } from 'ai';

// Uses SAIA_API_KEY environment variable
const { text } = await generateText({
  model: saia('meta-llama-3.1-8b-instruct'),
  prompt: 'Write a haiku about TypeScript',
});
```

### Streaming Responses

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';
import { streamText } from 'ai';

const saia = createSaia({
  apiKey: process.env.SAIA_API_KEY,
});

const { textStream } = await streamText({
  model: saia('meta-llama-3.1-8b-instruct'),
  prompt: 'Count from 1 to 10',
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}
```

### Chat Completions

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';
import { generateText } from 'ai';

const saia = createSaia({
  apiKey: process.env.SAIA_API_KEY,
});

const { text } = await generateText({
  model: saia('meta-llama-3.1-8b-instruct'),
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' },
  ],
});
```

### Vision Models (Image Understanding)

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';
import { generateText } from 'ai';
import fs from 'fs';

const saia = createSaia({
  apiKey: process.env.SAIA_API_KEY,
});

// Read image and convert to base64
const imageBuffer = fs.readFileSync('./path/to/image.jpg');
const base64Image = imageBuffer.toString('base64');

const { text } = await generateText({
  model: saia('gemma-3-27b-it'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What is in this image?' },
        {
          type: 'image',
          image: `data:image/jpeg;base64,${base64Image}`
        },
      ],
    },
  ],
});

console.log(text);
```

**Note:** SAIA requires images to be uploaded as base64-encoded data or file uploads. Fetching images from URLs is not supported.

### Embeddings

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';
import { embed } from 'ai';

const saia = createSaia({
  apiKey: process.env.SAIA_API_KEY,
});

const { embedding } = await embed({
  model: saia.textEmbeddingModel('multilingual-e5-large-instruct'),
  value: 'Hello, world!',
});

console.log(embedding);
```

## Configuration

### Provider Options

```typescript
import { createSaia } from '@mantey/saia-ai-sdk';

const saia = createSaia({
  // Your SAIA API key (can also use SAIA_API_KEY environment variable)
  apiKey: 'your-api-key',

  // Custom base URL (optional)
  baseURL: 'https://chat-ai.academiccloud.de/v1',

  // Custom headers (optional)
  headers: {
    'X-Custom-Header': 'value',
  },

  // Custom fetch implementation (optional)
  fetch: customFetch,
});
```

## Available Models (From SAIA Documentation)

### Chat Models

General purpose text generation models:

- `meta-llama-3.1-8b-instruct`
- `llama-3.3-70b-instruct`
- `openai-gpt-oss-120b`
- `mistral-large-instruct`
- `teuken-7b-instruct-research`

**Code Generation:**
- `qwen2.5-coder-32b-instruct`
- `codestral-22b`

**Reasoning Models:**
- `deepseek-r1`
- `qwen3-235b-a22b`
- `qwq-32b`
- `qwen3-32b`

**RAG-Enabled Models:**
- `meta-llama-3.1-8b-rag`
- `llama-3.1-sauerkrautlm-70b-instruct`

### Vision Models (Multimodal)

Models that can analyze images and videos:

- `gemma-3-27b-it`
- `qwen2.5-vl-72b-instruct`
- `medgemma-27b-it` - Medical image analysis (Text + Image)
- `internvl2.5-8b`
- `qwen2.5-omni-7b`

**Note:** Images must be uploaded as part of requests (base64 or file upload). Fetching images from URLs is not supported.

### Embedding Models

Text embedding models for semantic search and similarity:

- `e5-mistral-7b-instruct`
- `multilingual-e5-large-instruct` - Multilingual support
- `qwen3-embedding-4b`

## Environment Variables

You can set your SAIA API key via environment variable:

```bash
export SAIA_API_KEY=your-api-key
```

Or use a `.env` file:

```env
SAIA_API_KEY=your-api-key
```

## TypeScript Support

This package is written in TypeScript and provides full type definitions. All model IDs, settings, and options are properly typed.

```typescript
import type {
  SAIAChatModelId,
  SAIAEmbeddingModelId,
  SAIAProviderOptions
} from '@mantey/saia-ai-sdk';

const modelId: SAIAChatModelId = 'meta-llama-3.1-8b-instruct';
```

## API Reference

### `createSaia(options?)`

Creates a new SAIA provider instance.

**Parameters:**
- `options` (optional): Provider configuration options
  - `apiKey`: Your SAIA API key
  - `baseURL`: Custom base URL (default: `https://chat-ai.academiccloud.de/v1`)
  - `headers`: Custom headers to include in requests
  - `fetch`: Custom fetch implementation

**Returns:** SAIA provider instance compatible with Vercel AI SDK

### `saia`

Default SAIA provider instance that uses the `SAIA_API_KEY` environment variable.

## Examples

Check out the [examples directory](./examples) for more usage examples.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT

## Links

- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
- [GWDG SAIA Documentation](https://docs.hpc.gwdg.de/index.html)
- [GitHub Repository](https://github.com/mantey-github/saia-ai-sdk)

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/mantey-github/saia-ai-sdk/issues)
- Check the [Vercel AI SDK documentation](https://sdk.vercel.ai/docs)