agentphone 0.1.0__tar.gz

agentphone-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/

agentphone-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: agentphone
+Version: 0.1.0
+Summary: AgentPhone Python SDK — give your AI agents phone numbers, SMS, and voice calls
+Project-URL: Homepage, https://agentphone.to
+Project-URL: Repository, https://github.com/AgentPhone-AI/agentphone-python
+Project-URL: Documentation, https://docs.agentphone.to
+Author-email: AgentPhone <hello@agentphone.to>
+License: MIT
+Keywords: agentphone,ai,phone,sms,telephony,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentPhone Python SDK
+
+Official Python SDK for [AgentPhone](https://agentphone.to) — give your AI agents real phone numbers, SMS, and voice calls.
+
+## Installation
+
+```bash
+pip install agentphone
+```
+
+For async support:
+
+```bash
+pip install agentphone[async]
+```
+
+## Quickstart
+
+```python
+from agentphone import AgentPhone
+
+client = AgentPhone(api_key="your-api-key")
+
+# Create an agent and buy a number
+agent = client.agents.create(name="My Agent")
+number = client.numbers.buy(country="US", agent_id=agent.id)
+
+# Make an AI conversation call — no webhook needed
+call = client.calls.make_conversation(
+    agent_id=agent.id,
+    to_number="+14155551234",
+    topic="You are a friendly assistant. Ask about their day.",
+    initial_greeting="Hey! This is an AI calling from AgentPhone.",
+)
+print(call.status)  # registered
+```
+
+## Async
+
+```python
+from agentphone import AsyncAgentPhone
+
+async with AsyncAgentPhone(api_key="your-api-key") as client:
+    numbers = await client.numbers.list()
+    call = await client.calls.make_conversation(...)
+```
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.numbers` | `list()`, `buy()`, `release()`, `get_messages()` |
+| `client.agents` | `list()`, `create()`, `get()`, `attach_number()` |
+| `client.calls` | `list()`, `get()`, `make()`, `make_conversation()` |
+| `client.conversations` | `list()`, `get()` |
+| `client.webhooks` | `get()`, `set()`, `delete()`, `list_deliveries()`, `test()` |
+
+## Webhook Verification
+
+```python
+from agentphone import construct_event, WebhookVerificationError
+
+@app.post("/webhook")
+async def handle(request: Request):
+    body = await request.body()
+    sig = request.headers["X-Webhook-Signature"]
+    try:
+        event = construct_event(body, sig, secret="whsec_...")
+    except WebhookVerificationError:
+        return Response(status_code=403)
+
+    if event.event == "agent.message":
+        print(f"SMS from {event.data.from_number}: {event.data.message}")
+```
+
+## Error Handling
+
+```python
+from agentphone import AgentPhoneError, AuthenticationError, NotFoundError
+
+try:
+    call = client.calls.get("bad-id")
+except NotFoundError:
+    print("Call not found")
+except AgentPhoneError as e:
+    print(f"API error {e.status}: {e.message}")
+```
+
+## Publishing to PyPI
+
+1. **Install build tools** (one-time):
+   ```bash
+   pip install hatch twine
+   ```
+
+2. **Build** the package:
+   ```bash
+   hatch build
+   ```
+   This creates a `dist/` folder with the `.tar.gz` and `.whl` files.
+
+3. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   You'll be prompted for your PyPI credentials. To use an API token instead:
+   ```bash
+   twine upload dist/* -u __token__ -p pypi-your-token-here
+   ```
+
+4. **Publishing a new version** — bump the version in `pyproject.toml` first:
+   ```toml
+   version = "0.1.1"
+   ```
+   Then rebuild and upload:
+   ```bash
+   hatch build && twine upload dist/*
+   ```
+
+## Requirements
+
+- Python 3.9+
+- `requests` (sync client)
+- `httpx` (async client, optional)
+
+## Links
+
+- [AgentPhone Dashboard](https://agentphone.to)
+- [MCP Server](https://github.com/AgentPhone-AI/agentphone-mcp)
+- [Node.js SDK](https://github.com/AgentPhone-AI/agentphone-node)

agentphone-0.1.0/README.md

@@ -0,0 +1,130 @@
+# AgentPhone Python SDK
+
+Official Python SDK for [AgentPhone](https://agentphone.to) — give your AI agents real phone numbers, SMS, and voice calls.
+
+## Installation
+
+```bash
+pip install agentphone
+```
+
+For async support:
+
+```bash
+pip install agentphone[async]
+```
+
+## Quickstart
+
+```python
+from agentphone import AgentPhone
+
+client = AgentPhone(api_key="your-api-key")
+
+# Create an agent and buy a number
+agent = client.agents.create(name="My Agent")
+number = client.numbers.buy(country="US", agent_id=agent.id)
+
+# Make an AI conversation call — no webhook needed
+call = client.calls.make_conversation(
+    agent_id=agent.id,
+    to_number="+14155551234",
+    topic="You are a friendly assistant. Ask about their day.",
+    initial_greeting="Hey! This is an AI calling from AgentPhone.",
+)
+print(call.status)  # registered
+```
+
+## Async
+
+```python
+from agentphone import AsyncAgentPhone
+
+async with AsyncAgentPhone(api_key="your-api-key") as client:
+    numbers = await client.numbers.list()
+    call = await client.calls.make_conversation(...)
+```
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.numbers` | `list()`, `buy()`, `release()`, `get_messages()` |
+| `client.agents` | `list()`, `create()`, `get()`, `attach_number()` |
+| `client.calls` | `list()`, `get()`, `make()`, `make_conversation()` |
+| `client.conversations` | `list()`, `get()` |
+| `client.webhooks` | `get()`, `set()`, `delete()`, `list_deliveries()`, `test()` |
+
+## Webhook Verification
+
+```python
+from agentphone import construct_event, WebhookVerificationError
+
+@app.post("/webhook")
+async def handle(request: Request):
+    body = await request.body()
+    sig = request.headers["X-Webhook-Signature"]
+    try:
+        event = construct_event(body, sig, secret="whsec_...")
+    except WebhookVerificationError:
+        return Response(status_code=403)
+
+    if event.event == "agent.message":
+        print(f"SMS from {event.data.from_number}: {event.data.message}")
+```
+
+## Error Handling
+
+```python
+from agentphone import AgentPhoneError, AuthenticationError, NotFoundError
+
+try:
+    call = client.calls.get("bad-id")
+except NotFoundError:
+    print("Call not found")
+except AgentPhoneError as e:
+    print(f"API error {e.status}: {e.message}")
+```
+
+## Publishing to PyPI
+
+1. **Install build tools** (one-time):
+   ```bash
+   pip install hatch twine
+   ```
+
+2. **Build** the package:
+   ```bash
+   hatch build
+   ```
+   This creates a `dist/` folder with the `.tar.gz` and `.whl` files.
+
+3. **Upload to PyPI**:
+   ```bash
+   twine upload dist/*
+   ```
+   You'll be prompted for your PyPI credentials. To use an API token instead:
+   ```bash
+   twine upload dist/* -u __token__ -p pypi-your-token-here
+   ```
+
+4. **Publishing a new version** — bump the version in `pyproject.toml` first:
+   ```toml
+   version = "0.1.1"
+   ```
+   Then rebuild and upload:
+   ```bash
+   hatch build && twine upload dist/*
+   ```
+
+## Requirements
+
+- Python 3.9+
+- `requests` (sync client)
+- `httpx` (async client, optional)
+
+## Links
+
+- [AgentPhone Dashboard](https://agentphone.to)
+- [MCP Server](https://github.com/AgentPhone-AI/agentphone-mcp)
+- [Node.js SDK](https://github.com/AgentPhone-AI/agentphone-node)

agentphone-0.1.0/agentphone/__init__.py

@@ -0,0 +1,78 @@
+"""
+AgentPhone Python SDK
+
+Give your AI agents phone numbers, SMS, and voice calls.
+
+Usage::
+
+    from agentphone import AgentPhone
+
+    client = AgentPhone(api_key="your-api-key")
+    number = client.numbers.buy(country="US")
+    call = client.calls.make_conversation(
+        agent_id="...",
+        to_number="+14155551234",
+        topic="You are a friendly assistant. Ask about their day.",
+    )
+"""
+
+from .async_client import AsyncAgentPhone
+from .client import AgentPhone
+from ._http import AgentPhoneError, AuthenticationError, NotFoundError, RateLimitError
+from .models import (
+    Agent,
+    AgentList,
+    AgentNumber,
+    Call,
+    CallList,
+    CallTranscript,
+    Conversation,
+    ConversationList,
+    ConversationMessage,
+    Message,
+    MessageList,
+    PhoneNumber,
+    PhoneNumberList,
+    Webhook,
+    WebhookDelivery,
+    WebhookEvent,
+    WebhookEventData,
+    WebhookHistoryItem,
+)
+from .webhook import WebhookVerificationError, construct_event, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "AgentPhone",
+    "AsyncAgentPhone",
+    # Errors
+    "AgentPhoneError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "WebhookVerificationError",
+    # Webhook helpers
+    "verify_webhook",
+    "construct_event",
+    # Models
+    "Agent",
+    "AgentList",
+    "AgentNumber",
+    "Call",
+    "CallList",
+    "CallTranscript",
+    "Conversation",
+    "ConversationList",
+    "ConversationMessage",
+    "Message",
+    "MessageList",
+    "PhoneNumber",
+    "PhoneNumberList",
+    "Webhook",
+    "WebhookDelivery",
+    "WebhookEvent",
+    "WebhookEventData",
+    "WebhookHistoryItem",
+]

agentphone-0.1.0/agentphone/_http.py

@@ -0,0 +1,44 @@
+"""
+Shared HTTP logic for sync and async clients.
+"""
+
+from __future__ import annotations
+
+DEFAULT_BASE_URL = "https://api.agentphone.to"
+
+
+class AgentPhoneError(Exception):
+    """Raised when the AgentPhone API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"AgentPhone API error {status}: {message}")
+
+
+class AuthenticationError(AgentPhoneError):
+    pass
+
+
+class NotFoundError(AgentPhoneError):
+    pass
+
+
+class RateLimitError(AgentPhoneError):
+    pass
+
+
+def _raise_for_status(status: int, text: str) -> None:
+    try:
+        import json as _json
+        detail = _json.loads(text).get("detail") or _json.loads(text).get("message") or text
+    except Exception:
+        detail = text
+
+    if status == 401:
+        raise AuthenticationError(status, detail)
+    if status == 404:
+        raise NotFoundError(status, detail)
+    if status == 429:
+        raise RateLimitError(status, detail)
+    raise AgentPhoneError(status, detail)

agentphone-0.1.0/agentphone/async_client.py

@@ -0,0 +1,210 @@
+"""
+Asynchronous AgentPhone client (requires httpx).
+"""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+from ._http import DEFAULT_BASE_URL, _raise_for_status
+from .models import (
+    Agent,
+    AgentList,
+    Call,
+    CallList,
+    Conversation,
+    ConversationList,
+    MessageList,
+    PhoneNumber,
+    PhoneNumberList,
+    Webhook,
+    WebhookDelivery,
+)
+
+
+class _AsyncResource:
+    def __init__(self, client: "AsyncAgentPhone") -> None:
+        self._client = client
+
+    async def _get(self, path: str, **params) -> dict:
+        return await self._client._request("GET", path, params=params or None)
+
+    async def _post(self, path: str, **body) -> dict:
+        return await self._client._request(
+            "POST", path, json={k: v for k, v in body.items() if v is not None}
+        )
+
+    async def _delete(self, path: str) -> dict:
+        return await self._client._request("DELETE", path)
+
+
+class AsyncNumbersResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> PhoneNumberList:
+        return PhoneNumberList.from_dict(await self._get("/v1/numbers", limit=limit, offset=offset))
+
+    async def buy(self, country: str = "US", agent_id: Optional[str] = None) -> PhoneNumber:
+        return PhoneNumber.from_dict(await self._post("/v1/numbers", country=country, agentId=agent_id))
+
+    async def release(self, number_id: str) -> dict:
+        return await self._delete(f"/v1/numbers/{number_id}")
+
+    async def get_messages(self, number_id: str, limit: int = 50) -> MessageList:
+        return MessageList.from_dict(await self._get(f"/v1/numbers/{number_id}/messages", limit=limit))
+
+
+class AsyncAgentsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> AgentList:
+        return AgentList.from_dict(await self._get("/v1/agents", limit=limit, offset=offset))
+
+    async def create(self, name: str, description: Optional[str] = None) -> Agent:
+        return Agent.from_dict(await self._post("/v1/agents", name=name, description=description))
+
+    async def get(self, agent_id: str) -> Agent:
+        return Agent.from_dict(await self._get(f"/v1/agents/{agent_id}"))
+
+    async def attach_number(self, agent_id: str, number_id: str) -> dict:
+        return await self._post(f"/v1/agents/{agent_id}/numbers", numberId=number_id)
+
+
+class AsyncCallsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> CallList:
+        return CallList.from_dict(await self._get("/v1/calls", limit=limit, offset=offset))
+
+    async def get(self, call_id: str) -> Call:
+        return Call.from_dict(await self._get(f"/v1/calls/{call_id}"))
+
+    async def make(
+        self,
+        agent_id: str,
+        to_number: str,
+        initial_greeting: Optional[str] = None,
+    ) -> Call:
+        return Call.from_dict(
+            await self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                initialGreeting=initial_greeting,
+            )
+        )
+
+    async def make_conversation(
+        self,
+        agent_id: str,
+        to_number: str,
+        topic: str,
+        initial_greeting: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> Call:
+        return Call.from_dict(
+            await self._post(
+                "/v1/calls",
+                agentId=agent_id,
+                toNumber=to_number,
+                systemPrompt=topic,
+                initialGreeting=initial_greeting,
+                model=model,
+            )
+        )
+
+
+class AsyncConversationsResource(_AsyncResource):
+    async def list(self, limit: int = 20, offset: int = 0) -> ConversationList:
+        return ConversationList.from_dict(await self._get("/v1/conversations", limit=limit, offset=offset))
+
+    async def get(self, conversation_id: str, message_limit: int = 50) -> Conversation:
+        return Conversation.from_dict(
+            await self._get(f"/v1/conversations/{conversation_id}", message_limit=message_limit)
+        )
+
+
+class AsyncWebhooksResource(_AsyncResource):
+    async def get(self) -> Optional[Webhook]:
+        data = await self._get("/v1/webhooks")
+        return Webhook.from_dict(data) if data else None
+
+    async def set(self, url: str, context_limit: Optional[int] = None) -> Webhook:
+        return Webhook.from_dict(await self._post("/v1/webhooks", url=url, contextLimit=context_limit))
+
+    async def delete(self) -> dict:
+        return await self._delete("/v1/webhooks")
+
+    async def list_deliveries(self, limit: int = 50) -> list[WebhookDelivery]:
+        data = await self._get("/v1/webhooks/deliveries", limit=limit)
+        return [WebhookDelivery.from_dict(d) for d in data]
+
+    async def test(self) -> dict:
+        return await self._post("/v1/webhooks/test")
+
+
+class AsyncAgentPhone:
+    """
+    Asynchronous AgentPhone client.
+
+    Requires: pip install agentphone[async]
+
+    Example::
+
+        from agentphone import AsyncAgentPhone
+
+        async with AsyncAgentPhone(api_key="your-api-key") as client:
+            number = await client.numbers.buy(country="US")
+            call = await client.calls.make_conversation(
+                agent_id="...",
+                to_number="+14155551234",
+                topic="You are a friendly assistant.",
+            )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError:
+            raise ImportError(
+                "The async client requires httpx. Install it with: pip install agentphone[async]"
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = _httpx.AsyncClient(
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "agentphone-python/0.1.0",
+            },
+            timeout=timeout,
+        )
+
+        self.numbers = AsyncNumbersResource(self)
+        self.agents = AsyncAgentsResource(self)
+        self.calls = AsyncCallsResource(self)
+        self.conversations = AsyncConversationsResource(self)
+        self.webhooks = AsyncWebhooksResource(self)
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:  # type: ignore[override]
+        url = f"{self.base_url}{path}"
+        resp = await self._client.request(method, url, **kwargs)
+
+        if not resp.is_success:
+            _raise_for_status(resp.status_code, resp.text)
+
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncAgentPhone":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()