Metadata-Version: 2.4
Name: marona
Version: 0.2.5
Summary: Official Python client SDK for Marona-compatible AI runtimes and Hub integrations.
Author: Blessing Nyuwani
License-Expression: MIT
Project-URL: Homepage, https://www.marona.ai
Project-URL: Repository, https://github.com/BlessingNyuwani/edge-node-service
Project-URL: Documentation, https://hub.marona.ai
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
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

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

```bash
pip install marona
```

## Create A Client

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

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

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

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

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

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

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

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