@polyswitch/sdk

1-line drop-in replacement for the OpenAI SDK — route all your AI traffic through Polyswitch Enterprise AI Gateway with zero code changes.

Installation

npm install @polyswitch/sdk
# or
pnpm add @polyswitch/sdk
# or
yarn add @polyswitch/sdk

Quick Start

Replace your existing openai import with @polyswitch/sdk — everything else stays exactly the same:

// Before
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// After — 1-line change
import Polyswitch from '@polyswitch/sdk';
const client = new Polyswitch({ polyswitchKey: process.env.POLYSWITCH_API_KEY });

Or use the aliased import for a truly zero-change migration:

import { OpenAI } from '@polyswitch/sdk';
const client = new OpenAI(); // reads POLYSWITCH_API_KEY from env automatically

Environment Variables

| Variable | Description | Default | | ------------------------ | ------------------------ | ------------------------------ | | POLYSWITCH_API_KEY | Your Polyswitch API key | pr_guest (demo mode) | | POLYSWITCH_GATEWAY_URL | Gateway endpoint | http://localhost:3000/api/v1 | | OPENAI_API_KEY | Fallback — also accepted | — | | OPENAI_BASE_URL | Fallback — also accepted | — |

Routing Strategies

Control how Polyswitch routes your requests across AI providers:

import Polyswitch, { Strategies } from '@polyswitch/sdk';

const client = new Polyswitch({
  strategy: Strategies.autoSmart() // Auto-pick best model (default)
  // strategy: Strategies.costOptimized(1.0), // Stay under $1/M tokens
  // strategy: Strategies.hedgedLatency({ thresholdMs: 500, fallbackModel: 'gpt-4o-mini' }),
  // strategy: Strategies.kvAffinity('user-session-123'), // Sticky routing for KV cache
});

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

PII Redaction

Automatically strip PII from all requests before they leave your network:

const client = new Polyswitch({
  piiRedact: true
});

Compression

Token compression is enabled by default. Disable explicitly if needed:

const client = new Polyswitch({
  compression: false
});

Extra APIs

The SDK exposes additional Polyswitch-native APIs beyond standard OpenAI:

Agents

const result = await client.agents.run({
  persona: { name: 'Aria', role: 'analyst', systemPrompt: 'You are a data analyst.' },
  taskGoal: 'Summarize Q4 revenue trends',
  tools: [{ name: 'fetch_data', description: 'Fetch financial data' }],
  limits: { maxToolCalls: 5, maxBudgetUsd: 0.1 }
});

OCR

const result = await client.ocr.extract({
  file: fileBlob,
  model: 'mistral/mistral-ocr'
});

Rerank

const result = await client.rerank.create({
  query: 'What is the capital of France?',
  documents: ['Paris is in France.', 'London is in England.'],
  topN: 1
});

Search

const result = await client.search.query({
  query: 'latest AI research papers',
  maxResults: 5
});

Quota

const quota = await client.quota.get();

Telemetry Hooks

React to token savings and fallback events:

const client = new Polyswitch({
  telemetry: {
    onTokensSaved: ({ savedTokens, ratio }) => {
      console.log(`Saved ${savedTokens} tokens (${(ratio * 100).toFixed(1)}% reduction)`);
    },
    onFallbackTriggered: ({ primaryModel, fallbackModel, latencyMs }) => {
      console.log(`Fell back from ${primaryModel} → ${fallbackModel} after ${latencyMs}ms`);
    }
  }
});

TypeScript

Full type support included. The SDK ships .d.ts declarations and works with both CommonJS and ESM:

// ESM
import Polyswitch, { Strategies, PolyswitchOptions } from '@polyswitch/sdk';

// CommonJS
const { Polyswitch } = require('@polyswitch/sdk');

License

MIT © Polyswitch