marona 0.1.5

Official Python client SDK for Marona-compatible AI runtimes and Hub integrations.

marona

Official Python client for Marona-compatible AI runtimes and Marona Hub.

Use marona when you are building an application, bot, device, or agent interface that needs to:

• send messages to a Marona-compatible runtime
• discover available apps
• connect approved Hub apps to your own agent framework
• manage user permissions and service connections
• receive inbound events
• create realtime voice or vision sessions

Install

pip install marona

1. Create A Client

Marona Cloud:

from marona import Marona

marona = Marona(
    base_url="https://edge.marona.ai",
    api_key="mrn_live_...",
)

When api_key is provided, hosted Marona Runtime calls are authorized and usage is recorded against that developer account. Use hub.connect(...) when your own agent runtime only needs approved Hub app connection metadata.

Self-hosted runtime:

from marona import Marona

marona = Marona(
    base_url="https://runtime.example.com",
    api_key="mrn_live_...",
)

2. Send A Runtime Message

import asyncio

from marona import Marona


async def main() -> None:
    marona = Marona(api_key="mrn_live_...")
    response = await marona.message(
        "Create a PowerPoint about AI introduction",
        interface="api",
        conversation_id="demo",
    )

    print(response.reply)
    for artifact in response.artifacts:
        print(artifact.get("filename"), artifact.get("url"))


asyncio.run(main())

3. Connect Hub Apps To Your Own Agent

Every Hub app has a unique app ID, also called a slug. Examples:

• weather-mcp
• knowledge-mcp
• company-crm-mcp

Use hub.connect(...) when your own agent framework will execute the model and you only need approved app connections from Marona Hub.

import asyncio

from marona import Marona


async def main() -> None:
    marona = Marona(api_key="mrn_live_...")
    servers = await marona.hub.connect(
        ["weather-mcp", "knowledge-mcp"],
        adapter="openai_mcp",
    )
    print(servers)


asyncio.run(main())

For frameworks that need tool descriptors instead of MCP server configs:

tools = await marona.hub.connect(
    ["weather-mcp"],
    adapter="tools",
)

4. List Available Apps

apps = await marona.list_apps(limit=20, search="slides")

for app in apps.apps:
    print(app["slug"], app["name"])

5. Pair A User Interface

Pairing lets a web, mobile, desktop, wearable, or other interface attach to the same user identity.

pairing = await marona.start_pairing(
    interface="web",
    device_name="My web app",
)

print(pairing.display_code)
print(pairing.whatsapp_url)

After the user sends the pairing code from WhatsApp, poll for completion:

status = await marona.pairing_status(pairing.pairing_id)

if status.identity:
    identity_token = status.identity.access_token

Use the identity token on future requests:

response = await marona.message(
    "What is on my calendar today?",
    identity_token=identity_token,
)

6. Connect A User Service Account

Some apps need a user connection, such as Google Calendar, Gmail, or Google Slides.

connection = await marona.connect_app(
    "slides",
    provider="google",
    identity_token=identity_token,
    return_url="https://example.com/connected",
)

print(connection.authorization_url)

Open authorization_url in a browser so the user can authorize the provider.

7. Send Files

from marona import RuntimeAttachment

attachment = RuntimeAttachment.from_bytes(
    b"hello",
    filename="note.txt",
    mime_type="text/plain",
    kind="document",
)

response = await marona.message(
    "Summarize this file",
    attachments=[attachment],
    identity_token=identity_token,
)

8. Edge Runtime Activation

Device runtimes can activate and sync against Marona Hub with the same package:

from marona import EdgeHubClient

edge = EdgeHubClient(hub_url="https://hub.marona.ai")
activation = await edge.start_activation(
    device_name="Office runtime",
    device_public_key="...",
)

Package Names

• Python client: marona, import marona
• Dart client: marona, import package:marona/marona.dart
• TypeScript client: marona, import Marona from "marona"
• Developer SDK for building apps: marona-sdk, import marona_sdk