@relayplane/sdk
Version:
RelayPlane SDK with zero-config AI access, intelligent model selection, built-in examples, and contextual error handling. The easiest way to add AI to your app with automatic optimization and fallback.
689 lines (559 loc) • 19.8 kB
Markdown
# @relayplane/sdk v0.2
[](https://www.npmjs.com/package/@relayplane/sdk)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
> 🪄 **Zero-config AI for developers** - The easiest way to add intelligent AI to your applications
RelayPlane SDK provides seamless AI integration with automatic optimization, intelligent model selection, and built-in examples. No configuration required - just ask!
## 📚 **[Complete Documentation →](https://relayplane.com/docs/sdk)**
## ✨ Zero-Config Wins (New in v0.2)
### 🪄 Zero-Config Quick Start
```javascript
import RelayPlane from '@relayplane/sdk';
// Magic! Just ask - auto-detects your API keys and picks the best model
const result = await RelayPlane.ask("Explain quantum computing simply");
console.log(result.response);
console.log(result.reasoning.rationale); // See why this model was chosen
```
**What makes this magical:**
- Auto-detects your available API keys
- Intelligently selects the best model for your task
- Provides reasoning for every decision
- Falls back gracefully if providers are unavailable
- Works instantly without any setup
### 🎯 Smart Model Selection with Reasoning
```javascript
// Get intelligent model selection with full reasoning
const result = await RelayPlane.ask("Complex financial analysis task", {
budget: 'moderate', // 'minimal', 'moderate', 'unlimited'
priority: 'quality', // 'speed', 'balanced', 'quality'
taskType: 'analysis' // 'coding', 'creative', 'analysis', 'general'
});
console.log(result.reasoning.rationale);
// "Selected Claude-3-sonnet over GPT-4 because:
// - 40% faster for financial analysis tasks
// - $0.02 vs $0.08 estimated cost
// - 94% success rate for this task type"
```
### 📚 Built-in Examples Library
Ready-to-use patterns for instant productivity:
```javascript
// Summarization with intelligent length control
const summary = await RelayPlane.examples.summarize(longText, {
length: 'brief'
});
// Translation with context awareness
const translation = await RelayPlane.examples.translate('Hello world', 'Spanish');
// Code review with focus areas
const review = await RelayPlane.examples.codeReview(myCode, {
focus: 'security'
});
// Research workflow
const research = await RelayPlane.examples.research('quantum computing applications');
// Chatbot with personality
const chat = await RelayPlane.examples.chatbot('How are you?', {
personality: 'helpful and friendly assistant',
context: previousMessages
});
```
### ⚡ Smart Retry with Automatic Model Switching
```javascript
// Automatic retry with intelligent model switching
const result = await RelayPlane.smartRetry({
to: 'claude-3-7-sonnet-20250219',
payload: { messages: [{ role: 'user', content: 'Complex task' }] }
}, {
maxRetries: 3,
confidenceThreshold: 0.9, // Retry until 90% confident
retryOnFailureTypes: ['rate_limit', 'timeout', 'model_error']
});
console.log(result.retryInfo.modelAttempts); // See all attempts and reasoning
```
### 🌊 Optimized Streaming
```javascript
// Enhanced streaming with intelligent chunking
for await (const { chunk, metadata } of RelayPlane.optimizeStreaming(response, 'claude-3-7-sonnet-20250219')) {
console.log(chunk); // Optimally sized chunks for natural reading
console.log(metadata.isTyping); // Typing indicators
console.log(metadata.estimatedCost); // Real-time cost tracking
console.log(metadata.estimatedProgress); // Progress estimation
}
// React integration (if using React)
const { content, metadata, isStreaming, startStreaming } = RelayPlane.useOptimizedStreaming();
```
### 🔧 Contextual Error Recovery
```javascript
try {
const result = await RelayPlane.ask("Test prompt");
} catch (error) {
if (error instanceof RelayPlane.RelayApiKeyError) {
console.log(error.getHelpfulMessage());
// Shows exact steps to fix API key issues with copy-paste commands
}
if (error instanceof RelayPlane.RelayRateLimitError) {
console.log(error.suggestions);
// ["Use RelayPlane.configure({ optimization: true }) for automatic fallbacks",
// "Try again in 60 seconds",
// "Consider adding additional provider API keys for better redundancy"]
}
}
```
## 🚀 Instant Demo Experience
Want to see all these features in action? Try our interactive demos:
```bash
# Interactive guided demo (5 minutes)
npm run demo
# Quick start example (2 minutes)
npm run quick-start
# Experience the magic in 30 seconds
npx @relayplane/cli demo
```
**Interactive Demo Features:**
- 🪄 Zero-Config AI magic with real-time model selection
- 📚 Built-in examples library walkthrough
- 🔧 Smart error handling demonstrations
- 🚀 Advanced features showcase
- 💡 Contextual help and next steps
**Quick Start Features:**
- ✨ Copy-paste examples that work immediately
- 🧠 Model selection reasoning display
- 📝 Built-in examples (summarize, translate)
- 🛡️ Error handling patterns
## 📦 Installation
```bash
npm install @relayplane/sdk
```
## ⚙️ Configuration (Optional!)
RelayPlane works without configuration, but you can customize it with advanced optimization settings:
```javascript
// Basic configuration
RelayPlane.configure({
debug: true,
defaultOptimization: {
enabled: true,
strategy: 'balanced'
}
});
// Advanced global optimization settings
RelayPlane.configure({
debug: true,
defaultOptimization: {
enabled: true,
strategy: 'balanced',
// Cache strategy configuration
cacheStrategy: {
type: 'hybrid', // 'memory', 'disk', 'hybrid', 'none'
maxSize: 200, // Cache size in MB
evictionPolicy: 'lru', // 'lru', 'lfu', 'ttl'
compression: true, // Enable compression for disk cache
encryption: true // Enable encryption for sensitive data
},
// Batch processing settings
batchProcessing: {
enabled: true,
defaultConcurrency: 8, // Concurrent requests in batches
maxBatchSize: 25, // Maximum requests per batch
autoGrouping: true, // Automatically group similar requests
timeoutMs: 45000 // Batch timeout
},
// Parallel execution configuration
parallelExecution: {
enabled: true,
maxConcurrentRequests: 15, // Global concurrency limit
requestPooling: true, // Pool connections for efficiency
loadBalancing: 'least_latency' // 'round_robin', 'least_latency', 'least_cost'
},
// Comprehensive timeout settings
timeoutSettings: {
requestTimeoutMs: 25000, // Individual request timeout
connectionTimeoutMs: 4000, // Connection establishment timeout
readTimeoutMs: 20000, // Response reading timeout
totalTimeoutMs: 50000, // Total operation timeout
retryTimeoutMs: 10000 // Retry attempt timeout
},
// Rate limiting strategy
rateLimitingStrategy: {
strategy: 'graceful_backoff', // 'aggressive_retry', 'graceful_backoff', 'fail_fast', 'provider_switching'
backoffMultiplier: 2.0, // Exponential backoff multiplier
maxBackoffMs: 25000, // Maximum backoff time
jitterEnabled: true, // Add randomization to backoff
respectProviderLimits: true, // Honor provider rate limits
globalRateLimit: {
requestsPerMinute: 200, // Global requests per minute
requestsPerSecond: 8 // Global requests per second
}
}
}
});
// Use it anywhere with optimized performance
const result = await RelayPlane.ask("What's the weather like today?");
console.log(result.response.body);
```
## 🚀 Quick Start
### 1. Install the SDK
```bash
npm install @relayplane/sdk
```
### 2. Set up your API keys
```bash
# Set your provider API keys (choose what you need)
export OPENAI_API_KEY=sk-... # For GPT models
export ANTHROPIC_API_KEY=sk-ant-... # For Claude models
export GOOGLE_API_KEY=... # For Gemini models
```
### 3. Start using AI
```javascript
import RelayPlane from '@relayplane/sdk';
// Configure your SDK
RelayPlane.configure({
debug: true,
defaultOptimization: {
enabled: true,
strategy: 'balanced'
}
});
// Use it anywhere
const result = await RelayPlane.ask("What's the weather like today?");
console.log(result.response.body);
```
## 🔗 Advanced Usage
### Multi-Agent Chaining
```javascript
// Create intelligent workflows
const result = await RelayPlane.chain({
steps: [
{ step: 'research', to: 'claude-3-7-sonnet-20250219', prompt: 'Research topic' },
{ step: 'analyze', to: 'gpt-4-turbo', prompt: 'Analyze findings' },
{ step: 'summarize', to: 'claude-haiku', prompt: 'Create summary' }
],
input: 'Analyze the impact of AI on healthcare',
optimization: true
});
```
### Batch Processing
```javascript
// Process multiple requests efficiently
const results = await RelayPlane.batch({
requests: [
{ to: 'claude-3-7-sonnet-20250219', payload: { messages: [...] } },
{ to: 'gpt-4-turbo', payload: { messages: [...] } }
],
parallel: true,
optimization: { enabled: true }
});
```
### Manual Relay (Advanced Users)
```javascript
// Full control when needed
const response = await RelayPlane.relay({
to: 'claude-3-7-sonnet-20250219',
payload: {
messages: [
{ role: 'user', content: 'Hello, Claude!' }
],
max_tokens: 1000,
temperature: 0.7
},
optimization: {
enabled: true,
fallback: ['gpt-4-turbo', 'claude-haiku']
}
});
```
## 🎯 Why RelayPlane v0.2?
### Before RelayPlane
```javascript
// Complex setup required
import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
// Manual model selection and error handling
let response;
try {
response = await openai.chat.completions.create({
model: 'gpt-4', // Hard-coded model choice
messages: [{ role: 'user', content: 'Hello' }]
});
} catch (error) {
if (error.status === 429) {
// Manual fallback logic
response = await anthropic.messages.create({
model: 'claude-3-sonnet-20240229',
messages: [{ role: 'user', content: 'Hello' }]
});
}
}
```
### With RelayPlane v0.2
```javascript
// Zero config, intelligent optimization
import RelayPlane from '@relayplane/sdk';
// Configure your SDK
RelayPlane.configure({
debug: true,
defaultOptimization: {
enabled: true,
strategy: 'balanced'
}
});
// Use it anywhere
const result = await RelayPlane.ask("What's the weather like today?");
console.log(result.response.body);
```
### Key Differentiators
✅ **Zero Configuration** - Works instantly without setup
✅ **Intelligent Model Selection** - AI chooses the best model for your task
✅ **Built-in Examples** - Ready-to-use patterns for common tasks
✅ **Smart Retry Logic** - Automatic fallback with reasoning
✅ **Contextual Error Messages** - Helpful recovery suggestions
✅ **Real-time Cost Tracking** - Know your spend as you go
✅ **Optimized Streaming** - Perfect chunk sizes and timing
✅ **Bring Your Own Keys (BYOK)** - Full control over your API keys
## 📚 Supported Models
| Provider | Model Identifiers |
|----------|------------------|
| **Anthropic** | `claude-3-7-sonnet-20250219`, `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`, `claude-3-opus-20240229`, `claude-3-sonnet-20240229`, `claude-3-haiku-20240307` |
| **OpenAI** | `gpt-4.1`, `gpt-4.1-mini`, `o3`, `o3-pro`, `o3-mini`, `o4-mini`, `gpt-4o`, `gpt-4o-mini`, `o1-preview`, `o1-mini`, `gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo` |
| **Google** | `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-pro`, `gemini-pro-vision` |
## ⚙️ Configuration & Timeouts
### Default Settings
The SDK uses realistic defaults optimized for production use:
- **Timeout**: 60 seconds (accommodates model processing time)
- **Retries**: 3 attempts with intelligent fallback
- **Base URL**: `https://api.relayplane.com`
### Performance Expectations
Typical response times by complexity:
- **Simple queries**: 5-15 seconds
- **Complex analysis**: 15-30 seconds
- **Large documents**: 30-60 seconds
### Custom Configuration
```javascript
import RelayPlane from '@relayplane/sdk';
// Configure for your environment
RelayPlane.configure({
timeout: 90000, // 90s for slow machines
debug: true, // Enable detailed logging
baseUrl: 'https://api.relayplane.com',
defaultOptimization: {
enabled: true,
strategy: 'balanced'
}
});
// Per-request timeout override
const result = await RelayPlane.ask("Complex analysis task", {
timeout: 120000 // 2 minutes for this specific request
});
```
### Slow Machine Optimization
If you're experiencing timeouts:
```javascript
// Increase timeout for slow machines
RelayPlane.configure({
timeout: 120000, // 2 minutes
debug: true // See detailed timing info
});
// Or per-request
const result = await RelayPlane.relay({
to: 'claude-3-7-sonnet-20250219',
payload: { messages: [...] },
timeout: 120000
});
```
## 🔧 Troubleshooting
### Common Issues and Solutions
#### **"Model not available" Errors**
**Problem:** Getting errors like `Model "claude-opus-4-20250514" is not available`
**Solution:**
```javascript
// ✅ Use confirmed working models
const result = await RelayPlane.ask("Your question", {
model: 'claude-3-7-sonnet-20250219' // Working model
});
// ❌ Avoid non-existent models
// model: 'claude-opus-4-20250514' // This doesn't exist
```
#### **Timeout Issues on Slow Machines**
**Problem:** Requests timing out with "Request timeout" errors
**Symptoms:**
- Timeouts after 15-30 seconds
- Slow computer performance
- Network connectivity issues
**Solutions:**
```javascript
// Option 1: Increase global timeout
RelayPlane.configure({
timeout: 120000, // 2 minutes for slow machines
debug: true // See detailed timing info
});
// Option 2: Per-request timeout
const result = await RelayPlane.ask("Complex analysis", {
timeout: 180000 // 3 minutes for complex tasks
});
// Option 3: Use faster models for testing
const result = await RelayPlane.ask("Quick test", {
model: 'claude-3-5-haiku-20241022', // Faster model
timeout: 30000
});
```
#### **Response Format Issues**
**Problem:** Receiving malformed or unexpected response formats
**Solution:**
```javascript
// Enable debug mode to see raw responses
RelayPlane.configure({
debug: true
});
// Handle different response formats
const result = await RelayPlane.ask("Generate JSON", {
responseFormat: 'json'
});
// Validate response structure
if (result && result.response) {
console.log('Response received:', result.response);
} else {
console.error('Unexpected response format:', result);
}
```
#### **Performance Optimization**
**Problem:** Slow response times even with working models
**Solutions:**
```javascript
// 1. Use appropriate model for task complexity
const simpleResult = await RelayPlane.ask("Simple question", {
model: 'claude-3-5-haiku-20241022' // Fast for simple tasks
});
const complexResult = await RelayPlane.ask("Complex analysis", {
model: 'claude-3-7-sonnet-20250219' // Better for complex tasks
});
// 2. Reduce max tokens for faster responses
const result = await RelayPlane.ask("Brief summary", {
maxTokens: 500 // Limit response length
});
// 3. Use streaming for long responses
const result = await RelayPlane.ask("Long analysis", {
stream: true
});
```
#### **Development Environment Issues**
**Problem:** SDK works in production but fails in development
**Solutions:**
```javascript
// Check environment variables
if (!process.env.RELAY_API_KEY) {
console.error('Missing RELAY_API_KEY environment variable');
}
// Use local development settings
if (process.env.NODE_ENV === 'development') {
RelayPlane.configure({
timeout: 180000, // Longer timeout for dev
debug: true, // Enable detailed logging
baseUrl: 'http://localhost:3001' // Local server
});
}
```
#### **Error Handling Best Practices**
```javascript
try {
const result = await RelayPlane.ask("Your question", {
timeout: 60000,
maxRetries: 3 // Automatic retry on failure
});
console.log('Success:', result.response);
} catch (error) {
if (error.name === 'RelayTimeoutError') {
console.error('Request timed out. Try increasing timeout or using a faster model.');
} else if (error.name === 'RelayModelError') {
console.error('Model not available. Check model name:', error.message);
} else if (error.name === 'RelayNetworkError') {
console.error('Network issue. Check connectivity:', error.message);
} else {
console.error('Unexpected error:', error);
}
}
```
### **Environment-Specific Optimizations**
#### **Slow Machines (< 8GB RAM)**
```javascript
RelayPlane.configure({
timeout: 300000, // 5 minutes
debug: true,
defaultOptimization: {
enabled: false // Disable optimization overhead
}
});
```
#### **Limited Bandwidth**
```javascript
// Use smaller models and shorter responses
const result = await RelayPlane.ask("Brief answer please", {
model: 'claude-3-5-haiku-20241022',
maxTokens: 200
});
```
#### **Development/Testing**
```javascript
// Faster feedback loop
RelayPlane.configure({
timeout: 30000,
debug: true
});
// Use mock responses for faster development
if (process.env.NODE_ENV === 'test') {
// Use mock data
}
```
### **Getting Help**
1. **Enable Debug Mode:**
```javascript
RelayPlane.configure({ debug: true });
```
2. **Check Server Logs:**
- Look for detailed timing information
- Check for model availability messages
- Monitor response format issues
3. **Test with Simple Queries:**
```javascript
const test = await RelayPlane.ask("Hello");
console.log('Basic test:', test);
```
4. **Verify Environment:**
```javascript
console.log('API Key present:', !!process.env.RELAY_API_KEY);
console.log('Base URL:', process.env.RELAY_BASE_URL);
```
## 🎮 Interactive Examples
Run these examples locally to experience the SDK:
```bash
# Interactive guided demo
npm run demo
# Quick 2-minute start
npm run quick-start
# Provider-specific examples
npm run examples:gpt # OpenAI integration
npm run examples:claude # Anthropic integration
npm run examples:optimize # Advanced optimization
npm run examples:chain # Multi-agent workflows
npm run examples:global-optimization # Global optimization settings
```
## 🔗 Links
- [📖 Full Documentation](https://relayplane.com/docs)
- [🎮 Interactive Playground](https://relayplane.com/playground)
- [🧪 Try the CLI Demo](https://www.npmjs.com/package/@relayplane/cli)
- [💬 GitHub Discussions](https://github.com/matthewturley/a2ar-relay/discussions)
- [🐙 GitHub Repository](https://github.com/relayplane/sdk)
## 🆘 Support
### Quick Help
```bash
# Test your setup instantly
npx @relayplane/cli test
# See error recovery demos
npx @relayplane/cli demo
# Select: "🔧 Error Recovery"
```
### Get Help
- [Documentation](https://relayplane.com/docs)
- [Troubleshooting Guide](https://relayplane.com/docs/troubleshooting)
- [GitHub Discussions](https://github.com/matthewturley/a2ar-relay/discussions)
- [GitHub Issues](https://github.com/relayplane/sdk/issues)
---
**Start with zero config:** `npm install @relayplane/sdk` 🪄