marona 0.1.0__tar.gz

marona-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blessing Nyuwani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marona-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: marona
+Version: 0.1.0
+Summary: Official Python client SDK for Marona-compatible AI runtimes.
+Author: Blessing Nyuwani
+License-Expression: MIT
+Project-URL: Homepage, https://www.marona.ai
+Project-URL: Repository, https://github.com/BlessingNyuwani/edge-node-service
+Project-URL: Documentation, https://hub.marona.ai
+Keywords: marona,sdk,mcp,agents,ai,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1.0,>=0.28
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: build<2.0,>=1.2; extra == "dev"
+Requires-Dist: twine<7.0,>=6.0; extra == "dev"
+Dynamic: license-file
+
+# marona
+
+Official Python client SDK for Marona-compatible AI runtimes.
+
+Marona provides a simple interface for messaging, discovering apps, managing
+permissions, connecting service accounts, receiving inbound events, and using
+tools from any compatible runtime.
+
+You can use it with Marona Cloud or with your own self-hosted Marona-compatible
+runtime.
+
+## Install
+
+```bash
+pip install marona
+```
+
+## Send a message
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona(
+        base_url="https://edge.marona.ai",
+        api_key="mrn_live_...",
+    )
+    response = await client.message(
+        "Create a PowerPoint about AI introduction",
+        interface="api",
+        conversation_id="demo",
+    )
+    print(response.reply)
+    for artifact in response.artifacts:
+        print(artifact.get("filename"))
+
+
+asyncio.run(main())
+```
+
+## Runtime targets
+
+Marona Cloud:
+
+```python
+from marona import Marona
+
+client = Marona(
+    base_url="https://edge.marona.ai",
+    api_key="mrn_live_...",
+)
+```
+
+Self-hosted:
+
+```python
+from marona import Marona
+
+client = Marona(
+    base_url="https://my-company-edge.example.com",
+    api_key="mrn_live_...",
+)
+```
+
+## List available apps
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    apps = await client.list_apps(limit=20, search="slides")
+
+    for app in apps.apps:
+        print(app["slug"], app["name"])
+
+
+asyncio.run(main())
+```
+
+## Pair an interface with WhatsApp
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    pairing = await client.start_pairing(interface="web", device_name="My web app")
+
+    print(pairing.display_code)
+    print(pairing.whatsapp_url)
+
+
+asyncio.run(main())
+```
+
+After the user sends the pairing code from WhatsApp, poll for completion:
+
+```python
+status = await client.pairing_status(pairing.pairing_id)
+
+if status.identity:
+    identity_token = status.identity.access_token
+```
+
+Use the identity token on future requests:
+
+```python
+response = await client.message(
+    "What is on my calendar today?",
+    identity_token=identity_token,
+)
+```
+
+## Connect an app account
+
+Some apps need a user service connection, such as Gmail, Google Calendar, or
+Google Slides.
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    identity_token = "mrn_identity_token_from_pairing"
+    connection = await client.connect_app(
+        "slides",
+        provider="google",
+        identity_token=identity_token,
+        return_url="https://example.com/connected",
+    )
+
+    print(connection.authorization_url)
+
+
+asyncio.run(main())
+```
+
+Open `authorization_url` in a browser so the user can authorize the provider.
+
+## Attach files
+
+```python
+import asyncio
+
+from marona import Marona, RuntimeAttachment
+
+
+async def main() -> None:
+    identity_token = "mrn_identity_token_from_pairing"
+    attachment = RuntimeAttachment.from_bytes(
+        b"hello",
+        filename="note.txt",
+        mime_type="text/plain",
+        kind="document",
+    )
+
+    client = Marona("https://edge.marona.ai")
+    response = await client.message(
+        "Summarize this file",
+        attachments=[attachment],
+        identity_token=identity_token,
+    )
+    print(response.reply)
+
+
+asyncio.run(main())
+```
+
+## Advanced
+
+`EdgeRuntimeClient` is kept as a compatibility class for existing integrations.
+New integrations should import `Marona`.

marona-0.1.0/README.md

@@ -0,0 +1,185 @@
+# marona
+
+Official Python client SDK for Marona-compatible AI runtimes.
+
+Marona provides a simple interface for messaging, discovering apps, managing
+permissions, connecting service accounts, receiving inbound events, and using
+tools from any compatible runtime.
+
+You can use it with Marona Cloud or with your own self-hosted Marona-compatible
+runtime.
+
+## Install
+
+```bash
+pip install marona
+```
+
+## Send a message
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona(
+        base_url="https://edge.marona.ai",
+        api_key="mrn_live_...",
+    )
+    response = await client.message(
+        "Create a PowerPoint about AI introduction",
+        interface="api",
+        conversation_id="demo",
+    )
+    print(response.reply)
+    for artifact in response.artifacts:
+        print(artifact.get("filename"))
+
+
+asyncio.run(main())
+```
+
+## Runtime targets
+
+Marona Cloud:
+
+```python
+from marona import Marona
+
+client = Marona(
+    base_url="https://edge.marona.ai",
+    api_key="mrn_live_...",
+)
+```
+
+Self-hosted:
+
+```python
+from marona import Marona
+
+client = Marona(
+    base_url="https://my-company-edge.example.com",
+    api_key="mrn_live_...",
+)
+```
+
+## List available apps
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    apps = await client.list_apps(limit=20, search="slides")
+
+    for app in apps.apps:
+        print(app["slug"], app["name"])
+
+
+asyncio.run(main())
+```
+
+## Pair an interface with WhatsApp
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    pairing = await client.start_pairing(interface="web", device_name="My web app")
+
+    print(pairing.display_code)
+    print(pairing.whatsapp_url)
+
+
+asyncio.run(main())
+```
+
+After the user sends the pairing code from WhatsApp, poll for completion:
+
+```python
+status = await client.pairing_status(pairing.pairing_id)
+
+if status.identity:
+    identity_token = status.identity.access_token
+```
+
+Use the identity token on future requests:
+
+```python
+response = await client.message(
+    "What is on my calendar today?",
+    identity_token=identity_token,
+)
+```
+
+## Connect an app account
+
+Some apps need a user service connection, such as Gmail, Google Calendar, or
+Google Slides.
+
+```python
+import asyncio
+
+from marona import Marona
+
+
+async def main() -> None:
+    client = Marona("https://edge.marona.ai")
+    identity_token = "mrn_identity_token_from_pairing"
+    connection = await client.connect_app(
+        "slides",
+        provider="google",
+        identity_token=identity_token,
+        return_url="https://example.com/connected",
+    )
+
+    print(connection.authorization_url)
+
+
+asyncio.run(main())
+```
+
+Open `authorization_url` in a browser so the user can authorize the provider.
+
+## Attach files
+
+```python
+import asyncio
+
+from marona import Marona, RuntimeAttachment
+
+
+async def main() -> None:
+    identity_token = "mrn_identity_token_from_pairing"
+    attachment = RuntimeAttachment.from_bytes(
+        b"hello",
+        filename="note.txt",
+        mime_type="text/plain",
+        kind="document",
+    )
+
+    client = Marona("https://edge.marona.ai")
+    response = await client.message(
+        "Summarize this file",
+        attachments=[attachment],
+        identity_token=identity_token,
+    )
+    print(response.reply)
+
+
+asyncio.run(main())
+```
+
+## Advanced
+
+`EdgeRuntimeClient` is kept as a compatibility class for existing integrations.
+New integrations should import `Marona`.

marona-0.1.0/marona/__init__.py

@@ -0,0 +1,39 @@
+from .business import MaronaBusinessApiError, MaronaBusinessClient
+from .client import EdgeRuntimeClient, EdgeRuntimeError, Marona
+from .models import (
+    IdentityAuthenticated,
+    IdentityPairingStarted,
+    IdentityPairingStatus,
+    RealtimeSessionCreated,
+    RealtimeSessionRequest,
+    RuntimeApp,
+    RuntimeAppsPage,
+    RuntimeAttachment,
+    RuntimeInboundEvent,
+    RuntimeMessageRequest,
+    RuntimeMessageResponse,
+    ServiceConnectionAction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EdgeRuntimeClient",
+    "EdgeRuntimeError",
+    "Marona",
+    "__version__",
+    "MaronaBusinessApiError",
+    "MaronaBusinessClient",
+    "IdentityAuthenticated",
+    "IdentityPairingStarted",
+    "IdentityPairingStatus",
+    "RealtimeSessionCreated",
+    "RealtimeSessionRequest",
+    "RuntimeApp",
+    "RuntimeAppsPage",
+    "RuntimeAttachment",
+    "RuntimeInboundEvent",
+    "RuntimeMessageRequest",
+    "RuntimeMessageResponse",
+    "ServiceConnectionAction",
+]

marona-0.1.0/marona/business.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class MaronaBusinessApiError(RuntimeError):
+    pass
+
+
+class MaronaBusinessClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str = "",
+        app_id: str = "",
+        timeout: float = 30,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.app_id = app_id
+        self.timeout = timeout
+        self._client = client
+
+    async def upload_media(
+        self,
+        *,
+        media_type: str,
+        file_name: str,
+        mime_type: str,
+        data: bytes,
+        purpose: str = "generated_reply",
+    ) -> dict[str, Any]:
+        self._require_token()
+        files = {"file": (file_name, data, mime_type)}
+        form = {
+            "type": media_type,
+            "purpose": purpose,
+            **({"app_id": self.app_id} if self.app_id else {}),
+        }
+        response = await self._request(
+            "POST",
+            "/media",
+            timeout=60,
+            data=form,
+            files=files,
+        )
+        payload = response.json()
+        media = payload.get("media") if isinstance(payload, dict) else None
+        if not isinstance(media, dict) or not media.get("media_id"):
+            raise MaronaBusinessApiError("Marona Business API media upload did not return media_id.")
+        return self._normalize_media_response_url(media)
+
+    async def send_reply(
+        self,
+        conversation_id: str,
+        *,
+        message_type: str = "text",
+        body: str = "",
+        media_id: str | None = None,
+        caption: str | None = None,
+    ) -> dict[str, Any]:
+        self._require_token()
+        clean_type = (message_type or "text").strip().lower()
+        if clean_type == "text":
+            payload: dict[str, Any] = {
+                "conversation_id": conversation_id,
+                "type": "text",
+                "text": {"body": body},
+            }
+        elif clean_type in {"image", "audio", "video", "document"}:
+            if not media_id:
+                raise MaronaBusinessApiError("media_id is required for media replies.")
+            payload = {
+                "conversation_id": conversation_id,
+                "type": clean_type,
+                clean_type: {
+                    "media_id": media_id,
+                    "caption": caption if caption is not None else body,
+                },
+            }
+        else:
+            raise MaronaBusinessApiError(f"Unsupported reply type: {clean_type}")
+        if self.app_id:
+            payload["app_id"] = self.app_id
+        response = await self._request("POST", "/messages", json=payload, timeout=20)
+        return response.json()
+
+    async def sync_external_conversation_message(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self._require_token()
+        if self.app_id:
+            payload = {**payload, "app_id": self.app_id}
+        response = await self._request(
+            "POST",
+            "/external/conversations/sync",
+            json=payload,
+            timeout=30,
+        )
+        return response.json()
+
+    async def get_memory_context(
+        self,
+        *,
+        conversation_id: str | None = None,
+        external_conversation_id: str | None = None,
+        external_conversation_key: str | None = None,
+        limit: int = 12,
+    ) -> dict[str, Any]:
+        self._require_token()
+        payload = {
+            "app_id": self.app_id or None,
+            "conversation_id": conversation_id,
+            "external_conversation_id": external_conversation_id,
+            "external_conversation_key": external_conversation_key,
+            "limit": max(4, min(int(limit or 12), 24)),
+        }
+        response = await self._request("POST", "/memory/context", json=payload, timeout=20)
+        return response.json()
+
+    async def update_external_message_status(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self._require_token()
+        if self.app_id:
+            payload = {**payload, "app_id": self.app_id}
+        response = await self._request(
+            "PATCH",
+            "/external/messages/status",
+            json=payload,
+            timeout=20,
+        )
+        return response.json()
+
+    async def accept_call(self, call_id: str) -> dict[str, Any]:
+        self._require_token()
+        clean_call_id = (call_id or "").strip()
+        if not clean_call_id:
+            raise MaronaBusinessApiError("call_id is required.")
+        response = await self._request("POST", f"/calls/{clean_call_id}/accept", timeout=30)
+        return response.json()
+
+    async def health(self) -> dict[str, Any]:
+        response = await self._request("GET", "/health", auth=False, timeout=10)
+        return response.json()
+
+    async def _request(self, method: str, path: str, *, timeout: float | None = None, auth: bool = True, **kwargs: Any) -> httpx.Response:
+        headers = {**(self._headers() if auth else {}), **kwargs.pop("headers", {})}
+        client = self._client
+        close_after = False
+        if client is None:
+            client = httpx.AsyncClient(timeout=timeout or self.timeout)
+            close_after = True
+        try:
+            response = await client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=headers or None,
+                **kwargs,
+            )
+            if response.status_code >= 400:
+                raise MaronaBusinessApiError(
+                    f"Marona Business API request failed with {response.status_code}: {response.text[:500]}"
+                )
+            return response
+        finally:
+            if close_after:
+                await client.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {self.token}"}
+        if self.app_id:
+            headers["X-Marona-App-Id"] = self.app_id
+        return headers
+
+    def _require_token(self) -> None:
+        if not self.token:
+            raise MaronaBusinessApiError("MARONA_BUSINESS_API_TOKEN is not configured.")
+
+    def _normalize_media_response_url(self, media: dict[str, Any]) -> dict[str, Any]:
+        url = str(media.get("url") or "").strip()
+        if url.startswith("http://") and self.base_url.startswith("https://"):
+            return {**media, "url": f"https://{url.removeprefix('http://')}"}
+        return media