marona 0.2.5

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.
• offline: use only local cache, local models, and installed offline-capable execution targets.
• 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, execution modes, execution targets, permissions, workspace config, and runtime config in the local Marona cache.

If the interface is paired, sync can also cache a safe private context pack for offline use. Cloud-only app data is not copied into offline mode. Offline messages use recent local conversation context, synced private context, and installed offline-capable app targets 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 installed offline-capable execution targets. 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 expose provider or backend details to client interfaces. Marona routes by execution mode and registered runtime resources.

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, runtime internals, 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