---

अवलोकन

Capsule एक रनटाइम है जो अविश्वसनीय कोड को पृथक वातावरण में निष्पादित करने के लिए है। प्रत्येक कार्य अपने स्वयं के WebAssembly सैंडबॉक्स के अंदर चलता है, जो प्रदान करता है:

• पृथक निष्पादन: प्रत्येक कार्य आपके होस्ट सिस्टम से पृथक चलता है
• संसाधन सीमाएँ: प्रति कार्य CPU, मेमोरी और टाइमआउट सीमाएँ निर्धारित करें
• स्वचालित पुनर्प्रयास: मैन्युअल हस्तक्षेप के बिना विफलताओं को संभालें
• जीवनचक्र ट्रैकिंग: मॉनिटर करें कि कौन से कार्य चल रहे हैं, पूर्ण हुए हैं या विफल हुए हैं

यह कैसे काम करता है

Python के साथ

अपने Python फ़ंक्शन को @task डेकोरेटर से एनोटेट करें:

from capsule import task

@task(name="analyze_data", compute="MEDIUM", ram="512MB", timeout="30s", max_retries=1)
def analyze_data(dataset: list) -> dict:
    """एक पृथक, संसाधन-नियंत्रित वातावरण में डेटा संसाधित करें।"""
    # आपका कोड सुरक्षित रूप से Wasm सैंडबॉक्स में चलता है
    return {"processed": len(dataset), "status": "complete"}

TypeScript / JavaScript के साथ

npm इकोसिस्टम तक पूर्ण पहुँच के साथ task() रैपर फ़ंक्शन का उपयोग करें:

import { task } from "@capsule-run/sdk";

export const analyzeData = task({
  name: "analyze_data",
  compute: "MEDIUM",
  ram: "512MB",
  timeout: "30s",
  maxRetries: 1
}, (dataset: number[]): object => {
  // आपका कोड सुरक्षित रूप से Wasm सैंडबॉक्स में चलता है
  return { processed: dataset.length, status: "complete" };
});

[!NOTE] रनटाइम के लिए एक कार्य का नाम "main" प्रवेश बिंदु के रूप में होना आवश्यक है। Python स्वचालित रूप से एक बनाएगा यदि कोई परिभाषित नहीं है, लेकिन इसे स्पष्ट रूप से सेट करने की अनुशंसा की जाती है।

जब आप capsule run main.py (या main.ts) चलाते हैं, तो आपका कोड WebAssembly मॉड्यूल में संकलित होता है और पृथक सैंडबॉक्स में निष्पादित होता है।

प्रत्येक कार्य अपने स्वयं के सैंडबॉक्स के भीतर कॉन्फ़िगरेबल संसाधन सीमाओं के साथ संचालित होता है, यह सुनिश्चित करता है कि विफलताएँ नियंत्रित रहें और आपके वर्कफ़्लो के अन्य भागों में न फैलें। होस्ट सिस्टम निष्पादन के हर पहलू को नियंत्रित करता है, Wasm ईंधन मीटरिंग के माध्यम से CPU आवंटन से लेकर मेमोरी बाधाओं और टाइमआउट प्रवर्तन तक।

आरंभ करें

Python

pip install capsule-run

hello.py बनाएँ:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
    return "Hello from Capsule!"

इसे चलाएँ:

capsule run hello.py

TypeScript / JavaScript

npm install -g @capsule-run/cli
npm install @capsule-run/sdk

hello.ts बनाएँ:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (): string => {
  return "Hello from Capsule!";
});

इसे चलाएँ:

capsule run hello.ts

[!TIP] वास्तविक समय में कार्य निष्पादन विवरण देखने के लिए --verbose जोड़ें।

अपने कोड से चलाएँ

run() फ़ंक्शन आपको CLI के बजाय अपने कोड से प्रोग्रामेटिक रूप से कार्य निष्पादित करने देता है। args स्वचालित रूप से main कार्य में पैरामीटर के रूप में अग्रेषित किए जाते हैं।

Python

from capsule import run

result = await run(
    file="./sandbox.py",
    args=["code to execute"]
)

sandbox.py बनाएँ:

from capsule import task

@task(name="main", compute="LOW", ram="64MB")
def main(code: str) -> str:
    return eval(code)

TypeScript / JavaScript

[!IMPORTANT] TypeScript में रनर फ़ंक्शन का उपयोग करने के लिए आपको अपनी निर्भरताओं में @capsule-run/cli की आवश्यकता है।

import { run } from '@capsule-run/sdk/runner';

const result = await run({
  file: './sandbox.ts',
  args: ['code to execute']
});

sandbox.ts बनाएँ:

import { task } from "@capsule-run/sdk";

export const main = task({
  name: "main",
  compute: "LOW",
  ram: "64MB"
}, (code: string): string => {
  return eval(code);
});

[!TIP] यदि आप पूर्व-कॉन्फ़िगर, उपयोग के लिए तैयार समाधान खोज रहे हैं, तो Python एडाप्टर या TypeScript एडाप्टर देखें।

दस्तावेज़ीकरण

कार्य कॉन्फ़िगरेशन विकल्प

अपने कार्यों को इन पैरामीटरों से कॉन्फ़िगर करें:

पैरामीटर	विवरण	प्रकार	डिफ़ॉल्ट	उदाहरण
name	कार्य पहचानकर्ता	str	फ़ंक्शन नाम (Python) / आवश्यक (TS)	"process_data"
compute	CPU आवंटन स्तर: "LOW", "MEDIUM" या "HIGH"	str	"MEDIUM"	"HIGH"
ram	कार्य के लिए मेमोरी सीमा	str	असीमित	"512MB", "2GB"
timeout	अधिकतम निष्पादन समय	str	असीमित	"30s", "5m", "1h"
max_retries / maxRetries	विफलता पर पुनर्प्रयास प्रयासों की संख्या	int	0	3
allowed_files / allowedFiles	सैंडबॉक्स में सुलभ फ़ोल्डर (वैकल्पिक एक्सेस मोड के साथ)	list	[]	["./data"], [{"path": "./data", "mode": "ro"}]
allowed_hosts / allowedHosts	सैंडबॉक्स में सुलभ डोमेन	list	[]	["api.openai.com", "*.anthropic.com"]
env_variables / envVariables	सैंडबॉक्स में सुलभ पर्यावरण चर	list	[]	["API_KEY"]

कंप्यूट स्तर (Compute Levels)

Capsule WebAssembly के ईंधन तंत्र के माध्यम से CPU उपयोग को नियंत्रित करता है, जो अनुदेश निष्पादन को मीटर करता है। कंप्यूट स्तर निर्धारित करता है कि आपके कार्य को कितना ईंधन मिलता है।

• LOW हल्के कार्यों के लिए न्यूनतम आवंटन प्रदान करता है
• MEDIUM सामान्य वर्कलोड के लिए संतुलित संसाधन प्रदान करता है
• HIGH कंप्यूट-गहन संचालन के लिए अधिकतम ईंधन प्रदान करता है
• CUSTOM निष्पादन सीमाओं पर सटीक नियंत्रण के लिए एक सटीक ईंधन मान निर्दिष्ट करने के लिए (जैसे, compute="1000000")।

प्रतिक्रिया प्रारूप

प्रत्येक कार्य एक संरचित JSON आवरण लौटाता है जिसमें परिणाम और निष्पादन मेटाडेटा दोनों शामिल होते हैं:

{
  "success": true,
  "result": "Hello from Capsule!",
  "error": null,
  "execution": {
    "task_name": "data_processor",
    "duration_ms": 1523,
    "retries": 0,
    "fuel_consumed": 45000,
    "ram_used": 1200000,
    "host_requests": [{...}]
  }
}

प्रतिक्रिया फ़ील्ड:

• success — बूलियन जो दर्शाता है कि कार्य सफलतापूर्वक पूर्ण हुआ या नहीं
• result — आपके कार्य से वास्तविक वापसी मान (json, string, विफलता पर null आदि)
• error — यदि कार्य विफल हुआ तो त्रुटि विवरण ({ error_type: string, message: string })
• execution — प्रदर्शन मीट्रिक्स:
  • task_name — निष्पादित कार्य का नाम
  • duration_ms — मिलीसेकंड में निष्पादन समय
  • retries — हुई पुनर्प्रयास प्रयासों की संख्या
  • fuel_consumed — उपयोग किए गए CPU संसाधन (देखें कंप्यूट स्तर)
  • ram_used — बाइट्स में उपयोग की गई अधिकतम मेमोरी
  • host_requests — कार्य द्वारा किए गए होस्ट अनुरोधों की सूची

नेटवर्क पहुँच

कार्य allowed_hosts में निर्दिष्ट डोमेन पर HTTP अनुरोध कर सकते हैं। डिफ़ॉल्ट रूप से, कोई आउटबाउंड अनुरोध अनुमत नहीं है ([])। पहुँच प्रदान करने के लिए डोमेन की एक अनुमति सूची प्रदान करें, या सभी डोमेन की अनुमति देने के लिए ["*"] का उपयोग करें।

Python

import json
from capsule import task
from urllib.request import urlopen