npm package: @robilabs/lexa
Description: JavaScript SDK for Lexa, the AI Model by Robi Labs. Build with powerful chat, text, and multimodal APIs.
Author: Robi Labs
Latest version: 2.0.1

# Lexa TypeScript and JavaScript API Library

[![npm version](https://img.shields.io/npm/v/@robilabs/lexa.svg)](https://www.npmjs.com/package/@robilabs/lexa)
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@robilabs/lexa)](https://bundlephobia.com/package/@robilabs/lexa)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

This library provides convenient access to the Lexa REST API from TypeScript or JavaScript.

To learn how to use the Lexa API, check out the [API Reference](https://docs.lexa.chat) and [Documentation](https://docs.lexa.chat).

## Installation

```sh
npm install @robilabs/lexa
```

## Usage

```ts
import Lexa from '@robilabs/lexa';

const client = new Lexa(process.env['LEXA_API_KEY']); // This is the default and can be omitted

const completion = await client.chat({
  model: 'lexa-mml',
  messages: [{ role: 'user', content: 'Are semicolons optional in JavaScript?' }],
});

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

## Streaming responses

We provide support for streaming responses using Server Sent Events (SSE).

```ts
import Lexa from '@robilabs/lexa';

const client = new Lexa();

const completion = await client.chat({
  model: 'lexa-mml',
  messages: [{ role: 'user', content: 'Say "Sheep sleep deep" ten times fast!' }],
  stream: true,
});

for await (const chunk of completion.stream) {
  console.log(chunk);
}
```

## Models

### Listing available models

Models are fetched live from the API and cached after the first call.

```ts
const { data: models } = await client.models();
console.log(models);
// [
//   { id: 'lexa-mml', object: 'model', owned_by: 'lexa', input_token_rate: 0.002,   output_token_rate: 0.008  },
//   { id: 'lexa-x1',  object: 'model', owned_by: 'lexa', input_token_rate: 0.00012, output_token_rate: 0.0005 },
//   { id: 'lime',     object: 'model', owned_by: 'lexa', input_token_rate: 0.0004,  output_token_rate: 0.002  },
// ]
```

### Available models

| Model | Description | Input ($/1K tokens) | Output ($/1K tokens) |
|-------|-------------|--------------------:|---------------------:|
| `lexa-mml` | Multimodal model with vision capabilities | $0.002 | $0.008 |
| `lexa-x1` | Fast, lightweight text-based model | $0.00012 | $0.0005 |
| `lime` | Balanced model for general-purpose tasks | $0.0004 | $0.002 |

### Getting a single model

```ts
const model = await client.model('lexa-mml');
console.log(model?.id); // "lexa-mml"
```

### Refreshing the model cache

```ts
const { data: models } = await client.refreshModels();
```

## Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), an `APICallError` will be thrown:

```ts
import Lexa from '@robilabs/lexa';

const client = new Lexa();

const completion = await client
  .chat({
    model: 'lexa-mml',
    messages: [{ role: 'user', content: 'Hello!' }],
  })
  .catch((err) => {
    console.log(err.statusCode); // 401
    console.log(err.message);   // "Lexa API error: 401 Unauthorized"
    throw err;
  });
```

| Status Code | Description              |
| ----------- | ------------------------ |
| 401         | Invalid or missing API key |
| 429         | Rate limit exceeded (retryable) |
| >=500       | Internal server error    |
| N/A         | Network / connection error |

## Retries

Requests that fail with a `429 Rate Limit` or `>=500` status are automatically retried. The built-in `isRetryable` flag is set accordingly so upstream AI SDK tooling can handle backoff automatically.

## Advanced Usage

### Custom base URL

```ts
const client = new Lexa('your-api-key', {
  baseURL: 'https://your-custom-endpoint.com/v1',
});
```

### Custom headers

```ts
const client = new Lexa('your-api-key', {
  headers: {
    'X-Custom-Header': 'my-value',
  },
});
```

### Using with the AI SDK

`@robilabs/lexa` implements the `LanguageModelV2` interface from `@ai-sdk/provider`, so it works seamlessly with the [Vercel AI SDK](https://sdk.vercel.ai):

```ts
import { LexaProvider } from '@robilabs/lexa';
import { generateText } from 'ai';

const provider = new LexaProvider({ apiKey: 'your-api-key' });

const { text } = await generateText({
  model: provider.languageModel('lexa-mml'),
  prompt: 'Write a haiku about the ocean.',
});

console.log(text);
```

## Migration from OpenAI

If you're currently using OpenAI's SDK, migrating to Lexa is straightforward:

**Before (OpenAI):**

```ts
import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'your-key' });

const completion = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

**After (Lexa):**

```ts
import Lexa from '@robilabs/lexa';

const client = new Lexa('your-key');

const completion = await client.chat({
  model: 'lexa-mml',
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

## Getting Your API Key

1. Visit [lexa.chat](https://lexa.chat)
2. Sign up or log in to your account
3. Navigate to **Account → API Keys**
4. Generate a new API key and use it in your application

We recommend storing your key in an environment variable:

```sh
export LEXA_API_KEY="your-api-key"
```

```ts
const client = new Lexa(process.env['LEXA_API_KEY']);
```

## Semantic versioning

This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes that only affect static types, without breaking runtime behavior.
2. Changes to library internals which are technically public but not intended for external use.
3. Changes that we do not expect to impact the vast majority of users in practice.

We are keen for your feedback — please open an [issue](https://github.com/Robi-Labs/lexa-js-sdk/issues) with questions, bugs, or suggestions.

## Requirements

TypeScript >= 4.9 is supported.

The following runtimes are supported:

- Node.js 18 LTS or later
- Bun 1.0 or later
- Cloudflare Workers
- Vercel Edge Runtime
- Modern web browsers (be cautious about exposing your API key in client-side code)

## Links

- **NPM**: https://www.npmjs.com/package/@robilabs/lexa
- **GitHub**: https://github.com/Robi-Labs/lexa-js-sdk
- **Issues**: https://github.com/Robi-Labs/lexa-js-sdk/issues
- **Email**: lexa@robiai.com
- **Community**: https://community.robiai.com

## License

MIT — see [LICENSE](LICENSE) for details.

---

Made with ❤️ by [Robi Labs](https://labs.robiai.com)