Python Quickstart

Get started with the PolarGrid Python SDK

Python SDK

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

Installation

pip install polargrid-sdk

Quick Start

Async Client (Recommended)

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, yul-01, yul-02, yvr-02, nyc-01, nyc-02, dfw-01, dfw-02, sfo-01, lax-01, sea-01, chi-01, phx-01, was-01, mia-01, sfo-03
    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)

Response Metadata (latency)

PolarGrid attaches per-request metadata (region, latency breakdown) under response.pg_metadata. It is optional — fields may be None, and on the non-stream path latency_ms is commonly None. Always read it through the typed attribute and guard for None; never index a top-level latency_ms key (it does not exist and raises KeyError).

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

text = response.choices[0].message.content

meta = response.pg_metadata
if meta is not None:
    print(f"region={meta.region} latency_ms={meta.latency_ms}")  # latency_ms may be None

Streaming chat chunks (ChatCompletionChunk) do not carry pg_metadata — only the non-stream chat_completion response exposes it. If you need region/latency metadata on a streamed request, issue a non-stream call, or read the timing from your own client-side measurements.

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