🚀 Rax AI SDK

Official SDK for Rax AI Platform - Simple, powerful, and production-ready.

Build AI-powered applications with the Rax AI API. This SDK provides a clean, type-safe interface for chat completions, model management, usage tracking, and more.

Installation

npm install rax-ai

yarn add rax-ai

pnpm add rax-ai

Quick Start

import { RaxAI } from 'rax-ai';

const rax = new RaxAI({
  apiKey: 'your-api-key' // Get one at https://ai.raxcore.dev
});

const response = await rax.chat({
  model: 'rax-4.0',
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});

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

Features

• ✅ Simple API - Clean, intuitive methods for all operations
• ✅ Full TypeScript Support - Complete type definitions included
• ✅ Auto Retry - Smart error handling with exponential backoff
• ✅ Streaming Support - Real-time response streaming
• ✅ Models API - List and validate available models
• ✅ Usage Tracking - Monitor your API consumption
• ✅ Zero Dependencies - Uses native fetch (Node.js 18+)
• ✅ Platform Integration - Built for ai.raxcore.dev

Configuration

const rax = new RaxAI({
  apiKey: 'your-key',           // Required: Your API key
  baseURL: 'https://ai.raxcore.dev/api', // Optional: Custom base URL
  timeout: 30000                // Optional: Request timeout (default: 30s)
});

API Reference

Chat Completions

Send messages and receive AI-generated responses.

const response = await rax.chat({
  model: 'rax-4.0',           // Required: 'rax-4.0' or 'rax-4.5'
  messages: [                  // Required: Conversation messages
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing' }
  ],
  max_tokens: 1000,           // Optional: Max response length (1-4096)
  temperature: 0.7,           // Optional: Creativity (0-2)
  top_p: 0.9                  // Optional: Nucleus sampling
});

// Access the response
console.log(response.choices[0].message.content);
console.log('Tokens used:', response.usage.total_tokens);

Streaming Responses

Stream responses in real-time for better UX. Streaming shows text as it's generated instead of waiting for the complete response.

const stream = await rax.chatStream({
  model: 'rax-4.5',
  messages: [{ role: 'user', content: 'Write a short story about a robot.' }]
});

// Process chunks as they arrive
for await (const chunk of stream) {
  if (chunk.choices[0]?.delta?.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}

Streaming in Next.js API Route:

// app/api/chat/route.ts
import { RaxAI } from 'rax-ai';

const rax = new RaxAI({ apiKey: process.env.RAX_AI_API_KEY! });

export async function POST(request: Request) {
  const { message } = await request.json();
  
  const stream = await rax.chatStream({
    model: 'rax-4.0',
    messages: [{ role: 'user', content: message }]
  });
  
  const encoder = new TextEncoder();
  const readable = new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        const content = chunk.choices[0]?.delta?.content;
        if (content) {
          controller.enqueue(encoder.encode(content));
        }
      }
      controller.close();
    }
  });
  
  return new Response(readable, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' }
  });
}

Available Models

Get the list of available models.

const models = await rax.getModels();

models.data.forEach(model => {
  console.log(`${model.id}: ${model.name}`);
  console.log(`  Context: ${model.context_length} tokens`);
});

Available Models:

• rax-4.0 - Fast and efficient for general tasks
• rax-4.5 - Advanced reasoning and complex tasks

Usage Analytics

Track your API usage and costs.

// Get all-time usage
const usage = await rax.getUsage();
console.log('Total requests:', usage.total_requests);
console.log('Total tokens:', usage.total_tokens);
console.log('Estimated cost:', usage.total_cost);

// Get usage for a specific date range
const monthlyUsage = await rax.getUsage('2024-01-01', '2024-01-31');
console.log('Daily breakdown:', monthlyUsage.daily_breakdown);

API Key Validation

Check if your API key is valid.

const isValid = await rax.validateKey();
if (!isValid) {
  console.error('Invalid API key. Get one at https://ai.raxcore.dev');
}

Configuration Access

Get or update client configuration.

// Get current config
const config = rax.getConfig();
console.log('Base URL:', config.baseURL);
console.log('Timeout:', config.timeout);

// Update API key
rax.setApiKey('new-api-key');

Framework Integration

Next.js (App Router)

// app/api/chat/route.ts
import { RaxAI } from 'rax-ai';

const rax = new RaxAI({ 
  apiKey: process.env.RAX_AI_API_KEY!
});

export async function POST(request: Request) {
  const { message } = await request.json();
  
  const response = await rax.chat({
    model: 'rax-4.0',
    messages: [{ role: 'user', content: message }]
  });
  
  return Response.json(response);
}

Express.js

import express from 'express';
import { RaxAI } from 'rax-ai';

const app = express();
const rax = new RaxAI({ apiKey: process.env.RAX_AI_API_KEY! });

app.use(express.json());

app.post('/chat', async (req, res) => {
  try {
    const response = await rax.chat({
      model: 'rax-4.0',
      messages: req.body.messages
    });
    res.json(response);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

React (Client-side)

import { useState } from 'react';

// Note: Don't expose API keys in client code!
// Use a backend API route instead.

function ChatComponent() {
  const [response, setResponse] = useState('');
  
  async function sendMessage(message: string) {
    const res = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message })
    });
    const data = await res.json();
    setResponse(data.choices[0].message.content);
  }
  
  return <div>{response}</div>;
}

Error Handling

The SDK provides detailed error information and helper methods for debugging.

import { RaxAI, RaxAIError } from 'rax-ai';

const rax = new RaxAI({ apiKey: 'rax_your_api_key' });

try {
  const response = await rax.chat({
    model: 'rax-4.0',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error instanceof RaxAIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
    
    // Use helper methods to check error type
    if (error.isRateLimited()) {
      console.log('Rate limited. Retry after:', error.retryAfter, 'seconds');
    } else if (error.isAuthError()) {
      console.log('Authentication failed. Check your API key.');
    } else if (error.isServerError()) {
      console.log('Server error. Please retry.');
    }
    
    // Get full error details as JSON
    console.error('Full error:', error.toJSON());
  } else {
    console.error('Unexpected error:', error);
  }
}

RaxAIError Properties

Property	Type	Description
message	string	Human-readable error message
status	number	HTTP status code
code	string	Error code (e.g., 'rate_limit_exceeded')
retryAfter	number | undefined	Seconds to wait before retrying (rate limits)

RaxAIError Helper Methods

Method	Returns	Description
isRateLimited()	boolean	True if rate limit exceeded (429)
isAuthError()	boolean	True if authentication failed (401)
isServerError()	boolean	True if server error (500+)
toJSON()	object	Full error details as plain object

Error Types

Status	Type	Description
400	invalid_request_error	Bad request format
401	authentication_error	Invalid API key
429	rate_limit_exceeded	Too many requests
500	server_error	Internal server error

Environment Variables

# .env
RAX_AI_API_KEY=rax_xxxxxxxxxxxxxxxxxxxxx
RAX_AI_BASE_URL=https://ai.raxcore.dev/api  # Optional

TypeScript Support

Full TypeScript definitions are included:

import type { 
  RaxAIConfig,
  ChatMessage, 
  ChatRequest, 
  ChatResponse,
  Model,
  UsageStats,
  StreamChunk
} from 'rax-ai';

// Type-safe usage
const messages: ChatMessage[] = [
  { role: 'system', content: 'You are helpful.' },
  { role: 'user', content: 'Hello!' }
];

const request: ChatRequest = {
  model: 'rax-4.0',
  messages,
  temperature: 0.7
};

Retry Logic

The SDK automatically retries failed requests:

• 3 automatic retries for network/server errors
• Exponential backoff (1s, 2s, 4s delays)
• No retry for client errors (4xx)
• Timeout handling with configurable duration

Requirements

• Node.js 18.0.0 or higher (uses native fetch)
• TypeScript 5.0+ (optional, for type support)

Get Your API Key

1. Visit ai.raxcore.dev
2. Create an account or sign in
3. Navigate to Dashboard → API Keys
4. Create a new key
5. Copy and secure your key

Support

• 📖 Documentation
• 🎮 Playground
• 📊 Dashboard
• 🐛 Issues

License

MIT © Raxcore Development Team

---

Built for the Rax AI Platform at ai.raxcore.dev