digitalocean/gradient-python

digitalocean/gradient-python

Description: DigitalOcean Gradient AI Platform SDK

Language: Python

License: Apache-2.0

Stars: 18

Forks: 20

Open issues: 10

Created: 2025-05-28T21:16:47Z

Pushed: 2026-05-12T19:04:14Z

Default branch: main

Fork: no

Archived: no

README: !Header image for the DigitalOcean Gradient AI Agentic Cloud

Gradient Python API library

The Gradient Python library provides convenient access to the Gradient REST API from any Python 3.9+ application. The library includes type definitions for all request params and response fields, and offers both synchronous and asynchronous clients powered by httpx.

It is generated with Stainless.

Documentation

The getting started guide can be found on gradient-sdk.digitalocean.com. The REST API documentation can be found on developers.digitalocean.com. The full API of this library can be found in [api.md](api.md).

Installation

# install from PyPI
pip install gradient

Usage

The Gradient SDK provides clients for:

• DigitalOcean API
• Gradient Serverless Inference
• Gradient Agent Inference

The full API of this library can be found in [api.md](api.md).

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",
)

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

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

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

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

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

While you can provide an access_token, model_access_key keyword argument, we recommend using python-dotenv to add DIGITALOCEAN_ACCESS_TOKEN="My Access Token", GRADIENT_MODEL_ACCESS_KEY="My Model Access Key" to your .env file so that your keys are not stored in source control.

Async usage

Simply import AsyncGradient instead of Gradient and use await with each API call:

import os
import asyncio
from gradient import AsyncGradient

client = AsyncGradient()

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())

Functionality between the synchronous and asynchronous clients is otherwise identical.

With aiohttp

By default, the async client uses httpx for HTTP requests. However, for improved concurrency performance you may also use aiohttp as the HTTP backend.

You can enable this by installing aiohttp:

# install from PyPI
pip install gradient[aiohttp]

Then you can enable it by instantiating the client with http_client=DefaultAioHttpClient():

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())

Streaming responses

We provide support for streaming responses using Server Side Events (SSE).

from gradient import Gradient

client = Gradient()

stream = client.chat.completions.create(
messages=[
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="llama3.3-70b-instruct",
stream=True,
)
for completion in stream:
print(completion.choices)

The async client uses the exact same interface.

from gradient import AsyncGradient

client = AsyncGradient()

stream = await client.chat.completions.create(
messages=[
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="llama3.3-70b-instruct",
stream=True,
)
async for completion in stream:
print(completion.choices)

Using types

Nested request parameters are TypedDicts. Responses are Pydantic models which also provide helper methods for things like:

• Serializing back into JSON, model.to_json()
• Converting to a dictionary, model.to_dict()

Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set python.analysis.typeCheckingMode to basic.

Nested params

Nested parameters are dictionaries, typed using TypedDict, for example:

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)

Handling errors

When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of gradient.APIConnectionError is raised.

When the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of gradient.APIStatusError is raised, containing status_code and response properties.

All errors inherit from gradient.APIError.

import gradient
from gradient import Gradient…