marona-sdk 0.1.0__tar.gz

marona_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blessing Nyuwani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marona_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+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.

marona_sdk-0.1.0/README.md

@@ -0,0 +1,159 @@
+# 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.

marona_sdk-0.1.0/marona_sdk/__init__.py

@@ -0,0 +1,25 @@
+from marona_sdk.hub import DeveloperHubClient
+from marona_sdk.models import (
+    PermissionSpec,
+    ToolSpec,
+    standard_attachment_schema,
+    standard_attachments_property,
+    standard_output_schema,
+)
+from marona_sdk.results import failure, success
+from marona_sdk.server import AgentApp
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentApp",
+    "DeveloperHubClient",
+    "PermissionSpec",
+    "ToolSpec",
+    "standard_attachment_schema",
+    "standard_attachments_property",
+    "standard_output_schema",
+    "failure",
+    "success",
+    "__version__",
+]

marona_sdk-0.1.0/marona_sdk/cli.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="marona-sdk",
+        description="Marona SDK developer helpers.",
+    )
+    parser.add_argument(
+        "command",
+        choices=["version"],
+        help="Command to run. More commands will be added as the SDK grows.",
+    )
+    args = parser.parse_args()
+    if args.command == "version":
+        print("marona-sdk 0.1.0")

marona_sdk-0.1.0/marona_sdk/hub.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class DeveloperHubClient:
+    """Small helper for developer workflows. Runtime edge sync belongs in Edge SDK."""
+
+    def __init__(self, *, hub_url: str, token: str, timeout_seconds: float = 30) -> None:
+        self.hub_url = hub_url.rstrip("/")
+        self.token = token
+        self.timeout_seconds = timeout_seconds
+
+    async def create_agent_app(self, registration_payload: dict[str, Any]) -> dict[str, Any]:
+        return await self._request("POST", "/portal/developer/agent-apps", json=registration_payload)
+
+    async def sync_agent_app(self, agent_app_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/portal/developer/agent-apps/{agent_app_id}/sync-mcp-server")
+
+    async def submit_agent_app(self, agent_app_id: str, comments: str | None = None) -> dict[str, Any]:
+        return await self._request(
+            "POST",
+            f"/portal/developer/agent-apps/{agent_app_id}/submit",
+            json={"comments": comments} if comments else {},
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        async with httpx.AsyncClient(
+            base_url=self.hub_url,
+            timeout=self.timeout_seconds,
+            headers={"Authorization": f"Bearer {self.token}"},
+        ) as client:
+            response = await client.request(method, path, json=json)
+            response.raise_for_status()
+            return response.json()

marona_sdk-0.1.0/marona_sdk/models.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+STANDARD_OUTPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "status": {"type": "string"},
+        "success": {"type": "boolean"},
+        "message": {"type": "string"},
+        "content": {
+            "type": "string",
+            "description": "Primary user-facing content the agent can display or reason over.",
+        },
+        "content_type": {
+            "type": "string",
+            "description": "Provider-neutral semantic type for content, such as text, document, message, list, media, or search_results.",
+        },
+        "presentation_hint": {
+            "type": "string",
+            "description": "Provider-neutral presentation hint, such as display_as_provided or summarize_if_requested.",
+        },
+        "context": {
+            "type": "string",
+            "description": "Provider-neutral guidance for interpreting this result.",
+        },
+        "data": {
+            "type": "object",
+            "description": "Provider-specific structured object payload. Keep provider fields inside this object.",
+            "additionalProperties": True,
+        },
+        "items": {
+            "type": "array",
+            "description": "Provider-specific structured list payload. Use for search/list results from any MCP.",
+            "items": {"type": "object", "additionalProperties": True},
+        },
+        "count": {
+            "type": "integer",
+            "description": "Number of items represented in items when applicable.",
+        },
+        "artifacts": {
+            "type": "array",
+            "description": "Generic artifacts produced by the tool.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "type": {"type": "string"},
+                    "label": {"type": "string"},
+                    "mime_type": {"type": "string"},
+                    "url": {"type": "string"},
+                    "base64": {"type": "string"},
+                    "text": {"type": "string"},
+                    "external_id": {"type": "string"},
+                    "filename": {"type": "string"},
+                    "metadata": {"type": "object", "additionalProperties": True},
+                },
+                "additionalProperties": True,
+            },
+        },
+        "job": {
+            "type": "object",
+            "description": "Generic async job payload with provider-specific details.",
+            "additionalProperties": True,
+        },
+    },
+    "required": ["status", "success", "message", "content", "content_type", "presentation_hint", "context"],
+    "additionalProperties": True,
+}
+
+
+STANDARD_ATTACHMENT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": "Provider-neutral user file/artifact passed by the runtime.",
+    "properties": {
+        "artifact_id": {
+            "type": "string",
+            "description": "Runtime artifact id for this attachment, when available.",
+        },
+        "filename": {
+            "type": "string",
+            "description": "Original or display filename.",
+        },
+        "mime_type": {
+            "type": "string",
+            "description": "MIME type, for example application/pdf or image/png.",
+        },
+        "kind": {
+            "type": "string",
+            "description": "Runtime artifact kind, for example document, image, audio, video, or file.",
+        },
+        "url": {
+            "type": "string",
+            "description": "Runtime-accessible URL for the attachment, when available.",
+        },
+        "file_url": {
+            "type": "string",
+            "description": "Runtime-accessible file URL for tools that consume file_url.",
+        },
+        "content_base64": {
+            "type": "string",
+            "description": "Base64-encoded attachment bytes when the runtime sends inline bytes.",
+        },
+        "content": {
+            "type": "string",
+            "description": "Inline text content when the attachment is text-like.",
+        },
+        "metadata": {
+            "type": "object",
+            "description": "Runtime or provider-specific attachment metadata.",
+            "additionalProperties": True,
+        },
+    },
+    "additionalProperties": True,
+}
+
+STANDARD_ATTACHMENTS_PROPERTY: dict[str, Any] = {
+    "type": "array",
+    "description": (
+        "User-provided files or runtime artifacts. Declare this property on any "
+        "tool that can consume uploaded files; the Edge runtime injects the "
+        "current conversation attachments automatically."
+    ),
+    "items": STANDARD_ATTACHMENT_SCHEMA,
+}
+
+
+def standard_attachment_schema() -> dict[str, Any]:
+    return deepcopy(STANDARD_ATTACHMENT_SCHEMA)
+
+
+def standard_attachments_property() -> dict[str, Any]:
+    return deepcopy(STANDARD_ATTACHMENTS_PROPERTY)
+
+
+def standard_output_schema(schema: dict[str, Any] | None = None) -> dict[str, Any]:
+    if schema is None:
+        return deepcopy(STANDARD_OUTPUT_SCHEMA)
+
+    merged = deepcopy(schema)
+    base = deepcopy(STANDARD_OUTPUT_SCHEMA)
+    merged["type"] = merged.get("type") or "object"
+    merged["properties"] = {
+        **base["properties"],
+        **(merged.get("properties") or {}),
+    }
+    required = list(dict.fromkeys([*base["required"], *(merged.get("required") or [])]))
+    merged["required"] = required
+    merged.setdefault("additionalProperties", True)
+    return merged
+
+
+class PermissionSpec(BaseModel):
+    key: str = Field(pattern=r"^[a-zA-Z0-9_.:-]+$")
+    name: str
+    description: str | None = None
+    required: bool = True
+    scope: str | None = None
+
+
+class ToolSpec(BaseModel):
+    name: str
+    title: str | None = None
+    description: str
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any] = Field(default_factory=standard_output_schema)
+    is_destructive: bool = False
+    requires_user_confirmation: bool = False
+
+    def descriptor(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "title": self.title or self.name.replace("_", " ").title(),
+            "description": self.description,
+            "input_schema": self.input_schema,
+            "output_schema": standard_output_schema(self.output_schema),
+            "is_destructive": self.is_destructive,
+            "requires_user_confirmation": self.requires_user_confirmation,
+        }
+
+    def mcp_descriptor(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "title": self.title or self.name.replace("_", " ").title(),
+            "description": self.description,
+            "inputSchema": self.input_schema,
+            "annotations": {
+                "readOnlyHint": not self.is_destructive,
+                "destructiveHint": self.is_destructive,
+                "openWorldHint": True,
+            },
+        }
+
+
+class AuthConfig(BaseModel):
+    is_auth_required: bool = False
+    auth_type: Literal["none", "oauth2", "api_key", "bearer_token", "custom"] = "none"
+    auth_instructions: str | None = None
+    connection_schema: dict[str, Any] | None = None

marona_sdk-0.1.0/marona_sdk/py.typed

@@ -0,0 +1 @@
+