computesdk 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,38 @@
-# ComputeSDK
+<div align="center">
+  <img src="https://www.computesdk.com/_astro/hv_main_logo_light.CpYMD9-V.svg" alt="ComputeSDK" width="300" />
+</div>
 
-A unified abstraction layer for executing code in secure, isolated sandboxed environments across multiple cloud providers.
+<div align="center">
+  <strong>A free and open-source toolkit for running other people's code in your applications.</strong>
+</div>
 
-Similar to how Vercel's AI SDK abstracts different LLM providers, ComputeSDK abstracts different compute sandbox providers into a single, consistent TypeScript interface.
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/computesdk.svg)](https://badge.fury.io/js/computesdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-computesdk.com-blue)](https://computesdk.com)
+
+</div>
+
+---
+
+## What is ComputeSDK?
+
+ComputeSDK is a free and open-source toolkit for running other people's code in your applications. Think of it as the "AI SDK for compute" - providing a consistent TypeScript interface whether you're using E2B, Vercel, or Daytona.
+
+**Why ComputeSDK?**
+- 🔄 **Provider-agnostic** - Switch between E2B, Vercel, Daytona and more (coming soon) without code changes
+- 🛡️ **Security-first** - Isolated sandboxes protect your infrastructure
+- ⚡ **Developer experience** - Simple, TypeScript-native API
+- 🌍 **Production-ready** - Used by teams building the next generation of developer tools
+
+**Perfect for building:**
+- **Code execution platforms** - Run user-submitted code safely
+- **Educational tools** - Interactive coding environments  
+- **Data analysis applications** - Process code with full filesystem access
+- **AI-powered development tools** - Let AI agents write and execute code
+- **Testing & CI/CD systems** - Isolated test environments
 
 ## Features
 
@@ -10,256 +40,207 @@ Similar to how Vercel's AI SDK abstracts different LLM providers, ComputeSDK abs
 - 📁 **Filesystem operations** - Read, write, create directories across providers
 - 🖥️ **Terminal support** - Interactive PTY terminals (E2B)
 - ⚡ **Command execution** - Run shell commands directly
-- 🔄 **Auto-detection** - Automatically selects providers based on environment variables
 - 🛡️ **Type-safe** - Full TypeScript support with comprehensive error handling
 - 📦 **Modular** - Install only the providers you need
 - 🔧 **Extensible** - Easy to add custom providers
+- 🌐 **Web Framework Integration** - Built-in request handlers for Next.js, Nuxt, SvelteKit, etc.
+- 🎨 **Frontend Integration** - Client-side hooks and utilities via @computesdk/ui
 
-## Supported Providers
-
-| Provider | Code Execution | Filesystem | Terminal | Use Cases |
-|----------|----------------|------------|----------|-----------|
-| **E2B** | Python | ✅ Full | ✅ PTY | Data science, AI/ML, interactive development |
-| **Vercel** | Node.js, Python | ✅ Full | ❌ | Web apps, APIs, serverless functions |
-| **Daytona** | Python, Node.js | ✅ Full | ❌ | Development workspaces, custom environments |
-
-## Installation
+## Get Started in 30 Seconds
 
 ```bash
-# Core SDK
+# Install the core SDK
 npm install computesdk
 
-# Provider packages (install only what you need)
-npm install @computesdk/e2b        # E2B provider
-npm install @computesdk/vercel     # Vercel provider
-npm install @computesdk/daytona    # Daytona provider
+# Add your preferred provider
+npm install @computesdk/e2b        # For data science and Python
+npm install @computesdk/vercel     # For web-scale Node.js/Python  
+npm install @computesdk/daytona    # For development workspaces
+
+# Frontend integration (optional)
+npm install @computesdk/ui         # React hooks and utilities
 ```
 
-## Quick Start
+Set your environment variables and you're ready to go:
 
-### Auto-detection (Recommended)
+```bash
+export E2B_API_KEY=your_api_key
+# or VERCEL_TOKEN=your_token
+# or DAYTONA_API_KEY=your_key
+```
 
-ComputeSDK automatically detects available providers based on environment variables:
+## Quick Start
 
 ```typescript
-import { ComputeSDK } from 'computesdk';
+import { compute } from 'computesdk';
+import { e2b } from '@computesdk/e2b';
 
-// Automatically detects and uses the first available provider
-const sandbox = ComputeSDK.createSandbox();
+// Set default provider
+compute.setConfig({ 
+  provider: e2b({ apiKey: process.env.E2B_API_KEY }) 
+});
+
+// Create a sandbox
+const sandbox = await compute.sandbox.create({});
 
-const result = await sandbox.execute('print("Hello World!")');
+// Execute code
+const result = await sandbox.runCode('print("Hello World!")');
 console.log(result.stdout); // "Hello World!"
 
-await sandbox.kill();
+// Clean up
+await compute.sandbox.destroy(sandbox.sandboxId);
 ```
 
-### Provider-specific Usage
+## Provider Setup
 
-```typescript
-import { executeSandbox } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
+### E2B - Full Development Environment
 
-// Execute with specific provider
-const result = await executeSandbox({
-  sandbox: e2b(),
-  code: 'print("Hello from E2B!")',
-  runtime: 'python'
-});
+E2B provides full filesystem and terminal support:
 
-console.log(result.stdout);
+```bash
+export E2B_API_KEY=e2b_your_api_key_here
 ```
 
-### Advanced Usage with Type Safety
+```typescript
+import { compute } from 'computesdk';
+import { e2b } from '@computesdk/e2b';
 
-ComputeSDK provides rich TypeScript interfaces for different provider capabilities:
+compute.setConfig({ 
+  provider: e2b({ apiKey: process.env.E2B_API_KEY }) 
+});
 
-```typescript
-import { ComputeSDK, FilesystemComputeSandbox, TerminalComputeSandbox } from 'computesdk';
+const sandbox = await compute.sandbox.create({});
 
-const sandbox = ComputeSDK.createSandbox();
+// Execute Python with data science libraries
+const result = await sandbox.runCode(`
+import pandas as pd
+import numpy as np
 
-// Check provider capabilities at runtime
-if ('filesystem' in sandbox) {
-  const fsSandbox = sandbox as FilesystemComputeSandbox;
-  
-  // Use filesystem operations
-  await fsSandbox.filesystem.writeFile('/tmp/data.txt', 'Hello World!');
-  const content = await fsSandbox.filesystem.readFile('/tmp/data.txt');
-  console.log(content); // "Hello World!"
-}
+data = {'A': [1, 2, 3], 'B': [4, 5, 6]}
+df = pd.DataFrame(data)
+print(df)
+print(f"Sum: {df.sum().sum()}")
+`);
 
-if ('terminal' in sandbox) {
-  const termSandbox = sandbox as TerminalComputeSandbox;
-  
-  // Create interactive terminal (E2B only)
-  const terminal = await termSandbox.terminal.create({
-    command: 'bash',
-    cols: 80,
-    rows: 24
-  });
-  
-  await terminal.write('echo "Interactive terminal!"\n');
-  await terminal.kill();
-}
+// Interactive terminal support
+const terminal = await sandbox.terminal.create({
+  command: 'bash',
+  cols: 80,
+  rows: 24
+});
 ```
 
-## Environment Setup
+### Vercel - Scalable Serverless Execution
 
-Each provider requires specific environment variables for authentication:
+Vercel provides reliable execution with filesystem support:
 
-### E2B (Full Features)
 ```bash
-export E2B_API_KEY=e2b_your_api_key_here
-```
-Get your API key from [e2b.dev](https://e2b.dev/)
+# Method 1: OIDC Token (Recommended)
+vercel env pull  # Downloads VERCEL_OIDC_TOKEN
 
-### Vercel (Filesystem + Code Execution)
-```bash
+# Method 2: Traditional
 export VERCEL_TOKEN=your_vercel_token_here
 export VERCEL_TEAM_ID=your_team_id_here
 export VERCEL_PROJECT_ID=your_project_id_here
 ```
-Get your token from [Vercel Account Tokens](https://vercel.com/account/tokens)
-
-### Daytona (Development Workspaces)
-```bash
-export DAYTONA_API_KEY=your_daytona_api_key_here
-```
-
-
-
-## API Reference
-
-### Core SDK
-
-#### `ComputeSDK.createSandbox(config?)`
-
-Creates a sandbox using auto-detection or specified configuration.
 
 ```typescript
-// Auto-detection
-const sandbox = ComputeSDK.createSandbox();
-
-// With configuration
-const sandbox = ComputeSDK.createSandbox({
-  provider: 'e2b',
-  runtime: 'python',
-  timeout: 600000 // 10 minutes
-});
-```
-
-**Parameters:**
-- `config` (optional): Sandbox configuration object
+import { compute } from 'computesdk';
+import { vercel } from '@computesdk/vercel';
 
-**Returns:** `ComputeSandbox` - The appropriate sandbox type based on provider capabilities
+compute.setConfig({ 
+  provider: vercel({ runtime: 'node' }) 
+});
 
-#### `ComputeSDK.detectProviders()`
+const sandbox = await compute.sandbox.create({});
 
-Detects available providers based on environment variables.
+// Execute Node.js or Python
+const result = await sandbox.runCode(`
+console.log('Node.js version:', process.version);
+console.log('Hello from Vercel!');
+`);
 
-```typescript
-const providers = ComputeSDK.detectProviders();
-console.log('Available providers:', providers); // ['e2b', 'vercel']
+// Up to 45 minutes execution time
+// Global infrastructure deployment
 ```
 
-**Returns:** `ProviderType[]` - Array of available provider names
-
-### Utility Functions
+### Daytona - Development Workspaces
 
-#### `executeSandbox(params)`
+Daytona provides development workspace environments:
 
-Utility function for one-off code execution.
+```bash
+export DAYTONA_API_KEY=your_daytona_api_key_here
+```
 
 ```typescript
-import { executeSandbox } from 'computesdk';
-import { vercel } from '@computesdk/vercel';
+import { compute } from 'computesdk';
+import { daytona } from '@computesdk/daytona';
 
-const result = await executeSandbox({
-  sandbox: vercel({ runtime: 'node' }),
-  code: 'console.log("Hello from Node.js!");',
-  runtime: 'node'
+compute.setConfig({ 
+  provider: daytona({ apiKey: process.env.DAYTONA_API_KEY }) 
 });
-```
-
-**Parameters:**
-```typescript
-interface ExecuteSandboxParams {
-  sandbox: ComputeSandbox;
-  code: string;
-  runtime?: Runtime;
-}
-```
 
-### Sandbox Interfaces
+const sandbox = await compute.sandbox.create({});
 
-ComputeSDK provides a rich type system for different provider capabilities:
+// Execute in development workspace
+const result = await sandbox.runCode(`
+print('Hello from Daytona!')
+import sys
+print(f'Python version: {sys.version}')
+`);
+```
 
-#### `BaseComputeSandbox`
+## Core API
 
-Basic code execution capabilities (all providers support this):
+### Configuration
 
 ```typescript
-interface BaseComputeSandbox {
-  provider: string;
-  sandboxId: string;
-  
-  execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-  runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-  runCommand(command: string, args?: string[]): Promise<ExecutionResult>;
-  kill(): Promise<void>;
-  getInfo(): Promise<SandboxInfo>;
-}
-```
+import { compute } from 'computesdk';
 
-#### `FilesystemComputeSandbox`
+// Set default provider
+compute.setConfig({ provider: myProvider });
 
-Extends base capabilities with filesystem operations (E2B, Vercel, Daytona):
+// Get current config
+const config = compute.getConfig();
 
-```typescript
-interface FilesystemComputeSandbox extends BaseComputeSandbox {
-  readonly filesystem: SandboxFileSystem;
-}
-
-interface SandboxFileSystem {
-  readFile(path: string): Promise<string>;
-  writeFile(path: string, content: string): Promise<void>;
-  mkdir(path: string): Promise<void>;
-  readdir(path: string): Promise<FileEntry[]>;
-  exists(path: string): Promise<boolean>;
-  remove(path: string): Promise<void>;
-}
+// Clear config
+compute.clearConfig();
 ```
 
-#### `TerminalComputeSandbox`
-
-Extends base capabilities with terminal operations (E2B only):
+### Sandbox Management
 
 ```typescript
-interface TerminalComputeSandbox extends BaseComputeSandbox {
-  readonly terminal: SandboxTerminal;
-}
+// Create sandbox with explicit provider
+const sandbox = await compute.sandbox.create({
+  provider: e2b({ apiKey: 'your-key' }),
+  options: { runtime: 'python', timeout: 300000 }
+});
 
-interface SandboxTerminal {
-  create(options?: TerminalCreateOptions): Promise<InteractiveTerminalSession>;
-  list(): Promise<InteractiveTerminalSession[]>;
-}
-```
+// Create sandbox with default provider
+const sandbox = await compute.sandbox.create({
+  options: { runtime: 'python' }
+});
 
-#### `FullComputeSandbox`
+// Get existing sandbox
+const sandbox = await compute.sandbox.getById('sandbox-id');
 
-Full capabilities including filesystem and terminal (E2B only):
+// List all sandboxes
+const sandboxes = await compute.sandbox.list();
 
-```typescript
-interface FullComputeSandbox extends FilesystemComputeSandbox, TerminalComputeSandbox {}
+// Destroy sandbox
+await compute.sandbox.destroy('sandbox-id');
 ```
 
-### Data Types
+### Code Execution
 
-#### `ExecutionResult`
+```typescript
+// Run code
+const result = await sandbox.runCode('print("Hello")', 'python');
 
-Result object returned by all execution methods:
+// Run shell command
+const result = await sandbox.runCommand('ls', ['-la']);
 
-```typescript
+// Result structure
 interface ExecutionResult {
   stdout: string;
   stderr: string;
@@ -270,477 +251,383 @@ interface ExecutionResult {
 }
 ```
 
-#### `SandboxInfo`
-
-Information about a sandbox instance:
+### Filesystem Operations
 
 ```typescript
-interface SandboxInfo {
-  id: string;
-  provider: string;
-  runtime: Runtime;
-  status: 'running' | 'stopped' | 'error';
-  createdAt: Date;
-  timeout: number;
-  metadata?: Record<string, any>;
-}
-```
+// Write file
+await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello")');
 
-#### `FileEntry`
+// Read file
+const content = await sandbox.filesystem.readFile('/tmp/hello.py');
 
-File system entry information:
+// Create directory
+await sandbox.filesystem.mkdir('/tmp/mydir');
 
-```typescript
-interface FileEntry {
-  name: string;
-  path: string;
-  isDirectory: boolean;
-  size: number;
-  lastModified: Date;
-}
-```
+// List directory
+const files = await sandbox.filesystem.readdir('/tmp');
 
-## Examples
+// Check if exists
+const exists = await sandbox.filesystem.exists('/tmp/hello.py');
 
-### Cross-Provider Data Processing
+// Remove file/directory
+await sandbox.filesystem.remove('/tmp/hello.py');
+```
 
-```typescript
-import { ComputeSDK, FilesystemComputeSandbox } from 'computesdk';
+### Terminal Operations
 
-async function processData() {
-  // Auto-detect best available provider
-  const sandbox = ComputeSDK.createSandbox();
-  
-  if ('filesystem' in sandbox) {
-    const fsSandbox = sandbox as FilesystemComputeSandbox;
-    
-    // Create project structure
-    await fsSandbox.filesystem.mkdir('/project/data');
-    await fsSandbox.filesystem.mkdir('/project/output');
-    
-    // Write input data
-    const data = JSON.stringify([
-      { name: 'Alice', sales: 1000 },
-      { name: 'Bob', sales: 1500 },
-      { name: 'Charlie', sales: 800 }
-    ]);
-    
-    await fsSandbox.filesystem.writeFile('/project/data/sales.json', data);
-    
-    // Process data based on provider
-    let code: string;
-    if (sandbox.provider === 'e2b') {
-      // Python processing for E2B
-      code = `
-import json
-import pandas as pd
-
-# Read data
-with open('/project/data/sales.json', 'r') as f:
-    data = json.load(f)
+```typescript
+// Create terminal (E2B only)
+const terminal = await sandbox.terminal.create({
+  command: 'bash',
+  cols: 80,
+  rows: 24
+});
 
-# Process with pandas
-df = pd.DataFrame(data)
-total_sales = df['sales'].sum()
-avg_sales = df['sales'].mean()
+// Write to terminal
+await terminal.write('ls -la\n');
 
-# Write results
-results = {
-    'total_sales': total_sales,
-    'average_sales': avg_sales,
-    'top_performer': df.loc[df['sales'].idxmax(), 'name']
-}
+// Resize terminal
+await terminal.resize(120, 30);
 
-with open('/project/output/results.json', 'w') as f:
-    json.dump(results, f, indent=2)
+// Kill terminal
+await terminal.kill();
 
-print(f"Total Sales: ${total_sales}")
-print(f"Average Sales: ${avg_sales:.2f}")
-print(f"Top Performer: {results['top_performer']}")
-      `;
-    } else {
-      // JavaScript processing for Vercel/Daytona
-      code = `
-const fs = require('fs');
-
-// Read data
-const data = JSON.parse(fs.readFileSync('/project/data/sales.json', 'utf8'));
-
-// Process data
-const totalSales = data.reduce((sum, person) => sum + person.sales, 0);
-const avgSales = totalSales / data.length;
-const topPerformer = data.reduce((top, person) => 
-  person.sales > top.sales ? person : top
-);
-
-// Write results
-const results = {
-  total_sales: totalSales,
-  average_sales: avgSales,
-  top_performer: topPerformer.name
-};
-
-fs.writeFileSync('/project/output/results.json', JSON.stringify(results, null, 2));
-
-console.log(\`Total Sales: $\${totalSales}\`);
-console.log(\`Average Sales: $\${avgSales.toFixed(2)}\`);
-console.log(\`Top Performer: \${results.top_performer}\`);
-      `;
-    }
-    
-    // Execute processing
-    const result = await fsSandbox.execute(code);
-    console.log('Processing Output:', result.stdout);
-    
-    // Read results
-    const results = await fsSandbox.filesystem.readFile('/project/output/results.json');
-    console.log('Results:', JSON.parse(results));
-    
-    // List generated files
-    const outputFiles = await fsSandbox.filesystem.readdir('/project/output');
-    console.log('Generated files:', outputFiles.map(f => f.name));
-  }
-  
-  await sandbox.kill();
-}
+// List terminals
+const terminals = await sandbox.terminal.list();
 
-processData().catch(console.error);
+// Get terminal by ID
+const terminal = await sandbox.terminal.getById('terminal-id');
 ```
 
-### Interactive Development with E2B
+## Web Framework Integration
+
+ComputeSDK provides built-in request handlers for web frameworks:
 
 ```typescript
+import { handleComputeRequest } from 'computesdk';
 import { e2b } from '@computesdk/e2b';
-import { TerminalComputeSandbox, FilesystemComputeSandbox } from 'computesdk';
 
-async function interactiveDevelopment() {
-  const sandbox = e2b() as TerminalComputeSandbox & FilesystemComputeSandbox;
-  
-  // Set up development environment
-  await sandbox.filesystem.mkdir('/workspace');
-  await sandbox.filesystem.writeFile('/workspace/requirements.txt', 
-    'pandas\nnumpy\nmatplotlib\nscikit-learn'
-  );
-  
-  // Create interactive terminal
-  const terminal = await sandbox.terminal.create({
-    command: 'bash',
-    cols: 120,
-    rows: 30
+// Next.js API route
+export async function POST(request: Request) {
+  return handleComputeRequest({
+    request,
+    provider: e2b({ apiKey: process.env.E2B_API_KEY })
   });
-  
-  // Set up output handler
-  terminal.onData = (data: Uint8Array) => {
-    const output = new TextDecoder().decode(data);
-    console.log('Terminal:', output);
-  };
-  
-  // Install dependencies
-  await terminal.write('cd /workspace\n');
-  await terminal.write('pip install -r requirements.txt\n');
-  
-  // Start interactive Python session
-  await terminal.write('python3\n');
-  await terminal.write('import pandas as pd\n');
-  await terminal.write('import numpy as np\n');
-  await terminal.write('print("Development environment ready!")\n');
-  
-  // Simulate interactive development
-  await new Promise(resolve => setTimeout(resolve, 5000));
-  
-  // Clean up
-  await terminal.kill();
-  await sandbox.kill();
 }
 
-interactiveDevelopment().catch(console.error);
+// Client usage
+const response = await fetch('/api/compute', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    action: 'compute.sandbox.runCode',
+    code: 'print("Hello from web!")',
+    runtime: 'python'
+  })
+});
+
+const result = await response.json();
+console.log(result.result.stdout);
 ```
 
-### Multi-Provider Comparison
+### Supported Actions
+
+- `compute.sandbox.create` - Create new sandbox
+- `compute.sandbox.destroy` - Destroy sandbox
+- `compute.sandbox.getInfo` - Get sandbox information
+- `compute.sandbox.list` - List all sandboxes
+- `compute.sandbox.runCode` - Execute code
+- `compute.sandbox.runCommand` - Run shell command
+- `compute.sandbox.filesystem.readFile` - Read file
+- `compute.sandbox.filesystem.writeFile` - Write file
+- `compute.sandbox.filesystem.mkdir` - Create directory
+- `compute.sandbox.filesystem.readdir` - List directory
+- `compute.sandbox.filesystem.exists` - Check if path exists
+- `compute.sandbox.filesystem.remove` - Remove file/directory
+- `compute.sandbox.terminal.create` - Create terminal
+- `compute.sandbox.terminal.list` - List terminals
+- `compute.sandbox.terminal.getById` - Get terminal by ID
+- `compute.sandbox.terminal.destroy` - Destroy terminal
+- `compute.sandbox.terminal.write` - Write to terminal
+- `compute.sandbox.terminal.resize` - Resize terminal
+- `compute.sandbox.terminal.kill` - Kill terminal
+
+## Frontend Integration
+
+Use `@computesdk/ui` for framework-agnostic factory functions:
 
 ```typescript
-import { executeSandbox } from 'computesdk';
-import { e2b } from '@computesdk/e2b';
-import { vercel } from '@computesdk/vercel';
-import { daytona } from '@computesdk/daytona';
-
-async function compareProviders() {
-  const testCode = `
-import json
-import time
-start = time.time()
-
-# Simple computation
-result = sum(range(1000))
-elapsed = time.time() - start
-
-output = {
-    "result": result,
-    "elapsed_ms": round(elapsed * 1000, 2),
-    "provider": "will_be_set"
-}
+import { createCompute, createSandboxConsole } from '@computesdk/ui';
 
-print(json.dumps(output))
-  `;
-  
-  const providers = [
-    { name: 'E2B', factory: () => e2b() },
-    { name: 'Vercel', factory: () => vercel({ runtime: 'python' }) },
-    { name: 'Daytona', factory: () => daytona({ runtime: 'python' }) },
-  ];
+function CodeExecutor() {
+  const compute = createCompute({
+    apiEndpoint: '/api/compute',
+    defaultRuntime: 'python'
+  });
   
-  console.log('Performance Comparison:');
-  console.log('='.repeat(50));
+  const executeCode = async () => {
+    const sandbox = await compute.sandbox.create();
+    const result = await sandbox.runCode('print("Hello World!")');
+    console.log(result.result?.stdout);
+    await sandbox.destroy();
+  };
   
-  for (const { name, factory } of providers) {
-    try {
-      const start = Date.now();
-      const result = await executeSandbox({
-        sandbox: factory(),
-        code: testCode,
-        runtime: 'python'
-      });
-      const totalTime = Date.now() - start;
-      
-      const output = JSON.parse(result.stdout);
-      console.log(`${name}:`);
-      console.log(`  Computation: ${output.result}`);
-      console.log(`  Execution time: ${output.elapsed_ms}ms`);
-      console.log(`  Total time: ${totalTime}ms`);
-      console.log(`  Provider overhead: ${totalTime - output.elapsed_ms}ms`);
-      console.log();
-      
-    } catch (error) {
-      console.log(`${name}: Failed - ${error.message}`);
-      console.log();
-    }
-  }
+  return (
+    <button onClick={executeCode}>
+      Execute Code
+    </button>
+  );
 }
-
-compareProviders().catch(console.error);
 ```
 
 ## Error Handling
 
-ComputeSDK provides comprehensive error handling with specific error types:
-
 ```typescript
-import { ComputeSDK } from 'computesdk';
-
 try {
-  const sandbox = ComputeSDK.createSandbox();
-  const result = await sandbox.execute('invalid python code');
+  const sandbox = await compute.sandbox.create({});
+  const result = await sandbox.runCode('invalid code');
 } catch (error) {
-  if (error.message.includes('Missing') && error.message.includes('API key')) {
-    console.error('Authentication Error: Check your environment variables');
-    console.error('Required: E2B_API_KEY, VERCEL_TOKEN, etc.');
-  } else if (error.message.includes('timeout')) {
-    console.error('Timeout Error: Execution took too long');
-  } else if (error.message.includes('quota') || error.message.includes('limit')) {
-    console.error('Quota Error: API usage limits exceeded');
-  } else if (error.message.includes('not installed')) {
-    console.error('Configuration Error: Provider package not installed');
-    console.error('Run: npm install @computesdk/[provider-name]');
-  } else {
-    console.error('Execution Error:', error.message);
-  }
+  console.error('Execution failed:', error.message);
 }
 ```
 
-## Provider-Specific Features
-
-### E2B - Full Development Environment
+## Examples
 
-E2B provides the richest feature set with full filesystem and terminal support:
+### Data Science with E2B
 
 ```typescript
+import { compute } from 'computesdk';
 import { e2b } from '@computesdk/e2b';
 
-const sandbox = e2b();
-
-// Full Python environment with data science libraries
-const result = await sandbox.execute(`
-import pandas as pd
-import matplotlib.pyplot as plt
-import numpy as np
+compute.setConfig({ provider: e2b({ apiKey: process.env.E2B_API_KEY }) });
 
-# Create and visualize data
-data = np.random.randn(1000)
-plt.hist(data, bins=50)
-plt.savefig('/tmp/histogram.png')
-print("Histogram saved!")
-`);
+const sandbox = await compute.sandbox.create({});
 
-// Check if file was created
-const exists = await sandbox.filesystem.exists('/tmp/histogram.png');
-console.log('Histogram created:', exists);
-```
+// Create project structure
+await sandbox.filesystem.mkdir('/analysis');
+await sandbox.filesystem.mkdir('/analysis/data');
+await sandbox.filesystem.mkdir('/analysis/output');
 
-### Vercel - Scalable Serverless Execution
+// Write input data
+const csvData = `name,age,city
+Alice,25,New York
+Bob,30,San Francisco
+Charlie,35,Chicago`;
 
-Vercel provides reliable execution with filesystem support:
+await sandbox.filesystem.writeFile('/analysis/data/people.csv', csvData);
 
-```typescript
-import { vercel } from '@computesdk/vercel';
+// Process data with Python
+const result = await sandbox.runCode(`
+import pandas as pd
+import matplotlib.pyplot as plt
 
-const sandbox = vercel({ runtime: 'node' });
+# Read data
+df = pd.read_csv('/analysis/data/people.csv')
+print("Data loaded:")
+print(df)
+
+# Calculate statistics
+avg_age = df['age'].mean()
+print(f"\\nAverage age: {avg_age}")
+
+# Create visualization
+plt.figure(figsize=(8, 6))
+plt.bar(df['name'], df['age'])
+plt.title('Age by Person')
+plt.xlabel('Name')
+plt.ylabel('Age')
+plt.savefig('/analysis/output/age_chart.png')
+print("\\nChart saved to /analysis/output/age_chart.png")
+
+# Save results
+results = {
+    'total_people': len(df),
+    'average_age': avg_age,
+    'cities': df['city'].unique().tolist()
+}
 
-// Process data with Node.js
-const result = await sandbox.execute(`
-const fs = require('fs');
-const path = require('path');
+import json
+with open('/analysis/output/results.json', 'w') as f:
+    json.dump(results, f, indent=2)
 
-// Create API simulation
-const apiData = {
-  users: 1000,
-  active: 750,
-  revenue: 50000
-};
+print("Results saved!")
+`);
 
-// Write to filesystem
-fs.writeFileSync('/tmp/api-data.json', JSON.stringify(apiData, null, 2));
+console.log(result.stdout);
 
-console.log('API data processed and saved');
-console.log('Active users:', apiData.active);
-`);
+// Read the results
+const results = await sandbox.filesystem.readFile('/analysis/output/results.json');
+console.log('Analysis results:', JSON.parse(results));
 
-// Read the generated data
-const data = await sandbox.filesystem.readFile('/tmp/api-data.json');
-console.log('Generated data:', JSON.parse(data));
+await compute.sandbox.destroy(sandbox.sandboxId);
 ```
 
-### Daytona - Development Workspaces
-
-Daytona provides development workspace environments with full filesystem support:
+### Cross-Provider Data Processing
 
 ```typescript
+import { compute } from 'computesdk';
+import { vercel } from '@computesdk/vercel';
 import { daytona } from '@computesdk/daytona';
 
-const sandbox = daytona({ runtime: 'python' });
-
-// Execute Python code in workspace
-const result = await sandbox.execute(`
+async function processData(provider: any) {
+  compute.setConfig({ provider });
+  
+  const sandbox = await compute.sandbox.create({});
+  
+  // Create workspace
+  await sandbox.filesystem.mkdir('/workspace');
+  
+  // Write input data
+  await sandbox.filesystem.writeFile('/workspace/input.json', 
+    JSON.stringify({ numbers: [1, 2, 3, 4, 5] })
+  );
+  
+  // Process with code execution
+  const result = await sandbox.runCode(`
 import json
-import os
 
-# Create project structure
-os.makedirs('/workspace/src', exist_ok=True)
-os.makedirs('/workspace/tests', exist_ok=True)
+# Read input
+with open('/workspace/input.json', 'r') as f:
+    data = json.load(f)
 
-# Write project files
-with open('/workspace/src/main.py', 'w') as f:
-    f.write('def hello():\\n    return "Hello from Daytona!"\\n')
+# Process
+numbers = data['numbers']
+result = {
+    'sum': sum(numbers),
+    'average': sum(numbers) / len(numbers),
+    'count': len(numbers)
+}
 
-with open('/workspace/tests/test_main.py', 'w') as f:
-    f.write('from src.main import hello\\n\\ndef test_hello():\\n    assert hello() == "Hello from Daytona!"\\n')
+# Write output
+with open('/workspace/output.json', 'w') as f:
+    json.dump(result, f, indent=2)
 
-print("Project structure created!")
-print("Files:", os.listdir('/workspace'))
-`);
+print("Processing complete!")
+  `);
+  
+  // Read results
+  const output = await sandbox.filesystem.readFile('/workspace/output.json');
+  await compute.sandbox.destroy(sandbox.sandboxId);
+  
+  return JSON.parse(output);
+}
 
-// Check created files
-const files = await sandbox.filesystem.readdir('/workspace');
-console.log('Workspace files:', files.map(f => f.name));
+// Use with different providers
+const vercelResult = await processData(vercel({ runtime: 'python' }));
+console.log('Vercel result:', vercelResult);
 
-// Read project file
-const mainPy = await sandbox.filesystem.readFile('/workspace/src/main.py');
-console.log('main.py content:', mainPy);
+const daytonaResult = await processData(daytona({ runtime: 'python' }));
+console.log('Daytona result:', daytonaResult);
 ```
 
+## Provider Packages
 
+ComputeSDK uses separate provider packages:
 
-## Best Practices
-
-### 1. Provider Selection
-
-Choose providers based on your use case:
+```bash
+npm install @computesdk/e2b        # E2B provider
+npm install @computesdk/vercel     # Vercel provider  
+npm install @computesdk/daytona    # Daytona provider
+```
 
-- **E2B**: Data science, ML, interactive development, full Python environment
-- **Vercel**: Web applications, APIs, serverless functions, long-running tasks
-- **Daytona**: Development workspaces, custom environments, team collaboration
+Each provider implements the same interface but may support different capabilities (filesystem, terminal, etc.).
 
-### 2. Resource Management
+## Custom Providers
 
-Always clean up resources:
+Create custom providers using the factory:
 
 ```typescript
-const sandbox = ComputeSDK.createSandbox();
-try {
-  // Your code here
-  const result = await sandbox.execute('print("Hello")');
-} finally {
-  // Always clean up
-  await sandbox.kill();
-}
+import { createProvider } from 'computesdk';
+
+const myProvider = createProvider({
+  name: 'my-provider',
+  methods: {
+    sandbox: {
+      create: async (config, options) => {
+        // Implementation
+      },
+      getById: async (config, id) => {
+        // Implementation  
+      },
+      list: async (config) => {
+        // Implementation
+      },
+      destroy: async (config, id) => {
+        // Implementation
+      }
+    }
+  }
+});
 ```
 
-### 3. Error Handling
+## TypeScript Support
 
-Implement comprehensive error handling:
+ComputeSDK is fully typed with comprehensive TypeScript definitions:
 
 ```typescript
-async function robustExecution(code: string) {
-  let sandbox;
-  try {
-    sandbox = ComputeSDK.createSandbox();
-    return await sandbox.execute(code);
-  } catch (error) {
-    console.error('Execution failed:', error.message);
-    throw error;
-  } finally {
-    if (sandbox) {
-      await sandbox.kill();
-    }
-  }
-}
+import type { 
+  Sandbox, 
+  Provider, 
+  ExecutionResult,
+  ComputeConfig,
+  Runtime 
+} from 'computesdk';
 ```
 
-### 4. Type Safety
+## Provider Comparison
 
-Use TypeScript interfaces for better development experience:
+| Provider | Code Execution | Filesystem | Terminal | Use Cases |
+|----------|----------------|------------|----------|-----------|
+| **E2B** | Python, Node.js | ✅ Full | ✅ PTY | Data science, AI/ML, interactive development |
+| **Vercel** | Node.js, Python | ✅ Full | ❌ | Web apps, APIs, serverless functions |
+| **Daytona** | Python, Node.js | ✅ Full | ❌ | Development workspaces, custom environments |
 
-```typescript
-import { FilesystemComputeSandbox, TerminalComputeSandbox } from 'computesdk';
+### Key Differences
 
-function requiresFilesystem(sandbox: FilesystemComputeSandbox) {
-  // TypeScript ensures filesystem operations are available
-  return sandbox.filesystem.readFile('/path/to/file');
-}
+- **E2B**: Full development environment with data science libraries and interactive terminals
+- **Vercel**: Ephemeral sandboxes optimized for serverless execution (up to 45 minutes)
+- **Daytona**: Development workspaces with persistent environments
 
-function requiresTerminal(sandbox: TerminalComputeSandbox) {
-  // TypeScript ensures terminal operations are available
-  return sandbox.terminal.create({ command: 'bash' });
-}
-```
+## Examples
 
-## Contributing
+Check out the [examples directory](./examples) for complete implementations with different web frameworks:
 
-We welcome contributions! Please see our [Contributing Guide](https://github.com/computesdk/computesdk/blob/main/CONTRIBUTING.md) for details.
+- [Next.js](./examples/nextjs)
+- [Nuxt](./examples/nuxt) 
+- [SvelteKit](./examples/sveltekit)
+- [Remix](./examples/remix)
+- [Astro](./examples/astro)
 
-### Adding New Providers
+## Resources
 
-1. Implement the appropriate `ComputeSpecification` interface:
-   - `BaseComputeSpecification` for basic execution
-   - `FilesystemComputeSpecification` for filesystem support
-   - `TerminalComputeSpecification` for terminal support
-   - `FullComputeSpecification` for complete functionality
+- 📖 **[Full Documentation](https://computesdk.com)** - Complete guides and API reference
+- 🚀 **[Getting Started](https://computesdk.com/getting-started)** - Quick setup guide
+- 💡 **[Examples](./examples)** - Real-world usage examples
+- 🎯 **[Providers](https://computesdk.com/providers)** - Provider-specific guides
 
-2. Add comprehensive tests covering all implemented interfaces
+## Contributing
 
-3. Include documentation and examples
+ComputeSDK is open source and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, we'd love your help.
 
-4. Submit a pull request
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-## License
+## Community & Support
 
-MIT - see [LICENSE](https://github.com/computesdk/computesdk/blob/main/LICENSE) for details.
+- 💬 **[GitHub Discussions](https://github.com/computesdk/computesdk/discussions)** - Ask questions and share ideas
+- 🐛 **[GitHub Issues](https://github.com/computesdk/computesdk/issues)** - Report bugs and request features
+- 📧 **[Contact Us](https://computesdk.com/contact)** - Get in touch with the team
 
-## Support
+## License
 
-- [GitHub Issues](https://github.com/computesdk/computesdk/issues)
-- [Documentation](https://github.com/computesdk/computesdk)
-- [Examples](https://github.com/computesdk/computesdk/tree/main/examples)
+MIT License - see the [LICENSE](LICENSE) file for details.
 
 ---
 
-Made with ❤️ by the ComputeSDK team
+<div align="center">
+  <strong>Built with ❤️ by the ComputeSDK team</strong><br>
+  <a href="https://computesdk.com">computesdk.com</a>
+</div>