@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.
316 lines (252 loc) • 10.1 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-sonnet-4-20250514',
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-sonnet-4-20250514')) {
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",
// "Switch to hosted mode for better rate limiting",
// "Try again in 60 seconds"]
}
}
```
## 🚀 Instant Demo Experience
Want to see all these features in action? Try our interactive CLI:
```bash
# Experience the magic in 30 seconds
npx @relayplane/cli demo
```
This provides a beautiful terminal experience showcasing:
- Zero-Config Wins
- Smart model selection reasoning
- Built-in examples in action
- Performance comparisons
- Error recovery demonstrations
## 📦 Installation
```bash
npm install @relayplane/sdk
```
## ⚙️ Configuration (Optional!)
RelayPlane works without configuration, but you can customize it:
```javascript
// Optional: Configure for enhanced features
RelayPlane.configure({
apiKey: 'your-relayplane-key', // For hosted mode
debug: true, // Enable debug logging
defaultOptimization: {
enabled: true, // Auto-fallback and optimization
strategy: 'balanced' // 'speed', 'balanced', 'quality'
},
costMonitoring: {
dailyLimit: 10.00, // Daily spend limit
alertThreshold: 0.8 // Alert at 80% of limit
}
});
// Or use environment variables (zero config!)
// RELAYPLANE_API_KEY=rp_... (hosted mode)
// OPENAI_API_KEY=sk-... (local mode)
// ANTHROPIC_API_KEY=sk-... (local mode)
// GOOGLE_API_KEY=... (local mode)
```
## 🔗 Advanced Usage
### Multi-Agent Chaining
```javascript
// Create intelligent workflows
const result = await RelayPlane.chain({
steps: [
{ step: 'research', to: 'claude-sonnet-4-20250514', 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-sonnet-4-20250514', 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-sonnet-4-20250514',
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';
// That's it! Everything else is automatic
const result = await RelayPlane.ask('Hello');
console.log(result.response.body);
console.log(result.reasoning.rationale); // See the intelligent decision-making
```
### 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
✅ **Dual Mode Operation** - Use your keys or our hosted service
## 📚 Supported Models
| Provider | Model Identifiers |
|----------|------------------|
| **Anthropic** | `claude-opus-4-20250514`, `claude-sonnet-4-20250514`, `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` |
## 🔗 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` 🪄