mash-api 0.1.0__tar.gz

mash_api-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: mash-api
+Version: 0.1.0
+Summary: OpenAPI service package for Mash applications
+Author: imsid
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mashpy>=0.1.2
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# mash-api
+
+OpenAPI service package for self-hosted Mash applications.
+
+## Install
+
+```bash
+pip install mash-api
+# or
+pip install "mashpy[api]"
+```
+
+## Usage
+
+```python
+from mash_api import create_app
+from my_app import definition
+
+app = create_app(definition)
+```
+
+Run with Uvicorn:
+
+```bash
+uvicorn my_module:app --host 127.0.0.1 --port 8000
+```
+
+Or use the bundled CLI:
+
+```bash
+mash-api --app my_app:build_definition
+```

mash_api-0.1.0/README.md

@@ -0,0 +1,32 @@
+# mash-api
+
+OpenAPI service package for self-hosted Mash applications.
+
+## Install
+
+```bash
+pip install mash-api
+# or
+pip install "mashpy[api]"
+```
+
+## Usage
+
+```python
+from mash_api import create_app
+from my_app import definition
+
+app = create_app(definition)
+```
+
+Run with Uvicorn:
+
+```bash
+uvicorn my_module:app --host 127.0.0.1 --port 8000
+```
+
+Or use the bundled CLI:
+
+```bash
+mash-api --app my_app:build_definition
+```

mash_api-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "mash-api"
+version = "0.1.0"
+description = "OpenAPI service package for Mash applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Proprietary"}
+authors = [{ name = "imsid" }]
+dependencies = [
+  "mashpy>=0.1.2",
+  "fastapi>=0.115.0",
+  "uvicorn>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+mash-api = "mash_api.main:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mash_api*"]

mash_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mash_api-0.1.0/src/mash_api/__init__.py

@@ -0,0 +1,7 @@
+"""Public exports for mash-api package."""
+
+from .app import create_app, run_app
+from .config import MashAPIConfig
+from .types import MashAPIAppSpec, SubagentRegistration
+
+__all__ = ["create_app", "run_app", "MashAPIConfig", "MashAPIAppSpec", "SubagentRegistration"]

mash_api-0.1.0/src/mash_api/app.py

@@ -0,0 +1,662 @@
+"""FastAPI composition for mash-api runtime and telemetry endpoints."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from contextlib import asynccontextmanager
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, AsyncIterator, Iterator, Optional, Sequence
+
+import uvicorn
+from fastapi import APIRouter, Depends, FastAPI, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import BaseModel, Field
+
+from mash.logging.logger import EventLogger
+from mash.memory.search.service import MemorySearchService
+from mash.memory.search.types import FusionWeights, RetrievalConfig
+from mash.memory.store import SQLiteStore
+from mash.runtime import MashAgentClient, MashAgentClientError, MashAgentHost, MashRuntimeDefinition
+
+from .config import MashAPIConfig
+from .types import SubagentRegistration
+
+
+class APIError(RuntimeError):
+    """Structured API error for envelope serialization."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+
+
+@dataclass
+class _AppRuntimeState:
+    host: MashAgentHost
+    primary_agent_id: str
+    primary_client: MashAgentClient
+    api_key: Optional[str]
+    observability_enabled: bool
+    observability_log_path: Optional[Path]
+    observability_memory_db_path: Optional[Path]
+    search_service: Optional[MemorySearchService]
+    default_events_limit: int
+    default_search_limit: int
+
+
+class InvokeRequest(BaseModel):
+    message: str = Field(min_length=1)
+    session_id: Optional[str] = None
+    turn_metadata: dict[str, Any] = Field(default_factory=dict)
+    timeout_ms: Optional[int] = None
+
+
+class SubmitRequest(BaseModel):
+    message: str = Field(min_length=1)
+    session_id: Optional[str] = None
+    turn_metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class PreferencesUpdateRequest(BaseModel):
+    preferences: dict[str, Any]
+
+
+class AppDataSetRequest(BaseModel):
+    value: Any
+
+
+class CompactSessionRequest(BaseModel):
+    reason: str = "manual"
+    session_total_tokens_reset: int = 0
+
+
+def _success(data: Any) -> dict[str, Any]:
+    return {"data": data}
+
+
+def _error_payload(code: str, message: str, details: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+    return {
+        "error": {
+            "code": code,
+            "message": message,
+            "details": details or {},
+        }
+    }
+
+
+def _state_from_request(request: Request) -> _AppRuntimeState:
+    state = getattr(request.app.state, "runtime_state", None)
+    if state is None:
+        raise APIError(
+            code="RUNTIME_NOT_READY",
+            message="runtime is not initialized",
+            status_code=503,
+        )
+    return state
+
+
+def _normalize_optional_text(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    text = value.strip()
+    return text or None
+
+
+def _require_message(value: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        raise APIError(code="INVALID_REQUEST", message="message is required", status_code=400)
+    return text
+
+
+def _parse_limit(raw: Optional[int], *, default: int, max_value: int) -> int:
+    if raw is None:
+        return default
+    return max(1, min(int(raw), max_value))
+
+
+def _build_runtime_event_sse_payload(event_name: str, payload: Any) -> str:
+    data = json.dumps(payload, ensure_ascii=True)
+    return f"event: {event_name}\ndata: {data}\n\n"
+
+
+def _build_observability_sse_payload(payload: str) -> str:
+    return f"data: {payload}\n\n"
+
+
+def create_app(
+    definition: MashRuntimeDefinition,
+    *,
+    subagents: Sequence[SubagentRegistration] | None = None,
+    config: MashAPIConfig | None = None,
+) -> FastAPI:
+    """Build a FastAPI app that composes Mash runtime + observability APIs."""
+
+    resolved_config = config or MashAPIConfig()
+
+    @asynccontextmanager
+    async def _lifespan(application: FastAPI):
+        host = MashAgentHost(bind_host=resolved_config.runtime_bind_host)
+        primary_agent_id = host.register_primary(definition)
+        for registration in subagents or ():
+            host.register_subagent(
+                registration.definition,
+                metadata=registration.metadata,
+                agent_id=registration.agent_id,
+            )
+        host.start()
+        primary_client = host.get_client(primary_agent_id)
+
+        default_log_path = definition.get_log_destination().expanduser().resolve()
+        observability_log_path = resolved_config.resolved_log_path() or default_log_path
+        observability_memory_db_path = resolved_config.resolved_memory_db_path()
+
+        search_service: Optional[MemorySearchService] = None
+        if resolved_config.enable_observability and observability_memory_db_path is not None:
+            event_logger = EventLogger(observability_log_path)
+            search_service = MemorySearchService(
+                SQLiteStore(observability_memory_db_path),
+                event_logger=event_logger,
+                retrieval_config=RetrievalConfig(enable_keyword=True, enable_semantic=False),
+                fusion_weights=FusionWeights(keyword_weight=1.0, semantic_weight=0.0),
+            )
+
+        application.state.runtime_state = _AppRuntimeState(
+            host=host,
+            primary_agent_id=primary_agent_id,
+            primary_client=primary_client,
+            api_key=resolved_config.resolved_api_key(),
+            observability_enabled=resolved_config.enable_observability,
+            observability_log_path=observability_log_path,
+            observability_memory_db_path=observability_memory_db_path,
+            search_service=search_service,
+            default_events_limit=max(1, int(resolved_config.default_events_limit)),
+            default_search_limit=max(1, int(resolved_config.default_search_limit)),
+        )
+        try:
+            yield
+        finally:
+            state = getattr(application.state, "runtime_state", None)
+            if state is not None:
+                state.host.close()
+            application.state.runtime_state = None
+
+    app = FastAPI(title="Mash API", version="1.0.0", lifespan=_lifespan)
+
+    cors_origins = resolved_config.resolved_cors_origins()
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+            allow_credentials=False,
+        )
+
+    @app.exception_handler(APIError)
+    async def _api_error_handler(_: Request, exc: APIError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=_error_payload(exc.code, exc.message, exc.details),
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation_error_handler(_: Request, exc: RequestValidationError) -> JSONResponse:
+        return JSONResponse(
+            status_code=422,
+            content=_error_payload(
+                "VALIDATION_ERROR",
+                "request validation failed",
+                {"errors": exc.errors()},
+            ),
+        )
+
+    @app.exception_handler(MashAgentClientError)
+    async def _client_error_handler(_: Request, exc: MashAgentClientError) -> JSONResponse:
+        return JSONResponse(
+            status_code=502,
+            content=_error_payload("RUNTIME_CLIENT_ERROR", str(exc)),
+        )
+
+    async def _authorize(request: Request) -> None:
+        state = _state_from_request(request)
+        expected_key = state.api_key
+        if expected_key is None:
+            return
+
+        header_token: Optional[str] = None
+        auth_header = request.headers.get("authorization")
+        if isinstance(auth_header, str) and auth_header.lower().startswith("bearer "):
+            header_token = auth_header[7:].strip() or None
+
+        x_api_key = _normalize_optional_text(request.headers.get("x-api-key"))
+        provided = header_token or x_api_key
+        if provided != expected_key:
+            raise APIError(
+                code="UNAUTHORIZED",
+                message="valid API key is required",
+                status_code=401,
+            )
+
+    api = APIRouter(prefix=resolved_config.api_prefix, dependencies=[Depends(_authorize)])
+
+    @api.get("/health")
+    def health(request: Request) -> dict[str, Any]:
+        state = _state_from_request(request)
+        session_info = state.primary_client.get_session_info()
+        log_path = state.observability_log_path
+        return _success(
+            {
+                "status": "ok",
+                "api_version": "v1",
+                "runtime": {
+                    "primary_agent_id": state.primary_agent_id,
+                    "app_id": session_info.get("app_id"),
+                    "session_id": session_info.get("session_id"),
+                    "subagent_ids": session_info.get("subagent_ids", []),
+                    "model": session_info.get("model"),
+                    "max_steps": session_info.get("max_steps"),
+                },
+                "observability": {
+                    "enabled": state.observability_enabled,
+                    "events": {
+                        "configured": log_path is not None,
+                        "path": str(log_path) if log_path is not None else None,
+                        "exists": bool(log_path.exists()) if log_path is not None else False,
+                        "default_limit": state.default_events_limit,
+                    },
+                    "memory": {
+                        "configured": state.observability_memory_db_path is not None,
+                        "search_available": state.search_service is not None,
+                        "path": (
+                            str(state.observability_memory_db_path)
+                            if state.observability_memory_db_path is not None
+                            else None
+                        ),
+                        "default_limit": state.default_search_limit,
+                    },
+                },
+            }
+        )
+
+    @api.post("/interactions/invoke")
+    def invoke(request: Request, body: InvokeRequest) -> dict[str, Any]:
+        state = _state_from_request(request)
+        message = _require_message(body.message)
+        session_id = _normalize_optional_text(body.session_id)
+        timeout_ms = body.timeout_ms if body.timeout_ms is None else int(body.timeout_ms)
+        if timeout_ms is not None and timeout_ms <= 0:
+            timeout_ms = None
+
+        try:
+            result = state.primary_client.invoke(
+                message,
+                session_id=session_id,
+                turn_metadata=dict(body.turn_metadata or {}),
+                timeout_ms=timeout_ms,
+            )
+        except TimeoutError as exc:
+            raise APIError(
+                code="REQUEST_TIMEOUT",
+                message=str(exc),
+                status_code=504,
+            ) from exc
+        return _success(result)
+
+    @api.post("/interactions/requests")
+    def submit_request(request: Request, body: SubmitRequest) -> dict[str, Any]:
+        state = _state_from_request(request)
+        request_id = state.primary_client.post_request(
+            _require_message(body.message),
+            session_id=_normalize_optional_text(body.session_id),
+            turn_metadata=dict(body.turn_metadata or {}),
+        )
+        return _success({"request_id": request_id})
+
+    @api.get("/interactions/requests/{request_id}/events")
+    def stream_request_events(request: Request, request_id: str) -> StreamingResponse:
+        state = _state_from_request(request)
+        normalized_request_id = request_id.strip()
+        if not normalized_request_id:
+            raise APIError(
+                code="INVALID_REQUEST",
+                message="request_id is required",
+                status_code=400,
+            )
+
+        def _generate() -> Iterator[str]:
+            try:
+                for event in state.primary_client.stream(normalized_request_id):
+                    event_name = str(event.get("event") or "message")
+                    payload = event.get("data")
+                    yield _build_runtime_event_sse_payload(event_name, payload)
+                    if event_name in {"request.completed", "request.error"}:
+                        break
+            except MashAgentClientError as exc:
+                yield _build_runtime_event_sse_payload(
+                    "request.error",
+                    {
+                        "request_id": normalized_request_id,
+                        "status": "error",
+                        "error": str(exc),
+                    },
+                )
+
+        return StreamingResponse(
+            _generate(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )
+
+    @api.get("/runtime/session")
+    def get_runtime_session(request: Request, session_id: Optional[str] = None) -> dict[str, Any]:
+        state = _state_from_request(request)
+        info = state.primary_client.get_session_info(_normalize_optional_text(session_id))
+        return _success(info)
+
+    @api.get("/runtime/subagents")
+    def get_subagents(request: Request) -> dict[str, Any]:
+        state = _state_from_request(request)
+        return _success({"subagent_ids": state.primary_client.get_subagent_ids()})
+
+    @api.get("/runtime/sessions/{session_id}/preferences")
+    def get_preferences(request: Request, session_id: str) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id is required", status_code=400)
+        return _success({"preferences": state.primary_client.get_preferences(session_id)})
+
+    @api.put("/runtime/sessions/{session_id}/preferences")
+    def set_preferences(request: Request, session_id: str, body: PreferencesUpdateRequest) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id is required", status_code=400)
+        state.primary_client.set_preferences(session_id, body.preferences)
+        return _success({"ok": True})
+
+    @api.get("/runtime/sessions/{session_id}/app-data")
+    def list_app_data(request: Request, session_id: str) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id is required", status_code=400)
+        return _success({"items": state.primary_client.list_app_data(session_id)})
+
+    @api.get("/runtime/sessions/{session_id}/app-data/{key}")
+    def get_app_data(request: Request, session_id: str, key: str) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip() or not key.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id and key are required", status_code=400)
+        return _success({"value": state.primary_client.get_app_data(session_id, key)})
+
+    @api.put("/runtime/sessions/{session_id}/app-data/{key}")
+    def set_app_data(request: Request, session_id: str, key: str, body: AppDataSetRequest) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip() or not key.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id and key are required", status_code=400)
+        state.primary_client.set_app_data(session_id, key, body.value)
+        return _success({"ok": True})
+
+    @api.delete("/runtime/sessions/{session_id}/app-data/{key}")
+    def delete_app_data(request: Request, session_id: str, key: str) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip() or not key.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id and key are required", status_code=400)
+        deleted = state.primary_client.delete_app_data(session_id, key)
+        return _success({"deleted": bool(deleted)})
+
+    @api.get("/runtime/sessions/{session_id}/history")
+    def get_history(
+        request: Request,
+        session_id: str,
+        limit: Optional[int] = Query(default=None),
+    ) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id is required", status_code=400)
+        turns = state.primary_client.get_history_turns(session_id, limit=limit)
+        return _success({"turns": turns})
+
+    @api.post("/runtime/sessions/{session_id}/compact")
+    def compact_session(
+        request: Request,
+        session_id: str,
+        body: CompactSessionRequest,
+    ) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not session_id.strip():
+            raise APIError(code="INVALID_REQUEST", message="session_id is required", status_code=400)
+        summary_text, turn_id = state.primary_client.compact_session(
+            session_id=session_id,
+            reason=body.reason,
+            session_total_tokens_reset=body.session_total_tokens_reset,
+        )
+        return _success({"summary_text": summary_text, "turn_id": turn_id})
+
+    @api.get("/telemetry/events")
+    def get_observability_events(
+        request: Request,
+        limit: Optional[int] = Query(default=None),
+    ) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not state.observability_enabled:
+            raise APIError(
+                code="OBSERVABILITY_DISABLED",
+                message="telemetry endpoints are disabled",
+                status_code=503,
+            )
+
+        log_path = state.observability_log_path
+        if log_path is None:
+            raise APIError(
+                code="OBSERVABILITY_EVENTS_UNCONFIGURED",
+                message="telemetry log path is not configured",
+                status_code=503,
+            )
+        if not log_path.exists():
+            raise APIError(
+                code="LOG_FILE_NOT_FOUND",
+                message="log file not found",
+                status_code=404,
+                details={"path": str(log_path)},
+            )
+
+        resolved_limit = _parse_limit(limit, default=state.default_events_limit, max_value=20000)
+        events: list[dict[str, Any]] = []
+        with log_path.open("r", encoding="utf-8") as handle:
+            lines = handle.readlines()
+
+        for raw in lines[-resolved_limit:]:
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(payload, dict):
+                events.append(payload)
+
+        return _success({
+            "events": events,
+            "path": str(log_path),
+            "limit": resolved_limit,
+        })
+
+    @api.get("/telemetry/events/stream")
+    async def stream_observability_events(request: Request) -> StreamingResponse:
+        state = _state_from_request(request)
+        if not state.observability_enabled:
+            raise APIError(
+                code="OBSERVABILITY_DISABLED",
+                message="telemetry endpoints are disabled",
+                status_code=503,
+            )
+
+        log_path = state.observability_log_path
+        if log_path is None:
+            raise APIError(
+                code="OBSERVABILITY_EVENTS_UNCONFIGURED",
+                message="telemetry log path is not configured",
+                status_code=503,
+            )
+        if not log_path.exists():
+            raise APIError(
+                code="LOG_FILE_NOT_FOUND",
+                message="log file not found",
+                status_code=404,
+                details={"path": str(log_path)},
+            )
+
+        async def _generate() -> AsyncIterator[str]:
+            with log_path.open("r", encoding="utf-8") as handle:
+                handle.seek(0, os.SEEK_END)
+                while True:
+                    if await request.is_disconnected():
+                        break
+                    line = handle.readline()
+                    if not line:
+                        yield ": keep-alive\n\n"
+                        await asyncio.sleep(0.25)
+                        continue
+                    payload = line.strip()
+                    if not payload:
+                        continue
+                    try:
+                        json.loads(payload)
+                    except json.JSONDecodeError:
+                        continue
+                    yield _build_observability_sse_payload(payload)
+
+        return StreamingResponse(
+            _generate(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )
+
+    @api.get("/telemetry/memory/search")
+    def search_memory(
+        request: Request,
+        q: str,
+        app_id: str,
+        session_id: Optional[str] = None,
+        limit: Optional[int] = Query(default=None),
+    ) -> dict[str, Any]:
+        state = _state_from_request(request)
+        if not state.observability_enabled:
+            raise APIError(
+                code="OBSERVABILITY_DISABLED",
+                message="telemetry endpoints are disabled",
+                status_code=503,
+            )
+
+        query_text = q.strip()
+        if not query_text:
+            raise APIError(
+                code="MISSING_QUERY",
+                message="q is required",
+                status_code=400,
+                details={"param": "q"},
+            )
+
+        app_id_value = app_id.strip()
+        if not app_id_value:
+            raise APIError(
+                code="MISSING_APP_ID",
+                message="app_id is required",
+                status_code=400,
+                details={"param": "app_id"},
+            )
+
+        if state.search_service is None:
+            raise APIError(
+                code="MEMORY_SEARCH_UNAVAILABLE",
+                message="memory search unavailable (configure memory db path)",
+                status_code=503,
+            )
+
+        resolved_limit = _parse_limit(limit, default=state.default_search_limit, max_value=50)
+        normalized_session_id = _normalize_optional_text(session_id)
+        try:
+            results = state.search_service.search(
+                query_text,
+                limit=resolved_limit,
+                session_id=normalized_session_id,
+                app_id=app_id_value,
+            )
+        except ValueError as exc:
+            raise APIError(
+                code="SEARCH_VALIDATION_ERROR",
+                message=str(exc),
+                status_code=400,
+            ) from exc
+        except (NotImplementedError, RuntimeError) as exc:
+            raise APIError(
+                code="SEARCH_UNAVAILABLE",
+                message=str(exc),
+                status_code=503,
+            ) from exc
+        except Exception as exc:  # pragma: no cover
+            raise APIError(
+                code="SEARCH_FAILED",
+                message=f"search failed: {exc}",
+                status_code=500,
+            ) from exc
+
+        return _success(
+            {
+                "results": [asdict(result) for result in results],
+                "app_id": app_id_value,
+                "session_id": normalized_session_id,
+                "query": query_text,
+                "limit": resolved_limit,
+            }
+        )
+
+    app.include_router(api)
+
+    @app.get("/")
+    def root() -> dict[str, Any]:
+        return {
+            "service": "mash-api",
+            "api": {
+                "version": "v1",
+                "base": resolved_config.api_prefix,
+                "openapi": "/openapi.json",
+                "docs": "/docs",
+            },
+        }
+
+    return app
+
+
+def run_app(
+    definition: MashRuntimeDefinition,
+    *,
+    subagents: Sequence[SubagentRegistration] | None = None,
+    config: MashAPIConfig | None = None,
+) -> None:
+    """Run mash-api service with uvicorn."""
+    resolved_config = config or MashAPIConfig()
+    app = create_app(definition, subagents=subagents, config=resolved_config)
+    uvicorn.run(app, host=resolved_config.bind_host, port=resolved_config.bind_port)

mash_api-0.1.0/src/mash_api/config.py

@@ -0,0 +1,53 @@
+"""Configuration types for mash-api."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Sequence
+
+_DEFAULT_CORS_ORIGINS = (
+    "http://127.0.0.1:3000",
+    "http://localhost:3000",
+    "http://127.0.0.1:5173",
+    "http://localhost:5173",
+)
+
+
+@dataclass
+class MashAPIConfig:
+    """Runtime configuration for mash-api server composition."""
+
+    api_prefix: str = "/api/v1"
+    bind_host: str = "127.0.0.1"
+    bind_port: int = 8000
+    runtime_bind_host: str = "127.0.0.1"
+    api_key: Optional[str] = None
+    cors_allow_origins: Sequence[str] = field(default_factory=lambda: _DEFAULT_CORS_ORIGINS)
+    enable_observability: bool = True
+    observability_log_path: Optional[Path] = None
+    observability_memory_db_path: Optional[Path] = None
+    default_events_limit: int = 2000
+    default_search_limit: int = 10
+
+    def resolved_api_key(self) -> Optional[str]:
+        value = (self.api_key or "").strip()
+        return value or None
+
+    def resolved_cors_origins(self) -> list[str]:
+        values: list[str] = []
+        for origin in self.cors_allow_origins:
+            text = str(origin).strip()
+            if text:
+                values.append(text)
+        return values
+
+    def resolved_log_path(self) -> Optional[Path]:
+        if self.observability_log_path is None:
+            return None
+        return Path(self.observability_log_path).expanduser().resolve()
+
+    def resolved_memory_db_path(self) -> Optional[Path]:
+        if self.observability_memory_db_path is None:
+            return None
+        return Path(self.observability_memory_db_path).expanduser().resolve()

mash_api-0.1.0/src/mash_api/main.py

@@ -0,0 +1,114 @@
+"""CLI entrypoint for mash-api package."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+from typing import Any, Sequence
+
+import uvicorn
+
+from mash.runtime import MashRuntimeDefinition
+
+from .app import create_app
+from .config import MashAPIConfig
+from .types import MashAPIAppSpec
+
+
+def _load_target(app_ref: str) -> Any:
+    module_name, sep, attr_name = app_ref.partition(":")
+    if not sep or not module_name.strip() or not attr_name.strip():
+        raise ValueError("--app must be in 'module:attribute' format")
+
+    module = importlib.import_module(module_name)
+    if not hasattr(module, attr_name):
+        raise ValueError(f"module '{module_name}' has no attribute '{attr_name}'")
+    return getattr(module, attr_name)
+
+
+def _resolve_spec(app_ref: str) -> MashAPIAppSpec:
+    target = _load_target(app_ref)
+    resolved = target() if callable(target) else target
+
+    if isinstance(resolved, MashAPIAppSpec):
+        return resolved
+    if isinstance(resolved, MashRuntimeDefinition):
+        return MashAPIAppSpec(definition=resolved)
+
+    raise ValueError(
+        "app target must resolve to MashRuntimeDefinition or MashAPIAppSpec"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run mash-api server")
+    parser.add_argument(
+        "--app",
+        required=True,
+        help="Application reference in module:attribute format.",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="API bind host")
+    parser.add_argument("--port", type=int, default=8000, help="API bind port")
+    parser.add_argument(
+        "--runtime-bind-host",
+        default="127.0.0.1",
+        help="Internal mash runtime bind host",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="Optional API key (or set MASH_API_KEY)",
+    )
+    parser.add_argument(
+        "--cors-origin",
+        action="append",
+        default=None,
+        help="Allowed CORS origin; repeat for multiple values.",
+    )
+    parser.add_argument("--log-path", default=None, help="Observability log path")
+    parser.add_argument(
+        "--memory-db",
+        default=None,
+        help="Optional SQLite path for /telemetry/memory/search",
+    )
+    parser.add_argument(
+        "--disable-observability",
+        action="store_true",
+        help="Disable telemetry endpoints.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    spec = _resolve_spec(args.app)
+
+    api_key = args.api_key
+    if api_key is None:
+        api_key = os.environ.get("MASH_API_KEY")
+
+    config = MashAPIConfig(
+        bind_host=args.host,
+        bind_port=args.port,
+        runtime_bind_host=args.runtime_bind_host,
+        api_key=api_key,
+        cors_allow_origins=(
+            args.cors_origin
+            if args.cors_origin is not None
+            else MashAPIConfig().cors_allow_origins
+        ),
+        enable_observability=not args.disable_observability,
+        observability_log_path=args.log_path,
+        observability_memory_db_path=args.memory_db,
+    )
+
+    app = create_app(spec.definition, subagents=spec.subagents, config=config)
+    uvicorn.run(app, host=config.bind_host, port=config.bind_port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mash_api-0.1.0/src/mash_api/types.py

@@ -0,0 +1,25 @@
+"""Public types for mash-api app composition."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from mash.runtime import MashRuntimeDefinition, SubAgentMetadata
+
+
+@dataclass(frozen=True)
+class SubagentRegistration:
+    """Subagent registration payload for host-backed API composition."""
+
+    definition: MashRuntimeDefinition
+    metadata: SubAgentMetadata
+    agent_id: str | None = None
+
+
+@dataclass(frozen=True)
+class MashAPIAppSpec:
+    """Application spec used by mash-api CLI loading."""
+
+    definition: MashRuntimeDefinition
+    subagents: Sequence[SubagentRegistration] = ()

mash_api-0.1.0/src/mash_api.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: mash-api
+Version: 0.1.0
+Summary: OpenAPI service package for Mash applications
+Author: imsid
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mashpy>=0.1.2
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+
+# mash-api
+
+OpenAPI service package for self-hosted Mash applications.
+
+## Install
+
+```bash
+pip install mash-api
+# or
+pip install "mashpy[api]"
+```
+
+## Usage
+
+```python
+from mash_api import create_app
+from my_app import definition
+
+app = create_app(definition)
+```
+
+Run with Uvicorn:
+
+```bash
+uvicorn my_module:app --host 127.0.0.1 --port 8000
+```
+
+Or use the bundled CLI:
+
+```bash
+mash-api --app my_app:build_definition
+```

mash_api-0.1.0/src/mash_api.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/mash_api/__init__.py
+src/mash_api/app.py
+src/mash_api/config.py
+src/mash_api/main.py
+src/mash_api/types.py
+src/mash_api.egg-info/PKG-INFO
+src/mash_api.egg-info/SOURCES.txt
+src/mash_api.egg-info/dependency_links.txt
+src/mash_api.egg-info/entry_points.txt
+src/mash_api.egg-info/requires.txt
+src/mash_api.egg-info/top_level.txt

mash_api-0.1.0/src/mash_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mash_api-0.1.0/src/mash_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mash-api = mash_api.main:main

mash_api-0.1.0/src/mash_api.egg-info/requires.txt

@@ -0,0 +1,7 @@
+mashpy>=0.1.2
+fastapi>=0.115.0
+uvicorn>=0.30.0
+
+[dev]
+pytest>=8.3.0
+httpx>=0.27.0

mash_api-0.1.0/src/mash_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+mash_api