pollax 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pollax/__init__.py ADDED
@@ -0,0 +1,43 @@
1
+ """
2
+ Pollax Python SDK
3
+
4
+ Official Python client library for the Pollax AI Voice Platform.
5
+ """
6
+
7
+ __version__ = "1.0.0"
8
+
9
+ from .client import Pollax
10
+ from .errors import (
11
+ PollaxError,
12
+ AuthenticationError,
13
+ NotFoundError,
14
+ RateLimitError,
15
+ ValidationError,
16
+ )
17
+ from .models import (
18
+ Agent,
19
+ Call,
20
+ Campaign,
21
+ KnowledgeDocument,
22
+ Integration,
23
+ PhoneNumber,
24
+ ApiKey,
25
+ VoiceProfile,
26
+ )
27
+
28
+ __all__ = [
29
+ "Pollax",
30
+ "PollaxError",
31
+ "AuthenticationError",
32
+ "NotFoundError",
33
+ "RateLimitError",
34
+ "ValidationError",
35
+ "Agent",
36
+ "Call",
37
+ "Campaign",
38
+ "KnowledgeDocument",
39
+ "Integration",
40
+ "PhoneNumber",
41
+ "ApiKey",
42
+ "VoiceProfile",
43
+ ]
pollax/client.py ADDED
@@ -0,0 +1,188 @@
1
+ """Pollax API client"""
2
+
3
+ from typing import Optional
4
+ import time
5
+ import httpx
6
+
7
+ from .resources.agents import AgentsResource
8
+ from .resources.calls import CallsResource
9
+ from .resources.campaigns import CampaignsResource
10
+ from .resources.knowledge import KnowledgeResource
11
+ from .resources.analytics import AnalyticsResource
12
+ from .resources.integrations import IntegrationsResource
13
+ from .resources.phone_numbers import PhoneNumbersResource
14
+ from .resources.api_keys import ApiKeysResource
15
+ from .resources.voice_cloning import VoiceCloningResource
16
+ from .errors import PollaxError, AuthenticationError, NotFoundError, RateLimitError
17
+
18
+
19
+ class Pollax:
20
+ """
21
+ Pollax API client.
22
+
23
+ Example:
24
+ >>> from pollax import Pollax
25
+ >>> client = Pollax(api_key="sk_live_...")
26
+ >>> agent = client.agents.create(
27
+ ... name="Support Agent",
28
+ ... system_prompt="You are helpful",
29
+ ... )
30
+ """
31
+
32
+ def __init__(
33
+ self,
34
+ api_key: str,
35
+ base_url: str = "https://api.pollax.ai",
36
+ timeout: float = 30.0,
37
+ max_retries: int = 3,
38
+ tenant_id: Optional[str] = None,
39
+ ):
40
+ """
41
+ Initialize Pollax client.
42
+
43
+ Args:
44
+ api_key: Your Pollax API key (required)
45
+ base_url: Base URL for the API
46
+ timeout: Request timeout in seconds
47
+ max_retries: Maximum number of retry attempts
48
+ tenant_id: Organization/tenant ID (optional)
49
+
50
+ Raises:
51
+ ValueError: If api_key is not provided
52
+ """
53
+ if not api_key:
54
+ raise ValueError("API key is required. Get one at https://pollax.ai/settings/api-keys")
55
+
56
+ self.api_key = api_key
57
+ self.base_url = base_url.rstrip("/")
58
+ self.max_retries = max_retries
59
+
60
+ headers = {
61
+ "Authorization": f"Bearer {api_key}",
62
+ "Content-Type": "application/json",
63
+ "User-Agent": "Pollax-SDK-Python/1.0.0",
64
+ }
65
+
66
+ if tenant_id:
67
+ headers["X-Tenant-ID"] = tenant_id
68
+
69
+ self.client = httpx.Client(
70
+ base_url=self.base_url,
71
+ headers=headers,
72
+ timeout=timeout,
73
+ )
74
+
75
+ # Initialize resources
76
+ self.agents = AgentsResource(self)
77
+ self.calls = CallsResource(self)
78
+ self.campaigns = CampaignsResource(self)
79
+ self.knowledge = KnowledgeResource(self)
80
+ self.analytics = AnalyticsResource(self)
81
+ self.integrations = IntegrationsResource(self)
82
+ self.phone_numbers = PhoneNumbersResource(self)
83
+ self.api_keys = ApiKeysResource(self)
84
+ self.voice_cloning = VoiceCloningResource(self)
85
+
86
+ def request(
87
+ self,
88
+ method: str,
89
+ path: str,
90
+ *,
91
+ json: Optional[dict] = None,
92
+ params: Optional[dict] = None,
93
+ files: Optional[dict] = None,
94
+ _retries: int = 0,
95
+ ) -> dict:
96
+ """
97
+ Make an HTTP request with automatic retries.
98
+
99
+ Args:
100
+ method: HTTP method (GET, POST, PUT, DELETE)
101
+ path: API endpoint path
102
+ json: JSON request body
103
+ params: Query parameters
104
+ files: Files to upload
105
+ _retries: Internal retry counter
106
+
107
+ Returns:
108
+ Response data as dictionary
109
+
110
+ Raises:
111
+ PollaxError: On API errors
112
+ AuthenticationError: On authentication failures
113
+ NotFoundError: When resource not found
114
+ RateLimitError: When rate limit exceeded
115
+ """
116
+ try:
117
+ if files:
118
+ # Remove Content-Type for multipart/form-data
119
+ headers = {k: v for k, v in self.client.headers.items() if k != "Content-Type"}
120
+ response = self.client.request(
121
+ method,
122
+ path,
123
+ params=params,
124
+ files=files,
125
+ headers=headers,
126
+ )
127
+ else:
128
+ response = self.client.request(
129
+ method,
130
+ path,
131
+ json=json,
132
+ params=params,
133
+ )
134
+
135
+ response.raise_for_status()
136
+
137
+ # Handle empty responses
138
+ if not response.content:
139
+ return {}
140
+
141
+ return response.json()
142
+
143
+ except httpx.HTTPStatusError as e:
144
+ status_code = e.response.status_code
145
+
146
+ # Handle rate limiting with exponential backoff
147
+ if status_code == 429 and _retries < self.max_retries:
148
+ retry_after = int(e.response.headers.get("Retry-After", "1"))
149
+ time.sleep(retry_after)
150
+ return self.request(method, path, json=json, params=params, files=files, _retries=_retries + 1)
151
+
152
+ # Parse error message
153
+ try:
154
+ error_data = e.response.json()
155
+ message = error_data.get("error") or error_data.get("detail", str(e))
156
+ except Exception:
157
+ message = str(e)
158
+
159
+ # Raise appropriate error type
160
+ if status_code == 401:
161
+ raise AuthenticationError(message)
162
+ elif status_code == 404:
163
+ raise NotFoundError(message)
164
+ elif status_code == 429:
165
+ raise RateLimitError(message)
166
+ else:
167
+ raise PollaxError(message, status_code=status_code)
168
+
169
+ except httpx.RequestError as e:
170
+ # Retry on network errors
171
+ if _retries < self.max_retries:
172
+ delay = 2 ** _retries # Exponential backoff
173
+ time.sleep(delay)
174
+ return self.request(method, path, json=json, params=params, files=files, _retries=_retries + 1)
175
+
176
+ raise PollaxError(f"Network error: {str(e)}")
177
+
178
+ def close(self) -> None:
179
+ """Close the HTTP client."""
180
+ self.client.close()
181
+
182
+ def __enter__(self) -> "Pollax":
183
+ """Context manager entry."""
184
+ return self
185
+
186
+ def __exit__(self, *args) -> None:
187
+ """Context manager exit."""
188
+ self.close()
pollax/errors.py ADDED
@@ -0,0 +1,38 @@
1
+ """Custom exceptions for Pollax SDK"""
2
+
3
+
4
+ class PollaxError(Exception):
5
+ """Base exception for all Pollax errors."""
6
+
7
+ def __init__(self, message: str, status_code: int = 0):
8
+ super().__init__(message)
9
+ self.message = message
10
+ self.status_code = status_code
11
+
12
+
13
+ class AuthenticationError(PollaxError):
14
+ """Raised when authentication fails."""
15
+
16
+ def __init__(self, message: str = "Authentication failed"):
17
+ super().__init__(message, status_code=401)
18
+
19
+
20
+ class NotFoundError(PollaxError):
21
+ """Raised when a requested resource is not found."""
22
+
23
+ def __init__(self, message: str = "Resource not found"):
24
+ super().__init__(message, status_code=404)
25
+
26
+
27
+ class RateLimitError(PollaxError):
28
+ """Raised when rate limit is exceeded."""
29
+
30
+ def __init__(self, message: str = "Rate limit exceeded"):
31
+ super().__init__(message, status_code=429)
32
+
33
+
34
+ class ValidationError(PollaxError):
35
+ """Raised for validation errors."""
36
+
37
+ def __init__(self, message: str = "Validation error"):
38
+ super().__init__(message, status_code=400)
pollax/models.py ADDED
@@ -0,0 +1,149 @@
1
+ """Pydantic models for Pollax API"""
2
+
3
+ from datetime import datetime
4
+ from typing import Any, Dict, List, Literal, Optional
5
+ from pydantic import BaseModel, Field
6
+
7
+
8
+ class Agent(BaseModel):
9
+ """AI Agent model"""
10
+
11
+ id: str
12
+ name: str
13
+ description: Optional[str] = None
14
+ system_prompt: str
15
+ provider: Literal["openai", "anthropic", "ollama"] = "openai"
16
+ model: str = "gpt-4"
17
+ voice_provider: Optional[Literal["elevenlabs", "openai", "google"]] = None
18
+ voice_id: Optional[str] = None
19
+ stt_provider: Optional[Literal["deepgram", "whisper", "google"]] = "deepgram"
20
+ temperature: Optional[float] = None
21
+ max_tokens: Optional[int] = None
22
+ is_active: bool = True
23
+ tenant_id: str
24
+ config: Optional[Dict[str, Any]] = None
25
+ created_at: datetime
26
+ updated_at: datetime
27
+ calls_count: Optional[int] = None
28
+ success_rate: Optional[str] = None
29
+ avg_duration: Optional[str] = None
30
+
31
+
32
+ class Call(BaseModel):
33
+ """Voice call model"""
34
+
35
+ call_sid: str
36
+ agent_id: str
37
+ to_number: str
38
+ from_number: Optional[str] = None
39
+ status: Literal["queued", "ringing", "in-progress", "completed", "failed", "busy", "no-answer"]
40
+ direction: Literal["inbound", "outbound"]
41
+ duration: Optional[int] = None
42
+ start_time: Optional[datetime] = None
43
+ end_time: Optional[datetime] = None
44
+ recording_url: Optional[str] = None
45
+ transcript: Optional[str] = None
46
+ metadata: Optional[Dict[str, Any]] = None
47
+ created_at: datetime
48
+ agent_name: Optional[str] = None
49
+
50
+
51
+ class Contact(BaseModel):
52
+ """Campaign contact model"""
53
+
54
+ name: Optional[str] = None
55
+ phone: str
56
+ email: Optional[str] = None
57
+ metadata: Optional[Dict[str, Any]] = None
58
+
59
+
60
+ class Campaign(BaseModel):
61
+ """Campaign model"""
62
+
63
+ id: str
64
+ name: str
65
+ agent_id: Optional[str] = None
66
+ agent_name: Optional[str] = None
67
+ status: Literal["draft", "scheduled", "running", "paused", "completed", "cancelled"]
68
+ scheduled_time: Optional[datetime] = None
69
+ contacts: List[Contact] = Field(default_factory=list)
70
+ total_contacts: int = 0
71
+ completed_calls: int = 0
72
+ successful_calls: int = 0
73
+ failed_calls: int = 0
74
+ tenant_id: str
75
+ created_at: datetime
76
+ updated_at: datetime
77
+
78
+
79
+ class KnowledgeDocument(BaseModel):
80
+ """Knowledge base document model"""
81
+
82
+ id: str
83
+ name: str
84
+ type: Literal["pdf", "txt", "docx", "url"]
85
+ content: Optional[str] = None
86
+ url: Optional[str] = None
87
+ chunks_count: int = 0
88
+ status: Literal["processing", "ready", "failed"]
89
+ tenant_id: str
90
+ created_at: datetime
91
+
92
+
93
+ class DashboardStats(BaseModel):
94
+ """Dashboard statistics model"""
95
+
96
+ total_calls: int
97
+ active_agents: int
98
+ success_rate: str
99
+ avg_duration: str
100
+ calls_by_status: Dict[str, int]
101
+
102
+
103
+ class Integration(BaseModel):
104
+ """Integration model"""
105
+
106
+ id: str
107
+ name: str
108
+ type: Literal["twilio", "salesforce", "hubspot", "slack", "zapier", "webhook"]
109
+ config: Dict[str, Any]
110
+ is_active: bool
111
+ tenant_id: str
112
+ created_at: datetime
113
+ updated_at: datetime
114
+
115
+
116
+ class PhoneNumber(BaseModel):
117
+ """Phone number model"""
118
+
119
+ id: str
120
+ phone_number: str
121
+ country_code: str
122
+ capabilities: Dict[str, bool]
123
+ is_active: bool
124
+ tenant_id: str
125
+ created_at: datetime
126
+
127
+
128
+ class ApiKey(BaseModel):
129
+ """API key model"""
130
+
131
+ id: str
132
+ name: str
133
+ key_prefix: str
134
+ last_used_at: Optional[datetime] = None
135
+ is_active: bool
136
+ created_at: datetime
137
+
138
+
139
+ class VoiceProfile(BaseModel):
140
+ """Voice cloning profile model"""
141
+
142
+ id: str
143
+ name: str
144
+ description: Optional[str] = None
145
+ voice_id: str
146
+ provider: Literal["elevenlabs", "openai"]
147
+ status: Literal["training", "ready", "failed"]
148
+ tenant_id: str
149
+ created_at: datetime
@@ -0,0 +1,23 @@
1
+ """Resource modules"""
2
+
3
+ from .agents import AgentsResource
4
+ from .calls import CallsResource
5
+ from .campaigns import CampaignsResource
6
+ from .knowledge import KnowledgeResource
7
+ from .analytics import AnalyticsResource
8
+ from .integrations import IntegrationsResource
9
+ from .phone_numbers import PhoneNumbersResource
10
+ from .api_keys import ApiKeysResource
11
+ from .voice_cloning import VoiceCloningResource
12
+
13
+ __all__ = [
14
+ "AgentsResource",
15
+ "CallsResource",
16
+ "CampaignsResource",
17
+ "KnowledgeResource",
18
+ "AnalyticsResource",
19
+ "IntegrationsResource",
20
+ "PhoneNumbersResource",
21
+ "ApiKeysResource",
22
+ "VoiceCloningResource",
23
+ ]
@@ -0,0 +1,196 @@
1
+ """Agents resource"""
2
+
3
+ from typing import List, Optional, TYPE_CHECKING
4
+ from ..models import Agent
5
+
6
+ if TYPE_CHECKING:
7
+ from ..client import Pollax
8
+
9
+
10
+ class AgentsResource:
11
+ """Agents API resource"""
12
+
13
+ def __init__(self, client: "Pollax"):
14
+ self._client = client
15
+
16
+ def create(
17
+ self,
18
+ name: str,
19
+ system_prompt: str,
20
+ description: Optional[str] = None,
21
+ provider: str = "openai",
22
+ model: str = "gpt-4",
23
+ voice_provider: Optional[str] = None,
24
+ voice_id: Optional[str] = None,
25
+ stt_provider: str = "deepgram",
26
+ temperature: Optional[float] = None,
27
+ max_tokens: Optional[int] = None,
28
+ config: Optional[dict] = None,
29
+ ) -> Agent:
30
+ """
31
+ Create a new AI agent.
32
+
33
+ Args:
34
+ name: Agent name
35
+ system_prompt: System prompt for the agent
36
+ description: Agent description
37
+ provider: LLM provider (openai, anthropic, ollama)
38
+ model: Model name
39
+ voice_provider: Voice provider (elevenlabs, openai, google)
40
+ voice_id: Voice ID
41
+ stt_provider: Speech-to-text provider
42
+ temperature: Model temperature
43
+ max_tokens: Maximum tokens
44
+ config: Additional configuration
45
+
46
+ Returns:
47
+ Created agent
48
+
49
+ Example:
50
+ >>> agent = client.agents.create(
51
+ ... name="Support Agent",
52
+ ... system_prompt="You are helpful",
53
+ ... voice_id="alloy",
54
+ ... )
55
+ """
56
+ data = {
57
+ "name": name,
58
+ "system_prompt": system_prompt,
59
+ "description": description,
60
+ "provider": provider,
61
+ "model": model,
62
+ "voice_provider": voice_provider,
63
+ "voice_id": voice_id,
64
+ "stt_provider": stt_provider,
65
+ "temperature": temperature,
66
+ "max_tokens": max_tokens,
67
+ "config": config,
68
+ }
69
+ # Remove None values
70
+ data = {k: v for k, v in data.items() if v is not None}
71
+
72
+ response = self._client.request("POST", "/api/v1/agents", json=data)
73
+ return Agent(**response)
74
+
75
+ def list(
76
+ self,
77
+ is_active: Optional[bool] = None,
78
+ skip: int = 0,
79
+ limit: int = 100,
80
+ ) -> List[Agent]:
81
+ """
82
+ List all agents.
83
+
84
+ Args:
85
+ is_active: Filter by active status
86
+ skip: Number of agents to skip
87
+ limit: Maximum number of agents to return
88
+
89
+ Returns:
90
+ List of agents
91
+
92
+ Example:
93
+ >>> agents = client.agents.list(is_active=True)
94
+ """
95
+ params = {"skip": skip, "limit": limit}
96
+ if is_active is not None:
97
+ params["is_active"] = is_active
98
+
99
+ response = self._client.request("GET", "/api/v1/agents", params=params)
100
+ return [Agent(**item) for item in response]
101
+
102
+ def retrieve(self, agent_id: str) -> Agent:
103
+ """
104
+ Get a single agent by ID.
105
+
106
+ Args:
107
+ agent_id: Agent ID
108
+
109
+ Returns:
110
+ Agent
111
+
112
+ Example:
113
+ >>> agent = client.agents.retrieve("agent_123")
114
+ """
115
+ response = self._client.request("GET", f"/api/v1/agents/{agent_id}")
116
+ return Agent(**response)
117
+
118
+ def update(
119
+ self,
120
+ agent_id: str,
121
+ name: Optional[str] = None,
122
+ description: Optional[str] = None,
123
+ system_prompt: Optional[str] = None,
124
+ is_active: Optional[bool] = None,
125
+ **kwargs,
126
+ ) -> Agent:
127
+ """
128
+ Update an agent.
129
+
130
+ Args:
131
+ agent_id: Agent ID
132
+ name: New agent name
133
+ description: New description
134
+ system_prompt: New system prompt
135
+ is_active: Active status
136
+ **kwargs: Additional fields to update
137
+
138
+ Returns:
139
+ Updated agent
140
+
141
+ Example:
142
+ >>> agent = client.agents.update(
143
+ ... "agent_123",
144
+ ... name="New Name",
145
+ ... is_active=False,
146
+ ... )
147
+ """
148
+ data = {
149
+ "name": name,
150
+ "description": description,
151
+ "system_prompt": system_prompt,
152
+ "is_active": is_active,
153
+ **kwargs,
154
+ }
155
+ data = {k: v for k, v in data.items() if v is not None}
156
+
157
+ response = self._client.request("PUT", f"/api/v1/agents/{agent_id}", json=data)
158
+ return Agent(**response)
159
+
160
+ def delete(self, agent_id: str) -> dict:
161
+ """
162
+ Delete an agent.
163
+
164
+ Args:
165
+ agent_id: Agent ID
166
+
167
+ Returns:
168
+ Success response
169
+
170
+ Example:
171
+ >>> client.agents.delete("agent_123")
172
+ """
173
+ return self._client.request("DELETE", f"/api/v1/agents/{agent_id}")
174
+
175
+ def test(self, agent_id: str, message: str) -> dict:
176
+ """
177
+ Test an agent with a sample message.
178
+
179
+ Args:
180
+ agent_id: Agent ID
181
+ message: Test message
182
+
183
+ Returns:
184
+ Agent response
185
+
186
+ Example:
187
+ >>> response = client.agents.test(
188
+ ... "agent_123",
189
+ ... "Hello, how can you help?",
190
+ ... )
191
+ """
192
+ return self._client.request(
193
+ "POST",
194
+ f"/api/v1/agents/{agent_id}/test",
195
+ json={"message": message},
196
+ )
@@ -0,0 +1,35 @@
1
+ """Analytics resource"""
2
+
3
+ from typing import Optional, TYPE_CHECKING
4
+ from ..models import DashboardStats
5
+
6
+ if TYPE_CHECKING:
7
+ from ..client import Pollax
8
+
9
+
10
+ class AnalyticsResource:
11
+ """Analytics API resource"""
12
+
13
+ def __init__(self, client: "Pollax"):
14
+ self._client = client
15
+
16
+ def get_stats(self) -> DashboardStats:
17
+ """Get dashboard statistics."""
18
+ response = self._client.request("GET", "/api/v1/analytics/stats")
19
+ return DashboardStats(**response)
20
+
21
+ def get_call_volume(self, period: str = "7d") -> dict:
22
+ """Get call volume over time."""
23
+ return self._client.request("GET", "/api/v1/analytics/call-volume", params={"period": period})
24
+
25
+ def get_agent_performance(self, agent_id: str) -> dict:
26
+ """Get agent performance metrics."""
27
+ return self._client.request("GET", f"/api/v1/analytics/agents/{agent_id}/performance")
28
+
29
+ def export(self, start_date: str, end_date: str, format: str = "csv") -> dict:
30
+ """Export analytics data."""
31
+ return self._client.request(
32
+ "GET",
33
+ "/api/v1/analytics/export",
34
+ params={"start_date": start_date, "end_date": end_date, "format": format},
35
+ )