Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (greed.js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

logo

Greed.js

A powerful JavaScript library that enables seamless execution of Python code in web browsers with actual WebGPU-accelerated PyTorch support using compute shaders and intelligent worker-based parallel execution.

📦 Installation

npm install greed.js

yarn add greed.js

<!-- CDN -->
<script src="https://unpkg.com/greed.js@2.0.1/dist/greed.min.js"></script>

✨ Features

🏗️ Modular Architecture: Clean separation of concerns with EventEmitter-based communication
PyTorch in Browser: Full PyTorch polyfill with neural networks, tensors, and deep learning operations
⚡ WebGPU Compute Shaders: True GPU acceleration with 50+ optimized WGSL compute shaders for tensor operations
🎯 Intelligent Fallback: WebGPU → CPU → Worker execution strategy with automatic optimization
Complete Neural Networks: Support for torch.nn.Module, layers, loss functions, and training
Python in Browser: Execute Python code directly using Pyodide/WebAssembly
🛡️ Enhanced Security: Advanced input validation and threat detection system
🧠 Smart Compute Strategy: Intelligent fallback between WebGPU → CPU → Worker execution
📊 Memory Management: Automatic resource cleanup and memory pressure monitoring
Dynamic Package Installation: Automatically install Python packages on-demand
Simple API: Easy-to-use interface with comprehensive PyTorch compatibility
Context Preservation: Maintain variables and state across multiple executions
📈 Production Ready: Comprehensive testing, security validation, and performance optimization

Quick Start

<!DOCTYPE html>
<html>
<head>
    <title>Greed.js PyTorch Demo</title>
    <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
    <script type="module" src="dist/greed.js"></script>
</head>
<body>
    <script>
        async function runPyTorch() {
            const greed = new Greed({ enableWebGPU: true });
            await greed.initialize();
            
            // WebGPU-accelerated tensor operations
            const result = await greed.run(`
import torch

# Create tensors with WebGPU acceleration  
x = torch.randn(1000, 1000, device='webgpu')
y = torch.randn(1000, 1000, device='webgpu')

# Matrix multiplication using WebGPU compute shaders
result = torch.matmul(x, y)

# Neural network operations on GPU
model = torch.nn.Sequential(
    torch.nn.Linear(1000, 512),
    torch.nn.ReLU(),
    torch.nn.Linear(512, 10)
).to('webgpu')

output = model(x)
print(f"Model output shape: {output.shape}")
print(f"WebGPU acceleration: {torch.cuda.is_available()}")

output.mean().item()
            `);
            
            console.log('WebGPU PyTorch result:', result);
        }
        
        runPyTorch();
    </script>
</body>
</html>

🏗️ Architecture

Greed.js features a modular architecture designed for performance, maintainability, and extensibility:

Core Components

RuntimeManager: Handles Pyodide initialization and Python package management
ComputeStrategy: Intelligent compute orchestration with WebGPU/CPU/Worker fallback
WebGPUComputeEngine: Hardware-accelerated tensor operations using WebGPU compute shaders
WebGPUTensor: PyTorch-compatible tensor implementation with GPU acceleration
TensorBridge: Seamless interoperability between JavaScript and Python tensors
PipelineCache: Optimized shader compilation and caching system
MemoryManager: Advanced resource cleanup with automatic garbage collection
SecurityValidator: Comprehensive input validation and threat detection
EventEmitter: Base class providing event-driven inter-component communication

API Usage

// Basic usage
const greed = new Greed();
await greed.initialize();
const result = await greed.run('import torch; print(torch.tensor([1,2,3]))');

// Advanced configuration
const greed = new Greed({
  enableWebGPU: true,
  maxMemoryMB: 1024,
  strictSecurity: true,
  enableWorkers: true,
  maxWorkers: 4
});

// Component lifecycle events
greed.on('init:complete', () => console.log('Initialization complete'));
greed.on('memory:warning', (data) => console.log('Memory pressure:', data));

// Advanced tensor operations
await greed.tensor('matmul', [tensorA, tensorB], { device: 'webgpu' });

// Comprehensive statistics
const stats = greed.getStats();
console.log('Memory usage:', stats.memory.memoryUsageMB);
console.log('Operations:', stats.operations);

PyTorch Support

Tensor Operations

import torch

# Tensor creation
x = torch.tensor([[1, 2], [3, 4]], dtype=torch.float)
y = torch.randn(2, 2)

# GPU acceleration
x_gpu = x.cuda()  # Move to WebGPU
result = torch.mm(x_gpu, y.cuda())  # Matrix multiplication on GPU

# All standard operations supported
z = x + y * 2.0 - torch.ones_like(x)

Neural Networks

import torch
import torch.nn as nn

class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(784, 128)
        self.relu = nn.ReLU()
        self.fc2 = nn.Linear(128, 10)
    
    def forward(self, x):
        x = self.relu(self.fc1(x))
        return self.fc2(x)

# Create and use model
model = SimpleNet()
x = torch.randn(32, 784)  # Batch of 32 samples
output = model(x)

# Training with loss functions
criterion = nn.CrossEntropyLoss()
target = torch.randint(0, 10, (32,))
loss = criterion(output, target)

GPU Acceleration Features

Element-wise operations: +, -, *, / with smart GPU thresholds
Matrix operations: torch.mm(), torch.matmul(), @ operator
Reduction operations: torch.sum(), torch.mean(), torch.max()
Neural network layers: nn.Linear, nn.ReLU, nn.CrossEntropyLoss
Automatic fallback: Seamless CPU fallback for small tensors or when WebGPU unavailable

API Reference

Constructor

const greed = new Greed({
    maxWorkers: 2,           // Number of worker threads
    enableWebGPU: true       // Enable WebGPU acceleration
});

Main Execution Method

const result = await greed.executeCode(pythonCode, options);

Options:

packages: Array of Python packages to install
useGPU: Force GPU acceleration (default: auto-detect)
preserveContext: Maintain variables between executions

Returns:

{
    success: true,
    output: result,              // Python execution result
    stdout: "print output",      // Console output
    executionTime: 1234,         // Execution time in ms
    usedGPU: true               // Whether GPU was used
}

⚡ WebGPU Implementation

Greed.js features a complete WebGPU implementation that replaces numpy operations with actual GPU compute shaders for true hardware acceleration.

WebGPU Architecture

PyTorch Tensor Operation
        ↓
WebGPU Compute Engine
        ↓
WGSL Compute Shader → GPU Execution → Result
        ↑
Pipeline Cache & Optimization

Supported Operations

Arithmetic Operations

add, sub, mul, div, pow
Element-wise operations with broadcasting support

Matrix Operations

matmul - Optimized matrix multiplication with tiled algorithms
bmm - Batch matrix multiplication for neural networks
transpose - Efficient dimension swapping

Activation Functions

relu, leaky_relu, sigmoid, tanh, gelu
softmax - Numerically stable with workgroup reduction

Neural Network Operations

conv2d - 2D convolution with optimized memory access
maxpool2d, avgpool2d - Pooling operations
batch_norm - Batch normalization with running statistics

Reduction Operations

sum, mean - Parallel reduction with shared memory
max, min - Index-preserving reductions

Loss Functions

cross_entropy - Numerically stable cross-entropy loss
mse_loss - Mean squared error with broadcasting

Performance Features

Intelligent Workgroup Sizing

// Automatically optimizes workgroup sizes based on operation type
matmul: [16, 16, 1]    // 2D tiled matrix multiplication  
conv2d: [8, 8, 8]      // 3D spatial convolution
elementwise: [64, 1, 1] // 1D parallel processing
reduction: [256, 1, 1]  // Maximize parallel reduction

Pipeline Caching

Automatic shader compilation and caching
LRU eviction for memory efficiency
Warmup for common operations
Adaptive optimization based on usage patterns

Memory Management

Buffer pooling and reuse
Automatic garbage collection
Memory pressure monitoring
Fallback to CPU when GPU memory exhausted

Usage Examples

Basic Tensor Operations

const greed = new Greed({ enableWebGPU: true });
await greed.initialize();

// WebGPU-accelerated tensor operations
await greed.run(`
import torch

# Tensors automatically use WebGPU when available
x = torch.randn(1000, 1000, device='webgpu')
y = torch.randn(1000, 1000, device='webgpu')

# GPU-accelerated matrix multiplication
result = torch.matmul(x, y)
print(f"Computed on: {result.device}")
`);

Neural Network Training

await greed.run(`
import torch
import torch.nn as nn

# Neural network on GPU
class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = nn.Linear(784, 128)
        self.relu = nn.ReLU()
        self.output = nn.Linear(128, 10)
    
    def forward(self, x):
        return self.output(self.relu(self.linear(x)))

# Move model to WebGPU
model = SimpleNet().to('webgpu')
optimizer = torch.optim.Adam(model.parameters())

# Training step with GPU acceleration
def train_step(data, target):
    output = model(data)
    loss = torch.nn.functional.cross_entropy(output, target)
    loss.backward()
    optimizer.step()
    return loss.item()
`);

Browser Compatibility

Browser	WebGPU Support	Status
Chrome 113+	✅ Full	Production Ready
Edge 113+	✅ Full	Production Ready
Firefox	🚧 Flag Required	`dom.webgpu.enabled=true`
Safari	🚧 Technology Preview	Limited Support

Fallback Strategy

When WebGPU is unavailable, Greed.js automatically falls back to:

CPU Numpy Operations - Full compatibility maintained
Web Workers - Parallel processing for large operations
Graceful Degradation - Same API, different execution engine

Architecture

Python Code → Greed.js → WebGPU Tensor Bridge → WGSL Compute Shaders → GPU
                ↓                                    ↓
         Pyodide Runtime                    Pipeline Cache & Optimization
                ↓                                    ↓
    Context Preservation ← Memory Manager ← Buffer Management & GC

Execution Contexts

WebGPU Engine: Hardware-accelerated tensor operations using compute shaders
CPU Engine: NumPy-based operations for compatibility and fallback
Worker Engine: Multi-threaded parallel processing for large computations
Tensor Bridge: Seamless interoperability between JavaScript and Python tensors

Framework Integration

React Usage

import React, { useState, useEffect } from 'react';

function PyTorchComponent() {
  const [greed, setGreed] = useState(null);
  const [result, setResult] = useState('');
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const loadGreed = async () => {
      try {
        // Import Pyodide first
        await import('https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js');
        
        // Then import Greed
        const { Greed } = await import('greed.js');
        
        const greedInstance = new Greed({ enableWebGPU: true });
        setGreed(greedInstance);
        setLoading(false);
      } catch (error) {
        console.error('Failed to load Greed:', error);
        setLoading(false);
      }
    };

    loadGreed();
  }, []);

  const runPython = async () => {
    if (!greed) return;

    const code = `
import torch
x = torch.randn(100, 100).cuda()
y = torch.randn(100, 100).cuda()
result = torch.mm(x, y)
result.mean().item()
    `;

    const output = await greed.executeCode(code);
    setResult(JSON.stringify(output, null, 2));
  };

  if (loading) return <div>Loading PyTorch...</div>;

  return (
    <div>
      <h2>PyTorch in React</h2>
      <button onClick={runPython}>Run PyTorch Code</button>
      <pre>{result}</pre>
    </div>
  );
}

Next.js Usage

import dynamic from 'next/dynamic';

// Dynamically import to avoid SSR issues
const PyTorchRunner = dynamic(() => import('../components/PyTorchRunner'), {
  ssr: false, // Important: Disable server-side rendering
  loading: () => <p>Loading PyTorch...</p>
});

export default function HomePage() {
  return (
    <div>
      <h1>Next.js with PyTorch</h1>
      <PyTorchRunner />
    </div>
  );
}

Custom React Hook

import { useState, useEffect } from 'react';

export function useGreed(options = {}) {
  const [greed, setGreed] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const initGreed = async () => {
      try {
        if (!window.loadPyodide) {
          await import('https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js');
        }
        const { Greed } = await import('greed.js');
        const instance = new Greed(options);
        setGreed(instance);
        setLoading(false);
      } catch (err) {
        setError(err);
        setLoading(false);
      }
    };

    initGreed();
    return () => greed?.destroy();
  }, []);

  return { greed, loading, error };
}

⚠️ Important Notes for React/Next.js:

Client-Side Only: Greed.js only works in browsers, not server-side
Next.js: Use dynamic imports with ssr: false
Memory: Call greed.destroy() in cleanup
WebGPU: Requires modern browsers (Chrome 113+, Edge 113+)

Examples

Image Classification with PyTorch

import torch
import torch.nn as nn

# Define a simple CNN
class ImageClassifier(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv1 = nn.Conv2d(3, 32, 3)
        self.relu = nn.ReLU()
        self.fc = nn.Linear(32, 10)
    
    def forward(self, x):
        x = self.relu(self.conv1(x))
        x = x.mean(dim=[2, 3])  # Global average pooling
        return self.fc(x)

# Create model and process batch
model = ImageClassifier()
images = torch.randn(8, 3, 32, 32).cuda()  # GPU acceleration
predictions = model(images)

Performance Benchmarking

import torch
import time

def benchmark_operation(name, func, *args):
    torch.cuda.is_available()  # Ensure GPU ready
    
    start = time.time()
    result = func(*args)
    end = time.time()
    
    print(f"{name}: {(end-start)*1000:.2f}ms")
    return result

# Benchmark GPU vs CPU
a_gpu = torch.randn(1000, 1000).cuda()
b_gpu = torch.randn(1000, 1000).cuda()

gpu_result = benchmark_operation("GPU MatMul", torch.mm, a_gpu, b_gpu)
cpu_result = benchmark_operation("CPU MatMul", torch.mm, a_gpu.cpu(), b_gpu.cpu())

Browser Support

Feature	Chrome	Firefox	Safari	Edge
Pyodide/WebAssembly	✅ 57+	✅ 52+	✅ 11+	✅ 16+
WebGPU Acceleration	✅ 113+	🔄 Exp	🔄 Exp	✅ 113+
Web Workers	✅	✅	✅	✅

Development

# Clone repository
git clone https://github.com/your-username/greed.git
cd greed

# Install dependencies  
npm install

# Start development server with live examples
npm run dev

# Build for production
npm run build

# Run test suite
npm test

📁 Project Structure

greed/
├── src/
│   ├── greed.js              # Main library file
│   └── gpu/
│       └── webgpu-compute.js # WebGPU compute engine
├── sandbox.html              # Interactive examples
├── examples/                 # Usage examples
├── tests/                    # Test suite
└── dist/                     # Built files

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Bug Reports: Use GitHub Issues with detailed reproduction steps
Feature Requests: Propose new PyTorch operations or WebGPU optimizations
Pull Requests: Include tests and ensure all examples still work

License

This software is dual-licensed under AGPL v3.0 and commercial licenses.

Open Source License (AGPL v3.0)

Free for open source projects and personal use
Requires your application to be open-sourced under AGPL v3.0
Suitable for academic research and community contributions
Must make complete source code available to users

Commercial License

Permits use in proprietary commercial applications
Allows keeping application source code confidential
No AGPL obligations for end users
Includes technical support and maintenance services

For commercial licensing inquiries, contact khalkaraditya8@gmail.com

Complete licensing terms are available in the LICENSE file.

Acknowledgments

Pyodide: Python-to-WebAssembly runtime
WebGPU: GPU acceleration standard
PyTorch: Deep learning framework inspiration
Python Community: For the incredible ecosystem

Greed.js - Bringing the power of PyTorch and GPU acceleration to every web browser!