pollax 1.2.0

Official Python SDK for the Pollax AI Voice Platform

Pollax Python SDK

Official Python client library for the Pollax AI Voice Platform.

Installation

pip install pollax

Quick Start

from pollax import Pollax

# Initialize client
client = Pollax(api_key="sk_live_your_api_key_here")

# Create an AI agent
agent = client.agents.create(
    name="Customer Support Agent",
    system_prompt="You are a helpful customer support agent for Acme Corp.",
    voice_id="alloy",
    model="gpt-4",
)

# Make a call
call = client.calls.create(
    agent_id=agent.id,
    to_number="[phone]",
    from_number="+0987654321",
)

print(f"Call initiated: {call.call_sid}")

Features

• Full type hints with Pydantic models
• Async/await support
• Automatic retry logic with exponential backoff
• Comprehensive error handling
• Context manager support
• Python 3.8+ support

Usage

Client Initialization

from pollax import Pollax

# Basic initialization
client = Pollax(api_key="sk_live_...")

# With custom configuration
client = Pollax(
    api_key="sk_live_...",
    base_url="https://api.pollax.ai",
    timeout=30.0,
    max_retries=3,
    tenant_id="org_123",
)

# Using context manager (recommended)
with Pollax(api_key="sk_live_...") as client:
    agents = client.agents.list()

Agents

# Create an agent
agent = client.agents.create(
    name="Support Agent",
    system_prompt="You are a helpful assistant",
    voice_provider="elevenlabs",
    voice_id="voice_abc123",
    model="gpt-4",
    temperature=0.7,
)

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

# Get a specific agent
agent = client.agents.retrieve("agent_123")

# Update an agent
agent = client.agents.update(
    "agent_123",
    name="New Name",
    is_active=False,
)

# Delete an agent
client.agents.delete("agent_123")

# Test an agent
response = client.agents.test("agent_123", "Hello, how can you help?")
print(response)

Calls

# Create a call
call = client.calls.create(
    agent_id="agent_123",
    to_number="[phone]",
    from_number="+0987654321",
    metadata={"customer_id": "cust_456"},
)

# List calls
calls = client.calls.list(
    agent_id="agent_123",
    status="completed",
)

# Get call details
call = client.calls.retrieve("CA123456")

# End a call
client.calls.end("CA123456")

# Transfer a call
client.calls.transfer("CA123456", to_number="[phone]")

# Get call transcript
transcript = client.calls.get_transcript("CA123456")
print(transcript)

# Get call recording
recording = client.calls.get_recording("CA123456")
print(recording["url"])

Campaigns

# Create a campaign
campaign = client.campaigns.create(
    name="Q1 Outreach Campaign",
    agent_id="agent_123",
    contacts=[
        {"name": "John Doe", "phone": "[phone]"},
        {"name": "Jane Smith", "phone": "+0987654321"},
    ],
)

# Start campaign
client.campaigns.start("campaign_123")

# Pause campaign
client.campaigns.pause("campaign_123")

# Get campaign stats
stats = client.campaigns.get_stats("campaign_123")
print(f"Success rate: {stats['success_rate']}")

Knowledge Base

# Upload a document
with open("manual.pdf", "rb") as f:
    doc = client.knowledge.upload(
        name="Product Manual",
        file=f,
        doc_type="pdf",
    )

# Upload from text
doc = client.knowledge.upload(
    name="FAQ",
    content="Q: How do I reset my password? A: Click forgot password...",
    doc_type="txt",
)

# Search knowledge base
results = client.knowledge.search(
    query="How do I reset my password?",
    limit=5,
)

for result in results["results"]:
    print(f"Score: {result['score']}")
    print(f"Content: {result['content']}")

# Delete a document
client.knowledge.delete("doc_123")

Analytics

# Get dashboard statistics
stats = client.analytics.get_stats()
print(f"Total calls: {stats.total_calls}")
print(f"Active agents: {stats.active_agents}")
print(f"Success rate: {stats.success_rate}")

# Get call volume over time
volume = client.analytics.get_call_volume(period="7d")

# Get agent performance
performance = client.analytics.get_agent_performance("agent_123")

# Export data
data = client.analytics.export(
    start_date="2024-01-01",
    end_date="2024-01-31",
    format="csv",
)

Integrations

# Create an integration
integration = client.integrations.create(
    name="Salesforce CRM",
    integration_type="salesforce",
    config={
        "client_id": "...",
        "client_secret": "...",
    },
)

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

# Delete integration
client.integrations.delete("int_123")

Phone Numbers

# Search available numbers
numbers = client.phone_numbers.search(
    country_code="US",
    area_code="415",
)

# Purchase a number
number = client.phone_numbers.purchase("[phone]")

# Release a number
client.phone_numbers.release("num_123")

Voice Cloning

# Create a custom voice
with open("sample1.wav", "rb") as f1, open("sample2.wav", "rb") as f2:
    voice = client.voice_cloning.create(
        name="Custom Voice",
        description="My custom voice profile",
        audio_files=[f1, f2],
        provider="elevenlabs",
    )

# List voices
voices = client.voice_cloning.list()

# Delete voice
client.voice_cloning.delete("voice_123")

Error Handling

from pollax import (
    Pollax,
    PollaxError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
)

client = Pollax(api_key="sk_live_...")

try:
    agent = client.agents.retrieve("agent_123")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Agent not found")
except RateLimitError:
    print("Rate limit exceeded, try again later")
except PollaxError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")

Type Safety

The SDK uses Pydantic for data validation and type safety:

from pollax import Pollax
from pollax.models import Agent, Call

client = Pollax(api_key="sk_live_...")

# Full type hints
agent: Agent = client.agents.create(
    name="Support Agent",
    system_prompt="You are helpful",
    model="gpt-4",
)

# IDE autocomplete works perfectly
print(agent.id)
print(agent.name)
print(agent.created_at)

Development

# Clone repository
git clone https://github.com/pollax/pollax-python
cd pollax-python

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black pollax tests

# Type checking
mypy pollax

License

MIT

Support

• 📧 Email: [e-mail]
• 💬 Discord Community
• 🐛 Report Issues
• 📖 Documentation