marona 0.1.1

Official Python client SDK for Marona-compatible AI runtimes.

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

pip install marona

Send a message

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:

from marona import Marona

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

Self-hosted:

from marona import Marona

client = Marona(
    base_url="https://my-company-edge.example.com",
    api_key="mrn_live_...",
)

List available apps

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

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:

status = await client.pairing_status(pairing.pairing_id)

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

Use the identity token on future requests:

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.

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

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.

Release

Build and verify the package before uploading:

rm -rf dist build marona.egg-info
python3 -m build
python3 -m twine check dist/*

Upload with the project-scoped PyPI token for marona:

TWINE_USERNAME=__token__ TWINE_PASSWORD='PROJECT_SCOPED_TOKEN' python3 -m twine upload dist/*

Use a project-scoped token for normal releases. Account-wide tokens should only be used for the first upload of a new PyPI project.