capsule

---

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:
    """Process data in an isolated, resource-controlled environment."""
    # Your code runs safely in a Wasm sandbox
    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 => {
  // Your code runs safely in a Wasm sandbox
  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"]

कंप्यूट स्तर

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

@task(name="main", allowed_hosts=["api.openai.com", "*.anthropic.com"])
def main() -> dict:
    with urlopen("https://api.openai.com/v1/models") as response:
        return json.loads(response.read().decode("utf-8"))