Metadata-Version: 2.4
Name: marona
Version: 1.1.1
Summary: Universal Model Gateway and MCP/Skill SDK with mandatory project-scoped Marona authentication.
Author: Blessing Nyuwani
License-Expression: MIT
Project-URL: Homepage, https://www.marona.ai
Project-URL: Documentation, https://platform.marona.ai/docs
Keywords: marona,sdk,mcp,agents,ai,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: websockets<17,>=15
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: twine<7.0,>=6.0; extra == "dev"
Dynamic: license-file

# Marona Python SDK

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

## Install

```bash
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`.

```python
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

```python
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

```python
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

```python
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`.
