Metadata-Version: 2.4
Name: ibee
Version: 0.3.0
Summary: Official Python SDK for the IBEE Solutions API
Author-email: IBEE Solutions <support@ibee.ai>
License-Expression: MIT
Project-URL: Homepage, https://ibee.ai
Project-URL: Documentation, https://ibee.ai/docs/api-reference
Project-URL: Repository, https://github.com/devs-ibee/ibee-python
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.21.2
Requires-Dist: pydantic>=1.9.2
Requires-Dist: typing_extensions>=4.0.0
Provides-Extra: aiohttp
Requires-Dist: httpx-aiohttp; extra == "aiohttp"
Dynamic: license-file

# IBEE Solutions Python SDK

Official Python SDK for the IBEE Solutions API. Manage cloud VMs, GPU VMs,
VPC networking, Reserved IPs, firewalls, load balancers, object storage,
Block Storage, CDN, and secrets programmatically.

## Installation

```bash
pip install ibee
```

## Usage

```python
from ibee import Ibee

client = Ibee(token="YOUR_TOKEN")

# Product create methods send one request. The public API edge checks billing
# authoritatively before routing billable creates. Applications can optionally
# call client.billing.check_resource_eligibility(...) for a UI preview.

# List cloud VMs
vms = client.cloud_vms.list_cloud_vms(workspace_id="907479")

# Create a cloud VM
vm = client.cloud_vms.create_cloud_vm(
    workspace_id="907479",
    idempotency_key="create-web-server-01",
    name="web-server",
    site_id="site_blr_01",
    plan_id="plan_standard_2c_4g",
    template_id="tmpl_ubuntu_2204",
    os_distro="ubuntu",
    os_type="linux",
    cpu=2,
    ram_mb=4096,
)

# List GPU VMs
gpu_vms = client.gpu_vms.list_gpu_vms(workspace_id="907479")

# Discover typed sites, plans, and images before creating a VM
sites = client.compute_catalog.list_compute_sites(workspace_id="907479")
plans = client.compute_catalog.list_compute_plans(
    workspace_id="907479",
    vm_type="cloud",
    site_id="site_blr_01",
    currency="INR",
    billing_interval="MONTHLY",
)
images = client.compute_catalog.list_compute_images(
    workspace_id="907479",
    vm_type="cloud",
    site_id="site_blr_01",
)

# Manage secrets
stores = client.secret_store.list_secret_stores(workspace_id="907479")

# List object storage buckets
buckets = client.object_storage.list_buckets(workspace_id="907479")
bucket = client.object_storage.create_bucket(
    workspace_id="907479",
    name="production-assets",
    region="in-south-1",
    is_public=False,
)
credential = client.object_storage.create_s3credential(
    workspace_id="907479",
    name="application-key",
    bucket_scope="specific",
    allowed_buckets=["production-assets"],
)

# Create an isolated VPC and reserve a public IP
vpc = client.vpcs.create_vpc(
    workspace_id="907479",
    name="production",
    site_id="site_blr_01",
    cidr="10.20.0.0/24",
)
reserved_ip = client.reserved_ips.reserve_ip(
    workspace_id="907479",
    site_id="site_blr_01",
    label="production-ingress",
)

# Firewall and load-balancer APIs use the same workspace scope
firewall_groups = client.firewalls.list_firewall_groups(workspace_id="907479")
load_balancers = client.load_balancers.list_load_balancers(workspace_id="907479")
```

The `vpcs` resource also manages subnets, VM attachments, NAT gateways, and
port-forwarding rules. `reserved_ips` includes attach, move, and detach;
`firewalls` and `load_balancers` provide their complete public lifecycle.
Synchronous and async clients expose matching methods.

To create a VM with explicit placement, pass the selected IDs. Omit `site_id`
to let IBEE select an available site automatically:

```python
vm = client.cloud_vms.create_cloud_vm(
    workspace_id="907479",
    idempotency_key="create-web-server-01",
    name="web-server-01",
    site_id="site_blr_01",
    os_distro="ubuntu",
    os_type="linux",
    template_id="tmpl_ubuntu_2204",
    plan_id="plan_standard_2c_4g",
    cpu=2,
    ram_mb=4096,
    disk_gb=80,
    ssh_key_ids=["ssh_key_123"],
    tags=["prod", "web"],
)
```

`plan_id` is the selected instance plan. `template_id` is the selected OS
template or image. `ssh_key_ids` are the SSH keys to inject at first boot.
In the current SDK, `cpu` and `ram_mb` are still required fallback fields even
when `plan_id` is provided.

## Secret Store lifecycle

The synchronous and asynchronous Secret Store clients expose the complete store,
secret-version, application-identity, and identity-scope lifecycle. Every call
is scoped with `workspace_id`; value and identity-access responses can contain
sensitive credentials and should never be logged.

```python
store = client.secret_store.create_secret_store(
    workspace_id="710995", name="payments"
)
secret = client.secret_store.create_secret(
    store.id,
    workspace_id="710995",
    secret_name="database",
    value={"username": "payments", "password": "replace-me"},
)
client.secret_store.patch_secret_value(
    secret.id,
    workspace_id="710995",
    value={"username": "payments-v2"},
)
versions = client.secret_store.list_secret_versions(
    secret.id, workspace_id="710995"
)
client.secret_store.rollback_secret(
    secret.id, workspace_id="710995", version=1
)
```

Stores support archive, unarchive, and explicit permanent deletion. Secrets
support batch creation, soft deletion, undelete, version destruction, rollback,
and permanent deletion. Workload identities support AppRole or Kubernetes
authentication, credential rotation, session revocation, and per-store scopes.
Permanent-delete and version-destroy operations are irreversible.

## Complete VM lifecycle

Cloud and GPU VM clients expose matching power, access, resize, volume,
monitoring, snapshot, and backup operations. Mutating operations that accept an
idempotency key can be retried safely with the same key:

```python
# Power and access
operation = client.cloud_vms.stop_cloud_vm(
    "vm_123",
    workspace_id="907479",
    idempotency_key="stop-vm-123-01",
)
client.cloud_vms.update_cloud_vm_access(
    "vm_123",
    workspace_id="907479",
    idempotency_key="rotate-access-vm-123-01",
    ssh_key_ids=["ssh_key_456"],
    ssh_key_mode="add",
)

# Precheck and apply a resize
decision = client.cloud_vms.precheck_cloud_vm_resize(
    "vm_123", workspace_id="907479", cpu=4, ram_mb=8192
)
operation = client.cloud_vms.resize_cloud_vm(
    "vm_123",
    workspace_id="907479",
    idempotency_key="resize-vm-123-01",
    cpu=4,
    ram_mb=8192,
)

# Volumes, events, and time-series metrics
client.cloud_vms.attach_cloud_vm_volume(
    "vm_123",
    workspace_id="907479",
    idempotency_key="attach-volume-789-01",
    volume_id="volume_789",
)
events = client.cloud_vms.list_cloud_vm_events("vm_123", workspace_id="907479")
metrics = client.cloud_vms.get_cloud_vm_metrics_timeseries(
    "vm_123", workspace_id="907479", range="24h"
)

# Snapshots and backups
snapshot = client.cloud_vms.create_cloud_vm_snapshot(
    "vm_123", workspace_id="907479", name="before-upgrade", mode="root_only"
)
policy = client.cloud_vms.enable_cloud_vm_backups(
    "vm_123", workspace_id="907479", retention_days=14
)
backup = client.cloud_vms.create_cloud_vm_backup_run(
    "vm_123", workspace_id="907479", reason="before-upgrade"
)

# Short-lived graphical console session. Treat connect_url as a secret: do not
# log or persist it, and close the session when finished.
session = client.vm_console.create_vm_console_session(
    workspace_id="907479", vm_id="vm_123", vm_type="cloud"
)
client.vm_console.close_vm_console_session(
    session.session_id, workspace_id="907479", reason="finished"
)
```

Use the corresponding `gpu_vms` methods for GPU instances. Snapshot and backup
item/status methods use family-specific public routes, so cloud and GPU recovery
records cannot be mixed accidentally. The async client provides the same method
names and arguments.

## Environments

The client defaults to the production API (`https://api.ibee.ai/v1`).
`IbeeEnvironment.PRODUCTION` is an explicit alias for that default. Use
`IbeeEnvironment.DEVELOPMENT` for the development API (`https://api.ibee.co.in/v1`):

```python
from ibee import Ibee
from ibee.environment import IbeeEnvironment

client = Ibee(token="IBEE_DEV_TOKEN", environment=IbeeEnvironment.DEVELOPMENT)
```

Billable creates are admitted at the public API edge before the request reaches
the existing product service. This applies equally to raw REST, the Python and
TypeScript SDKs, and the CLI, so create helpers do not perform duplicate billing
or catalog calls. The explicit eligibility method remains available as an
optional, point-in-time preview and does not reserve funds.

Block Storage is exposed at `client.block_storage` with list, create, get,
delete, operations, attach, detach, and resize methods. CDN is exposed at
`client.cdn` with distribution, static-website, custom-domain, URL-generation,
verification, and cache-purge methods.

Requires Python 3.10+.

## Async usage

```python
import asyncio
from ibee import AsyncIbee

async def main():
    client = AsyncIbee(token="YOUR_TOKEN")
    vms = await client.cloud_vms.list_cloud_vms(workspace_id="907479")
    print(vms)

asyncio.run(main())
```

## Authentication

Generate a platform API token from the IBEE portal under Settings > Platform API Tokens. Use the token with the `token` parameter when creating the client.

## Documentation

Production API reference: [https://ibee.ai/docs/api-reference](https://ibee.ai/docs/api-reference)

## License

MIT
