> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/developers/python-sdk.md).

# Python SDK (clore-ai)

द **clore-ai** पैकेज ... के लिए आधिकारिक Python SDK है [Clore.ai](https://clore.ai) GPU मार्केटप्लेस। यह पूरे REST API को एक साफ़, टाइप-सुरक्षित इंटरफ़ेस में लपेटता है, जिसमें अंतर्निहित rate limiting, स्वचालित पुनः प्रयास, और संरचित त्रुटि-प्रबंधन शामिल है — ताकि आप GPU किराये पर लेने पर ध्यान दे सकें, HTTP plumbing पर नहीं।

***

## स्थापना

```bash
pip install clore-ai
```

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

पैकेज Python SDK और ... दोनों को इंस्टॉल करता है [`clore` CLI](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/developers/cli-guide.md).

***

## प्रमाणीकरण

अपनी API key प्राप्त करें [Clore.ai डैशबोर्ड](https://clore.ai) → **API** अनुभाग से।

### विकल्प 1: परिवेश चर (अनुशंसित)

```bash
export CLORE_API_KEY=your_api_key_here
```

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

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

```bash
clore config set api_key YOUR_API_KEY
```

यह key को इसमें सहेजता है `~/.clore/config.json`.

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

```python
from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")
```

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

***

## त्वरित शुरुआत

```python
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`)

### कंस्ट्रक्टर

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

क्लाइंट स्वचालित सफ़ाई के लिए context managers का समर्थन करता है:

```python
with CloreAI() as client:
    wallets = client.wallets()
    # client.close() स्वचालित रूप से कॉल होता है
```

***

### `wallets()`

अपने वॉलेट बैलेंस और जमा पते प्राप्त करें।

```python
wallets = client.wallets()

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

**लौटाता है:** `List[Wallet]`

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

***

### `marketplace()`

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

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

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

# पर्याप्त RAM वाले मल्टी-GPU rigs
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)
```

**पैरामीटर:**

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

**लौटाता है:** `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` | GB में RAM                                               |
| `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`, etc.) |
| `मूल्य`       | `ServerPrice \| None`  | पूर्ण मूल्य ऑब्जेक्ट (`price.usd.on_demand_usd`, `price.usd.spot`, `price.on_demand`, etc.)      |
| `rented`      | `bool \| None`         | क्या सर्वर वर्तमान में किराये पर दिया गया है                                                     |
| `reliability` | `float \| None`        | सर्वर विश्वसनीयता स्कोर                                                                          |
| `rating`      | `ServerRating \| None` | सर्वर रेटिंग (`rating.avg`, `rating.cnt`)                                                        |

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

***

### `my_servers()`

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

```python
my_servers = client.my_servers()

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

**लौटाता है:** `List[MyServer]`

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

***

### `server_config(server_name)`

आपके द्वारा होस्ट किए गए किसी विशिष्ट सर्वर का कॉन्फ़िगरेशन प्राप्त करें।

```python
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}")
```

**पैरामीटर:**

| पैरामीटर    | प्रकार | विवरण        |
| ----------- | ------ | ------------ |
| `सर्वर नाम` | `str`  | सर्वर का नाम |

**लौटाता है:** `ServerConfig`

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

***

### `my_orders(include_completed)`

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

```python
# केवल सक्रिय ऑर्डर
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` | `असत्य`  | पूर्ण/समाप्त हुए ऑर्डर शामिल करें |

**लौटाता है:** `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`   | भुगतान मुद्रा                      |
| `मूल्य`       | `float \| None` | ऑर्डर की प्रति दिन कीमत            |
| `pub_cluster` | `str \| None`   | पहुंच के लिए सार्वजनिक होस्टनेम/IP |
| `tcp_ports`   | `dict \| None`  | TCP पोर्ट मैपिंग                   |

***

### `spot_marketplace(server_id)`

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

```python
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`

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

***

### `create_order(...)`

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

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

```python
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}")
```

#### स्पॉट ऑर्डर

```python
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 notebook token (अधिकतम 32 वर्ण)                                                                                                                                                                         |
| `command`            | `str`       | नहीं       | कंटेनर शुरू होने के बाद चलाने के लिए शेल कमांड                                                                                                                                                                  |
| `spot_price`         | `float`     | केवल स्पॉट | स्पॉट ऑर्डर के लिए प्रति दिन कीमत                                                                                                                                                                               |
| `required_price`     | `float`     | नहीं       | एक विशिष्ट कीमत लॉक करें (केवल ऑन-डिमांड)                                                                                                                                                                       |
| `autossh_entrypoint` | `str`       | नहीं       | Clore.ai SSH एंट्रीपॉइंट का उपयोग करें                                                                                                                                                                          |
| `gpu_count`          | `int`       | नहीं       | केवल उन सर्वरों पर N GPU किराये पर लें जिनमें [आंशिक किराया](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-renters/partial-gpu-rental.md) (केवल ऑन-डिमांड); पूरे rig को किराये पर लेने के लिए इसे छोड़ दें |
| `gpu_indices`        | `list[int]` | नहीं       | से सटीक GPU स्लॉट `partial_gpu_rental.free_indices`; लंबाई बराबर होनी चाहिए `gpu_count`; ऑटो-चयन के लिए छोड़ दें                                                                                                |

> **स्वतः-नवीनीकरण:** SDK (0.1.2 और उससे पहले) में कोई `create_order` पैरामीटर अभी तक नहीं हैं `rental_hours`, `auto_renew` या `auto_renew_max_price`और इसके लिए कोई मेथड नहीं हैं `set_order_auto_renew` या `order_renewals`. जब तक ऐसा नहीं होता, उन REST endpoints को सीधे कॉल करें: [`create_order`](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-hosts/api.md#id-10-create_order), [`set_order_auto_renew`](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-hosts/api.md#id-16-set_order_auto_renew) और [`order_renewals`](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-hosts/api.md#id-17-order_renewals). `Order` ऑब्जेक्ट API द्वारा जोड़े गए फ़ील्ड बनाए रखते हैं (`extra="allow"`), इसलिए `order.auto_renew`, `order.rental_end` और `order.term_end` उन ऑर्डर्स पर पढ़े जा सकते हैं जिनमें ये मौजूद हों; उपयोग करें `getattr(order, "auto_renew", None)` उस फ़ील्ड के लिए जो किसी ऑर्डर में न हो सकती हो।

**लौटाता है:** कच्चा API response (`{"code": 0}` सफल होने पर); बनाए गए ऑर्डर को इसके माध्यम से प्राप्त करें `my_orders()`

> **दर सीमा:** `create_order` कॉलों के बीच 5 सेकंड की विशेष cooldown होती है। SDK इसे स्वतः लागू करता है।

***

### `cancel_order(order_id, issue)`

एक सक्रिय ऑर्डर या spot offer को रद्द करें। वैकल्पिक रूप से सर्वर के बारे में कोई समस्या रिपोर्ट करें।

```python
# सरल रद्दीकरण
client.cancel_order(order_id=38)

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

**पैरामीटर:**

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

**लौटाता है:** `Dict[str, Any]`

***

### `set_server_settings(...)`

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

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

**पैरामीटर:**

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

**लौटाता है:** `Dict[str, Any]`

***

### `set_spot_price(order_id, price)`

अपने spot market offer की कीमत अपडेट करें।

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

**पैरामीटर:**

| पैरामीटर   | प्रकार  | विवरण              |
| ---------- | ------- | ------------------ |
| `order_id` | `int`   | Spot ऑर्डर/ऑफ़र ID |
| `मूल्य`    | `float` | प्रति दिन नई कीमत  |

**लौटाता है:** `Dict[str, Any]`

> **नोट:** आप spot कीमतें केवल हर 600 सेकंड में एक बार, और सीमित step size से ही कम कर सकते हैं। API लौटाता है `code: 6` यदि आप इन सीमाओं से अधिक जाते हैं, तो विवरण के साथ।

***

## Async Client (`AsyncCloreAI`)

द `AsyncCloreAI` client वही मेथड प्रदान करता है जो `CloreAI`का है, लेकिन सभी coroutines लौटाते हैं। इसका उपयोग तब करें जब आपको concurrent API calls चाहिए हों या आप किसी async application के भीतर काम कर रहे हों।

### मूल उपयोग

```python
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 calls को समानांतर में चलाएँ `asyncio.gather`:

```python
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)} उपलब्ध, सबसे सस्ता ${cheapest:.4f}/h")
            else:
                print(f"{name}: कोई उपलब्ध नहीं")

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)` | spot market offers प्राप्त करें       |
| `await create_order(...)`           | एक नया ऑर्डर बनाएँ                    |
| `await cancel_order(...)`           | एक ऑर्डर रद्द करें                    |
| `await set_server_settings(...)`    | सर्वर सेटिंग्स अपडेट करें             |
| `await set_spot_price(...)`         | spot मूल्य अपडेट करें                 |

***

## त्रुटि प्रबंधन

SDK हर API error code के लिए संरचित exception classes प्रदान करता है।

```python
from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,      # सभी API errors के लिए base class
    AuthError,          # Code 3 — अमान्य API key
    RateLimitError,     # Code 5 — rate limit पार हो गया
    InvalidInputError,  # Code 2 — गलत request data
    DBError,            # Code 1 — database error
    InvalidEndpointError,  # Code 4 — अमान्य endpoint
    FieldError,         # Code 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 key. अपना CLORE_API_KEY जांचें.")
except RateLimitError:
    print("Rate limit लगा। SDK स्वतः पुनः प्रयास करता है, लेकिन आपने अधिकतम retries तक पहुँच गए.")
except InvalidInputError as e:
    print(f"गलत अनुरोध: {e}")
except FieldError as e:
    # Code 6 त्रुटियों में response में विवरण शामिल होते हैं
    print(f"फ़ील्ड त्रुटि: {e} (विवरण: {e.response})")
except CloreAPIError as e:
    print(f"API त्रुटि: {e} (code: {e.code})")
```

### त्रुटि कोड

| Code | Exception              | विवरण                                                         |
| ---- | ---------------------- | ------------------------------------------------------------- |
| 0    | —                      | सफलता                                                         |
| 1    | `DBError`              | डेटाबेस त्रुटि                                                |
| 2    | `InvalidInputError`    | अमान्य इनपुट डेटा                                             |
| 3    | `AuthError`            | अमान्य API token                                              |
| 4    | `InvalidEndpointError` | अमान्य endpoint                                               |
| 5    | `RateLimitError`       | Rate limit पार हो गया                                         |
| 6    | `FieldError`           | विशिष्ट फ़ील्ड में त्रुटि (देखें `error` response में फ़ील्ड) |

सभी exception classes `CloreAPIError` से विरासत में आती हैं और इनमें शामिल हैं:

* `e.code` — संख्यात्मक error code
* `e.response` — पूर्ण API response dict (जब उपलब्ध हो)

***

## दर सीमित करना

SDK में एक अंतर्निहित rate limiter शामिल है जो Clore.ai की सीमाएँ स्वतः लागू करता है:

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

जब API rate-limit error (code 5) लौटाता है, तो SDK लागू करता है **exponential backoff** और पुनः प्रयास करता है `max_retries` बार तक (default: 3). आपको जोड़ने की आवश्यकता नहीं है `time.sleep()` कॉलों के बीच।

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

1. प्रत्येक अनुरोध से पहले, rate limiter तब तक प्रतीक्षा करता है जब तक न्यूनतम अंतराल पूरा न हो जाए।
2. `create_order` कॉलों के लिए अतिरिक्त 5 सेकंड का cooldown लागू होता है।
3. Rate-limit errors पर, SDK exponential रूप से back off करता है: 1s → 2s → 4s → ...
4. के बाद `max_retries` विफल प्रयासों के, एक `RateLimitError` उठाया जाता है।

### retry व्यवहार अनुकूलित करें

```python
client = CloreAI(
    max_retries=5,    # लंबे चलने वाले scripts के लिए अधिक retries
    timeout=60.0      # धीमे connections के लिए लंबा timeout
)
```

***

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

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

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

```json
{
  "api_key": "your_api_key_here"
}
```

### समाधान क्रम

SDK API key को इस क्रम में resolve करता है:

1. `api_key` कन्स्ट्रक्टर को पास किया गया तर्क
2. `CLORE_API_KEY` environment variable
3. `api_key` में फ़ील्ड `~/.clore/config.json`

### परिवेश चर

| चर              | विवरण                     |
| --------------- | ------------------------- |
| `CLORE_API_KEY` | प्रमाणीकरण के लिए API key |

***

## अगले चरण

* [**CLI संदर्भ**](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/developers/cli-guide.md) — अपने टर्मिनल से Clore.ai का उपयोग करें
* [**REST API**](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-hosts/api.md) — कस्टम integrations के लिए कच्चा API दस्तावेज़ीकरण
* [**On-Demand बनाम Spot**](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-renters/on-demand-vs-spot.md) — मूल्य निर्धारण मॉडल समझें
* [**उपलब्ध Docker Images**](https://docs.clore.ai/clore.ai/clore.ai-eng-hi/for-renters/docker-images.md) — GPU workloads के लिए पहले से बने images


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clore.ai/clore.ai/clore.ai-eng-hi/developers/python-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
