Metadata-Version: 2.4
Name: marona-sdk
Version: 0.1.0
Summary: Official developer SDK for building Marona-compatible apps, tool servers, skills, and workflows.
Author: Blessing Nyuwani
License-Expression: MIT
Project-URL: Homepage, https://www.marona.ai
Project-URL: Repository, https://github.com/BlessingNyuwani/agentnet-mcp-sdk
Project-URL: Documentation, https://hub.marona.ai
Keywords: marona,sdk,mcp,agents,ai,tools,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: mcp<2.0,>=1.28
Requires-Dist: pydantic<3.0,>=2.10
Requires-Dist: uvicorn[standard]<1.0,>=0.34
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
Requires-Dist: twine<7.0,>=6.0; extra == "dev"
Dynamic: license-file

# Marona SDK

Marona SDK is the official developer SDK for building Marona-compatible apps,
MCP servers, skills, tool servers, and workflows.

It is not the runtime client SDK. Use `marona` when you want an application to
call a Marona-compatible runtime. Use `marona-sdk` when you are building
developer-side integrations that need the Marona tool contract.

The SDK helps projects produce the Marona standard automatically:

- `GET /health`
- `GET /manifest`
- `GET /hub-registration`
- `POST /mcp/` using the official MCP Python SDK `FastMCP`
- Tool outputs with `status`, `success`, `message`, `content`,
  `content_type`, `presentation_hint`, and `context`

## Install For Local Development

```bash
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

## Install In A Developer Integration Repo

Developer integration repos can depend on this SDK like any other pip package:

```bash
pip install marona-sdk
```

In `requirements.txt`:

```text
marona-sdk
```

It installs from the package index and imports as `marona_sdk`.

## Minimal Server

```python
from marona_sdk import AgentApp, success

agent_app = AgentApp(
    name="Hello Tool Server",
    server_name="hello-tools",
    slug="hello",
    description="Example Marona-compatible tool server.",
    category="Tools",
)

@agent_app.tool(description="Say hello to a user.")
def say_hello(name: str) -> dict:
    return success(f"Hello {name}.", greeting=f"Hello {name}.")

app = agent_app.create_fastapi_app()
```

## Standard Tool Results

All Marona-compatible tools should return the SDK result shape. The required
fields are:

- `status`: machine-readable result status.
- `success`: boolean result success flag.
- `message`: short user-facing status line.
- `content`: primary user-facing text/content for the agent to use.
- `content_type`: provider-neutral semantic type, for example `text`, `document`, `message`, `list`, `media`, or `search_results`.
- `presentation_hint`: provider-neutral usage hint, for example `display_as_provided`.
- `context`: short provider-neutral guidance for interpreting the result.

Provider-specific payloads must live under generic standard fields:

- `data`: one structured provider-specific object.
- `items`: a list of structured provider-specific objects.
- `count`: item count when `items` is used.
- `artifacts`: generic artifact descriptors.
- `job`: generic async job metadata.

If a tool declares its own `output_schema`, the SDK merges these standard fields
into that schema before exposing `/manifest` and `/hub-registration`.

## Standard Tool Inputs For User Files

Tools that consume uploaded files should declare the SDK-standard
`attachments` input property. The Edge runtime injects the current conversation
files into that array automatically, so the tool does not need custom runtime
logic or a provider-specific input name.

```python
from marona_sdk import standard_attachments_property

input_schema = {
    "type": "object",
    "properties": {
        "question": {"type": "string"},
        "attachments": standard_attachments_property(),
    },
    "required": [],
    "additionalProperties": False,
}
```

Each attachment can include `artifact_id`, `filename`, `mime_type`, `kind`,
`url`, `file_url`, `content_base64`, `content`, and `metadata`.

Example:

```python
return success(
    "Loaded email.",
    content=email_text,
    content_type="email_message",
    presentation_hint="display_as_provided",
    context="Return content as provided unless the user asks for a summary.",
)
```

Run it:

```bash
uvicorn examples.hello_server:app --host 127.0.0.1 --port 62900
```

Then inspect:

```text
http://127.0.0.1:62900/health
http://127.0.0.1:62900/hub-registration
http://127.0.0.1:62900/mcp/
```

## Developer Hub Helper

`DeveloperHubClient` is only for developer workflow commands such as create,
sync, and submit. Apps, devices, bots, and user interfaces should use the
separate `marona` runtime client package.

## Release

Build and verify the package before uploading:

```bash
rm -rf dist build marona_sdk.egg-info
python3.11 -m build
python3.11 -m twine check dist/*
```

Upload with a PyPI token:

```bash
TWINE_USERNAME=__token__ TWINE_PASSWORD='PYPI_TOKEN' python3.11 -m twine upload dist/*
```

For the first upload of a new package, PyPI requires an account-scoped upload
token. After the project exists, use a project-scoped token for normal releases.
