Marona Python SDK

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

Install

pip install marona==1.1.1

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

registered = marona.hub.register_mcp_server(
    name="Microsoft 365 Outlook Mail",
    slug="microsoft-365-mail",
    server_url=(
        "https://agent365.svc.cloud.microsoft/agents/tenants/"
        f"{os.environ['MICROSOFT_TENANT_ID']}/servers/mcp_MailTools"
    ),
    auth_mode="oauth2",
)
server_id = registered["server"]["id"]
authorization = marona.hub.start_mcp_oauth(
    server_id, user_subject="YOUR_APPLICATION_USER_ID"
)
print(authorization["authorization_url"])
marona.hub.verify_mcp_server(server_id)
marona.hub.activate_mcp_server(server_id)
tools = marona.hub.connect(apps=["microsoft-365-mail"])

Marona manages the Microsoft OAuth client; each application user only follows the authorization URL and consents. Use the same user_subject as the runtime user_id afterward. Register the official Files endpoint when agents need OneDrive or SharePoint content, including stored Excel and PowerPoint files.

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.1 is published to PyPI from tag python-v1.1.1 only after tests, wheel/sdist validation, and coordinated release checks succeed on main.