Marona Python SDK

Universal Model Gateway and MCP/Skill SDK for Python 3.10+.

Install

pip install marona==1.1.3

Authentication

A project-scoped Marona Developer Key is mandatory for every client and runtime mode. Pass api_key explicitly or set MARONA_API_KEY.

from marona import Marona

marona = Marona(api_key=marona_developer_key)

Missing, invalid, revoked, and expired keys raise typed MaronaAuthenticationError subclasses. Create and rotate keys in the Marona Developer Portal.

Universal Model Gateway

response = marona.responses.create(
    model="marona/auto",
    input="Review this architecture.",
    routing={
        "strategy": "balanced",
        "allowed_models": [
            "marona/auto",
            "marona/company-assistant",
        ],
    },
)

print(response.output)

Every model name must use the marona/* namespace. marona/auto delegates selection to the project-scoped Model Registry; named aliases such as marona/company-assistant resolve there. Provider credentials and custom endpoints are configured once through the Marona Developer Portal or Model Registry API. They are write-only and never exposed through this package.

All calls—including registered Edge models—go through authenticated Marona Runtime. There is no direct-provider, local-executor, credential-cache, or public model-registration bypass.

Agents and Hub tools

from marona import Agent, Runner

tools = marona.hub.connect(apps=["sda-books"])
agent = Agent(
    name="Customer Assistant",
    model="marona/auto",
    instructions="Help clearly.",
    tools=tools,
)

result = Runner.run(
    agent,
    "Download Steps to Christ",
    user_id="customer_482",
    session_id="chat_91a7",
)
print(result.output)

The SDK also supports streaming, realtime, handoffs, delegation, A2A peers, validated function tools, lifecycle hooks, and published Marona Skills while keeping every model invocation behind the Universal Model Gateway.

Errors

MaronaError exposes code, request_id, retryable, required_action, retry_after_ms, and safe details. Typed subclasses cover authentication, namespace/model, credits, upstream service, custom model, billing, and Marona availability failures. Responses expose only safe routing fields, never upstream endpoints or raw provider payloads.

External MCP federation

tools = marona.hub.connect(apps=["microsoft-365"])

Marona manages the Microsoft OAuth client; each application user only follows the authorization URL returned by the first protected tool call and consents. Use the same runtime user_id afterward. The managed connection covers Outlook, Calendar, OneDrive, Excel, PowerPoint, and SharePoint, subject to the signed-in user's permissions and tenant policy.

An unscoped connect() returns every capability available to the developer key. External calls always pass through Marona's governed gateway; upstream credentials and direct external endpoints are never returned to the SDK.

Release

Version 1.1.3 is published to PyPI from tag python-v1.1.3 only after tests, wheel/sdist validation, and coordinated release checks succeed on main.