Skip to main content

​
Python SDK

The official Python SDK for PolarGrid with async and sync clients.

​
Installation

pip install polargrid-sdk

​
Quick Start

import asyncio
from polargrid import PolarGrid

async def main():
    # Auto-select best region by latency
    client = await PolarGrid.create(api_key="pg_your_api_key")
    
    print(f"Connected to: {client.get_region_name()}")  # e.g., "Toronto"

    response = await client.chat_completion({
        "model": "qwen-3.5-27b",
        "messages": [
            {"role": "user", "content": "Hello!"}
        ]
    })

    print(response.choices[0].message.content)

asyncio.run(main())

​
Sync Client

from polargrid import PolarGridSync

client = PolarGridSync(api_key="pg_your_api_key", region="toronto")

response = client.chat_completion({
    "model": "qwen-3.5-27b",
    "messages": [{"role": "user", "content": "Hello!"}]
})

print(response.choices[0].message.content)

​
Configuration

# Async client with auto-routing (recommended)
client = await PolarGrid.create(
    api_key="pg_your_api_key",  # or set POLARGRID_API_KEY env var
    debug=True,
)

# Sync constructor with explicit region
client = PolarGrid(
    api_key="pg_your_api_key",
    
    # Region alias: 'toronto', 'montreal', 'vancouver', 'new-york', 'dallas', 'san-francisco'
    # Or explicit ID: yto-01, yto-02, yul-01, yul-02, yvr-02, nyc-01, nyc-02, dal-01, dal-02, sfo-01
    region="vancouver",
    
    # Request timeout in seconds (default: 30.0)
    timeout=30.0,
    
    # Max retry attempts (default: 3)
    max_retries=3,
    
    # Enable debug logging
    debug=True,
    
    # Use mock data for development
    use_mock_data=False,
)

​
Auto-Routing

# Calls the autorouter which returns the optimal edge based on your origin
client = await PolarGrid.create(api_key="pg_...", debug=True)

# [PolarGrid] Auto-routing: selected Toronto (yto-01)

print(client.get_region_id())   # 'yto-01'
print(client.get_region_name()) # 'Toronto'

​
Streaming

async for chunk in client.chat_completion_stream({
    "model": "qwen-3.5-27b",
    "messages": [{"role": "user", "content": "Tell me a story"}],
}):
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

​
Mock Mode

client = PolarGrid(
    use_mock_data=True,  # No API calls
    debug=True,
)

# All methods return realistic mock data
response = await client.chat_completion({
    "model": "qwen-3.5-27b",
    "messages": [{"role": "user", "content": "Hello!"}]
})

​
Type Hints

The SDK uses Pydantic models with full type hints: 
from polargrid.types import (
    ChatCompletionRequest,
    ChatCompletionResponse,
    Message,
)

# Request with typed model
request = ChatCompletionRequest(
    model="qwen-3.5-27b",
    messages=[Message(role="user", content="Hello!")],
    max_tokens=100,
)

# Or use dict (auto-converted)
response = await client.chat_completion({
    "model": "qwen-3.5-27b",
    "messages": [{"role": "user", "content": "Hello!"}],
})

​
Environment Variables

export POLARGRID_API_KEY=pg_your_api_key
export POLARGRID_BASE_URL=https://api.yto-01.edge.polargrid.ai  # Optional. Pins the SDK to a specific edge. Leave unset and call PolarGrid.create() to auto-discover the fastest region via https://autorouter.polargrid.ai/v1/route.

​
Next Steps

Full Reference

Complete API reference

Voice Guide

Text-to-speech and speech-to-text