dogradient 1.0.0
Complete Python SDK for DigitalOcean's Gradient AI Platform - serverless inference, knowledge bases, agents, and more
License: MIT
Requires Python: >=3.8
Keywords: digitalocean, gradient, ai, llm, chat, rag, knowledge-base, agents, serverless, inference, llama, mistral, claude, gpt

# do-gradient-ai

A complete, unofficial Python SDK for [DigitalOcean's Gradient AI Platform](https://docs.digitalocean.com/products/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

```bash
pip install do-gradient-ai
```

## Quick Start

### Python SDK

```python
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

```bash
# 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.

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

Or pass directly:
```python
client = GradientAI(inference_key="sk-do-...")
```

### Management Token (Optional)
For creating/managing knowledge bases, agents, and other resources.

```bash
export DIGITALOCEAN_TOKEN="dop_v1_..."
```

Or pass directly:
```python
client = GradientAI(management_token="dop_v1_...")
```

## Chat Completions

```python
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)

```python
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

```python
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

```python
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 |

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

## CLI Reference

```bash
# 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

```python
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](https://docs.digitalocean.com/products/gradient-ai-platform/)
- [GitHub Repository](https://github.com/lukesteuber/do-gradient-ai)
- [PyPI Package](https://pypi.org/project/do-gradient-ai/)