switcher-client

Client library for Switcher API - AI Model Provider Router and Proxy. This library provides a clean, LiteLLM-inspired interface for making requests to your Switcher API server.

Install

npm install switcher-client

Quick Start

import { SwitcherClient } from 'switcher-client';

// Create a client
const client = new SwitcherClient('http://localhost:3000');

// Make a chat completion request
const response = await client.chat({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Hello, how are you?' }
  ]
});

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

API Reference

Creating a Client

import { SwitcherClient, createSwitcherClient } from 'switcher-client';

// Method 1: Using constructor
const client = new SwitcherClient('http://localhost:3000', 'your-api-key');

// Method 2: Using convenience function
const client = createSwitcherClient('http://localhost:3000', 'your-api-key');

Chat Completions

Basic Chat

const response = await client.chat({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ],
  temperature: 0.7,
  max_tokens: 100
});

console.log(response.choices[0].message.content);
console.log(`Used provider: ${response.provider}`);
console.log(`Latency: ${response.latency_ms}ms`);

Streaming Chat

const stream = client.chatStream({
  model: 'claude-3-opus',
  messages: [
    { role: 'user', content: 'Write a short story about a robot.' }
  ],
  stream: true
});

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

Provider Selection

// Auto-select best provider
const response = await client.chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
  provider_strategy: 'fastest' // or 'cheapest', 'highest_quality', 'most_reliable'
});

// Force specific provider
const response = await client.chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }],
  provider: 'openai',
  fallback: false
});

Image Generation

const response = await client.generateImage({
  model: 'dall-e-3',
  prompt: 'A beautiful sunset over mountains',
  n: 1,
  size: '1024x1024',
  quality: 'hd',
  style: 'vivid'
});

console.log(response.data[0].url);
console.log(`Used provider: ${response.provider}`);

Model Management

// List available chat models
const chatModels = await client.listChatModels();
console.log(chatModels.data.map(m => m.id));

// List available image models
const imageModels = await client.listImageModels();
console.log(imageModels.data.map(m => m.id));

// Get specific model info
const modelInfo = await client.getModel('gpt-4');
console.log(modelInfo);

Health Monitoring

// Check overall health
const health = await client.health();
console.log(`Status: ${health.status}`);

// Check provider health
const providerHealth = await client.providerHealth();
providerHealth.providers.forEach(p => {
  console.log(`${p.name}: ${p.status} (${p.latency_ms}ms)`);
});

// Check specific provider
const openaiHealth = await client.getProviderHealth('openai');
console.log(openaiHealth);

Request Schema

ChatCompletionRequest

interface ChatCompletionRequest {
  model: string;                    // Required: Model name
  messages: ChatMessage[];          // Required: Array of messages
  temperature?: number;             // Optional: 0-2, default 1
  top_p?: number;                   // Optional: 0-1, default 1
  n?: number;                       // Optional: Number of completions, default 1
  max_tokens?: number;              // Optional: Maximum tokens
  stop?: string | string[];         // Optional: Stop sequences
  presence_penalty?: number;        // Optional: -2 to 2, default 0
  frequency_penalty?: number;       // Optional: -2 to 2, default 0
  logit_bias?: Record<string, number>; // Optional: Token bias
  user?: string;                    // Optional: User identifier
  stream?: boolean;                 // Optional: Enable streaming, default false
  tools?: Tool[];                   // Optional: Function calling tools
  tool_choice?: ToolChoice;         // Optional: Tool selection
  response_format?: ResponseFormat; // Optional: Response format
  seed?: number;                    // Optional: Random seed
  provider?: string;                // Optional: Force specific provider
  fallback?: boolean;               // Optional: Allow fallback, default true
  provider_strategy?: ProviderStrategy; // Optional: Provider selection strategy
}

ImageGenerationRequest

interface ImageGenerationRequest {
  model: string;                    // Required: Model name
  prompt: string;                   // Required: Image description
  n?: number;                       // Optional: Number of images, default 1
  size?: ImageSize;                 // Optional: Image size
  quality?: 'standard' | 'hd';      // Optional: Image quality
  response_format?: 'url' | 'b64_json'; // Optional: Response format
  style?: 'vivid' | 'natural';      // Optional: Image style
  user?: string;                    // Optional: User identifier
  provider?: string;                // Optional: Force specific provider
  fallback?: boolean;               // Optional: Allow fallback, default true
  provider_strategy?: ProviderStrategy; // Optional: Provider selection strategy
}

Provider Strategies

• auto (default): Use intelligent routing based on performance metrics
• fastest: Select provider with lowest latency
• cheapest: Select provider with lowest cost
• highest_quality: Select provider with best quality rankings
• most_reliable: Select provider with highest uptime
• specific: Use a specific provider (requires provider parameter)

Error Handling

The client automatically handles API errors and throws descriptive error messages:

try {
  const response = await client.chat({
    model: 'invalid-model',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
} catch (error) {
  console.error(error.message); // "model_not_found: Model 'invalid-model' not found"
}

Examples

Complete Example

import { SwitcherClient } from 'switcher-client';

async function main() {
  const client = new SwitcherClient('http://localhost:3000');

  try {
    // Check health
    const health = await client.health();
    console.log('API Status:', health.status);

    // Generate text
    const chatResponse = await client.chat({
      model: 'gpt-4',
      messages: [
        { role: 'user', content: 'Explain quantum computing in simple terms' }
      ],
      provider_strategy: 'highest_quality'
    });

    console.log('Response:', chatResponse.choices[0].message.content);
    console.log('Provider used:', chatResponse.provider);

    // Generate image
    const imageResponse = await client.generateImage({
      model: 'dall-e-3',
      prompt: 'A futuristic city with flying cars',
      size: '1024x1024'
    });

    console.log('Image URL:', imageResponse.data[0].url);

  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

License

MIT