Python SDK (clore-ai)

द clore-ai पैकेज आधिकारिक पायथन SDK है Clore.ai GPU मार्केटप्लेस के लिए। यह पूरे REST API को एक साफ़, प्रकार-सुरक्षित इंटरफ़ेस में लपेटता है जिसमें अंतर्निर्मित दर-सीमा, स्वचालित पुन:प्रयास, और संरचित त्रुटि हैंडलिंग शामिल हैं — ताकि आप GPU किराए पर लेने पर ध्यान दे सकें, HTTP पाइपलाइनिंग पर नहीं।

---

इंस्टॉलेशन

pip install clore-ai

आवश्यकताएँ: Python 3.9+

पैकेज दोनों इंस्टॉल करता है: पायथन SDK और clore CLI.

---

प्रमाणीकरण

अपनी API कुंजी प्राप्त करें Clore.ai डैशबोर्ड → API अनुभाग।

विकल्प 1: एन्वायरनमेंट वेरिएबल (अनुशंसित)

export CLORE_API_KEY=your_api_key_here

SDK पढ़ता है CLORE_API_KEY स्वचालित रूप से — किसी कोड परिवर्तन की आवश्यकता नहीं।

विकल्प 2: CLI कॉन्फिग फ़ाइल

clore config set api_key YOUR_API_KEY

यह कुंजी में संग्रहीत करता है ~/.clore/config.json.

विकल्प 3: कोड में सीधे पास करें

from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")

⚠️ महत्वपूर्ण: Clore.ai API प्रमाणीकरण के लिए उपयोग करता है auth हेडर, नहीं Authorization: Bearer। SDK इसे स्वचालित रूप से संभालता है।

---

त्वरित आरंभ

from clore_ai import CloreAI

client = CloreAI()
servers = client.marketplace(gpu="RTX 4090", max_price_usd=5.0)
for s in servers:
    print(f"Server {s.id}: {s.gpu_model} — ${s.price_usd:.4f}/h")

---

सिंक क्लाइंट (CloreAI)

कन्स्ट्रक्टर

CloreAI(
    api_key: str | None = None,       # CLORE_API_KEY env / config पर वापसFallback
    base_url: str | None = None,       # डिफ़ॉल्ट: https://api.clore.ai/v1
    timeout: float = 30.0,             # अनुरोध टाइमआउट सेकंड में
    max_retries: int = 3               # दर-सीमा / नेटवर्क त्रुटियों पर पुन:प्रयास प्रयास
)

क्लाइंट स्वचालित क्लीनअप के लिए कॉन्टेक्स्ट मैनेजर का समर्थन करता है:

with CloreAI() as client:
    wallets = client.wallets()
    # client.close() स्वचालित रूप से कॉल किया गया

---

wallets()

अपनी वॉलेट शेष और जमा पते प्राप्त करें।

wallets = client.wallets()

for wallet in wallets:
    print(f"{wallet.name}: {wallet.balance:.8f}")
    if wallet.deposit:
        print(f"  Deposit: {wallet.deposit}")

परिणाम: List[Wallet]

फ़ील्ड	प्रकार	वर्णन
name	str	मुद्रा का नाम (उदा. "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance	float | None	वर्तमान शेष
deposit	str | None	जमा पता
withdrawal_fee	float | None	निकासी शुल्क

---

marketplace()

क्लाइंट-साइड विकल्पी फिल्टर के साथ GPU मार्केटप्लेस खोजें।

# सभी उपलब्ध सर्वर
servers = client.marketplace()

# GPU मॉडल और अधिकतम कीमत से फ़िल्टर करें
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# बहु-GPU रिग जिनमें पर्याप्त RAM है
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)

पैरामीटर:

पैरामीटर	प्रकार	डिफ़ॉल्ट	वर्णन
gpu	str | None	None	GPU मॉडल द्वारा फ़िल्टर करें (केस-इनसेंसिटिव सबस्ट्रिंग मैच)
min_gpu_count	int | None	None	न्यूनतम GPU की संख्या
min_ram_gb	float | None	None	GB में न्यूनतम RAM
max_price_usd	float | None	None	USD में प्रति घंटे अधिकतम कीमत
available_only	bool	True	केवल वे सर्वर लौटाएँ जो किराए पर उपलब्ध हैं

परिणाम: List[MarketplaceServer]

प्रत्येक MarketplaceServer अत्यधिक सामान्य फ़ील्ड्स के लिए सुविधाजनक गुण प्रदान करता है, साथ ही पूरा नेस्टेड डेटा तक पहुँच:

प्रॉपर्टी	प्रकार	वर्णन
id	int	विशिष्ट सर्वर ID
gpu_model	str | None	प्राथमिक GPU विवरण (उदा. "1x NVIDIA GeForce RTX 4090")
gpu_count	int	GPU की संख्या (से gpu_array)
ram_gb	float | None	RAM GB में
price_usd	float | None	ऑन-डिमांड कीमत USD में
spot_price_usd	float | None	स्पॉट कीमत USD में
available	bool	क्या सर्वर उपलब्ध है (किराए पर नहीं गया)
location	str | None	नेटवर्क स्पेस से देश कोड

उन्नत उपयोग मामलों के लिए, आप पूरा नेस्टेड स्ट्रक्चर एक्सेस कर सकते हैं:

फ़ील्ड	प्रकार	वर्णन
specs	ServerSpecs | None	पूर्ण हार्डवेयर विशिष्टताएँ (specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net, आदि)
price	ServerPrice | None	पूर्ण मूल्य ऑब्जेक्ट (price.usd.on_demand_usd, price.usd.spot, price.on_demand, आदि)
rented	bool | None	क्या सर्वर वर्तमान में किराए पर है
reliability	float | None	सर्वर विश्वसनीयता स्कोर
rating	ServerRating | None	सर्वर रेटिंग (rating.avg, rating.cnt)

नोट: द marketplace() एंडपॉइंट सार्वजनिक है — यह API कुंजी के बिना काम करता है।

---

my_servers()

उन सर्वरों की सूची बनाएं जो आप Clore.ai मार्केटप्लेस को प्रदान कर रहे हैं।

my_servers = client.my_servers()

for server in my_servers:
    print(f"{server.name}: {server.gpu_model} [{server.status}]")

परिणाम: List[MyServer]

प्रॉपर्टी	प्रकार	वर्णन
id	int	सर्वर ID
name	str | None	सर्वर नाम
gpu_model	str | None	प्राथमिक GPU विवरण
ram_gb	float | None	RAM GB में
status	str	मानव-पठनीय स्थिति: "Online", "Offline", "Disconnected", या "Not Working"
connected	bool | None	क्या सर्वर कनेक्टेड है
online	bool | None	क्या सर्वर ऑनलाइन है
visibility	str | None	"public" या "private"

---

server_config(server_name)

उस विशिष्ट सर्वर का कॉन्फ़िगरेशन प्राप्त करें जिसे आप होस्ट करते हैं।

config = client.server_config("MyGPU")

print(f"Server: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Min rental: {config.mrl}h")
print(f"On-demand: ${config.on_demand_price}")
print(f"Spot: ${config.spot_price}")

पैरामीटर:

पैरामीटर	प्रकार	वर्णन
server_name	str	सर्वर का नाम

परिणाम: ServerConfig

प्रॉपर्टी	प्रकार	वर्णन
name	str | None	सर्वर नाम
gpu_model	str | None	प्राथमिक GPU विवरण
mrl	int | None	घंटों में न्यूनतम किराये की अवधि
on_demand_price	float | None	पहली उपलब्ध ऑन-डिमांड USD कीमत
spot_price	float | None	पहली उपलब्ध स्पॉट USD कीमत
specs	ServerSpecs | None	पूर्ण हार्डवेयर विनिर्देश
connected	bool | None	क्या सर्वर कनेक्टेड है
visibility	str | None	"public" या "private"

---

my_orders(include_completed)

अप अपने वर्तमान ऑर्डर प्राप्त करें, वैकल्पिक रूप से पूर्ण/समाप्त ऑर्डर शामिल करके।

# केवल सक्रिय ऑर्डर
orders = client.my_orders()

# पूर्ण ऑर्डर शामिल करें
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Order {order.id}: {order.type} — {order.status}")
    if order.pub_cluster:
        print(f"  IP: {order.pub_cluster}")
    if order.tcp_ports:
        print(f"  Ports: {order.tcp_ports}")

पैरामीटर:

पैरामीटर	प्रकार	डिफ़ॉल्ट	वर्णन
include_completed	bool	False	पूर्ण/समाप्त ऑर्डर शामिल करें

परिणाम: List[Order]

फ़ील्ड	प्रकार	वर्णन
id	int	विशिष्ट ऑर्डर ID
server_id	int | None	सर्वर ID
type	str	"on-demand" या "spot"
status	str | None	ऑर्डर स्थिति
image	str | None	Docker इमेज
currency	str | None	भुगतान मुद्रा
price	float | None	ऑर्डर की दैनिक कीमत
pub_cluster	str | None	एक्सेस के लिए सार्वजनिक होस्टनाम/IP
tcp_ports	dict | None	TCP पोर्ट मैपिंग

---

spot_marketplace(server_id)

किसी विशिष्ट सर्वर के लिए स्पॉट मार्केट ऑफ़र देखें।

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Order {offer.order_id}: ${offer.price}/day (server {offer.server_id})")

if spot.currency_rates_in_usd:
    for coin, rate in spot.currency_rates_in_usd.items():
        print(f"  {coin}: ${rate}")

पैरामीटर:

पैरामीटर	प्रकार	वर्णन
server_id	int	जांच के लिए सर्वर ID

परिणाम: SpotMarket

फ़ील्ड	प्रकार	वर्णन
offers	List[SpotOffer] | None	स्पॉट ऑफ़र्स की सूची (order_id, price, server_id)
server	SpotServerInfo | None	सर्वर जानकारी (न्यूनतम मूल्य निर्धारण, दृश्यता, ऑनलाइन स्थिति)
currency_rates_in_usd	Dict[str, float] | None	USD में मुद्रा विनिमय दरें

---

create_order(...)

नया ऑन-डिमांड या स्पॉट ऑर्डर बनाएं। इसी तरह आप GPU किराए पर लेते हैं।

ऑन-डिमांड ऑर्डर

order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"}
)

print(f"Order created: {order.id}")
print(f"Connect: {order.pub_cluster}")

स्पॉट ऑर्डर

order = client.create_order(
    server_id=123,
    image="cloreai/pytorch",
    type="spot",
    currency="bitcoin",
    spot_price=0.000005,
    ssh_password="MySecurePass123",
    ports={"22": "tcp"}
)

पैरामीटर:

पैरामीटर	प्रकार	आवश्यक	वर्णन
server_id	int	हाँ	किराए पर लेने के लिए सर्वर ID
image	str	हाँ	Docker इमेज (उदा. "cloreai/ubuntu22.04-cuda12")
type	str	हाँ	"on-demand" या "spot"
currency	str	हाँ	भुगतान मुद्रा (उदा. "bitcoin")
ssh_password	str	नहीं	SSH पासवर्ड (अल्फ़ान्यूमेरिक, अधिकतम 32 अक्षर)
ssh_key	str	नहीं	SSH सार्वजनिक कुंजी (अधिकतम 3072 अक्षर)
ports	dict	नहीं	पोर्ट मैपिंग, उदाहरण के लिए {"22": "tcp", "8888": "http"}
env	dict	नहीं	पर्यावरण वेरिएबल
jupyter_token	str	नहीं	Jupyter नोटबुक टोकन (अधिकतम 32 अक्षर)
command	str	नहीं	कंटेनर शुरू होने के बाद चलाने के लिए शेल कमांड
spot_price	float	केवल स्पॉट	स्पॉट ऑर्डर्स के लिए प्रति दिन कीमत
required_price	float	नहीं	एक विशिष्ट कीमत लॉक करें (केवल ऑन-डिमांड)
autossh_entrypoint	str	नहीं	Clore.ai SSH एंट्रीपॉइंट का उपयोग करें

परिणाम: Order

रेट लिमिट: create_order कॉल्स के बीच एक विशेष 5-सेकंड कूलडाउन है। SDK इसे स्वचालित रूप से लागू करता है।

---

cancel_order(order_id, issue)

एक सक्रिय ऑर्डर या स्पॉट ऑफ़र रद्द करें। वैकल्पिक रूप से सर्वर के साथ एक मुद्दा रिपोर्ट करें।

# सरल रद्द करें
client.cancel_order(order_id=38)

# मुद्दा रिपोर्ट के साथ रद्द करें
client.cancel_order(
    order_id=38,
    issue="GPU #1 was overheating and throttling"
)

पैरामीटर:

पैरामीटर	प्रकार	आवश्यक	वर्णन
order_id	int	हाँ	रद्द करने के लिए ऑर्डर ID
issue	str	नहीं	रद्द करने का कारण / मुद्दा रिपोर्ट (अधिकतम 2048 अक्षर)

परिणाम: Dict[str, Any]

---

set_server_settings(...)

मार्केटप्लेस पर आप जो सर्वर होस्ट करते हैं उसके लिए सेटिंग्स अपडेट करें।

client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113
)

पैरामीटर:

पैरामीटर	प्रकार	आवश्यक	वर्णन
name	str	हाँ	सर्वर नाम
availability	bool	नहीं	क्या सर्वर किराए पर दिया जा सकता है
mrl	int	नहीं	घंटों में न्यूनतम किराये की अवधि
on_demand	float	नहीं	प्रति दिन ऑन-डिमांड कीमत
spot	float	नहीं	प्रति दिन न्यूनतम स्पॉट कीमत

परिणाम: Dict[str, Any]

---

set_spot_price(order_id, price)

अपने स्पॉट मार्केट ऑफ़र पर कीमत अपडेट करें।

client.set_spot_price(order_id=39, price=0.000003)

पैरामीटर:

पैरामीटर	प्रकार	वर्णन
order_id	int	स्पॉट ऑर्डर/ऑफ़र ID
price	float	नई प्रति दिन कीमत

परिणाम: Dict[str, Any]

नोट: आप केवल हर 600 सेकंड में एक बार स्पॉट कीमतें घटा सकते हैं, और सीमित कदम आकार द्वारा। यदि आप इन सीमाओं को पार करते हैं तो API लौटाता है code: 6 विवरण के साथ।

---

असिंक क्लाइंट (AsyncCloreAI)

द AsyncCloreAI क्लाइंट वही विधियाँ प्रदान करता है जो CloreAIके हैं, लेकिन सभी कोरूटीन लौटाते हैं। जब आपको समांतर API कॉल की आवश्यकता हो या आप किसी असिंक्रोनस अनुप्रयोग के भीतर काम कर रहे हों तो इसे उपयोग करें।

मूल उपयोग

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="your_key") as client:
        wallets = await client.wallets()
        for w in wallets:
            print(f"{w.name}: {w.balance:.8f}")

asyncio.run(main())

समांतर संचालन

एक साथ कई API कॉल चलाएं asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # एक साथ कई GPU मॉडलों के लिए खोजें
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        for name, servers in [("RTX 4090", rtx4090), ("RTX 3090", rtx3090), ("A100", a100)]:
            if servers:
                cheapest = min(s.price_usd or float('inf') for s in servers)
                print(f"{name}: {len(servers)} available, cheapest ${cheapest:.4f}/h")
            else:
                print(f"{name}: none available")

asyncio.run(compare_gpus())

उपलब्ध विधियाँ

AsyncCloreAI सभी वही विधियाँ समर्थित हैं जो CloreAI:

विधि	वर्णन
await wallets()	वॉलेट शेष प्राप्त करें
await marketplace(...)	मार्केटप्लेस खोजें
await my_servers()	आपके होस्ट किए गए सर्वरों की सूची
await server_config(name)	सर्वर कॉन्फ़िगरेशन प्राप्त करें
await my_orders(...)	आपके ऑर्डर की सूची
await spot_marketplace(server_id)	स्पॉट मार्केट ऑफ़र प्राप्त करें
await create_order(...)	नया ऑर्डर बनाएं
await cancel_order(...)	एक ऑर्डर रद्द करें
await set_server_settings(...)	सर्वर सेटिंग्स अपडेट करें
await set_spot_price(...)	स्पॉट कीमत अपडेट करें

---

त्रुटि हैंडलिंग

SDK प्रत्येक API त्रुटि कोड के लिए संरचित अपवाद कक्षाएं प्रदान करता है।

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # सभी API त्रुटियों के लिए बेस क्लास
    AuthError,          # कोड 3 — अवैध API कुंजी
    RateLimitError,     # कोड 5 — दर-सीमा पार
    InvalidInputError,  # कोड 2 — खराब अनुरोध डेटा
    DBError,            # कोड 1 — डेटाबेस त्रुटि
    InvalidEndpointError,  # कोड 4 — अवैध एंडपॉइंट
    FieldError,         # कोड 6 — फ़ील्ड-विशिष्ट त्रुटि
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("अमान्य API कुंजी। अपनी CLORE_API_KEY जांचें.")
except RateLimitError:
    print("रेट लिमिट पार हुई। SDK स्वचालित रूप से पुन: प्रयास करता है, लेकिन आपने अधिकतम पुन: प्रयास सीमा पार कर दी है.")
except InvalidInputError as e:
    print(f"खराब अनुरोध: {e}")
except FieldError as e:
    # कोड 6 त्रुटियों में प्रतिक्रिया में विवरण शामिल होते हैं
    print(f"फ़ील्ड त्रुटि: {e} (विवरण: {e.response})")
except CloreAPIError as e:
    print(f"API त्रुटि: {e} (कोड: {e.code})")

त्रुटि कोड

कोड	अपवाद	वर्णन
0	—	सफलता
1	DBError	डेटाबेस त्रुटि
2	InvalidInputError	अमान्य इनपुट डेटा
3	AuthError	अमान्य API टोकन
4	InvalidEndpointError	अमान्य एंडपॉइंट
5	RateLimitError	रेट लिमिट पार हुई
6	FieldError	विशिष्ट फ़ील्ड में त्रुटि (देखें त्रुटि प्रतिक्रिया में फ़ील्ड)

सभी अपवाद क्लासेस वारिस होते हैं CloreAPIError और इनमें शामिल हैं:

• e.code — संख्यात्मक त्रुटि कोड

• e.response — पूर्ण API प्रतिक्रिया dict (जब उपलब्ध हो)

---

रेट लिमिटिंग

SDK में एक अंतर्निर्मित रेट लिमिटर शामिल है जो स्वचालित रूप से Clore.ai की सीमाओं को लागू करता है:

एंडपॉइंट	सीमा
अधिकांश एंडपॉइंट	1 अनुरोध/सेकंड
create_order	1 अनुरोध/5 सेकंड

जब API रेट-लिमिट त्रुटि (कोड 5) लौटाता है, SDK लागू करता है घातीय बैकऑफ और पुन: प्रयास करता है तक max_retries बार (डिफ़ॉल्ट: 3). आपको जोड़ने की आवश्यकता नहीं है time.sleep() कॉल्स के बीच।

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

1. प्रत्येक अनुरोध से पहले, रेट लिमिटर न्यूनतम अंतराल के समाप्त होने तक प्रतीक्षा करता है।

2. create_order कॉल्स एक अतिरिक्त 5-सेकंड कूलडाउन लागू करते हैं।

3. रेट-लिमिट त्रुटियों पर, SDK घातीय रूप से पीछे हटता है: 1s → 2s → 4s → ...

4. के बाद max_retries असफल प्रयासों, एक RateLimitError उठाया जाता है।

पुन: प्रयास व्यवहार अनुकूलित करें

client = CloreAI(
    max_retries=5,    # लंबी चलने वाली स्क्रिप्ट्स के लिए अधिक पुन: प्रयास
    timeout=60.0      # धीमे कनेक्शनों के लिए लंबा टाइमआउट
)

---

कॉन्फ़िगरेशन

कॉन्फ़िग फ़ाइल

CLI कॉन्फ़िगरेशन को संग्रहीत करता है ~/.clore/config.json:

{
  "api_key": "your_api_key_here"
}

रिज़ॉल्यूशन क्रम

SDK इस क्रम में API कुंजी हल करता है:

1. api_key कंस्ट्रक्टर को पास किया गया आर्गुमेंट

2. CLORE_API_KEY पर्यावरण चर

3. api_key में फ़ील्ड ~/.clore/config.json

पर्यावरण वेरिएबल

वेरिएबल	वर्णन
CLORE_API_KEY	प्रमाणीकरण के लिए API कुंजी

---

अगले कदम

• CLI संदर्भ — अपने टर्मिनल से Clore.ai का उपयोग करें

• REST API — कस्टम एकीकरण के लिए रॉ API दस्तावेज़

• ऑन-डिमांड बनाम स्पॉट — मूल्य निर्धारण मॉडल को समझें

• उपलब्ध Docker इमेजेज़ — GPU वर्कलोड्स के लिए पूर्व-निर्मित इमेजेज़