do-gradient-ai

A complete, unofficial Python SDK for DigitalOcean's Gradient AI Platform.

Features

• Serverless Inference: Access 23+ foundation models including Llama, Mistral, DeepSeek, Claude, GPT
• Knowledge Bases: Create and query RAG-enabled knowledge bases with citations
• AI Agents: Build and interact with managed AI assistants
• Image Generation: Generate images with DALL-E (tier-dependent)
• Streaming: Full streaming support for real-time responses
• CLI Tool: Complete command-line interface included

Installation

pip install do-gradient-ai

Quick Start

Python SDK

from do_gradient_ai import GradientAI

# Initialize client (uses GRADIENT_API_KEY from environment)
client = GradientAI()

# Simple chat completion
response = client.complete("What is Python?")
print(response)

# Or use the full API
response = client.chat.complete("What is Python?")
print(response.content)

# Stream responses
for chunk in client.stream("Tell me a story"):
    print(chunk, end="", flush=True)

# List available models
models = client.list_models()
for model in models:
    print(model)

Command Line

# Chat completion
gradient chat "What is Python?"

# Stream response
gradient chat --stream "Tell me a story"

# List models
gradient models list

# Interactive mode
gradient interactive

# Test connection
gradient test

Authentication

The SDK uses two types of authentication:

Inference Key (Required)

For chat completions, knowledge base queries, and agent interactions.

export GRADIENT_API_KEY="sk-do-..."

Or pass directly:

client = GradientAI(inference_key="sk-do-...")

Management Token (Optional)

For creating/managing knowledge bases, agents, and other resources.

export DIGITALOCEAN_TOKEN="dop_v1_..."

Or pass directly:

client = GradientAI(management_token="dop_v1_...")

Chat Completions

from do_gradient_ai import GradientAI, Message

client = GradientAI()

# Simple string input
response = client.chat.complete("Hello!")

# With system prompt
response = client.chat.complete(
    "What is Python?",
    system="You are a helpful programming tutor."
)

# Full conversation
messages = [
    Message.system("You are helpful."),
    Message.user("What is Python?"),
    Message.assistant("Python is a programming language..."),
    Message.user("What are its main features?"),
]
response = client.chat.complete(messages)

# With parameters
response = client.chat.complete(
    "Explain quantum computing",
    model="llama3.3-70b-instruct",
    temperature=0.7,
    max_tokens=2048,
)

# Streaming
for chunk in client.chat.stream("Tell me a story"):
    print(chunk, end="", flush=True)

# Async support
response = await client.chat.acomplete("Hello!")

Knowledge Bases (RAG)

from do_gradient_ai import GradientAI, DataSource

client = GradientAI()

# List knowledge bases
kbs = client.knowledge_bases.list()

# Query a knowledge base
results = client.knowledge_bases.query(
    kb_id="your-kb-id",
    query="What is the return policy?",
    num_results=5,
)

for result in results.results:
    print(f"Score: {result.score}")
    print(f"Text: {result.text}")
    print(f"Source: {result.source}")

# Create a knowledge base (requires management token)
kb = client.knowledge_bases.create(
    name="Company Docs",
    project_id="your-project-id",
    region="tor1",
)

# Add data sources
ds = client.knowledge_bases.add_data_source(
    kb.id,
    DataSource.spaces("my-bucket", "tor1", folder="docs/"),
)

# Or from web crawler
ds = client.knowledge_bases.add_data_source(
    kb.id,
    DataSource.web_crawler("https://docs.example.com", max_pages=500),
)

# Start indexing
job = client.knowledge_bases.start_indexing(kb.id, ds.id)

AI Agents

from do_gradient_ai import GradientAI, AgentConfig

client = GradientAI()

# List agents
agents = client.agents.list()

# Chat with an agent
response = client.agents.chat(
    agent_id="your-agent-id",
    messages="What is your return policy?",
)
print(response.content)
for citation in response.citations:
    print(f"Source: {citation}")

# Stream agent chat
for chunk in client.agents.stream_chat(agent_id, "Help me with my order"):
    print(chunk, end="", flush=True)

# Create an agent (requires management token)
agent = client.agents.create(
    AgentConfig(
        name="Support Bot",
        model_id="model-uuid",
        instruction="You are a helpful customer support agent.",
        project_id="your-project-id",
        region="tor1",
        knowledge_base_ids=["kb-uuid"],
    )
)

# Add multi-agent routing
client.agents.add_route(
    agent_id=agent.id,
    target_agent_id="specialist-agent-id",
    description="Route technical questions",
)

Image Generation

from do_gradient_ai import GradientAI

client = GradientAI()

# Generate an image
response = client.images.generate(
    prompt="A sunset over mountains",
    size="1024x1024",
    quality="hd",
)

# Save to file
response.image.save("sunset.png")

# Generate multiple images
response = client.images.generate(
    prompt="Abstract art",
    n=4,
)
for i, img in enumerate(response.images):
    img.save(f"art_{i}.png")

Available Models

The platform provides access to 23+ models including:

Model	Provider	Notes
llama3.3-70b-instruct	Meta	Default model
llama3.2-3b-instruct	Meta	Smaller, faster
deepseek-r1-distill-llama-70b	DeepSeek	Reasoning model
mistral-nemo-instruct	Mistral
claude-3.5-sonnet	Anthropic	Higher tier
gpt-4o	OpenAI	Higher tier

# List all available models
models = client.models.list()
for m in models:
    print(f"{m.id}: {m.name}")

CLI Reference

# Chat commands
gradient chat "message"              # Simple chat
gradient chat --stream "message"     # Stream response
gradient chat -m "message" --model llama3.2-3b-instruct
gradient chat --system "You are..." "message"
echo "input" | gradient chat         # Pipe input

# Model commands
gradient models list                 # List all models
gradient models get <model-id>       # Get model details

# Knowledge base commands
gradient kb list                     # List knowledge bases
gradient kb query <kb-id> "query"    # Query a KB

# Agent commands
gradient agents list                 # List agents
gradient agent chat <id> "message"   # Chat with agent
gradient agent chat <id> -s "msg"    # Stream response

# Other commands
gradient interactive                 # Interactive mode
gradient test                        # Test connection
gradient --help                      # Help

# Global options
gradient --api-key "..." chat "msg"  # Explicit API key
gradient --json chat "message"       # JSON output

Error Handling

from do_gradient_ai import GradientAI
from do_gradient_ai.models.common import APIError

client = GradientAI()

try:
    response = client.chat.complete("Hello")
except APIError as e:
    print(f"API Error {e.status_code}: {e.message}")
except Exception as e:
    print(f"Error: {e}")

Environment Variables

Variable	Description
GRADIENT_API_KEY	Model access key for inference
DIGITALOCEAN_TOKEN	API token for management operations

Requirements

• Python 3.8+
• requests >= 2.25.0

License

MIT License

Links

• DigitalOcean Gradient Documentation
• GitHub Repository
• PyPI Package