### Install from Wheel File

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Install the Gradient Python library using a locally built wheel file.

```sh
pip install ./path-to-wheel-file.whl
```

--------------------------------

### Add and Run Examples

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Add new example Python files to the `examples/` directory and make them executable. These files are not modified by the generator and can be freely edited.

```python
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```sh
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Install from Git

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Install the Gradient Python library directly from its Git repository using pip.

```sh
pip install git+ssh://git@github.com/digitalocean/gradient-python.git
```

--------------------------------

### Install Gradient Python Library

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Install the Gradient Python library using pip. This command installs the stable version from PyPI.

```sh
pip install gradient
```

--------------------------------

### Install Gradient with aiohttp Support

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Install the Gradient Python library with optional aiohttp support for improved concurrency in asynchronous operations.

```sh
pip install gradient[aiohttp]
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

If not using Rye, install development dependencies using pip and the lock file.

```sh
pip install -r requirements-dev.lock
```

--------------------------------

### Synchronous Client Initialization and Usage

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Demonstrates how to initialize synchronous clients for DigitalOcean API, Gradient Serverless Inference, and Gradient Agent Inference, along with example calls.

```APIDOC
## Synchronous Client Initialization and Usage

### Description
Initialize synchronous clients for different Gradient services and demonstrate basic API calls.

### Initialization
```python
import os
from gradient import Gradient

# Initialize DigitalOcean API client
api_client = Gradient(
    access_token=os.environ.get(
        "DIGITALOCEAN_ACCESS_TOKEN"
    )
)

# Initialize Gradient Serverless Inference client
inference_client = Gradient(
    model_access_key=os.environ.get(
        "GRADIENT_MODEL_ACCESS_KEY"
    )
)

# Initialize Gradient Agent Inference client
agent_client = Gradient(
    agent_access_key=os.environ.get(
        "GRADIENT_AGENT_ACCESS_KEY"
    ),
    agent_endpoint="https://my-agent.agents.do-ai.run",
)
```

### Usage Examples

#### DigitalOcean API
```python
api_response = api_client.agents.list()
print("---")
if api_response.agents:
    print(api_response.agents[0].name)
```

#### Serverless Inference
```python
inference_response = inference_client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="llama3.3-70b-instruct",
)

print("---")
print(inference_response.choices[0].message.content)
```

#### Agent Inference
```python
agent_response = agent_client.agents.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of Portugal?",
        }
    ],
    model="llama3.3-70b-instruct",
)

print("---")
print(agent_response.choices[0].message.content)
```

### Authentication
API keys can be provided as keyword arguments or set via environment variables (`DIGITALOCEAN_ACCESS_TOKEN`, `GRADIENT_MODEL_ACCESS_KEY`, `GRADIENT_AGENT_ACCESS_KEY`). Using environment variables with `python-dotenv` is recommended to avoid storing keys in source control.
```

--------------------------------

### Use Gradient API Client

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Example of listing agents using the synchronous API client. Ensure the DIGITALOCEAN_ACCESS_TOKEN is set in your environment.

```python
api_response = api_client.agents.list()
print("---")
if api_response.agents:
    print(api_response.agents[0].name)
```

--------------------------------

### Sync Dependencies with Rye

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

If installing Rye manually, use this command to sync all project dependencies, including features.

```sh
rye sync --all-features
```

--------------------------------

### Perform Agent Inference

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Example of creating a chat completion using the agent inference client. Requires GRADIENT_AGENT_ACCESS_KEY and agent_endpoint to be configured.

```python
agent_response = agent_client.agents.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of Portugal?",
        }
    ],
    model="llama3.3-70b-instruct",
)

print("---")
print(agent_response.choices[0].message.content)
```

--------------------------------

### Create Action for Image

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Initiate an action on a specific image. This is typically used for operations like starting or stopping an image process.

```python
client.gpu_droplets.images.actions.create(image_id, **params) -> Action
```

--------------------------------

### Perform Serverless Inference

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Example of creating a chat completion using the serverless inference client. Requires GRADIENT_MODEL_ACCESS_KEY to be set.

```python
inference_response = inference_client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="llama3.3-70b-instruct",
)

print("---")
print(inference_response.choices[0].message.content)
```

--------------------------------

### Create Chat Completion

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

This example demonstrates how to create a chat completion request using the Gradient client. It shows how to specify messages and the desired model. It also mentions the `APITimeoutError` that can be thrown on timeout and the default retry behavior.

```APIDOC
## POST /chat/completions

### Description
Creates a chat completion request.

### Method
POST

### Endpoint
`/chat/completions`

### Parameters
#### Request Body
- **messages** (list[dict]) - Required - A list of message objects, each with a 'role' and 'content'.
- **model** (str) - Required - The model to use for the completion.

### Request Example
```python
client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="llama3.3-70b-instruct",
)
```

### Response
#### Success Response (200)
- **completion** (object) - The chat completion object.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      }
    }
  ]
}
```
```

--------------------------------

### Access Raw HTTP Response Headers

Source: https://context7.com/digitalocean/gradient-python/llms.txt

This example shows how to access raw HTTP response headers, such as 'x-request-id', when making API calls. It also demonstrates parsing the response body into a normal object.

```python
import httpx
from gradient import Gradient

client = Gradient(model_access_key="<key>")

# Access response headers
raw = client.chat.completions.with_raw_response.create(
    model="llama3.3-70b-instruct",
    messages=[{"role": "user", "content": "Hello"}],
)
print(raw.headers.get("x-request-id"))
completion = raw.parse()    # returns the normal CompletionCreateResponse
print(completion.choices[0].message.content)
```

--------------------------------

### Perform Async Chat Completion

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Example of performing a chat completion asynchronously using the AsyncGradient client. The call must be awaited within an async function.

```python
async def main() -> None:
    completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "What is the capital of France?",
            }
        ],
        model="llama3.3-70b-instruct",
    )
    print(completion.choices)

asyncio.run(main())
```

--------------------------------

### Client Initialization

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Demonstrates how to initialize both synchronous and asynchronous Gradient clients with different credential types and optional HTTP tuning parameters.

```APIDOC
## Client Initialization

The `Gradient` (sync) and `AsyncGradient` (async) constructors accept separate credentials for each API surface and a full suite of HTTP tuning options.

```python
import os
import httpx
from gradient import Gradient, AsyncGradient, DefaultHttpxClient, DefaultAioHttpClient

# --- DigitalOcean control-plane client (agents, GPU droplets, knowledge bases, …)
api_client = Gradient(
    access_token=os.environ["DIGITALOCEAN_ACCESS_TOKEN"],  # or env var default
    max_retries=3,           # default 2; set 0 to disable
    timeout=30.0,            # seconds; default 60
)

# --- Serverless Inference client
inference_client = Gradient(
    model_access_key=os.environ["GRADIENT_MODEL_ACCESS_KEY"],
)

# --- Agent Inference client (routes requests to a specific deployed agent)
agent_client = Gradient(
    agent_access_key=os.environ["GRADIENT_AGENT_ACCESS_KEY"],
    agent_endpoint="https://my-agent.agents.do-ai.run",
)

# --- Async client with aiohttp backend for high-concurrency workloads
async def build_async_client():
    async with AsyncGradient(
        model_access_key=os.environ["GRADIENT_MODEL_ACCESS_KEY"],
        http_client=DefaultAioHttpClient(),
    ) as client:
        return client

# --- Per-request overrides via with_options()
custom = api_client.with_options(timeout=5.0, max_retries=0)

# --- Context-manager usage (auto-closes HTTP connections)
with Gradient() as client:
    agents = client.agents.list()
```
```

--------------------------------

### Initialize Gradient Clients

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Demonstrates initialization of synchronous and asynchronous Gradient clients for different API surfaces. Includes options for access tokens, API keys, agent endpoints, HTTP client customization, and context manager usage.

```python
import os
import httpx
from gradient import Gradient, AsyncGradient, DefaultHttpxClient, DefaultAioHttpClient

# --- DigitalOcean control-plane client (agents, GPU droplets, knowledge bases, …)
api_client = Gradient(
    access_token=os.environ["DIGITALOCEAN_ACCESS_TOKEN"],  # or env var default
    max_retries=3,           # default 2; set 0 to disable
    timeout=30.0,            # seconds; default 60
)

# --- Serverless Inference client
inference_client = Gradient(
    model_access_key=os.environ["GRADIENT_MODEL_ACCESS_KEY"],
)

# --- Agent Inference client (routes requests to a specific deployed agent)
agent_client = Gradient(
    agent_access_key=os.environ["GRADIENT_AGENT_ACCESS_KEY"],
    agent_endpoint="https://my-agent.agents.do-ai.run",
)

# --- Async client with aiohttp backend for high-concurrency workloads
async def build_async_client():
    async with AsyncGradient(
        model_access_key=os.environ["GRADIENT_MODEL_ACCESS_KEY"],
        http_client=DefaultAioHttpClient(),
    ) as client:
        return client

# --- Per-request overrides via with_options()
custom = api_client.with_options(timeout=5.0, max_retries=0)

# --- Context-manager usage (auto-closes HTTP connections)
with Gradient() as client:
    agents = client.agents.list()
```

--------------------------------

### Determine Installed Gradient Version

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Check the currently installed version of the Gradient SDK at runtime by accessing the `__version__` attribute.

```python
import gradient
print(gradient.__version__)
```

--------------------------------

### Initialize Gradient Clients (Sync)

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Initialize synchronous clients for DigitalOcean API, Gradient Serverless Inference, and Gradient Agent Inference. Access tokens are read from environment variables.

```python
import os
from gradient import Gradient

client = Gradient(
    access_token=os.environ.get(
        "DIGITALOCEAN_ACCESS_TOKEN" 
    ),  # This is the default and can be omitted
)
inference_client = Gradient(
    model_access_key=os.environ.get(
        "GRADIENT_MODEL_ACCESS_KEY" 
    ),  # This is the default and can be omitted
)
agent_client = Gradient(
    agent_access_key=os.environ.get(
        "GRADIENT_AGENT_ACCESS_KEY" 
    ),  # This is the default and can be omitted
    agent_endpoint="https://my-agent.agents.do-ai.run",
)
```

--------------------------------

### Initialize Async Gradient Client with aiohttp

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Initialize an asynchronous Gradient client using aiohttp as the HTTP backend. This requires importing DefaultAioHttpClient and using an async context manager.

```python
import os
import asyncio
from gradient import DefaultAioHttpClient
from gradient import AsyncGradient


async def main() -> None:
    async with AsyncGradient(
        model_access_key=os.environ.get(
            "GRADIENT_MODEL_ACCESS_KEY" 
        ),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        completion = await client.chat.completions.create(
            messages=[
                {
                    "role": "user",
                    "content": "What is the capital of France?",
                }
            ],
            model="llama3.3-70b-instruct",
        )
        print(completion.choices)

asyncio.run(main())
```

--------------------------------

### Retrieve a Volume Action

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to get details of a specific volume action by its ID.

```python
client.gpu_droplets.volumes.actions.retrieve(action_id, *volume_id, **params)
```

--------------------------------

### Bootstrap Environment with Rye

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Run this script to set up the development environment using Rye, which automatically provisions the correct Python version and dependencies.

```sh
./scripts/bootstrap
```

--------------------------------

### Initialize Async Gradient Client

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Initialize an asynchronous client for chat completions. This client uses httpx by default and requires an event loop.

```python
import os
import asyncio
from gradient import AsyncGradient

client = AsyncGradient()
```

--------------------------------

### List Supported Backup Policies

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Fetches a list of all supported backup policies for GPU Droplets.

```python
client.gpu_droplets.backups.list_supported_policies()
```

--------------------------------

### Retrieve Action for Image

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Get the details of a specific action performed on an image. Requires both the action ID and the associated image ID.

```python
client.gpu_droplets.images.actions.retrieve(action_id, *, image_id) -> Action
```

--------------------------------

### Initiate Volume Action by Name

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Initiate a volume action by specifying the volume's name.

```python
client.gpu_droplets.volumes.actions.initiate_by_name(**params)
```

--------------------------------

### Run Smoke Tests with Wrapper Script

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Use the convenience wrapper script to run smoke tests, which automatically loads a local `.env` file if present.

```bash
./scripts/smoke
```

--------------------------------

### List Evaluation Metric Regions

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Fetches a list of available regions for evaluation metrics. This method corresponds to the get /v2/gen-ai/regions API endpoint.

```python
client.agents.evaluation_metrics.list_regions(**params) -> EvaluationMetricListRegionsResponse
```

--------------------------------

### List Backup Policies

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Retrieves a list of available backup policies for GPU Droplets.

```python
client.gpu_droplets.backups.list_policies(**params)
```

--------------------------------

### Configure Per-Request Retries (Python)

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Overrides the default retry settings for a specific API call using the `with_options` method. This example sets `max_retries` to 5 for a single call.

```python
from gradient import Gradient

client = Gradient()

client.with_options(max_retries=5).chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="llama3.3-70b-instruct",
)
```

--------------------------------

### Access Raw Response Data and Headers

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Retrieve the raw HTTP response object, including headers, by prefixing `.with_raw_response.` to the method call. The response can then be parsed to get the structured completion object.

```python
from gradient import Gradient

client = Gradient()
response = client.chat.completions.with_raw_response.create(
    messages=[{
        "role": "user",
        "content": "What is the capital of France?",
    }],
    model="llama3.3-70b-instruct",
)
print(response.headers.get('X-My-Header'))

completion = response.parse()  # get the object that `chat.completions.create()` would have returned
print(completion.choices)
```

--------------------------------

### Create a Volume Snapshot

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Create a snapshot for a specified volume.

```python
client.gpu_droplets.volumes.snapshots.create(volume_id, **params)
```

--------------------------------

### Enable Gradient Logging

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Enable logging for the Gradient library by setting the GRADIENT_LOG environment variable. Use 'info' for general logging or 'debug' for more verbose output.

```shell
export GRADIENT_LOG=info
```

--------------------------------

### Make Undocumented POST Requests

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Send requests to undocumented API endpoints using `client.post` or other HTTP verbs. Options like retries are respected. Specify `cast_to=httpx.Response` to get the raw httpx response.

```python
import httpx

response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.headers.get("x-foo"))
```

--------------------------------

### Create Knowledge Base

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new knowledge base. Accepts parameters for configuration.

```APIDOC
## POST /v2/gen-ai/knowledge_bases

### Description
Creates a new knowledge base.

### Method
POST

### Endpoint
/v2/gen-ai/knowledge_bases

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating the knowledge base.

### Request Example
```json
{
  "example": "request body for create knowledge base"
}
```

### Response
#### Success Response (200)
- **KnowledgeBaseCreateResponse** (object) - Details of the created knowledge base.

### Response Example
```json
{
  "example": "response body for create knowledge base"
}
```
```

--------------------------------

### Run Tests

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Execute the project's test suite using the provided script.

```sh
./scripts/test
```

--------------------------------

### Create, Retrieve, List, and Delete GPU Droplets

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Demonstrates how to create a new GPU droplet, retrieve its details, list all existing GPU droplets, and delete a specific droplet.

```APIDOC
## Create GPU Droplet

### Description
Creates a new GPU-enabled Droplet with specified configurations.

### Method
`client.gpu_droplets.create()`

### Parameters
- **name** (string) - Required - The name of the droplet.
- **region** (string) - Required - The region where the droplet will be created.
- **size** (string) - Required - The size of the droplet, specifying GPU resources.
- **image** (string) - Required - The base image for the droplet.
- **ssh_keys** (list of strings) - Required - A list of SSH key IDs for accessing the droplet.
- **tags** (list of strings) - Optional - Tags to apply to the droplet.

### Request Example
```python
droplet = client.gpu_droplets.create(
    name="my-gpu-droplet",
    region="nyc3",
    size="gpu-h100x8-640gb",
    image="ubuntu-22-04-x64",
    ssh_keys=["<ssh-key-id>"],
    tags=["ml-training"],
)
droplet_id = droplet.droplet.id
```

## Retrieve GPU Droplet

### Description
Retrieves the details of a specific GPU droplet by its ID.

### Method
`client.gpu_droplets.retrieve()`

### Parameters
- **droplet_id** (string) - Required - The ID of the droplet to retrieve.

### Request Example
```python
info = client.gpu_droplets.retrieve(droplet_id)
print(info.droplet.status)
```

## List GPU Droplets

### Description
Lists all GPU droplets, optionally filtered by a tag.

### Method
`client.gpu_droplets.list()`

### Parameters
- **tag_name** (string) - Optional - Filters the list of droplets by a specific tag.

### Request Example
```python
all_droplets = client.gpu_droplets.list(tag_name="ml-training")
for d in (all_droplets.droplets or []):
    print(d.id, d.name, d.status)
```

## Delete GPU Droplet

### Description
Deletes a specific GPU droplet by its ID.

### Method
`client.gpu_droplets.delete()`

### Parameters
- **droplet_id** (string) - Required - The ID of the droplet to delete.

### Request Example
```python
client.gpu_droplets.delete(droplet_id)
```

## Delete GPU Droplets by Tag

### Description
Deletes all GPU droplets associated with a specific tag.

### Method
`client.gpu_droplets.delete_by_tag()`

### Parameters
- **tag_name** (string) - Required - The tag used to identify droplets for deletion.

### Request Example
```python
client.gpu_droplets.delete_by_tag(tag_name="ml-training")
```
```

--------------------------------

### Create Chat Completion with Nested Params (Python)

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Demonstrates creating a chat completion with nested parameters, including system messages and stream options. Note the use of an empty dictionary for `stream_options`.

```python
from gradient import Gradient

client = Gradient()

completion = client.chat.completions.create(
    messages=[
        {
            "content": "string",
            "role": "system",
        }
    ],
    model="llama3-8b-instruct",
    stream_options={},
)
print(completion.stream_options)
```

--------------------------------

### Asynchronous Client Usage

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Shows how to use the asynchronous client for making API calls with `async/await`.

```APIDOC
## Asynchronous Client Usage

### Description
Utilize the `AsyncGradient` client for non-blocking API requests using `async/await`.

### Initialization
```python
import os
import asyncio
from gradient import AsyncGradient

client = AsyncGradient()
```

### Usage Example
```python
async def main() -> None:
    completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "What is the capital of France?",
            }
        ],
        model="llama3.3-70b-instruct",
    )
    print(completion.choices)

asyncio.run(main())
```

### Asynchronous Client with aiohttp
For improved concurrency, the async client can be configured to use `aiohttp`.

#### Installation
```sh
pip install gradient[aiohttp]
```

#### Initialization with aiohttp
```python
import os
import asyncio
from gradient import DefaultAioHttpClient
from gradient import AsyncGradient

async def main() -> None:
    async with AsyncGradient(
        model_access_key=os.environ.get(
            "GRADIENT_MODEL_ACCESS_KEY"
        ),
        http_client=DefaultAioHttpClient(),
    ) as client:
        completion = await client.chat.completions.create(
            messages=[
                {
                    "role": "user",
                    "content": "What is the capital of France?",
                }
            ],
            model="llama3.3-70b-instruct",
        )
        print(completion.choices)

asyncio.run(main())
```
```

--------------------------------

### Initiate Volume Action by ID

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Initiate a volume action using the volume's ID.

```python
client.gpu_droplets.volumes.actions.initiate_by_id(volume_id, **params)
```

--------------------------------

### Create Knowledge Base

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to create a new Knowledge Base. It accepts parameters defined in `knowledge_base_create_params.py`.

```python
client.knowledge_bases.create(**params) -> KnowledgeBaseCreateResponse
```

--------------------------------

### List Supported Backup Policies

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Lists all supported backup policies.

```APIDOC
## GET /v2/droplets/backups/supported_policies

### Description
Lists all supported backup policies.

### Method
GET

### Endpoint
/v2/droplets/backups/supported_policies

### Response
#### Success Response (200)
- **BackupListSupportedPoliciesResponse** - A list of supported backup policies.
```

--------------------------------

### models.providers.openai.create

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Registers an OpenAI API key for agent use.

```APIDOC
## models.providers.openai.create

### Description
Registers an OpenAI API key for agent use.

### Method
POST

### Endpoint
/v1/models/providers/openai

### Parameters
#### Request Body
- **name** (string) - Required - A name for the API key.
- **api_key** (string) - Required - The OpenAI API key.

### Response
#### Success Response (201 Created)
- **api_key** (object) - Details of the registered API key.
  - **uuid** (string) - The UUID of the API key.
```

--------------------------------

### Import GPU Droplet Backup Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Import necessary types for managing GPU Droplet backups.

```python
from gradient.types.gpu_droplets import (
    BackupListResponse,
    BackupListPoliciesResponse,
    BackupListSupportedPoliciesResponse,
    BackupRetrievePolicyResponse,
)
```

--------------------------------

### Build Distribution Files

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Build the distributable package (source tarball and wheel file) for the library using Rye or Python's build module.

```sh
rye build
```

```sh
python -m build
```

--------------------------------

### List Snapshots for a GPU Droplet

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Fetches a list of snapshots for a specific GPU Droplet.

```python
client.gpu_droplets.list_snapshots(droplet_id, **params)
```

--------------------------------

### Create Firewall

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new Firewall. Requires parameters defining the firewall's configuration.

```python
client.gpu_droplets.firewalls.create(**params) -> FirewallCreateResponse
```

--------------------------------

### Create, Retrieve, List, and Delete GPU Droplets

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Use these methods to manage the lifecycle of GPU Droplets. Ensure you have the correct droplet size and image specified.

```python
droplet = client.gpu_droplets.create(
    name="my-gpu-droplet",
    region="nyc3",
    size="gpu-h100x8-640gb",
    image="ubuntu-22-04-x64",
    ssh_keys=["<ssh-key-id>"],
    tags=["ml-training"],
)
droplet_id = droplet.droplet.id  # type: ignore[union-attr]
print(f"Droplet ID: {droplet_id}")
```

```python
info = client.gpu_droplets.retrieve(droplet_id)
print(info.droplet.status)  # type: ignore[union-attr]
```

```python
all_droplets = client.gpu_droplets.list(tag_name="ml-training")
for d in (all_droplets.droplets or []):
    print(d.id, d.name, d.status)
```

```python
client.gpu_droplets.delete(droplet_id)
```

```python
client.gpu_droplets.delete_by_tag(tag_name="ml-training")
```

--------------------------------

### Import Volume Snapshot Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Import necessary types for managing volume snapshots.

```python
from gradient.types.gpu_droplets.volumes import (
    SnapshotCreateResponse,
    SnapshotRetrieveResponse,
    SnapshotListResponse,
)
```

--------------------------------

### Create Volume

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new volume.

```APIDOC
## POST /v2/volumes

### Description
Creates a new volume.

### Method
POST

### Endpoint
/v2/volumes

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a volume.

### Request Example
```json
{
  "name": "my-volume",
  "size_gigabytes": 100,
  "description": "My new volume"
}
```

### Response
#### Success Response (200)
- **VolumeCreateResponse** (object) - Details of the created volume.
```

--------------------------------

### Configure Gradient HTTP Client

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Customize the httpx client for proxies, transports, or advanced functionality. Set the base URL directly or via the GRADIENT_BASE_URL environment variable.

```python
import httpx
from gradient import Gradient, DefaultHttpxClient

client = Gradient(
    # Or use the `GRADIENT_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

--------------------------------

### Firewall Management

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Manage firewalls for GPU droplets using the Gradient Python client.

```APIDOC
## Firewalls

### Description
Provides methods to manage firewalls for GPU droplets.

### Methods

- **create**: Creates a new firewall.
  - **Endpoint**: `POST /v2/firewalls`
  - **Parameters**: Accepts various parameters for firewall configuration.
  - **Returns**: `FirewallCreateResponse`

- **retrieve**: Retrieves details of a specific firewall.
  - **Endpoint**: `GET /v2/firewalls/{firewall_id}`
  - **Parameters**: `firewall_id` (string) - The ID of the firewall.
  - **Returns**: `FirewallRetrieveResponse`

- **update**: Updates an existing firewall.
  - **Endpoint**: `PUT /v2/firewalls/{firewall_id}`
  - **Parameters**: `firewall_id` (string) - The ID of the firewall. Accepts various parameters for firewall configuration.
  - **Returns**: `FirewallUpdateResponse`

- **list**: Lists all firewalls.
  - **Endpoint**: `GET /v2/firewalls`
  - **Parameters**: Accepts various parameters for filtering and pagination.
  - **Returns**: `FirewallListResponse`

- **delete**: Deletes a firewall.
  - **Endpoint**: `DELETE /v2/firewalls/{firewall_id}`
  - **Parameters**: `firewall_id` (string) - The ID of the firewall.
  - **Returns**: `None`
```

--------------------------------

### Create Floating IP Action

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Initiates an action on a specific floating IP. Requires the floating IP ID and action parameters.

```python
client.gpu_droplets.floating_ips.actions.create(floating_ip, **params)
```

--------------------------------

### Create Load Balancer

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Provision a new Load Balancer. Use the provided params type to specify configuration details.

```python
client.gpu_droplets.load_balancers.create(**params) -> LoadBalancerCreateResponse
```

--------------------------------

### agents.wait_until_ready

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Block (sync or async) until a newly created agent finishes deploying, with configurable poll interval and timeout.

```APIDOC
## agents.wait_until_ready — Poll Until Agent is Deployed

Block (sync or async) until a newly created agent finishes deploying, with configurable poll interval and timeout.

```python
from gradient import Gradient, AgentDeploymentError, AgentDeploymentTimeoutError

client = Gradient(access_token="<DIGITALOCEAN_ACCESS_TOKEN>")

# Create the agent first
resp = client.agents.create(
    name="My New Agent",
    instruction="Be helpful.",
    model_uuid="<model-uuid>",
    region="nyc1",
)
agent_id = resp.agent.uuid  # type: ignore[union-attr]

try:
    ready = client.agents.wait_until_ready(
        agent_id,
        poll_interval=5.0,   # seconds between status checks (default 5)
        timeout=300.0,        # max wait in seconds (default 300)
    )
    print(f"Status: {ready.agent.deployment.status}")  # type: ignore[union-attr]
    print(f"URL:    {ready.agent.url}")                # type: ignore[union-attr]

except AgentDeploymentError as e:
    # Agent reached a terminal failure state
    print(f"Deployment failed with status: {e.status}")

except AgentDeploymentTimeoutError as e:
    print(f"Timed out waiting for agent {e.agent_id}")
```
```

--------------------------------

### Configure Granular Timeout (Python)

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Provides more granular control over timeout settings for read, write, and connect phases using an `httpx.Timeout` object.

```python
from gradient import Gradient
import httpx

client = Gradient(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)
```

--------------------------------

### List Backups for a GPU Droplet

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Retrieves a list of backups for a specific GPU Droplet, with optional parameters.

```python
client.gpu_droplets.backups.list(droplet_id, **params)
```

--------------------------------

### Async Streaming Chat Completions

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Demonstrates asynchronous streaming of chat completions using `AsyncGradient`. Requires an event loop to run.

```python
# --- Async streaming
import asyncio
from gradient import AsyncGradient

async def stream_async():
    async_client = AsyncGradient(model_access_key="<key>")
    stream = await async_client.chat.completions.create(
        model="llama3.3-70b-instruct",
        messages=[{"role": "user", "content": "Hello!"}],
        stream=True,
    )
    async for chunk in stream:
        if chunk.choices:
            print(chunk.choices[0].delta.content, end="")
    await async_client.close()

asyncio.run(stream_async())
```

--------------------------------

### List Firewalls

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Lists all Firewalls. Optional parameters can be provided for filtering.

```python
client.gpu_droplets.firewalls.list(**params) -> FirewallListResponse
```

--------------------------------

### Import Volume Actions Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Import necessary types for interacting with volume actions.

```python
from gradient.types.gpu_droplets.volumes import (
    VolumeAction,
    ActionRetrieveResponse,
    ActionListResponse,
    ActionInitiateByIDResponse,
    ActionInitiateByNameResponse,
)
```

--------------------------------

### Create Agent

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new agent using the client.agents.create method. Requires agent creation parameters.

```python
client.agents.create(**params) -> AgentCreateResponse
```

--------------------------------

### List Backups for GPU Droplet

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Lists backups for a specific GPU Droplet.

```APIDOC
## GET /v2/droplets/{droplet_id}/backups

### Description
Lists backups for a specific GPU Droplet.

### Method
GET

### Endpoint
/v2/droplets/{droplet_id}/backups

### Parameters
#### Path Parameters
- **droplet_id** (string) - Required - The unique identifier of the GPU Droplet.
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering the list of backups. Refer to `gradient.types.gpu_droplets.backup_list_params` for details.

### Response
#### Success Response (200)
- **BackupListResponse** - A list of backups for the GPU Droplet.
```

--------------------------------

### Create Workspace

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new workspace. This method requires parameters defined in `WorkspaceCreateParams` and returns a `WorkspaceCreateResponse`.

```python
from gradient.types.agents.evaluation_metrics import (
    WorkspaceCreateResponse,
    WorkspaceRetrieveResponse,
    WorkspaceUpdateResponse,
    WorkspaceListResponse,
    WorkspaceDeleteResponse,
    WorkspaceListEvaluationTestCasesResponse,
)
```

```python
client.agents.evaluation_metrics.workspaces.create(**params) -> WorkspaceCreateResponse
```

--------------------------------

### Create and Manage Network Firewall Rules for GPU Droplets

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Define inbound and outbound network rules and attach them to GPU Droplets or tags. Ensure correct protocol, ports, and source/destination addresses are specified.

```python
fw = client.gpu_droplets.firewalls.create(
    name="ml-firewall",
    inbound_rules=[
        {"protocol": "tcp", "ports": "22", "sources": {"addresses": ["0.0.0.0/0"]}},
    ],
    outbound_rules=[
        {"protocol": "tcp", "ports": "all", "destinations": {"addresses": ["0.0.0.0/0"]}},
    ],
)
fw_id = fw.firewall.id  # type: ignore[union-attr]
```

```python
client.gpu_droplets.firewalls.droplets.add(fw_id, droplet_ids=[12345, 67890])
```

```python
client.gpu_droplets.firewalls.tags.add(fw_id, tags=["ml-training"])
```

```python
client.gpu_droplets.firewalls.rules.add(
    fw_id,
    inbound_rules=[{"protocol": "tcp", "ports": "8080", "sources": {"addresses": ["10.0.0.0/8"]}}],
)
```

```python
client.gpu_droplets.firewalls.delete(fw_id)
```

--------------------------------

### List Available Inference Models

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Retrieve a list of all available AI models on the Gradient platform. Supports filtering by provider and pagination.

```python
from gradient import Gradient

client = Gradient(access_token="<DIGITALOCEAN_ACCESS_TOKEN>")

models = client.models.list(page=1, per_page=50)
for m in (models.models or []):
    print(m.uuid, m.name, m.version)
```

--------------------------------

### List Backup Policies

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Lists available backup policies.

```APIDOC
## GET /v2/droplets/backups/policies

### Description
Lists available backup policies.

### Method
GET

### Endpoint
/v2/droplets/backups/policies

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering the list of policies. Refer to `gradient.types.gpu_droplets.backup_list_policies_params` for details.

### Response
#### Success Response (200)
- **BackupListPoliciesResponse** - A list of backup policies.
```

--------------------------------

### Knowledge Base Lifecycle Management

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Create and manage vector-backed knowledge bases used by agents for retrieval-augmented generation. Requires region and embedding model UUID.

```python
from gradient import Gradient

client = Gradient(access_token="<DIGITALOCEAN_ACCESS_TOKEN>")

# Create
kb = client.knowledge_bases.create(
    name="Product Docs",
    region="nyc1",
    embedding_model_uuid="<embedding-model-uuid>",
)
kb_uuid = kb.knowledge_base.uuid  # type: ignore[union-attr]

# Retrieve
details = client.knowledge_bases.retrieve(kb_uuid)
print(details.knowledge_base.name)  # type: ignore[union-attr]

# Update
client.knowledge_bases.update(kb_uuid, name="Product Docs v2")

# List
all_kbs = client.knowledge_bases.list()
for k in (all_kbs.knowledge_bases or []):
    print(k.uuid, k.name)

# List indexing jobs attached to this KB
jobs = client.knowledge_bases.list_indexing_jobs(kb_uuid)
print(jobs)

# Delete
client.knowledge_bases.delete(kb_uuid)
```

--------------------------------

### Import Load Balancer Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Import all necessary types for managing Load Balancers. This includes various configuration and response types.

```python
from gradient.types.gpu_droplets import (
    Domains,
    ForwardingRule,
    GlbSettings,
    HealthCheck,
    LbFirewall,
    LoadBalancer,
    StickySessions,
    LoadBalancerCreateResponse,
    LoadBalancerRetrieveResponse,
    LoadBalancerUpdateResponse,
    LoadBalancerListResponse,
)
```

--------------------------------

### List Knowledge Bases

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Lists all available knowledge bases. Accepts optional parameters for filtering and pagination.

```APIDOC
## GET /v2/gen-ai/knowledge_bases

### Description
Lists all available knowledge bases.

### Method
GET

### Endpoint
/v2/gen-ai/knowledge_bases

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for listing knowledge bases (e.g., pagination, filtering).

### Request Example
```json
{
  "example": "request body for list knowledge bases"
}
```

### Response
#### Success Response (200)
- **KnowledgeBaseListResponse** (object) - A list of knowledge bases.

### Response Example
```json
{
  "example": "response body for list knowledge bases"
}
```
```

--------------------------------

### Import GPU Droplet Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Import necessary types for working with GPU Droplets.

```python
from gradient.types import (
    DropletBackupPolicy,
    GPUDropletCreateResponse,
    GPUDropletRetrieveResponse,
    GPUDropletListResponse,
    GPUDropletListFirewallsResponse,
    GPUDropletListKernelsResponse,
    GPUDropletListNeighborsResponse,
    GPUDropletListSnapshotsResponse,
)
```

--------------------------------

### gpu_droplets.create

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Provisions a DigitalOcean GPU-backed Droplet.

```APIDOC
## gpu_droplets.create

### Description
Provisions a DigitalOcean GPU-backed Droplet.

### Method
POST

### Endpoint
/v1/gpu-droplets

### Parameters
#### Request Body
- **name** (string) - Required - The name of the GPU Droplet.
- **region** (string) - Required - The region where the GPU Droplet will be provisioned.
- **size_slug** (string) - Required - The slug for the desired GPU Droplet size.
- **image** (string) - Required - The slug for the desired base image (e.g., 'ubuntu-20-04-x64').
- **ssh_keys** (list) - Optional - A list of SSH key slugs to associate with the Droplet.
- **tags** (list) - Optional - A list of tags to apply to the Droplet.

### Response
#### Success Response (201 Created)
- **droplet** (object) - Details of the provisioned GPU Droplet.
  - **id** (string) - The ID of the GPU Droplet.
  - **name** (string) - The name of the GPU Droplet.
```

--------------------------------

### List Load Balancers

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Retrieve a list of all configured Load Balancers. Optional parameters can be used for filtering the results.

```python
client.gpu_droplets.load_balancers.list(**params) -> LoadBalancerListResponse
```

--------------------------------

### Create and Manage Block Storage Volumes for GPU Droplets

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Create persistent block storage volumes, attach them to GPU Droplets, and manage snapshots. Specify volume size, region, and filesystem type.

```python
vol = client.gpu_droplets.volumes.create(
    name="dataset-volume",
    region="nyc3",
    size_gigabytes=500,
    description="Training dataset storage",
    filesystem_type="ext4",
)
volume_id = vol.volume.id  # type: ignore[union-attr]
```

```python
client.gpu_droplets.volumes.actions.initiate_by_id(
    volume_id,
    type="attach",
    droplet_id=12345,
    region="nyc3",
)
```

```python
snap = client.gpu_droplets.volumes.snapshots.create(
    volume_id,
    name="dataset-snapshot-2024",
)
```

```python
client.gpu_droplets.volumes.delete(volume_id)
```

--------------------------------

### client.agents.evaluation_metrics.workspaces.create

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new workspace for managing AI evaluations. Workspaces help organize and isolate different evaluation tasks.

```APIDOC
## POST /v2/gen-ai/workspaces

### Description
Creates a new workspace for managing AI evaluations.

### Method
POST

### Endpoint
/v2/gen-ai/workspaces

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating the workspace.

### Response
#### Success Response (200)
- **WorkspaceCreateResponse** (object) - The response object confirming workspace creation.
```

--------------------------------

### Run Smoke Tests

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Execute live smoke tests that interact with real Gradient API endpoints. Ensure required environment variables are set. Do not run against production credentials without understanding the API calls.

```bash
./scripts/smoke            # convenience wrapper
pytest -m smoke -q         # direct invocation
```

--------------------------------

### Create Data Source

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Adds a new Data Source to a specified Knowledge Base. Parameters are defined in `data_source_create_params.py`.

```python
client.knowledge_bases.data_sources.create(path_knowledge_base_uuid, **params) -> DataSourceCreateResponse
```

--------------------------------

### List Images for GPU Droplets

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Retrieve a list of all available images for GPU Droplets. Optional parameters can be used to filter the results.

```python
client.gpu_droplets.images.list(**params) -> ImageListResponse
```

--------------------------------

### Import Firewall Types

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Imports necessary types for Firewall management.

```python
from gradient.types.gpu_droplets import (
    Firewall,
    FirewallCreateResponse,
    FirewallRetrieveResponse,
    FirewallUpdateResponse,
    FirewallListResponse,
)
```

--------------------------------

### EvaluationRuns Create

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Creates a new evaluation run.

```APIDOC
## POST /v2/gen-ai/evaluation_runs

### Description
Creates a new evaluation run.

### Method
POST

### Endpoint
/v2/gen-ai/evaluation_runs

### Request Body
(Parameters are passed as keyword arguments to the `create` method)

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the created evaluation run.
- **status** (string) - The status of the evaluation run.
```

--------------------------------

### Stream Raw HTTP Body Line-by-Line

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Demonstrates how to stream the raw HTTP response body line by line, which is useful for processing large responses or real-time data.

```python
with client.chat.completions.with_streaming_response.create(
    model="llama3.3-70b-instruct",
    messages=[{"role": "user", "content": "Count to 5"}],
) as response:
    for line in response.iter_lines():
        print(line)
```

--------------------------------

### Create a GPU Droplet

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to create a new GPU-enabled Droplet. Requires specifying creation parameters.

```python
client.gpu_droplets.create(**params)
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/digitalocean/gradient-python/blob/main/CONTRIBUTING.md

Activate the virtual environment created by Rye to run Python scripts without the `rye run` prefix.

```sh
source .venv/bin/activate
```

--------------------------------

### List Kernels for a GPU Droplet

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Fetches a list of available kernels for a specific GPU Droplet.

```python
client.gpu_droplets.list_kernels(droplet_id, **params)
```

--------------------------------

### Run Automated Agent Evaluation

Source: https://context7.com/digitalocean/gradient-python/llms.txt

Initiate automated LLM-judge evaluations against test cases and inspect the scored results. This requires an access token and potentially other configurations not shown.

```python
from gradient import Gradient

client = Gradient(access_token="<DIGITALOCEAN_ACCESS_TOKEN>")
```

--------------------------------

### Create Evaluation Run

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to create a new evaluation run. Accepts various parameters for configuration.

```python
from gradient.types.agents import (
    APIEvaluationMetric,
    APIEvaluationMetricResult,
    APIEvaluationPrompt,
    APIEvaluationRun,
    EvaluationRunCreateResponse,
    EvaluationRunRetrieveResponse,
    EvaluationRunListResultsResponse,
    EvaluationRunRetrieveResultsResponse,
)

# Assuming 'client' is an initialized Gradient client instance
# client.agents.evaluation_runs.create(**params)
```

--------------------------------

### Create OpenAI API Key

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to create a new OpenAI API key. Requires provider-specific parameters.

```python
client.models.providers.openai.create(**params) -> OpenAICreateResponse
```

--------------------------------

### Create Image for GPU Droplets

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Use this method to create a new image for GPU Droplets. Refer to the params type for required parameters.

```python
client.gpu_droplets.images.create(**params) -> ImageCreateResponse
```

--------------------------------

### Create Presigned URLs for File Upload

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Generates presigned URLs for uploading files to be used as Data Sources. Parameters are defined in `data_source_create_presigned_urls_params.py`.

```python
client.knowledge_bases.data_sources.create_presigned_urls(**params) -> DataSourceCreatePresignedURLsResponse
```

--------------------------------

### Customize Client Per Request

Source: https://github.com/digitalocean/gradient-python/blob/main/README.md

Override the HTTP client for individual requests using the `with_options()` method.

```python
client.with_options(http_client=DefaultHttpxClient(...))
```

--------------------------------

### List Actions for Image

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

Retrieve a list of all actions performed on a specific image. This helps in tracking the history of operations on an image.

```python
client.gpu_droplets.images.actions.list(image_id) -> ActionListResponse
```

--------------------------------

### List Volume Snapshots

Source: https://github.com/digitalocean/gradient-python/blob/main/api.md

List all snapshots associated with a specific volume.

```python
client.gpu_droplets.volumes.snapshots.list(volume_id, **params)
```