@perf_technology/sdk

Official JavaScript/TypeScript SDK for Perf - the AI Runtime Orchestrator.

Perf automatically picks the best AI model for your prompt based on:

• Task type and complexity
• Cost constraints
• Output reliability
• Fallback logic

Installation

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

Quick Start

import { PerfClient } from '@perf_technology/sdk';

const client = new PerfClient({
  apiKey: 'pk_live_your_api_key',
});

// Simple chat completion
const response = await client.chat({
  messages: [
    { role: 'user', content: 'What is the capital of France?' }
  ],
});

console.log(response.choices[0].message.content);
// Output: "The capital of France is Paris."

// Access Perf metadata
console.log(response.perf);
// { model_used: 'gpt-4o-mini', cost_usd: 0.0001, latency_ms: 234, ... }

Streaming

// Stream responses
for await (const chunk of client.chatStream({
  messages: [{ role: 'user', content: 'Write a haiku about coding' }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

// Or collect into a string
const content = await client.chatStreamToString({
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
});

Error Handling

import {
  PerfClient,
  PerfError,
  RateLimitError,
  AuthenticationError
} from '@perf_technology/sdk';

try {
  const response = await client.chat({
    messages: [{ role: 'user', content: 'Hello!' }],
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    const retryAfter = error.retryAfter || 60;
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof PerfError) {
    console.error(`API Error: ${error.code} - ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Configuration Options

const client = new PerfClient({
  apiKey: 'pk_live_your_api_key',     // Required
  baseUrl: 'https://api.withperf.pro', // Optional, default shown
  timeout: 120000,                      // Request timeout in ms (default: 2 min)
  maxRetries: 3,                        // Retry attempts (default: 3)
  retryDelay: 1000,                     // Base retry delay in ms (default: 1s)
});

Request Options

const response = await client.chat({
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
  model: 'gpt-4o',           // Optional: override model selection
  max_tokens: 1000,          // Optional: limit response length
  temperature: 0.7,          // Optional: sampling temperature
  max_cost_per_call: 0.01,   // Optional: cost budget in USD
  metadata: {                // Optional: custom metadata
    user_id: '123',
    session_id: 'abc',
  },
});

TypeScript Types

All types are exported for your convenience:

import type {
  Message,
  ChatRequest,
  ChatResponse,
  ChatStreamChunk,
  PerfMetadata,
  PerfClientConfig,
} from '@perf_technology/sdk';

Features

• Full TypeScript support with comprehensive type definitions
• Streaming support with AsyncGenerator API
• Automatic retries with exponential backoff
• Error classes for different error types
• Timeout handling with configurable limits
• Dual ESM/CommonJS builds

Requirements

• Node.js 18 or higher
• Browser environments with Fetch API support

Links

• Documentation
• Dashboard
• Status
• Support

License

MIT