Python SDK

Installation

pip install tokenrouter

Quick Start

from tokenrouter import Tokenrouter

client = Tokenrouter(
    api_key="tr_..."
)

response = client.responses.create(
    model="auto:balance",
    input="Hello, world!"
)

Configuration

client = Tokenrouter(
    api_key="tr_...",
    environment="production",  # or "local"
    timeout=60.0,  # seconds
)

Making Requests

Basic Request

response = client.responses.create(
    model="auto:balance",
    input="What is Python?"
)

With Options

response = client.responses.create(
    model="gpt-4o:quality",
    input="Explain decorators",
    temperature=0.7,
    max_output_tokens=1000
)

Streaming

stream = client.responses.create(
    model="auto:balance",
    input="Write a story",
    stream=True
)

for chunk in stream:
    if chunk.event == 'content.delta':
        print(chunk.delta.text, end='', flush=True)

Async Support

from tokenrouter import AsyncTokenrouter

async_client = AsyncTokenrouter(api_key="tr_...")

response = await async_client.responses.create(
    model="auto:balance",
    input="Hello!"
)

Routing Rules

Manage custom routing logic to control how requests are routed.

Create Routing Rule

rule = client.routing_rules.create(
    name="Coding Tasks → OpenAI",
    priority=100,
    is_enabled=True,
    match_json={"task": "coding"},
    action_json={
        "set_provider": "openai",
        "set_model": "gpt-4o"
    }
)

print(f"Created rule: {rule.data.id}")

List Routing Rules

rules = client.routing_rules.list()

for rule in rules.data:
    print(f"{rule.name} (Priority: {rule.priority})")

Get Routing Rule

rule = client.routing_rules.retrieve(123)
print(rule.data)

Update Routing Rule

client.routing_rules.update(
    123,
    priority=150,
    is_enabled=False
)

Delete Routing Rule

client.routing_rules.delete(123)

Match Conditions

# Input contains text (case-insensitive)
match_json={"contains": "code review"}

# Match metadata
match_json={"metadata_equals": {"task": "documentation"}}

# Match routing mode
match_json={"mode": "balanced"}

# Multiple conditions (all must match)
match_json={
    "task": "coding",
    "mode": "quality"
}

Actions

# Force specific provider
action_json={"set_provider": "anthropic"}

# Force specific model
action_json={"set_model": "gpt-4o"}

# Override routing mode
action_json={"set_mode": "cost"}

# Add warning
action_json={
    "add_warning": {"message": "Using beta routing"}
}

# Combine actions
action_json={
    "set_provider": "openai",
    "set_model": "gpt-4o",
    "set_mode": "quality"
}

Firewall Rules

Protect your application by filtering sensitive content in requests and responses.

Create Firewall Rule

# Block credit card numbers
rule = client.firewall_rules.create(
    name="Block Credit Cards",
    priority=100,
    is_enabled=True,
    scope="prompt",
    type="regex",
    pattern=r"\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}",
    action="block"
)

Mask Sensitive Data

# Mask email addresses in responses
rule = client.firewall_rules.create(
    name="Mask Email Addresses",
    priority=80,
    is_enabled=True,
    scope="response",
    type="regex",
    pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
    action="mask",
    replacement="[EMAIL_REDACTED]"
)

Warn on Content

# Warn when profanity detected
rule = client.firewall_rules.create(
    name="Warn on Profanity",
    priority=50,
    is_enabled=True,
    scope="response",
    type="substring",
    pattern="inappropriate",
    action="warn"
)

List Firewall Rules

rules = client.firewall_rules.list()

for rule in rules.data:
    print(f"{rule.name} ({rule.action})")
    print(f"  Scope: {rule.scope}")
    print(f"  Pattern: {rule.pattern}")

Get Firewall Rule

rule = client.firewall_rules.retrieve(123)
print(rule.data)

Update Firewall Rule

# Disable temporarily
client.firewall_rules.update(123, is_enabled=False)

# Change action
client.firewall_rules.update(123, action="warn")

Delete Firewall Rule

client.firewall_rules.delete(123)

Rule Scopes

• prompt - Apply to user input before sending to LLM
• response - Apply to LLM output before returning to user

Rule Types

• substring - Case-insensitive text matching
• regex - Regular expression matching (PCRE-compatible)

Actions

• block - Reject request/response with 422 error
• mask - Replace matched content with replacement text
• warn - Allow but add warning to metadata

Common Patterns

# Social Security Numbers
pattern = r"\d{3}-\d{2}-\d{4}"

# Phone Numbers
pattern = r"\+?1?\s?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}"

# Email Addresses
pattern = r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"

# API Keys (OpenAI format)
pattern = r"sk-[a-zA-Z0-9]{32,}"

# Credit Cards (any format)
pattern = r"\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}"

Error Handling

from tokenrouter import APIError

try:
    response = client.responses.create(...)
except APIError as error:
    print(f"API Error: {error}")
    print(f"Status: {error.status}")
    print(f"Type: {error.type}")

Handle Firewall Blocks

try:
    response = client.responses.create(
        model="auto:balance",
        input="My credit card is 4532-1234-5678-9010"
    )
except APIError as error:
    if error.status == 422:
        print("Request blocked by firewall")
        print(f"Reason: {error.message}")

Advanced Usage

Conditional Routing

# Create multiple rules for different scenarios
client.routing_rules.create(
    name="Complex Analysis → GPT-4",
    priority=100,
    is_enabled=True,
    match_json={
        "contains": ["analyze", "complex"],
        "mode": "quality"
    },
    action_json={
        "set_provider": "openai",
        "set_model": "gpt-4o"
    }
)

client.routing_rules.create(
    name="Simple Tasks → Cost Mode",
    priority=50,
    is_enabled=True,
    match_json={"contains": ["summarize", "list"]},
    action_json={"set_mode": "cost"}
)

Multi-Layer Protection

# Layer 1: Block PII in prompts
client.firewall_rules.create(
    name="Block PII in Input",
    priority=100,
    is_enabled=True,
    scope="prompt",
    type="regex",
    pattern=r"\d{3}-\d{2}-\d{4}|\d{16}",
    action="block"
)

# Layer 2: Mask emails in responses
client.firewall_rules.create(
    name="Mask Emails in Output",
    priority=90,
    is_enabled=True,
    scope="response",
    type="regex",
    pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
    action="mask",
    replacement="[REDACTED]"
)

# Layer 3: Warn on sensitive keywords
client.firewall_rules.create(
    name="Warn on Sensitive Terms",
    priority=80,
    is_enabled=True,
    scope="response",
    type="substring",
    pattern="confidential",
    action="warn"
)

Type Hints

All SDK classes are fully typed with type hints:

from tokenrouter import (
    Tokenrouter,
    AsyncTokenrouter,
    RoutingRule,
    FirewallRule
)
from tokenrouter.types import (
    ResponseCreateParams,
    RoutingRuleCreateParams,
    FirewallRuleCreateParams
)

Next Steps

• Node.js SDK
• Rules API
• Firewall API
• API Reference