marona 0.2.3

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

marona

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

Use marona to build web apps, mobile backends, WhatsApp bots, smart glasses, desktop apps, devices, and agents that need one interface for cloud, local, and hybrid AI execution.

Install

pip install marona

Create A Client

from marona import Marona

marona = Marona(
    api_key="mrn_live_...",
    mode="hybrid",
)

Modes:

• online: use Marona Runtime and online app routes. The hosted runtime can route between configured cloud and private LiteRT-LM/Gemma providers.
• offline: use only local cache, local models, and local app routes.
• hybrid: try a registered local/LAN model first, then fall back to Marona Runtime when local execution fails and online access is allowed.

Send A Message

response = await marona.message(
    "Create a PowerPoint about AI introduction",
    interface="api",
    conversation_id="demo",
)

print(response.text)

Interface Names

interface identifies the client surface making the request.

Standard values are:

• api
• web
• mobile_app
• desktop
• whatsapp

Future devices can use custom lowercase slugs such as smart_glasses, vehicle_console, or kiosk. Interface names must match ^[a-z][a-z0-9_-]{0,63}$.

Sync Hub Metadata

await marona.sync()

Sync stores app IDs, app routes, permissions, workspace config, runtime config, and local/remote app endpoints in the local Marona cache.

Sync does not copy cloud-only private user data into offline mode. Offline messages use recent local conversation context plus local/private MCP app endpoints from the cache.

Connect Apps By ID

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

Marona resolves apps from local cache first. Offline mode uses only local app routes. Online and hybrid modes can refresh from Hub.

Register A Local Or Cloud Model

marona.models.register(
    name="office-model",
    endpoint="http://localhost:9379",
)

marona.models.use("office-model")

Developers do not need to specify provider, backend type, or capabilities. Marona detects model features internally and routes by execution mode.

Smart Glasses / Wearables

response = await marona.message(
    "What am I looking at?",
    interface="wearable",
    client_capabilities={
        "client_type": "wearable",
        "supports": {"voice": True, "camera": True, "screen": True},
        "constraints": {"screen_size": "tiny", "interaction": "voice"},
    },
)

The interface does not need to know model names, providers, or app endpoints.

Pair A User Interface

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

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

Use the returned identity token on future requests.

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])

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