@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

``bash
npm install @perf_technology/sdk


or

yarn add @perf_technology/sdk

or

pnpm add @perf_technology/sdk
`

Quick Start

`typescript
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

`typescript
// 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

`typescript
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

`typescript
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

`typescript
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:

`typescript
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