@rightnow/sdk

rightnow

TypeScript / JavaScript SDK for RightNow AI — Arabic-first AI inference API.

• Chat completions (streaming + non-streaming)
• Embeddings
• Speech-to-text (Whisper)
• Text-to-speech
• Dialect detection
• Document processing (summarize, translate, extract, diacritize)

Installation

npm install @rightnow/sdk

Requires Node.js 18+ (uses native fetch).

Quick Start

import RightNow from '@rightnow/sdk';

const client = new RightNow({ apiKey: 'rn-...' });

// Chat
const response = await client.chat.completions.create({
  model: 'falcon-h1-arabic-7b',
  messages: [{ role: 'user', content: 'مرحبا' }],
});
console.log(response.choices[0].message.content);

Streaming

const stream = await client.chat.completions.create({
  model: 'falcon-h1-arabic-7b',
  messages: [{ role: 'user', content: 'اكتب قصة قصيرة' }],
  stream: true,
});

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

Embeddings

const result = await client.embeddings.create({
  model: 'bge-m3-arabic',
  input: 'مرحبا بالعالم',
});
console.log(result.data[0].embedding.length); // 1024

Audio

import fs from 'fs';

// Speech-to-text
const transcription = await client.audio.transcriptions.create({
  file: fs.readFileSync('audio.wav'),
  model: 'whisper-v3-arabic',
});
console.log(transcription.text);

// Text-to-speech
const audio = await client.audio.speech.create({
  input: 'مرحبا بك',
  model: 'chatterbox-arabic',
});
fs.writeFileSync('output.mp3', Buffer.from(audio));

Documents

// Summarize
const summary = await client.documents.summarize({ text: '...' });

// Translate
const translated = await client.documents.translate({
  text: 'مرحبا',
  target_language: 'en',
});

// Extract entities
const entities = await client.documents.extract({
  text: 'أحمد يعمل في شركة أبل في الرياض',
  entities: ['person', 'organization', 'location'],
});

// Diacritize
const diacritized = await client.documents.diacritize({ text: 'كتب' });

Dialect Detection

const result = await client.dialects.detect({
  text: 'السلام عليكم ورحمة الله',
});
console.log(result.primary_dialect); // "MSA"

Models

const models = await client.models.list();
for (const model of models.data) {
  console.log(model.id);
}

Configuration

const client = new RightNow({
  apiKey: 'rn-...',               // or set RIGHTNOW_API_KEY env var
  baseURL: 'https://...',         // optional, defaults to production
  timeout: 300_000,               // optional, 5 min default
  maxRetries: 2,                  // optional
});

Error Handling

import { RightNowError, AuthenticationError, RateLimitError } from '@rightnow/sdk';

try {
  await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.error('Rate limited, retry later');
  } else if (err instanceof RightNowError) {
    console.error(err.status, err.message);
  }
}

Available Models

Model ID	Type	Description
falcon-h1-arabic-7b	Chat	Best price/quality (default)
falcon-h1-arabic-34b	Chat	Complex reasoning
jais-2-8b	Chat	Strong dialect understanding
allam-7b	Chat	Saudi Arabic, MSA
bge-m3-arabic	Embeddings	1024-dim, 8192 context
whisper-v3-arabic	STT	Arabic speech recognition
chatterbox-arabic	TTS	Arabic text-to-speech

License

MIT