agentping-sdk 0.1.0__tar.gz

agentping_sdk-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+*.tsbuildinfo
+
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/

agentping_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: agentping-sdk
+Version: 0.1.0
+Summary: Python SDK for AgentPing — escalation alerts for AI agents via SMS and voice calls.
+Project-URL: Homepage, https://agentping.me
+Project-URL: Documentation, https://agentping.me/docs
+Project-URL: Repository, https://github.com/agentping/agentping-sdk
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# AgentPing Python SDK
+
+Official Python SDK for [AgentPing](https://agentping.me) — escalation alerts for AI agents via voice calls.
+
+## Install
+
+```bash
+pip install agentping
+```
+
+## Quick start
+
+```python
+from agentping import AgentPingClient
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+# Send an alert (voice call with retry)
+alert = client.send_alert(
+    title="Deploy approval needed",
+    severity="normal",
+    message="v2.4.1 ready for production. 3 migrations pending.",
+    alert_type="approval",
+)
+
+print(alert["id"])       # "550e8400-..."
+print(alert["status"])   # "waiting_for_primary_ack"
+
+# Check status later
+status = client.get_alert(alert["id"])
+print(status["status"])  # "acknowledged", "escalating_sms", etc.
+
+# Acknowledge programmatically (stops escalation)
+ack = client.acknowledge(alert["id"])
+print(ack["status"])     # "acknowledged"
+```
+
+## Agent framework integration
+
+The SDK includes an OpenAI-compatible tool definition you can plug into any agent framework:
+
+```python
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+# 1. Add to your agent's tools
+tools = [tool_definition()]
+
+# 2. When the agent calls the tool, handle it:
+# (assuming `tool_call` is the parsed tool call from your framework)
+import json
+
+args = json.loads(tool_call.function.arguments)
+result = handle_tool_call(client, args)
+```
+
+### OpenAI example
+
+```python
+from openai import OpenAI
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+import json
+
+openai = OpenAI()
+agentping = AgentPingClient(api_key="ap_sk_...")
+
+messages = [
+    {"role": "system", "content": """You are a helpful assistant.
+When you need the user's attention and they haven't responded to your message,
+use the agentping_alert tool to escalate via voice call.
+Always try messaging in chat first — use agentping_alert as a fallback."""},
+    {"role": "user", "content": "Monitor my deploy and alert me if it fails."},
+]
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=[tool_definition()],
+)
+
+# Handle tool calls
+for tool_call in response.choices[0].message.tool_calls or []:
+    if tool_call.function.name == "agentping_alert":
+        args = json.loads(tool_call.function.arguments)
+        result = handle_tool_call(agentping, args)
+        print(f"Alert sent: {result['id']}")
+```
+
+### Anthropic Claude example
+
+```python
+from anthropic import Anthropic
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+import json
+
+anthropic = Anthropic()
+agentping = AgentPingClient(api_key="ap_sk_...")
+
+# Convert OpenAI tool format to Anthropic format
+openai_tool = tool_definition()
+anthropic_tool = {
+    "name": openai_tool["function"]["name"],
+    "description": openai_tool["function"]["description"],
+    "input_schema": openai_tool["function"]["parameters"],
+}
+
+response = anthropic.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    system="""You are a helpful assistant.
+When you need the user's attention and they haven't responded,
+use the agentping_alert tool to escalate via voice call.""",
+    messages=[{"role": "user", "content": "Monitor my deploy and alert me if it fails."}],
+    tools=[anthropic_tool],
+)
+
+# Handle tool use
+for block in response.content:
+    if block.type == "tool_use" and block.name == "agentping_alert":
+        result = handle_tool_call(agentping, block.input)
+        print(f"Alert sent: {result['id']}")
+```
+
+## Severity levels
+
+| Severity | Delivery | Behavior |
+|----------|----------|----------|
+| `normal` | Voice call | Call with retry (recommended default) |
+| `critical` | Immediate call | More retries, bypasses quiet hours |
+| `persistent_critical` | Repeated calls | Calls until acknowledged or retry limit hit |
+
+> **Deprecated:** `low` and `urgent` are still accepted but mapped to `normal` by the API.
+
+## Alert types
+
+| Type | Default Delay | Use when |
+|------|---------------|----------|
+| `approval` | 300s (5 min) | Agent needs a decision |
+| `task_failure` | 120s (2 min) | Something broke |
+| `threshold` | 600s (10 min) | Metric crossed a boundary |
+| `reminder` | 300s (5 min) | Time-sensitive nudge |
+| `other` | 0s (immediate) | General escalation |
+
+## Error handling
+
+```python
+from agentping import AgentPingClient, RateLimitError, ForbiddenError
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+try:
+    client.send_alert(title="Test", severity="normal")
+except RateLimitError:
+    print("Too many alerts — wait before retrying")
+except ForbiddenError as e:
+    print(f"Policy violation: {e}")
+```
+
+## API reference
+
+- `AgentPingClient(api_key, base_url=..., timeout=30.0)` — create a client
+- `client.send_alert(title, severity, message=..., alert_type=..., delay_seconds=..., phone_number=..., expires_in_minutes=..., metadata=...)` — create an alert
+- `client.get_alert(alert_id)` — get alert status
+- `client.acknowledge(alert_id, ack_source="api")` — acknowledge an alert
+- `client.close()` — close the HTTP client (also works as a context manager)
+
+## Links
+
+- [AgentPing docs](https://agentping.me/docs)
+- [API reference](https://agentping.me/docs)
+- [GitHub](https://github.com/agentping/agentping-sdk/tree/main/python)

agentping_sdk-0.1.0/README.md

@@ -0,0 +1,172 @@
+# AgentPing Python SDK
+
+Official Python SDK for [AgentPing](https://agentping.me) — escalation alerts for AI agents via voice calls.
+
+## Install
+
+```bash
+pip install agentping
+```
+
+## Quick start
+
+```python
+from agentping import AgentPingClient
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+# Send an alert (voice call with retry)
+alert = client.send_alert(
+    title="Deploy approval needed",
+    severity="normal",
+    message="v2.4.1 ready for production. 3 migrations pending.",
+    alert_type="approval",
+)
+
+print(alert["id"])       # "550e8400-..."
+print(alert["status"])   # "waiting_for_primary_ack"
+
+# Check status later
+status = client.get_alert(alert["id"])
+print(status["status"])  # "acknowledged", "escalating_sms", etc.
+
+# Acknowledge programmatically (stops escalation)
+ack = client.acknowledge(alert["id"])
+print(ack["status"])     # "acknowledged"
+```
+
+## Agent framework integration
+
+The SDK includes an OpenAI-compatible tool definition you can plug into any agent framework:
+
+```python
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+# 1. Add to your agent's tools
+tools = [tool_definition()]
+
+# 2. When the agent calls the tool, handle it:
+# (assuming `tool_call` is the parsed tool call from your framework)
+import json
+
+args = json.loads(tool_call.function.arguments)
+result = handle_tool_call(client, args)
+```
+
+### OpenAI example
+
+```python
+from openai import OpenAI
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+import json
+
+openai = OpenAI()
+agentping = AgentPingClient(api_key="ap_sk_...")
+
+messages = [
+    {"role": "system", "content": """You are a helpful assistant.
+When you need the user's attention and they haven't responded to your message,
+use the agentping_alert tool to escalate via voice call.
+Always try messaging in chat first — use agentping_alert as a fallback."""},
+    {"role": "user", "content": "Monitor my deploy and alert me if it fails."},
+]
+
+response = openai.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=[tool_definition()],
+)
+
+# Handle tool calls
+for tool_call in response.choices[0].message.tool_calls or []:
+    if tool_call.function.name == "agentping_alert":
+        args = json.loads(tool_call.function.arguments)
+        result = handle_tool_call(agentping, args)
+        print(f"Alert sent: {result['id']}")
+```
+
+### Anthropic Claude example
+
+```python
+from anthropic import Anthropic
+from agentping import AgentPingClient, tool_definition, handle_tool_call
+import json
+
+anthropic = Anthropic()
+agentping = AgentPingClient(api_key="ap_sk_...")
+
+# Convert OpenAI tool format to Anthropic format
+openai_tool = tool_definition()
+anthropic_tool = {
+    "name": openai_tool["function"]["name"],
+    "description": openai_tool["function"]["description"],
+    "input_schema": openai_tool["function"]["parameters"],
+}
+
+response = anthropic.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    system="""You are a helpful assistant.
+When you need the user's attention and they haven't responded,
+use the agentping_alert tool to escalate via voice call.""",
+    messages=[{"role": "user", "content": "Monitor my deploy and alert me if it fails."}],
+    tools=[anthropic_tool],
+)
+
+# Handle tool use
+for block in response.content:
+    if block.type == "tool_use" and block.name == "agentping_alert":
+        result = handle_tool_call(agentping, block.input)
+        print(f"Alert sent: {result['id']}")
+```
+
+## Severity levels
+
+| Severity | Delivery | Behavior |
+|----------|----------|----------|
+| `normal` | Voice call | Call with retry (recommended default) |
+| `critical` | Immediate call | More retries, bypasses quiet hours |
+| `persistent_critical` | Repeated calls | Calls until acknowledged or retry limit hit |
+
+> **Deprecated:** `low` and `urgent` are still accepted but mapped to `normal` by the API.
+
+## Alert types
+
+| Type | Default Delay | Use when |
+|------|---------------|----------|
+| `approval` | 300s (5 min) | Agent needs a decision |
+| `task_failure` | 120s (2 min) | Something broke |
+| `threshold` | 600s (10 min) | Metric crossed a boundary |
+| `reminder` | 300s (5 min) | Time-sensitive nudge |
+| `other` | 0s (immediate) | General escalation |
+
+## Error handling
+
+```python
+from agentping import AgentPingClient, RateLimitError, ForbiddenError
+
+client = AgentPingClient(api_key="ap_sk_...")
+
+try:
+    client.send_alert(title="Test", severity="normal")
+except RateLimitError:
+    print("Too many alerts — wait before retrying")
+except ForbiddenError as e:
+    print(f"Policy violation: {e}")
+```
+
+## API reference
+
+- `AgentPingClient(api_key, base_url=..., timeout=30.0)` — create a client
+- `client.send_alert(title, severity, message=..., alert_type=..., delay_seconds=..., phone_number=..., expires_in_minutes=..., metadata=...)` — create an alert
+- `client.get_alert(alert_id)` — get alert status
+- `client.acknowledge(alert_id, ack_source="api")` — acknowledge an alert
+- `client.close()` — close the HTTP client (also works as a context manager)
+
+## Links
+
+- [AgentPing docs](https://agentping.me/docs)
+- [API reference](https://agentping.me/docs)
+- [GitHub](https://github.com/agentping/agentping-sdk/tree/main/python)

agentping_sdk-0.1.0/agentping/__init__.py

@@ -0,0 +1,24 @@
+"""AgentPing Python SDK — escalation alerts for AI agents."""
+
+from agentping.client import AgentPingClient
+from agentping.exceptions import (
+    AgentPingError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from agentping.tool import handle_tool_call, tool_definition
+
+__all__ = [
+    "AgentPingClient",
+    "AgentPingError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "handle_tool_call",
+    "tool_definition",
+]

agentping_sdk-0.1.0/agentping/client.py

@@ -0,0 +1,150 @@
+"""AgentPing API client."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+
+from agentping.exceptions import (
+    AgentPingError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+Severity = Literal[
+    "normal",
+    "critical",
+    "persistent_critical",
+    "low",    # deprecated — mapped to "normal" by the API
+    "urgent",  # deprecated — mapped to "normal" by the API
+]
+AlertType = Literal["approval", "task_failure", "threshold", "reminder", "other"]
+AckSource = Literal["dtmf", "sms_link", "sms_reply", "api", "chat", "manual"]
+
+DEFAULT_BASE_URL = "https://api.agentping.me"
+
+
+class AgentPingClient:
+    """Thin client for the AgentPing alert API.
+
+    Usage::
+
+        from agentping import AgentPingClient
+
+        client = AgentPingClient(api_key="ap_sk_...")
+        alert = client.send_alert(
+            title="Deploy approval needed",
+            severity="normal",
+            alert_type="approval",
+        )
+        print(alert["id"], alert["status"])
+
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    # ── Public API ──────────────────────────────────────────────
+
+    def send_alert(
+        self,
+        *,
+        title: str,
+        severity: Severity,
+        message: str | None = None,
+        alert_type: AlertType | None = None,
+        delay_seconds: int | None = None,
+        phone_number: str | None = None,
+        expires_in_minutes: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create an alert. Returns the created alert object."""
+        body: dict[str, Any] = {"title": title, "severity": severity}
+        if message is not None:
+            body["message"] = message
+        if alert_type is not None:
+            body["alert_type"] = alert_type
+        if delay_seconds is not None:
+            body["delay_seconds"] = delay_seconds
+        if phone_number is not None:
+            body["phone_number"] = phone_number
+        if expires_in_minutes is not None:
+            body["expires_in_minutes"] = expires_in_minutes
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        resp = self._client.post("/v1/alerts", json=body)
+        return self._handle_response(resp)
+
+    def get_alert(self, alert_id: str) -> dict[str, Any]:
+        """Get alert status and delivery details."""
+        resp = self._client.get(f"/v1/alerts/{alert_id}")
+        return self._handle_response(resp)
+
+    def acknowledge(
+        self,
+        alert_id: str,
+        *,
+        ack_source: AckSource = "api",
+    ) -> dict[str, Any]:
+        """Acknowledge an alert to stop escalation."""
+        resp = self._client.post(
+            f"/v1/alerts/{alert_id}/acknowledge",
+            json={"ack_source": ack_source},
+        )
+        return self._handle_response(resp)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> AgentPingClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ── Internals ───────────────────────────────────────────────
+
+    def _handle_response(self, resp: httpx.Response) -> dict[str, Any]:
+        if resp.status_code in (200, 201):
+            return resp.json()
+
+        detail = ""
+        try:
+            body = resp.json()
+            detail = body.get("detail", str(body))
+        except Exception:
+            detail = resp.text
+
+        if resp.status_code == 401:
+            raise AuthenticationError(str(detail), status_code=401)
+        if resp.status_code == 403:
+            raise ForbiddenError(str(detail), status_code=403)
+        if resp.status_code == 404:
+            raise NotFoundError(str(detail), status_code=404)
+        if resp.status_code == 422:
+            errors = detail if isinstance(detail, list) else []
+            raise ValidationError(str(detail), errors=errors)
+        if resp.status_code == 429:
+            raise RateLimitError(str(detail), status_code=429)
+        raise AgentPingError(str(detail), status_code=resp.status_code)

agentping_sdk-0.1.0/agentping/exceptions.py

@@ -0,0 +1,35 @@
+"""Custom exceptions for the AgentPing SDK."""
+
+from __future__ import annotations
+
+
+class AgentPingError(Exception):
+    """Base exception for all AgentPing errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(AgentPingError):
+    """Raised on 401 — missing, invalid, or revoked API key."""
+
+
+class ForbiddenError(AgentPingError):
+    """Raised on 403 — policy violation, trial expired, or quota exceeded."""
+
+
+class NotFoundError(AgentPingError):
+    """Raised on 404 — alert not found or does not belong to user."""
+
+
+class ValidationError(AgentPingError):
+    """Raised on 422 — invalid request body."""
+
+    def __init__(self, message: str, errors: list[dict] | None = None) -> None:
+        super().__init__(message, status_code=422)
+        self.errors = errors or []
+
+
+class RateLimitError(AgentPingError):
+    """Raised on 429 — hourly or per-key rate limit exceeded."""