Metadata-Version: 2.4
Name: xinference-cloud
Version: 0.1.0
Summary: Python SDK for Xinference Cloud management APIs
License-Expression: Apache-2.0
Project-URL: Homepage, https://xinference.io
Project-URL: Documentation, https://xinference-kb-html.onrender.com/overview.html
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff==0.12.3; extra == "dev"
Dynamic: license-file

# Xinference Cloud Python SDK

Official Python SDK for the [Xinference Cloud](https://xinference.io) management
APIs: browse the deployable model catalog, create and manage model deployments,
and issue inference API keys — all from Python.

## Installation

```bash
pip install xinference-cloud
```

Requires Python 3.11 or later. The only runtime dependency is
[httpx](https://www.python-httpx.org/).

## Authentication

The SDK authenticates with an **SDK management credential** scoped to your
organization. You can obtain one in two ways:

- **Console UI** — the *SDK Credentials* page in the Xinference Cloud console
  (in development, rolling out soon).
- **Management API** — while signed in to the console, create one via
  `POST /api/v1/organization/sdk-credentials`:

  ```js
  // Run in your browser DevTools console while signed in
  const res = await fetch("/api/v1/organization/sdk-credentials", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "my-sdk-credential" }),
  });
  console.log((await res.json()).key);
  ```

The credential key is shown **only once** at creation time — store it securely.
If you lose it, revoke the credential and create a new one.

## Quickstart

```python
from xinference_cloud import XinferenceCloud

client = XinferenceCloud(
    base_url="https://<your-region>.cloud.xinference.co",
    credential="<your-sdk-credential>",
)

with client:
    # Browse the deployable model catalog
    models = client.deployable_models.list(enabled_only=True)

    # Deploy a model and wait until it is running
    deployment = client.deployments.create(model_name="qwen2.5-instruct")
    deployment = client.deployments.wait(deployment["id"], timeout=600)

    # Issue an inference API key bound to the deployment
    api_key = client.inference_api_keys.create(
        name="production",
        deployment_ids=[deployment["id"]],
    )
```

Instead of passing arguments explicitly, you can set the
`XINFERENCE_CLOUD_BASE_URL` and `XINFERENCE_CLOUD_CREDENTIAL` environment
variables and construct the client with `XinferenceCloud.from_env()`.

## Resources

| Resource | Methods |
|---|---|
| `client.deployable_models` | `list`, `get` |
| `client.deployments` | `create`, `list`, `list_page`, `get`, `wait`, `terminate`, `delete` |
| `client.inference_api_keys` | `list`, `list_deployment_options`, `create`, `update`, `revoke` |

`deployments.wait()` polls a deployment until it reaches a target status
(`running` by default), raises `RuntimeError` if it enters a failure status,
and raises `TimeoutError` on timeout.

## Error handling

API errors raise `xinference_cloud.APIStatusError`, which carries the HTTP
`status_code`, the server error `code` (when provided), and the raw
`httpx.Response`:

```python
from xinference_cloud import APIStatusError

try:
    client.deployments.get("unknown-id")
except APIStatusError as exc:
    print(exc.status_code, exc.code, str(exc))
```

## License

[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0)
