aamp-sdk 0.1.0__tar.gz

aamp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: aamp-sdk
+Version: 0.1.0
+Summary: Portable Python SDK for AAMP
+Author: AAMP
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websocket-client>=1.8.0
+
+# aamp-sdk
+
+Python SDK for AAMP.
+
+This SDK now includes the same core runtime shape as the Node.js SDK:
+
+- AAMP discovery and mailbox registration
+- directory query and profile updates
+- realtime stream create / append / get / close
+- AAMP header builders and parsers
+- SMTP sending for `task.dispatch`, `task.result`, `task.cancel`, `task.help_needed`, `task.stream.opened`, and `card.*`
+- JMAP WebSocket push reception with polling fallback
+- attachment blob download
+- recent mailbox reconciliation as a safety net
+
+## Install
+
+```bash
+python -m pip install aamp-sdk
+```
+
+## Usage
+
+```python
+from aamp_sdk import AampClient
+
+client = AampClient.from_mailbox_identity(
+    email="agent@example.com",
+    smtp_password="<smtp-password>",
+    base_url="https://meshmail.ai",
+    reject_unauthorized=False,
+)
+
+def on_dispatch(task: dict) -> None:
+    client.send_result(
+        to=task["from"],
+        task_id=task["taskId"],
+        status="completed",
+        output="done",
+        in_reply_to=task["messageId"],
+    )
+
+client.on("task.dispatch", on_dispatch)
+client.connect()
+
+task_id, message_id = client.send_task(
+    to="dispatcher@example.com",
+    title="Prepare a summary",
+    body_text="Summarize the latest rollout status.",
+    priority="high",
+)
+
+stream = client.create_stream(task_id=task_id, peer_email="dispatcher@example.com")
+client.send_stream_opened(
+    to="dispatcher@example.com",
+    task_id=task_id,
+    stream_id=stream["streamId"],
+    in_reply_to=message_id,
+)
+client.append_stream_event(
+    stream_id=stream["streamId"],
+    event_type="status",
+    payload={"stage": "running"},
+)
+
+client.send_result(
+    to="dispatcher@example.com",
+    task_id=task_id,
+    status="completed",
+    output="done",
+    in_reply_to=message_id,
+)
+```
+
+## Parse AAMP headers
+
+```python
+from aamp_sdk import parse_aamp_headers
+
+message = parse_aamp_headers(
+    {
+        "from": "dispatcher@example.com",
+        "to": "agent@example.com",
+        "subject": "[AAMP Task] Review patch",
+        "messageId": "<msg-1@example.com>",
+        "bodyText": "Please review the patch.",
+        "headers": {
+            "X-AAMP-Intent": "task.dispatch",
+            "X-AAMP-TaskId": "task-123",
+            "X-AAMP-Priority": "high",
+        },
+    }
+)
+```
+
+## Run tests
+
+```bash
+cd packages/sdk-python
+python -m unittest discover -s tests
+```

aamp_sdk-0.1.0/README.md

@@ -0,0 +1,101 @@
+# aamp-sdk
+
+Python SDK for AAMP.
+
+This SDK now includes the same core runtime shape as the Node.js SDK:
+
+- AAMP discovery and mailbox registration
+- directory query and profile updates
+- realtime stream create / append / get / close
+- AAMP header builders and parsers
+- SMTP sending for `task.dispatch`, `task.result`, `task.cancel`, `task.help_needed`, `task.stream.opened`, and `card.*`
+- JMAP WebSocket push reception with polling fallback
+- attachment blob download
+- recent mailbox reconciliation as a safety net
+
+## Install
+
+```bash
+python -m pip install aamp-sdk
+```
+
+## Usage
+
+```python
+from aamp_sdk import AampClient
+
+client = AampClient.from_mailbox_identity(
+    email="agent@example.com",
+    smtp_password="<smtp-password>",
+    base_url="https://meshmail.ai",
+    reject_unauthorized=False,
+)
+
+def on_dispatch(task: dict) -> None:
+    client.send_result(
+        to=task["from"],
+        task_id=task["taskId"],
+        status="completed",
+        output="done",
+        in_reply_to=task["messageId"],
+    )
+
+client.on("task.dispatch", on_dispatch)
+client.connect()
+
+task_id, message_id = client.send_task(
+    to="dispatcher@example.com",
+    title="Prepare a summary",
+    body_text="Summarize the latest rollout status.",
+    priority="high",
+)
+
+stream = client.create_stream(task_id=task_id, peer_email="dispatcher@example.com")
+client.send_stream_opened(
+    to="dispatcher@example.com",
+    task_id=task_id,
+    stream_id=stream["streamId"],
+    in_reply_to=message_id,
+)
+client.append_stream_event(
+    stream_id=stream["streamId"],
+    event_type="status",
+    payload={"stage": "running"},
+)
+
+client.send_result(
+    to="dispatcher@example.com",
+    task_id=task_id,
+    status="completed",
+    output="done",
+    in_reply_to=message_id,
+)
+```
+
+## Parse AAMP headers
+
+```python
+from aamp_sdk import parse_aamp_headers
+
+message = parse_aamp_headers(
+    {
+        "from": "dispatcher@example.com",
+        "to": "agent@example.com",
+        "subject": "[AAMP Task] Review patch",
+        "messageId": "<msg-1@example.com>",
+        "bodyText": "Please review the patch.",
+        "headers": {
+            "X-AAMP-Intent": "task.dispatch",
+            "X-AAMP-TaskId": "task-123",
+            "X-AAMP-Priority": "high",
+        },
+    }
+)
+```
+
+## Run tests
+
+```bash
+cd packages/sdk-python
+python -m unittest discover -s tests
+```

aamp_sdk-0.1.0/aamp_sdk/__init__.py

@@ -0,0 +1,45 @@
+"""Python SDK for portable AAMP integrations."""
+
+from .client import AampClient
+from .events import TinyEmitter
+from .jmap_push import JmapPushClient
+from .protocol import (
+    AAMP_HEADER,
+    AAMP_PROTOCOL_VERSION,
+    build_ack_headers,
+    build_cancel_headers,
+    build_card_query_headers,
+    build_card_response_headers,
+    build_dispatch_headers,
+    build_help_headers,
+    build_result_headers,
+    build_stream_opened_headers,
+    normalize_headers,
+    parse_aamp_headers,
+    parse_dispatch_context_header,
+    serialize_dispatch_context_header,
+)
+from .smtp import Attachment, SmtpSender, derive_mailbox_service_defaults
+
+__all__ = [
+    "AampClient",
+    "AAMP_HEADER",
+    "AAMP_PROTOCOL_VERSION",
+    "Attachment",
+    "JmapPushClient",
+    "SmtpSender",
+    "TinyEmitter",
+    "build_ack_headers",
+    "build_cancel_headers",
+    "build_card_query_headers",
+    "build_card_response_headers",
+    "build_dispatch_headers",
+    "build_help_headers",
+    "build_result_headers",
+    "build_stream_opened_headers",
+    "derive_mailbox_service_defaults",
+    "normalize_headers",
+    "parse_aamp_headers",
+    "parse_dispatch_context_header",
+    "serialize_dispatch_context_header",
+]

aamp_sdk-0.1.0/aamp_sdk/client.py

@@ -0,0 +1,371 @@
+"""Portable Python client for AAMP service APIs and message sending."""
+
+from __future__ import annotations
+
+import base64
+import json
+import ssl
+from typing import Any
+from urllib.parse import urlencode, urljoin
+from urllib.request import Request, urlopen
+
+from .events import TinyEmitter
+from .jmap_push import JmapPushClient
+from .smtp import SmtpSender, derive_mailbox_service_defaults
+
+DEFAULT_HTTP_TIMEOUT_SECS = 30
+
+
+def _ssl_context(reject_unauthorized: bool) -> ssl.SSLContext:
+    return ssl.create_default_context() if reject_unauthorized else ssl._create_unverified_context()
+
+
+class AampClient(TinyEmitter):
+    def __init__(
+        self,
+        *,
+        email: str,
+        mailbox_token: str,
+        base_url: str,
+        smtp_password: str,
+        http_send_base_url: str | None = None,
+        smtp_host: str | None = None,
+        smtp_port: int = 587,
+        reconnect_interval: float = 5.0,
+        reject_unauthorized: bool = True,
+    ) -> None:
+        super().__init__()
+        self.email = email
+        self.mailbox_token = mailbox_token
+        self.base_url = base_url
+        self.reject_unauthorized = reject_unauthorized
+
+        derived = derive_mailbox_service_defaults(email, base_url)
+        self.smtp_sender = SmtpSender(
+            host=smtp_host or str(derived["smtp_host"]),
+            port=smtp_port,
+            user=email,
+            password=smtp_password,
+            http_base_url=http_send_base_url or base_url,
+            auth_token=mailbox_token,
+            reject_unauthorized=reject_unauthorized,
+        )
+        decoded = base64.b64decode(mailbox_token.encode("ascii")).decode("utf-8")
+        _mailbox_email, _sep, password = decoded.partition(":")
+        if not _sep or not password:
+            raise RuntimeError("Invalid mailboxToken format: expected base64(email:password)")
+        self.jmap_client = JmapPushClient(
+            email=email,
+            password=password,
+            jmap_url=base_url,
+            reconnect_interval=reconnect_interval,
+            reject_unauthorized=reject_unauthorized,
+        )
+        for event_name in [
+            "task.dispatch",
+            "task.cancel",
+            "task.result",
+            "task.help_needed",
+            "task.ack",
+            "task.stream.opened",
+            "card.query",
+            "card.response",
+            "reply",
+            "connected",
+            "disconnected",
+            "error",
+        ]:
+            self.jmap_client.on(event_name, self._forward_event(event_name))
+        self.jmap_client.on("_autoAck", self._handle_auto_ack)
+
+    def _forward_event(self, event_name: str) -> Any:
+        def handler(*args: Any) -> None:
+            self.emit(event_name, *args)
+
+        return handler
+
+    def _handle_auto_ack(self, payload: dict[str, Any]) -> None:
+        try:
+            self.smtp_sender.send_ack(
+                to=str(payload["to"]),
+                task_id=str(payload["taskId"]),
+                in_reply_to=str(payload["messageId"]),
+            )
+        except Exception as err:
+            self.emit("error", RuntimeError(f"[AAMP] Failed to send ACK for task {payload.get('taskId')}: {err}"))
+
+    @classmethod
+    def from_mailbox_identity(
+        cls,
+        *,
+        email: str,
+        smtp_password: str,
+        base_url: str | None = None,
+        smtp_port: int = 587,
+        reconnect_interval: float = 5.0,
+        reject_unauthorized: bool = True,
+    ) -> "AampClient":
+        derived = derive_mailbox_service_defaults(email, base_url)
+        token = base64.b64encode(f"{email}:{smtp_password}".encode("utf-8")).decode("ascii")
+        return cls(
+            email=email,
+            mailbox_token=token,
+            base_url=str(derived["http_base_url"] or f"https://{email.split('@', 1)[1]}"),
+            smtp_password=smtp_password,
+            smtp_host=str(derived["smtp_host"]),
+            smtp_port=smtp_port,
+            reconnect_interval=reconnect_interval,
+            reject_unauthorized=reject_unauthorized,
+        )
+
+    @staticmethod
+    def _request_json(
+        url: str,
+        *,
+        method: str = "GET",
+        body: Any | None = None,
+        headers: dict[str, str] | None = None,
+        reject_unauthorized: bool = True,
+    ) -> Any:
+        data = None
+        request_headers = {"Accept": "application/json", **(headers or {})}
+        if body is not None:
+            request_headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        request = Request(url, method=method, data=data, headers=request_headers)
+        with urlopen(
+            request,
+            context=_ssl_context(reject_unauthorized),
+            timeout=DEFAULT_HTTP_TIMEOUT_SECS,
+        ) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    @classmethod
+    def discover_aamp_service(cls, aamp_host: str, *, reject_unauthorized: bool = True) -> dict[str, Any]:
+        base = aamp_host.rstrip("/")
+        discovery = cls._request_json(
+            f"{base}/.well-known/aamp",
+            reject_unauthorized=reject_unauthorized,
+        )
+        if not discovery.get("api", {}).get("url"):
+            raise RuntimeError("AAMP discovery did not return api.url")
+        return discovery
+
+    @classmethod
+    def _call_discovered_api(
+        cls,
+        base: str,
+        *,
+        action: str,
+        method: str = "GET",
+        query: dict[str, Any] | None = None,
+        body: Any | None = None,
+        auth_token: str | None = None,
+        reject_unauthorized: bool = True,
+    ) -> Any:
+        discovery = cls.discover_aamp_service(base, reject_unauthorized=reject_unauthorized)
+        api_url = urljoin(f"{base.rstrip('/')}/", discovery["api"]["url"])
+        params = {"action": action}
+        for key, value in (query or {}).items():
+            if value is not None:
+                params[key] = str(value).lower() if isinstance(value, bool) else str(value)
+        url = f"{api_url}?{urlencode(params)}"
+        headers = {"Authorization": f"Basic {auth_token}"} if auth_token else None
+        return cls._request_json(
+            url,
+            method=method,
+            body=body,
+            headers=headers,
+            reject_unauthorized=reject_unauthorized,
+        )
+
+    @classmethod
+    def register_mailbox(
+        cls,
+        *,
+        aamp_host: str,
+        slug: str,
+        description: str | None = None,
+        reject_unauthorized: bool = True,
+    ) -> dict[str, str]:
+        base = aamp_host.rstrip("/")
+        registration = cls._call_discovered_api(
+            base,
+            action="aamp.mailbox.register",
+            method="POST",
+            body={"slug": slug, "description": description},
+            reject_unauthorized=reject_unauthorized,
+        )
+        code = registration.get("registrationCode")
+        if not code:
+            raise RuntimeError("Mailbox registration succeeded but no registrationCode was returned")
+
+        credentials = cls._call_discovered_api(
+            base,
+            action="aamp.mailbox.credentials",
+            query={"code": code},
+            reject_unauthorized=reject_unauthorized,
+        )
+        email = credentials.get("email")
+        mailbox_token = credentials.get("mailbox", {}).get("token")
+        smtp_password = credentials.get("smtp", {}).get("password")
+        if not email or not mailbox_token or not smtp_password:
+            raise RuntimeError("Mailbox credential exchange returned an incomplete identity payload")
+
+        return {
+            "email": email,
+            "mailboxToken": mailbox_token,
+            "smtpPassword": smtp_password,
+            "baseUrl": base,
+        }
+
+    def send_task(self, **kwargs: Any) -> tuple[str, str]:
+        return self.smtp_sender.send_task(**kwargs)
+
+    def connect(self) -> None:
+        self.jmap_client.start()
+
+    def disconnect(self) -> None:
+        self.jmap_client.stop()
+
+    def is_connected(self) -> bool:
+        return self.jmap_client.is_connected()
+
+    def is_using_polling_fallback(self) -> bool:
+        return self.jmap_client.is_using_polling_fallback()
+
+    def send_result(self, **kwargs: Any) -> None:
+        self.smtp_sender.send_result(**kwargs)
+
+    def send_help(self, **kwargs: Any) -> None:
+        self.smtp_sender.send_help(**kwargs)
+
+    def send_cancel(self, **kwargs: Any) -> None:
+        self.smtp_sender.send_cancel(**kwargs)
+
+    def send_stream_opened(self, **kwargs: Any) -> None:
+        self.smtp_sender.send_stream_opened(**kwargs)
+
+    def send_card_query(self, **kwargs: Any) -> tuple[str, str]:
+        return self.smtp_sender.send_card_query(**kwargs)
+
+    def send_card_response(self, **kwargs: Any) -> None:
+        self.smtp_sender.send_card_response(**kwargs)
+
+    def download_blob(self, blob_id: str, filename: str | None = None) -> bytes:
+        return self.jmap_client.download_blob(blob_id, filename)
+
+    def reconcile_recent_emails(self, limit: int = 20, *, include_historical: bool = False) -> int:
+        return self.jmap_client.reconcile_recent_emails(limit, include_historical=include_historical)
+
+    def update_directory_profile(
+        self,
+        *,
+        summary: str | None = None,
+        card_text: str | None = None,
+    ) -> dict[str, Any]:
+        response = self._call_discovered_api(
+            self.base_url,
+            action="aamp.directory.upsert",
+            method="POST",
+            auth_token=self.mailbox_token,
+            body={"summary": summary, "cardText": card_text},
+            reject_unauthorized=self.reject_unauthorized,
+        )
+        return dict(response.get("profile", {}))
+
+    def list_directory(
+        self,
+        *,
+        scope: str | None = None,
+        include_self: bool | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        response = self._call_discovered_api(
+            self.base_url,
+            action="aamp.directory.list",
+            auth_token=self.mailbox_token,
+            query={"scope": scope, "includeSelf": include_self, "limit": limit},
+            reject_unauthorized=self.reject_unauthorized,
+        )
+        return list(response.get("agents", []))
+
+    def search_directory(
+        self,
+        *,
+        query: str,
+        scope: str | None = None,
+        include_self: bool | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        response = self._call_discovered_api(
+            self.base_url,
+            action="aamp.directory.search",
+            auth_token=self.mailbox_token,
+            query={
+                "q": query,
+                "scope": scope,
+                "includeSelf": include_self,
+                "limit": limit,
+            },
+            reject_unauthorized=self.reject_unauthorized,
+        )
+        return list(response.get("agents", []))
+
+    def _resolve_stream_capability(self) -> dict[str, Any]:
+        discovery = self.discover_aamp_service(
+            self.base_url,
+            reject_unauthorized=self.reject_unauthorized,
+        )
+        stream = discovery.get("capabilities", {}).get("stream")
+        if not stream or not stream.get("transport"):
+            raise RuntimeError("AAMP stream capability is not available on this service")
+        return dict(stream)
+
+    def create_stream(self, *, task_id: str, peer_email: str) -> dict[str, Any]:
+        stream = self._resolve_stream_capability()
+        return self._call_discovered_api(
+            self.base_url,
+            action=stream.get("createAction", "aamp.stream.create"),
+            method="POST",
+            auth_token=self.mailbox_token,
+            body={"taskId": task_id, "peerEmail": peer_email},
+            reject_unauthorized=self.reject_unauthorized,
+        )
+
+    def append_stream_event(self, *, stream_id: str, event_type: str, payload: dict[str, Any]) -> dict[str, Any]:
+        stream = self._resolve_stream_capability()
+        return self._call_discovered_api(
+            self.base_url,
+            action=stream.get("appendAction", "aamp.stream.append"),
+            method="POST",
+            auth_token=self.mailbox_token,
+            body={"streamId": stream_id, "type": event_type, "payload": payload},
+            reject_unauthorized=self.reject_unauthorized,
+        )
+
+    def close_stream(self, *, stream_id: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        stream = self._resolve_stream_capability()
+        return self._call_discovered_api(
+            self.base_url,
+            action=stream.get("closeAction", "aamp.stream.close"),
+            method="POST",
+            auth_token=self.mailbox_token,
+            body={"streamId": stream_id, "payload": payload or {}},
+            reject_unauthorized=self.reject_unauthorized,
+        )
+
+    def get_task_stream(
+        self,
+        *,
+        task_id: str | None = None,
+        stream_id: str | None = None,
+    ) -> dict[str, Any]:
+        stream = self._resolve_stream_capability()
+        return self._call_discovered_api(
+            self.base_url,
+            action=stream.get("getAction", "aamp.stream.get"),
+            auth_token=self.mailbox_token,
+            query={"taskId": task_id, "streamId": stream_id},
+            reject_unauthorized=self.reject_unauthorized,
+        )

aamp_sdk-0.1.0/aamp_sdk/events.py

@@ -0,0 +1,49 @@
+"""A tiny event emitter used by the Python SDK."""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Any, Callable
+
+
+Listener = Callable[..., Any]
+
+
+class TinyEmitter:
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[Listener]] = defaultdict(list)
+        self._once_wrappers: dict[tuple[str, Listener], Listener] = {}
+        self._lock = threading.RLock()
+
+    def on(self, event: str, listener: Listener) -> "TinyEmitter":
+        with self._lock:
+            self._listeners[event].append(listener)
+        return self
+
+    def once(self, event: str, listener: Listener) -> "TinyEmitter":
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            self.off(event, listener)
+            return listener(*args, **kwargs)
+
+        with self._lock:
+            self._once_wrappers[(event, listener)] = wrapped
+            self._listeners[event].append(wrapped)
+        return self
+
+    def off(self, event: str, listener: Listener) -> "TinyEmitter":
+        with self._lock:
+            wrapped = self._once_wrappers.pop((event, listener), None)
+            target = wrapped or listener
+            bucket = self._listeners.get(event, [])
+            self._listeners[event] = [item for item in bucket if item is not target]
+            if not self._listeners[event]:
+                self._listeners.pop(event, None)
+        return self
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> bool:
+        with self._lock:
+            listeners = list(self._listeners.get(event, []))
+        for listener in listeners:
+            listener(*args, **kwargs)
+        return bool(listeners)