@alveare/sdk

Official TypeScript SDK for the Alveare Private SLM Inference-as-a-Service platform.

Installation

npm install @alveare/sdk

Requires Node.js 18+ (uses native fetch). Zero runtime dependencies.

Quick start

import Alveare from '@alveare/sdk';

const client = new Alveare({ apiKey: 'alv_live_...' });

// Native inference
const result = await client.infer({
  specialist: 'summarise',
  prompt: 'Summarise this quarterly report...',
  maxTokens: 256,
});
console.log(result.text);

Authentication

Pass your API key directly or set the ALVEARE_API_KEY environment variable:

export ALVEARE_API_KEY=alv_live_abcdef0123456789abcdef0123456789

const client = new Alveare(); // reads from env

Production keys start with alv_live_, sandbox keys with alv_test_.

Usage

Native inference

const result = await client.infer({
  specialist: 'summarise',
  prompt: 'Summarise this quarterly report...',
  maxTokens: 256,
});

console.log(result.text);       // generated text
console.log(result.tokensUsed); // token count
console.log(result.latencyMs);  // server latency
console.log(result.cached);     // whether result was cached

Chat completions (OpenAI-compatible)

const completion = await client.chat.completions.create({
  model: 'alveare-summarise',
  messages: [{ role: 'user', content: 'Summarise this...' }],
  maxTokens: 256,
});

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

Usage stats

const usage = await client.usage();

List models

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

Health check

const health = await client.health();

Configuration

const client = new Alveare({
  apiKey: 'alv_live_...',           // or ALVEARE_API_KEY env var
  baseUrl: 'https://custom.host',   // or ALVEARE_BASE_URL env var
  maxRetries: 3,                    // automatic retries (default: 3)
  timeout: 30_000,                  // request timeout in ms (default: 30 000)
});

Error handling

import Alveare, {
  AlveareError,
  AuthenticationError,
  RateLimitError,
  APIError,
} from '@alveare/sdk';

try {
  await client.infer({ specialist: 'summarise', prompt: '...' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid or missing API key (401/403)
  } else if (err instanceof RateLimitError) {
    // Rate limited (429) — err.retryAfter may contain seconds to wait
  } else if (err instanceof APIError) {
    // Other HTTP error — err.status, err.body
  } else if (err instanceof AlveareError) {
    // Base SDK error (timeout, network, config)
  }
}

Automatic retries

The SDK retries automatically on:

• 429 Too Many Requests (respects Retry-After header)
• 408 Request Timeout
• 5xx Server errors

Retries use exponential backoff with jitter. Configure via maxRetries (default: 3).

License

MIT