Metadata-Version: 2.4
Name: intelion-cloud
Version: 0.7.0
Summary: Python client for the Intelion Cloud API
Author-email: Intelion Cloud <support@intelion.cloud>
License-Expression: MIT
Project-URL: Homepage, https://intelion.cloud
Project-URL: Documentation, https://intelion.cloud/swagger/
Project-URL: Repository, https://github.com/IntelionCloud/ic_python_client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Dynamic: license-file

# Intelion Cloud Python Client

[![PyPI](https://img.shields.io/pypi/v/intelion-cloud.svg)](https://pypi.org/project/intelion-cloud/)
[![Python](https://img.shields.io/pypi/pyversions/intelion-cloud.svg)](https://pypi.org/project/intelion-cloud/)
[![License](https://img.shields.io/pypi/l/intelion-cloud.svg)](https://github.com/IntelionCloud/ic_python_client/blob/main/LICENSE)

Official Python SDK for the [Intelion Cloud](https://intelion.cloud) GPU cloud API (`/api/v2/`).

Sync and async clients, typed dataclass models, automatic pagination, retries with exponential backoff.

## Install

```bash
pip install intelion-cloud
```

Requires Python 3.9+.

## Quickstart

```python
from intelion_cloud import IntelionCloud

client = IntelionCloud(token="your_api_token")

# List your cloud servers
for server in client.cloud_servers.list():
    print(server.id, server.name, server.status)

# Start / stop a server
client.cloud_servers.start(server_id=42)
client.cloud_servers.stop(server_id=42)

# Create a new server
new_server = client.cloud_servers.create(
    name="my-h100-box",
    flavor_id=1,          # FlavorConfig PK
    ssd_count=128,        # network disk size, GB (128 to 2048, step 128)
    os_id=1,              # OperationalSystemImage PK
    price_plan=0,         # 0 = hourly, 1 = monthly, ...
)

client.close()
```

### Async client

```python
import asyncio
from intelion_cloud import AsyncIntelionCloud

async def main():
    async with AsyncIntelionCloud(token="your_api_token") as client:
        me = await client.users.me()
        print(me.username, me.current_balance_rub_cents)

asyncio.run(main())
```

### Context manager

```python
with IntelionCloud(token="...") as client:
    servers = client.cloud_servers.list()
```

## Available resources

| Resource | Methods |
|---|---|
| `client.cloud_servers` | `list()`, `get()`, `create()`, `update()`, `start()`, `stop()`, `reboot()`, `delete()`, `get_status()`, `get_password()`, `clone()`, `migrate()` |
| `client.flavors` | `list()` |
| `client.os_images` | `list(flavor_id=, gpu_id=)` |
| `client.users` | `me()`, `get()`, `update()` |
| `client.ssh_keys` | `list()`, `create(public_key, name=)`, `delete(key_id)` |
| `client.gpus` / `client.cpus` / `client.ram` / `client.ssds` | `list(page=)`, `get(id)` |
| `client.software_addons` | `list()`, `get(id)` |
| `client.inference_api_keys` | `list()`, `get()`, `create()`, `update()`, `revoke()`, `rotate()`, `usage()`, `usage_range()`, `usage_range_csv()`, `models()`, `access_status()`, `request_access()` |

## AI API keys

Keys for LLM inference (`https://aiapi.intelion.cloud/v1/...`) — **not** the
same thing as your main `token` above, which authenticates every call in
this SDK. AI API is self-serve, gated on account balance:

```python
status = client.inference_api_keys.access_status()
if not status.granted:
    print(f"Не хватает {status.shortfall_rub_cents / 100:.2f} ₽")
    client.inference_api_keys.request_access()  # raises PaymentRequiredError if still short

key = client.inference_api_keys.create(name="prod-agent", rate_limit_rpm=60)
print(key.api_key)  # raw value — shown ONLY here, persist it now

usage = client.inference_api_keys.usage_range(date_from="2026-05-01", date_to="2026-05-31")
print(usage.total_rub_cents)  # reconciles with «История операций» for the same range

# Replace the key's value without losing its usage history; the old value
# keeps working for grace_period_hours (default 24, 0 = retire immediately).
rotated = client.inference_api_keys.rotate(key.key_hash, grace_period_hours=24)
print(rotated.new_key.api_key)
```

## Usage act costs

Every usage act (`server.usage_act`, `last_usage_act`, `last_finished_usage_act`,
`resume_usage_act`) carries server-computed costs in kopecks: `next_charge_rub_cents`
(the next debit), `full_period_cost_rub_cents` (current period incl. prepay) and
`full_planned_cost_rub_cents` (stand-alone price of the planned period, the number
to show in a "confirm start" dialog), plus the act's own `discount_percent` and the
applied `promocode_code` / `promocode_discount_value`. Do not recompute them
client-side.

## Cold storage

A stopped server keeps its boot volume for free for a while (`cold_free` says
until when and at what price after), then the compute is released and the
volume is billed as cold storage (`cold_storage`). Both blocks are `None` on a
running server; `resume_usage_act` is the server-side price of resuming a cold
server.

```python
from intelion_cloud import ServerState

server = client.cloud_servers.get(42)
if server.server_state in (ServerState.COLD_STORAGE, ServerState.COLD_GRACE):
    print(f"{server.cold_storage.storage_gb} GB, debt {server.cold_storage.accrued_debt_rub_cents} kopecks")
    print(f"resume costs {server.resume_usage_act.next_payment.amount_rub_cents} kopecks")
elif server.cold_free:
    print(f"free storage until {server.cold_free.free_until_dt}")
```

## Rental term

A monthly plan is a term too: a server on `price_plan` 1, 3, 6 or 12 months
needs the term conditions signed in the web panel when
`server.requires_term_consent` is true, otherwise `start` (and `reinstall_os`
without an open period) is refused with 409 `TERM_CONDITIONS_REQUIRED`. Servers
rented before the reform without a signature still start and report
`requires_term_consent == False`. Under a running term `stop` only powers the VM
off (the term stays open and charges continue) and `delete` is refused with 409
`TERM_TERMINATION_REQUIRED`. Servers on a term plan carry a read-only
snapshot of the commitment: `term_months`, `term_discount_percent`,
`term_started_at`, `term_ends_at` (already shifted by any downtime on our side),
`term_state` and the flags the server derives from them.

```python
from intelion_cloud import ConflictError, TermConflictCode, TermState

server = client.cloud_servers.get(42)
if server.term_state == TermState.ACTIVE:
    print(f"{server.term_months} months at -{server.term_discount_percent}% until {server.term_ends_at}")

# Turning auto-renewal off is always allowed. Turning it on under a running
# confirmed term extends the term: only the customer in the web panel.
try:
    client.cloud_servers.update(42, is_auto_renewal=True)
except ConflictError as e:
    if e.error_code == TermConflictCode.AUTO_RENEWAL_CONSENT_REQUIRED:
        print(e)  # the server's message for the user
```

Under a term `start(is_auto_renewal=...)` ignores the argument: the toggle stays
as in the signed consent. Consent, renewal and early termination are
personal-account actions and are not part of API v2; the SDK only reads their
state. A company or sole proprietor cannot clear `company_name` through
`users.update` (400): the name decides the client kind of the term.

## Authentication

Get your API token from the [Intelion Cloud dashboard](https://intelion.cloud). The client sends it as `Authorization: Token {token}`.

## Error handling

```python
from intelion_cloud import (
    AuthenticationError, NotFoundError, ConflictError,
    RateLimitError, ValidationError, ServerError, PaymentRequiredError,
)

try:
    server = client.cloud_servers.get(999)
except NotFoundError:
    print("Server not found")
except AuthenticationError:
    print("Invalid token")
except ValidationError as e:
    print("Field errors:", e.field_errors)
```

## Links

- **Homepage:** https://intelion.cloud
- **API docs (Swagger):** https://intelion.cloud/api/
- **Source:** https://github.com/IntelionCloud/ic_python_client

## License

MIT
