allternit-platform 0.1.0__tar.gz

allternit_platform-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: allternit-platform
+Version: 0.1.0
+Summary: Python SDK for the Allternit Platform API (agents, conversations, numbers, messaging, webhooks, usage).
+License: Apache-2.0
+Project-URL: Documentation, https://docs.allternit.com/api/platform/sdks/python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# allternit-platform
+
+Python SDK for the [Allternit Platform API](https://docs.allternit.com/api/platform/overview): agents, conversations, numbers, messaging, webhooks and usage.
+
+> **Not yet published to PyPI.** Publishing needs Eoj's OK. Until then, install it from this repo (see below).
+
+- Python 3.9+, standard library only.
+- Typed responses (`TypedDict`s) and one method per API operation, generated from `cmd/allternit-cloud-api/openapi/platform-v1.yaml`.
+- Sends an `Idempotency-Key` on every POST (random unless you pass one).
+- Errors are typed exceptions (`NotFoundError`, `RateLimitError`, …).
+- Cursor pagination helpers and streaming replies.
+
+## Install (from the repo, until it is published)
+
+```bash
+pip install /path/to/allternit/sdk/platform-python
+```
+
+## Quickstart
+
+```python
+from allternit_platform import AllternitPlatform, MessageDelta
+
+client = AllternitPlatform()  # reads ALLTERNIT_API_KEY (alt_test_... or alt_live_...)
+
+account = client.accounts.create(name="Lakeside Dental")
+agent = client.agents.create(
+    account_id=account["id"],
+    name="Front desk",
+    instructions="Answer questions about Lakeside Dental and book cleanings.",
+)
+conversation = client.conversations.create(agent["id"])
+
+# Whole reply
+reply = client.conversations.send_message(conversation["id"], content="Are you open Saturday?")
+print(reply["content"])
+
+# Streamed reply
+stream = client.conversations.stream(conversation["id"], content="Can I book a cleaning?")
+for event in stream:
+    if isinstance(event, MessageDelta):
+        print(event.delta, end="", flush=True)
+print(stream.final_message["id"])
+```
+
+## Errors
+
+```python
+from allternit_platform import APIError, NotFoundError, RateLimitError
+
+try:
+    client.agents.get("agent_missing")
+except NotFoundError as e:
+    print(e.code)  # "agent_not_found"
+except RateLimitError as e:
+    print(f"retry in {e.retry_after}s")
+except APIError as e:
+    print(e.status, e.type, e.code, e.param, e.request_id)
+```
+
+`503` with `code == "runtime_starting"` (an `InternalServerError`) means the project's hosted runtime is starting; retry after a few seconds.
+
+## Pagination
+
+```python
+page = client.agents.list(limit=50)       # {"data": [...], "has_more": ..., "next_cursor": ...}
+for agent in client.agents.list_all():   # every agent, page by page
+    ...
+```
+
+## Options
+
+`AllternitPlatform(api_key=None, *, base_url=None, timeout=60.0, default_headers=None)`. Every method takes `timeout=` and `extra_headers=`; POST methods also take `idempotency_key=`. Parameters whose names are Python keywords get a trailing underscore (`from_=`).
+
+## Regenerate and test
+
+```bash
+python3 scripts/platform-sdk/generate.py           # from the repo root, after editing platform-v1.yaml
+python3 scripts/platform-sdk/generate.py --check   # fails if the generated code is stale
+cd sdk/platform-python && python3 -m unittest discover -s tests
+```
+
+`allternit_platform/_generated.py` is generated; edit the other modules by hand.

allternit_platform-0.1.0/README.md

@@ -0,0 +1,83 @@
+# allternit-platform
+
+Python SDK for the [Allternit Platform API](https://docs.allternit.com/api/platform/overview): agents, conversations, numbers, messaging, webhooks and usage.
+
+> **Not yet published to PyPI.** Publishing needs Eoj's OK. Until then, install it from this repo (see below).
+
+- Python 3.9+, standard library only.
+- Typed responses (`TypedDict`s) and one method per API operation, generated from `cmd/allternit-cloud-api/openapi/platform-v1.yaml`.
+- Sends an `Idempotency-Key` on every POST (random unless you pass one).
+- Errors are typed exceptions (`NotFoundError`, `RateLimitError`, …).
+- Cursor pagination helpers and streaming replies.
+
+## Install (from the repo, until it is published)
+
+```bash
+pip install /path/to/allternit/sdk/platform-python
+```
+
+## Quickstart
+
+```python
+from allternit_platform import AllternitPlatform, MessageDelta
+
+client = AllternitPlatform()  # reads ALLTERNIT_API_KEY (alt_test_... or alt_live_...)
+
+account = client.accounts.create(name="Lakeside Dental")
+agent = client.agents.create(
+    account_id=account["id"],
+    name="Front desk",
+    instructions="Answer questions about Lakeside Dental and book cleanings.",
+)
+conversation = client.conversations.create(agent["id"])
+
+# Whole reply
+reply = client.conversations.send_message(conversation["id"], content="Are you open Saturday?")
+print(reply["content"])
+
+# Streamed reply
+stream = client.conversations.stream(conversation["id"], content="Can I book a cleaning?")
+for event in stream:
+    if isinstance(event, MessageDelta):
+        print(event.delta, end="", flush=True)
+print(stream.final_message["id"])
+```
+
+## Errors
+
+```python
+from allternit_platform import APIError, NotFoundError, RateLimitError
+
+try:
+    client.agents.get("agent_missing")
+except NotFoundError as e:
+    print(e.code)  # "agent_not_found"
+except RateLimitError as e:
+    print(f"retry in {e.retry_after}s")
+except APIError as e:
+    print(e.status, e.type, e.code, e.param, e.request_id)
+```
+
+`503` with `code == "runtime_starting"` (an `InternalServerError`) means the project's hosted runtime is starting; retry after a few seconds.
+
+## Pagination
+
+```python
+page = client.agents.list(limit=50)       # {"data": [...], "has_more": ..., "next_cursor": ...}
+for agent in client.agents.list_all():   # every agent, page by page
+    ...
+```
+
+## Options
+
+`AllternitPlatform(api_key=None, *, base_url=None, timeout=60.0, default_headers=None)`. Every method takes `timeout=` and `extra_headers=`; POST methods also take `idempotency_key=`. Parameters whose names are Python keywords get a trailing underscore (`from_=`).
+
+## Regenerate and test
+
+```bash
+python3 scripts/platform-sdk/generate.py           # from the repo root, after editing platform-v1.yaml
+python3 scripts/platform-sdk/generate.py --check   # fails if the generated code is stale
+cd sdk/platform-python && python3 -m unittest discover -s tests
+```
+
+`allternit_platform/_generated.py` is generated; edit the other modules by hand.

allternit_platform-0.1.0/allternit_platform/__init__.py

@@ -0,0 +1,28 @@
+"""Python SDK for the Allternit Platform API."""
+
+from ._client import AllternitPlatform, Conversations, ConversationStream, MessageCompleted, MessageDelta, StreamEvent
+from ._core import DEFAULT_BASE_URL, SSEEvent, Transport, parse_sse
+from ._errors import (
+    AllternitError,
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    InternalServerError,
+    InvalidRequestError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._generated import NOT_GIVEN
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AllternitPlatform", "Conversations", "ConversationStream", "MessageCompleted", "MessageDelta", "StreamEvent",
+    "DEFAULT_BASE_URL", "SSEEvent", "Transport", "parse_sse", "NOT_GIVEN",
+    "AllternitError", "APIConnectionError", "APIError", "APITimeoutError", "AuthenticationError", "ConflictError",
+    "InternalServerError", "InvalidRequestError", "NotFoundError", "PaymentRequiredError", "PermissionDeniedError", "RateLimitError",
+]

allternit_platform-0.1.0/allternit_platform/_client.py

@@ -0,0 +1,111 @@
+"""The Allternit Platform API client.
+
+    from allternit_platform import AllternitPlatform
+
+    client = AllternitPlatform()  # reads ALLTERNIT_API_KEY
+    agent = client.agents.create(account_id="acct_...", name="Front desk")
+
+Resources (``client.agents``, ``client.conversations``, ...) are generated
+from the OpenAPI file; this module adds the typed conversation stream.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterator, Optional, Union
+
+from ._core import DEFAULT_TIMEOUT, SSEEvent, Transport
+from ._errors import error_for
+from ._generated import ConversationsResource, GeneratedResources
+
+
+@dataclass
+class MessageDelta:
+    """A piece of the agent's reply (``message.delta``)."""
+
+    delta: str
+    type: str = "message.delta"
+
+
+@dataclass
+class MessageCompleted:
+    """The stored reply (``message.completed``)."""
+
+    message: Dict[str, Any]
+    type: str = "message.completed"
+
+
+StreamEvent = Union[MessageDelta, MessageCompleted]
+
+
+class ConversationStream:
+    """The agent's reply as it is written. Iterate it for ``MessageDelta`` and
+    ``MessageCompleted`` events; an ``error`` event raises a typed ``APIError``.
+    ``final_message`` is set once the stream finishes."""
+
+    def __init__(self, source: Iterator[SSEEvent]) -> None:
+        self._source = source
+        self._started = False
+        self.final_message: Optional[Dict[str, Any]] = None
+        self.text = ""
+
+    def __iter__(self) -> Iterator[StreamEvent]:
+        if self._started:
+            raise RuntimeError("A ConversationStream can only be read once.")
+        self._started = True
+        for ev in self._source:
+            if ev.event == "message.delta":
+                delta = str((ev.data or {}).get("delta", "")) if isinstance(ev.data, dict) else str(ev.data)
+                self.text += delta
+                yield MessageDelta(delta)
+            elif ev.event == "message.completed":
+                self.final_message = ev.data
+                yield MessageCompleted(ev.data)
+            elif ev.event == "error":
+                body = ev.data.get("error") if isinstance(ev.data, dict) else None
+                raise error_for(0, body or {"message": str(ev.data)}, None, "The stream reported an error.")
+
+    def until_done(self) -> Dict[str, Any]:
+        """Read the whole stream and return the stored reply."""
+        if not self._started:
+            for _ in self:
+                pass
+        if self.final_message is None:
+            raise RuntimeError("The stream ended without a message.completed event.")
+        return self.final_message
+
+
+class Conversations(ConversationsResource):
+    def stream(
+        self,
+        id: str,
+        *,
+        content: str,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> ConversationStream:
+        """Send a message and stream the agent's reply
+        (``POST /v1/conversations/{id}/messages`` with ``stream: true``)."""
+        return ConversationStream(
+            self.send_message_stream(id, content=content, idempotency_key=idempotency_key,
+                                     timeout=timeout, extra_headers=extra_headers)
+        )
+
+
+class AllternitPlatform(GeneratedResources):
+    """Client for https://api.allternit.com. Every API area is an attribute."""
+
+    conversations: Conversations
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.http = Transport(api_key, base_url=base_url, timeout=timeout, default_headers=default_headers)
+        super().__init__(self.http)
+        self.conversations = Conversations(self.http)

allternit_platform-0.1.0/allternit_platform/_core.py

@@ -0,0 +1,187 @@
+"""HTTP transport shared by every generated resource: auth, Idempotency-Key,
+timeouts, error mapping, cursor pagination and server-sent events.
+Standard library only."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import uuid
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Iterator, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from ._errors import APIConnectionError, APITimeoutError, error_for
+
+DEFAULT_BASE_URL = "https://api.allternit.com"
+DEFAULT_TIMEOUT = 60.0
+
+Page = Dict[str, Any]
+"""A list response: ``{"data": [...], "has_more": bool, "next_cursor": str | None}``."""
+
+
+@dataclass
+class SSEEvent:
+    """One server-sent event: its ``event:`` name and its ``data:`` payload, JSON-parsed when possible."""
+
+    event: str
+    data: Any
+
+
+class Transport:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        default_headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("ALLTERNIT_API_KEY")
+        if not api_key:
+            raise ValueError("No API key. Pass api_key=... or set ALLTERNIT_API_KEY (alt_test_... or alt_live_...).")
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("ALLTERNIT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.default_headers = dict(default_headers or {})
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _open(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]],
+        body: Any,
+        accept: str,
+        idempotency_key: Optional[str],
+        timeout: Optional[float],
+        extra_headers: Optional[Dict[str, str]],
+    ):
+        url = self.base_url + path
+        if query:
+            pairs = []
+            for k, v in query.items():
+                if v is None:
+                    continue
+                for item in v if isinstance(v, (list, tuple)) else [v]:
+                    pairs.append((k, "true" if item is True else "false" if item is False else str(item)))
+            if pairs:
+                url += "?" + urlencode(pairs)
+        headers = {
+            "Accept": accept,
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": "allternit-platform-python/0.1.0",
+            **self.default_headers,
+            **(extra_headers or {}),
+        }
+        data = None
+        if body is not None and method != "GET":
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode()
+        if method == "POST" and not any(h.lower() == "idempotency-key" for h in headers):
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        req = Request(url, data=data, headers=headers, method=method)
+        wait = self.timeout if timeout is None else timeout
+        try:
+            return urlopen(req, timeout=wait)
+        except HTTPError as e:
+            raw = e.read().decode("utf-8", "replace")
+            try:
+                parsed = json.loads(raw) if raw else None
+            except ValueError:
+                parsed = None
+            err = parsed.get("error") if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict) else None
+            raise error_for(e.code, err, dict(e.headers.items()), raw[:200] or None) from None
+        except (socket.timeout, TimeoutError) as e:
+            raise APITimeoutError(f"Request timed out after {wait} s.") from e
+        except URLError as e:
+            if isinstance(e.reason, (socket.timeout, TimeoutError)):
+                raise APITimeoutError(f"Request timed out after {wait} s.") from e
+            raise APIConnectionError(f"Could not reach {self.base_url}: {e.reason}") from e
+
+    # -- what generated resources call ------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        resp = self._open(method, path, query=query, body=body, accept="application/json",
+                          idempotency_key=idempotency_key, timeout=timeout, extra_headers=extra_headers)
+        with resp:
+            raw = resp.read()
+        return json.loads(raw) if raw else None
+
+    def stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        idempotency_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Iterator[SSEEvent]:
+        resp = self._open(method, path, query=query, body=body, accept="text/event-stream",
+                          idempotency_key=idempotency_key, timeout=timeout, extra_headers=extra_headers)
+
+        def events() -> Iterator[SSEEvent]:
+            with resp:
+                yield from parse_sse(iter(resp.readline, b""))
+
+        return events()
+
+    def paginate(self, fetch_page: Callable[[Optional[str]], Page], after: Optional[str] = None) -> Iterator[Any]:
+        cursor = after
+        while True:
+            page = fetch_page(cursor)
+            for item in page.get("data") or []:
+                yield item
+            if not page.get("has_more") or not page.get("next_cursor"):
+                return
+            cursor = page["next_cursor"]
+
+
+def parse_sse(lines: Iterator[bytes]) -> Iterator[SSEEvent]:
+    """Parse ``text/event-stream`` lines (bytes, newline-terminated) into events."""
+    event, data = "message", []
+    for raw in lines:
+        line = raw.decode("utf-8").rstrip("\r\n")
+        if line == "":
+            if data:
+                payload = "\n".join(data)
+                try:
+                    parsed: Any = json.loads(payload)
+                except ValueError:
+                    parsed = payload
+                yield SSEEvent(event, parsed)
+            event, data = "message", []
+            continue
+        if line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "event":
+            event = value
+        elif field == "data":
+            data.append(value)
+    if data:
+        payload = "\n".join(data)
+        try:
+            parsed = json.loads(payload)
+        except ValueError:
+            parsed = payload
+        yield SSEEvent(event, parsed)

allternit_platform-0.1.0/allternit_platform/_errors.py

@@ -0,0 +1,129 @@
+"""Typed errors. Every non-2xx answer becomes an ``APIError`` subclass picked
+by HTTP status, carrying the API's ``{"error": {type, code, message, param}}``."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class AllternitError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class APIError(AllternitError):
+    def __init__(
+        self,
+        status: int,
+        body: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        fallback: Optional[str] = None,
+    ) -> None:
+        body = body or {}
+        self.status = status
+        self.type: Optional[str] = body.get("type")
+        self.code: Optional[str] = body.get("code")
+        self.param: Optional[str] = body.get("param")
+        #: Where to fix it (402 ``payment_method_required``: the console billing page).
+        self.url: Optional[str] = body.get("url")
+        self.headers = dict(headers or {})
+        lower = {k.lower(): v for k, v in self.headers.items()}
+        self.request_id: Optional[str] = lower.get("x-request-id")
+        self.message: str = body.get("message") or fallback or f"HTTP {status}"
+        super().__init__(self.message)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class InvalidRequestError(APIError):
+    """400 / 422: the request was malformed or a field is invalid."""
+
+
+class AuthenticationError(APIError):
+    """401: missing, invalid or revoked API key."""
+
+
+class PermissionDeniedError(APIError):
+    """403: the key lacks a scope, or is bound to another account."""
+
+
+# Alias matching the API's `permission_error` type. Not the builtin PermissionError.
+PermissionError = PermissionDeniedError  # noqa: A001
+
+
+class NotFoundError(APIError):
+    """404: no such resource (or it belongs to another project)."""
+
+
+class PaymentRequiredError(APIError):
+    """402 ``billing_error``: ``payment_method_required`` (no card on file; open
+    ``url``, the console billing page) or ``spend_cap_reached``."""
+
+
+class ConflictError(APIError):
+    """409: e.g. ``conversation_busy`` or an idempotency key reused with a different request."""
+
+
+class RateLimitError(APIError):
+    """429: rate limited. ``retry_after`` is in seconds when the server sent ``Retry-After``."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        raw = {k.lower(): v for k, v in self.headers.items()}.get("retry-after")
+        try:
+            self.retry_after: Optional[float] = float(raw) if raw is not None else None
+        except ValueError:
+            self.retry_after = None
+
+
+class InternalServerError(APIError):
+    """5xx: the API failed, or (``code == "runtime_starting"``) asks you to retry shortly."""
+
+
+class APIConnectionError(AllternitError):
+    """The request never got an HTTP answer (DNS, refused, reset)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request took longer than ``timeout``."""
+
+
+_BY_TYPE = {
+    "invalid_request_error": InvalidRequestError,
+    "authentication_error": AuthenticationError,
+    "billing_error": PaymentRequiredError,
+    "permission_error": PermissionDeniedError,
+    "not_found_error": NotFoundError,
+    "conflict_error": ConflictError,
+    "rate_limit_error": RateLimitError,
+}
+
+
+def error_for(
+    status: int,
+    body: Optional[Mapping[str, Any]],
+    headers: Optional[Mapping[str, str]] = None,
+    fallback: Optional[str] = None,
+) -> APIError:
+    """The right error class for a status (0 = an ``error`` event inside a stream)."""
+    if status in (400, 422):
+        cls: type = InvalidRequestError
+    elif status == 401:
+        cls = AuthenticationError
+    elif status == 402:
+        cls = PaymentRequiredError
+    elif status == 403:
+        cls = PermissionDeniedError
+    elif status == 404:
+        cls = NotFoundError
+    elif status == 409:
+        cls = ConflictError
+    elif status == 429:
+        cls = RateLimitError
+    elif status >= 500:
+        cls = InternalServerError
+    elif status == 0:
+        cls = _BY_TYPE.get((body or {}).get("type") or "", APIError)
+    else:
+        cls = APIError
+    return cls(status, body, headers, fallback)