mh-service-kit 0.1.0__tar.gz

mh_service_kit-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: mh-service-kit
+Version: 0.1.0
+Summary: SDK for building standalone agent & tool services in the minimal-harness ecosystem
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: minimal-harness>=0.6.2
+Requires-Python: >=3.12

mh_service_kit-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mh-service-kit"
+version = "0.1.0"
+description = "SDK for building standalone agent & tool services in the minimal-harness ecosystem"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+    "minimal-harness>=0.6.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.12"]
+build-backend = "uv_build"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+minimal-harness = { workspace = true }

mh_service_kit-0.1.0/src/mh_service_kit/__init__.py

@@ -0,0 +1,14 @@
+from minimal_harness.types import ToolResult
+
+from mh_service_kit.app import ServiceApp
+from mh_service_kit.context import ToolContext
+from mh_service_kit.m2m_auth import M2MAuthProvider
+from mh_service_kit.models import parameters_from_model
+
+__all__ = [
+    "M2MAuthProvider",
+    "ServiceApp",
+    "ToolContext",
+    "ToolResult",
+    "parameters_from_model",
+]

mh_service_kit-0.1.0/src/mh_service_kit/app.py

@@ -0,0 +1,419 @@
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any, Callable
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse, StreamingResponse
+from minimal_harness.client.logging_setup import setup_service_logging
+from minimal_harness.types import ToolResult
+from openai import AsyncOpenAI
+from pydantic import BaseModel
+
+from mh_service_kit.context import ToolContext
+from mh_service_kit.llm import get_runner
+from mh_service_kit.llm import reset as reset_llm
+from mh_service_kit.locale import parse_locale, resolve_locale
+from mh_service_kit.models import (
+    AgentRunRequest,
+    ToolExecuteRequest,
+    parameters_from_model,
+    validate_args,
+)
+from mh_service_kit.playground import PLAYGROUND_HTML
+from mh_service_kit.m2m_auth import M2MAuthProvider, _DefaultM2MAuthProvider
+from mh_service_kit.sse import sse_line
+
+logger = logging.getLogger(__name__)
+
+
+class ServiceApp:
+    def __init__(
+        self,
+        *,
+        title: str = "Agent & Tool Service",
+        version: str = "0.1.0",
+        cors_origins: list[str] | None = None,
+        default_locale: str = "zh",
+        dev_mode: bool = True,
+        llm_client: AsyncOpenAI | None = None,
+        runner: Any | None = None,
+        llm_api_key: str = "",
+        llm_base_url: str = "",
+        m2m_auth_provider: M2MAuthProvider | None = None,
+    ):
+        self._title = title
+        self._version = version
+        self._cors_origins = cors_origins or ["http://localhost:5173"]
+        self._default_locale = default_locale
+        self._dev_mode = dev_mode
+        self._llm_client = llm_client
+        self._runner = runner
+        self._llm_api_key = llm_api_key
+        self._llm_base_url = llm_base_url
+        self._m2m_auth_provider = m2m_auth_provider
+
+        self._agents: dict[str, dict[str, Any]] = {}
+        self._tools: dict[str, dict[str, Any]] = {}
+        self._handlers: dict[str, Callable] = {}
+        self._params_models: dict[str, type[BaseModel] | None] = {}
+
+    # ── Agent registration ──────────────────────────────────────────
+
+    def add_agent(
+        self,
+        *,
+        name: str,
+        display_name: str = "",
+        description: str = "",
+        system_prompt: str = "",
+        display_name_locale: dict[str, str] | None = None,
+        description_locale: dict[str, str] | None = None,
+        system_prompt_locale: dict[str, str] | None = None,
+    ) -> None:
+        self._agents[name] = {
+            "name": name,
+            "display_name": display_name or name,
+            "display_name_locale": display_name_locale,
+            "description": description,
+            "description_locale": description_locale,
+            "system_prompt": system_prompt,
+            "system_prompt_locale": system_prompt_locale,
+        }
+
+    # ── Tool registration ───────────────────────────────────────────
+
+    def add_tool(
+        self,
+        *,
+        name: str,
+        display_name: str = "",
+        description: str = "",
+        parameters: dict | None = None,
+        params_model: type[BaseModel] | None = None,
+        handler: Callable[[dict], str]
+        | Callable[[dict], AsyncGenerator[str, None]]
+        | None = None,
+        display_name_locale: dict[str, str] | None = None,
+        description_locale: dict[str, str] | None = None,
+    ) -> None:
+        if params_model is not None:
+            resolved_params: dict = parameters_from_model(params_model)
+        else:
+            resolved_params = parameters or {}
+
+        self._tools[name] = {
+            "name": name,
+            "display_name": display_name or name,
+            "display_name_locale": display_name_locale,
+            "description": description,
+            "description_locale": description_locale,
+            "parameters": resolved_params,
+        }
+        self._params_models[name] = params_model
+        if handler:
+            self._handlers[name] = handler
+
+    # ── LLM helpers ─────────────────────────────────────────────────
+
+    def _resolve_runner(self) -> Any:
+        if self._runner is not None:
+            return self._runner
+        client = self._llm_client
+        if client is None:
+            client = self._get_default_client()
+        return get_runner(llm_client=client)
+
+    def _get_default_client(self) -> AsyncOpenAI:
+        from os import environ
+
+        api_key = self._llm_api_key or environ.get("MH_API_KEY", "")
+        base_url = self._llm_base_url or "https://aihubmix.com/v1"
+        return AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+    def reset_llm_singletons(self) -> None:
+        reset_llm()
+
+    # ── Build FastAPI app ───────────────────────────────────────────
+
+    def build(self) -> FastAPI:
+        app = FastAPI(title=self._title, version=self._version)
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=self._cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        if self._dev_mode:
+
+            @app.get("/playground", include_in_schema=False)
+            async def playground():
+                return HTMLResponse(PLAYGROUND_HTML)
+
+        agents = self._agents
+        tools = self._tools
+        handlers = self._handlers
+        resolve = resolve_locale
+        default_locale = self._default_locale
+        resolve_runner = self._resolve_runner
+        m2m_provider = self._m2m_auth_provider or _DefaultM2MAuthProvider()
+
+        async def verify_m2m(request: Request) -> str:
+            app_id = await m2m_provider.authenticate(request)
+            if app_id is None:
+                raise HTTPException(
+                    status_code=401, detail="M2M authentication required"
+                )
+            return app_id
+
+        # ── GET /agents ─────────────────────────────────────────────
+
+        @app.get("/agents")
+        async def list_agents(
+            accept_language: str | None = Header(None, alias="Accept-Language"),
+        ):
+            locale = parse_locale(accept_language) or default_locale
+            result = [
+                {
+                    "name": cfg["name"],
+                    "display_name": resolve(
+                        cfg["display_name"], cfg.get("display_name_locale"), locale
+                    ),
+                    "description": resolve(
+                        cfg["description"], cfg.get("description_locale"), locale
+                    ),
+                }
+                for cfg in agents.values()
+            ]
+            logger.debug(
+                "OUTBOUND GET /agents — locale=%s returned=%d",
+                locale,
+                len(result),
+            )
+            return result
+
+        # ── GET /tools ──────────────────────────────────────────────
+
+        @app.get("/tools")
+        async def list_tools(
+            accept_language: str | None = Header(None, alias="Accept-Language"),
+        ):
+            locale = parse_locale(accept_language) or default_locale
+            result = [
+                {
+                    **t,
+                    "display_name": resolve(
+                        t["display_name"], t.get("display_name_locale"), locale
+                    ),
+                    "description": resolve(
+                        t["description"], t.get("description_locale"), locale
+                    ),
+                }
+                for t in tools.values()
+            ]
+            logger.debug(
+                "OUTBOUND GET /tools — locale=%s returned=%d",
+                locale,
+                len(result),
+            )
+            return result
+
+        # ── POST /agent/{agent_name}/run ────────────────────────────
+
+        @app.post("/agent/{agent_name}/run")
+        async def run_agent(
+            agent_name: str,
+            body: AgentRunRequest,
+            _app_id: str = Depends(verify_m2m),
+            accept_language: str | None = Header(None, alias="Accept-Language"),
+        ):
+            logger.debug(
+                "INBOUND POST /agent/%s/run — user_input_count=%d tools_count=%d memory_count=%d locale=%s",
+                agent_name,
+                len(body.user_input),
+                len(body.tools),
+                len(body.memory),
+                accept_language,
+            )
+            agent = agents.get(agent_name)
+            if agent is None:
+                logger.warning("agent not found: %s", agent_name)
+                raise HTTPException(
+                    status_code=404, detail=f"Agent {agent_name} not found"
+                )
+
+            locale = parse_locale(accept_language) or default_locale
+            system_prompt = body.system_prompt or resolve(
+                agent["system_prompt"], agent.get("system_prompt_locale"), locale
+            )
+
+            runner = resolve_runner()
+
+            async def event_stream():
+                event_count = 0
+                async for line in runner.run(
+                    user_input=body.user_input,
+                    tools_schema=body.tools,
+                    memory_messages=body.memory,
+                    system_prompt=system_prompt,
+                    config=body.config,
+                ):
+                    event_count += 1
+                    logger.debug(
+                        "OUTBOUND /agent/%s/run event — event_count=%d line_preview=%r",
+                        agent_name,
+                        event_count,
+                        line[:120] if isinstance(line, str) else line,
+                    )
+                    yield line
+                logger.debug(
+                    "OUTBOUND /agent/%s/run complete — total_events=%d",
+                    agent_name,
+                    event_count,
+                )
+
+            return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+        # ── POST /tools/{tool_name}/execute ─────────────────────────
+
+        @app.post("/tools/{tool_name}/execute")
+        async def execute_tool(
+            tool_name: str,
+            body: ToolExecuteRequest,
+            request: Request,
+            _app_id: str = Depends(verify_m2m),
+        ):
+            logger.debug(
+                "INBOUND POST /tools/%s/execute — args_keys=%s",
+                tool_name,
+                list(body.args.keys()) if isinstance(body.args, dict) else [],
+            )
+            handler = handlers.get(tool_name)
+            if handler is None:
+                logger.warning("tool not found: %s", tool_name)
+
+                async def error_stream():
+                    yield sse_line("tool_end", f"Tool {tool_name} not found")
+
+                return StreamingResponse(error_stream(), media_type="text/event-stream")
+
+            params_model = self._params_models.get(tool_name)
+            tool_config = tools.get(tool_name, {})
+            validated, error = validate_args(
+                body.args, tool_config.get("parameters"), params_model
+            )
+            if error is not None:
+                logger.warning(
+                    "tool arg validation failed: tool=%s error=%s", tool_name, error
+                )
+
+                async def validation_error_stream():
+                    yield sse_line("tool_end", f"Validation error: {error}")
+
+                return StreamingResponse(
+                    validation_error_stream(), media_type="text/event-stream"
+                )
+
+            context = ToolContext(
+                headers={k.lower(): v for k, v in request.headers.items()},
+            )
+            needs_context = "context" in inspect.signature(handler).parameters
+
+            async def event_stream():
+                try:
+                    if inspect.isasyncgenfunction(handler):
+                        final_result = ""
+                        gen = (
+                            handler(validated, context=context)
+                            if needs_context
+                            else handler(validated)
+                        )
+                        async for chunk in gen:
+                            logger.debug(
+                                "OUTBOUND /tools/%s/tool_progress — chunk_type=%s chunk_preview=%r",
+                                tool_name,
+                                type(chunk).__name__,
+                                str(chunk)[:80],
+                            )
+                            yield sse_line("tool_progress", chunk)
+                            final_result = chunk
+                        result = final_result
+                    elif inspect.iscoroutinefunction(handler):
+                        result = (
+                            await handler(validated, context=context)
+                            if needs_context
+                            else await handler(validated)
+                        )
+                        logger.debug(
+                            "OUTBOUND /tools/%s/tool_progress — result_type=%s result_preview=%r",
+                            tool_name,
+                            type(result).__name__,
+                            str(result)[:80],
+                        )
+                        yield sse_line("tool_progress", result)
+                    else:
+                        result = (
+                            handler(validated, context=context)
+                            if needs_context
+                            else handler(validated)
+                        )
+                        logger.debug(
+                            "OUTBOUND /tools/%s/tool_progress — result_type=%s result_preview=%r",
+                            tool_name,
+                            type(result).__name__,
+                            str(result)[:80],
+                        )
+                        yield sse_line("tool_progress", result)
+
+                    logger.debug(
+                        "OUTBOUND /tools/%s/tool_end — result_preview=%r",
+                        tool_name,
+                        str(result)[:120],
+                    )
+                    if isinstance(result, ToolResult):
+                        yield sse_line(
+                            "tool_end",
+                            {
+                                "content": result.content,
+                                "__meta": result.meta,
+                                "__stop": result.stop,
+                            },
+                        )
+                    else:
+                        yield sse_line("tool_end", result)
+                except Exception as e:
+                    logger.exception(
+                        "Tool %s execution failed — error=%s",
+                        tool_name,
+                        e,
+                    )
+                    yield sse_line(
+                        "error",
+                        {"message": f"Tool execution failed: {e}"},
+                    )
+                    yield sse_line(
+                        "tool_end",
+                        {
+                            "tool_call": {"id": body.tool_call_id},
+                            "result": f"Error: {e}",
+                        },
+                    )
+
+            return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+        return app
+
+    # ── Run server ──────────────────────────────────────────────────
+
+    def run(self, host: str = "0.0.0.0", port: int = 8003) -> None:
+        import uvicorn
+
+        setup_service_logging()
+        logger.info("starting service — host=%s port=%d", host, port)
+        app = self.build()
+        uvicorn.run(app, host=host, port=port)

mh_service_kit-0.1.0/src/mh_service_kit/context.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToolContext:
+    """HTTP request context passed to tool handlers that declare a ``context`` parameter.
+
+    Carries the full original request headers (keys lowercased) so tool
+    implementations can extract whatever HTTP-level information they need
+    — cookies, auth tokens, custom headers, etc. — without the framework
+    having to predict every need.
+    """
+
+    headers: dict[str, str] = field(default_factory=dict)

mh_service_kit-0.1.0/src/mh_service_kit/llm.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+from minimal_harness.agent.runner import SSEAgentRunner
+
+_client: AsyncOpenAI | None = None
+_runner: SSEAgentRunner | None = None
+
+
+def get_client(api_key: str = "", base_url: str = "") -> AsyncOpenAI:
+    global _client
+    if _client is None:
+        _client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+    return _client
+
+
+def get_runner(llm_client: AsyncOpenAI | None = None) -> SSEAgentRunner:
+    global _runner
+    if _runner is None:
+        _runner = SSEAgentRunner(llm_client=llm_client)
+    return _runner
+
+
+def reset() -> None:
+    global _client, _runner
+    _client = None
+    _runner = None

mh_service_kit-0.1.0/src/mh_service_kit/locale.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+
+def parse_locale(accept_language: str | None = None) -> str:
+    if accept_language:
+        lang = accept_language.split(",")[0].split(";")[0].strip().lower()
+        if lang in ("zh", "en"):
+            return lang
+    return "zh"
+
+
+def resolve_locale(
+    value: str,
+    value_locale: dict[str, str] | None,
+    locale: str,
+) -> str:
+    if locale and value_locale and locale in value_locale:
+        return value_locale[locale]
+    return value

mh_service_kit-0.1.0/src/mh_service_kit/m2m_auth.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class M2MAuthProvider(Protocol):
+    """机机接口鉴权提供者。
+
+    在 agent 调用端点（``POST /agent/{name}/run``）和
+    tool 执行端点（``POST /tools/{name}/execute``）被调用时
+    验证调用方身份。
+
+    客户企业部署时实现此 protocol，通过 SOA、API Key、mTLS
+    或其他机制验证调用方应用身份。接收原始 ``Request`` 对象，
+    可自行决定检查方式（header、cookie、mTLS 证书等）。
+
+    返回 ``app_id`` 表示鉴权通过，返回 ``None`` 表示失败（返回 401）。
+    """
+
+    async def authenticate(self, request: Any) -> str | None:
+        """验证机机调用方身份。
+
+        Args:
+            request: 当前 FastAPI Request 对象。
+
+        Returns:
+            app_id 表示鉴权通过，``None`` 表示鉴权失败（调用方返回 401）。
+        """
+        ...
+
+    async def close(self) -> None:
+        """释放资源（连接池、文件句柄等）。"""
+        ...
+
+
+class _DefaultM2MAuthProvider:
+    """默认实现——不做判断，仅记录请求信息。
+
+    不执行任何鉴权校验，一律放行。仅以 INFO 级别打印请求的
+    method、path 和关键 header，方便开发阶段观察流量。
+
+    生产环境必须替换为实际的 M2M 鉴权实现（如 SOA、API Key
+    签名校验）。
+    """
+
+    async def close(self) -> None:
+        pass
+
+    async def authenticate(self, request: Any) -> str | None:
+        logger.info(
+            "M2M request — method=%s path=%s headers=%s",
+            request.method,
+            request.url.path,
+            dict(request.headers),
+        )
+        return "anonymous"

mh_service_kit-0.1.0/src/mh_service_kit/models.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class AgentRunRequest(BaseModel):
+    user_input: list[dict] = []
+    tools: list[dict] = []
+    memory: list[dict] = []
+    system_prompt: str = ""
+    config: dict = {}
+
+
+class ToolExecuteRequest(BaseModel):
+    args: dict = {}
+    tool_call_id: str = ""
+
+
+def parameters_from_model(model: type[BaseModel]) -> dict[str, Any]:
+    """Convert a Pydantic BaseModel to an OpenAI-compatible tool parameters JSON Schema dict.
+
+    Example:
+        >>> from pydantic import BaseModel, Field
+        >>> class CalcParams(BaseModel):
+        ...     expression: str = Field(description="Math expression")
+        >>> parameters_from_model(CalcParams)
+        {'type': 'object', 'properties': {'expression': {'type': 'string', 'description': 'Math expression', 'title': 'Expression'}}, 'required': ['expression']}
+    """
+    schema = model.model_json_schema()
+    return {
+        "type": "object",
+        "properties": schema.get("properties", {}),
+        "required": schema.get("required", []),
+    }
+
+
+def validate_args(
+    args: dict[str, Any],
+    parameters: dict[str, Any] | None,
+    params_model: type[BaseModel] | None,
+) -> tuple[dict[str, Any] | None, str | None]:
+    """Validate tool arguments against the declared schema.
+
+    Returns (validated_args, error_message). If valid, validated_args is the
+    cleaned/coerced dict and error_message is None. Otherwise validated_args
+    is None and error_message describes the problem.
+    """
+    if params_model is not None:
+        try:
+            instance = params_model.model_validate(args)
+            return instance.model_dump(mode="python"), None
+        except Exception as e:
+            return None, str(e)
+
+    if parameters:
+        required = parameters.get("required", [])
+        props = parameters.get("properties", {})
+
+        missing = [f for f in required if f not in args]
+        if missing:
+            return None, f"Missing required parameters: {', '.join(missing)}"
+
+        for key, value in args.items():
+            prop = props.get(key, {})
+            enum_vals = prop.get("enum")
+            if enum_vals is not None and value not in enum_vals:
+                return (
+                    None,
+                    f"Parameter '{key}' must be one of: {', '.join(str(v) for v in enum_vals)}",
+                )
+
+    return args, None

mh_service_kit-0.1.0/src/mh_service_kit/playground.py

@@ -0,0 +1,353 @@
+PLAYGROUND_HTML = r"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Developer Playground</title>
+<style>
+  *,*::before,*::after{box-sizing:border-box;margin:0;padding:0}
+  body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,sans-serif;background:#f5f5f7;color:#1d1d1f;padding:24px;min-height:100vh}
+  .container{max-width:960px;margin:0 auto}
+  h1{font-size:22px;font-weight:600;margin-bottom:4px}
+  .sub{color:#86868b;font-size:13px;margin-bottom:24px}
+  .card{background:#fff;border-radius:12px;padding:20px;margin-bottom:16px;box-shadow:0 1px 3px rgba(0,0,0,.08)}
+  .card-title{font-size:14px;font-weight:600;margin-bottom:12px;color:#555}
+  .row{display:flex;gap:12px;flex-wrap:wrap;align-items:end}
+  .col{flex:1;min-width:180px}
+  label{display:block;font-size:12px;font-weight:500;color:#555;margin-bottom:4px}
+  select,input[type=text],textarea{width:100%;padding:8px 10px;border:1px solid #d2d2d7;border-radius:8px;font-size:13px;background:#fff;outline:none;transition:border-color .15s}
+  select:focus,input:focus,textarea:focus{border-color:#0071e3}
+  textarea{font-family:ui-monospace,"SF Mono",Menlo,Consolas,monospace;font-size:12px;resize:vertical;min-height:38px}
+  .btn{padding:8px 20px;border:none;border-radius:8px;font-size:13px;font-weight:500;cursor:pointer;transition:opacity .15s;display:inline-flex;align-items:center;gap:6px}
+  .btn-primary{background:#0071e3;color:#fff}
+  .btn-primary:hover{opacity:.85}
+  .btn-primary:disabled{opacity:.4;cursor:not-allowed}
+  .btn-danger{background:#ff3b30;color:#fff}
+  .btn-danger:hover{opacity:.85}
+  .params-area{margin-top:12px}
+  .param-row{margin-bottom:8px}
+  .param-row label{font-size:12px;font-weight:500;color:#555;margin-bottom:2px}
+  .param-row .param-type{font-size:11px;color:#86868b;margin-left:6px;font-weight:400}
+  .param-row .param-desc{font-size:11px;color:#86868b;margin-top:1px}
+  .tabs{display:flex;gap:0;margin-bottom:16px;border-bottom:1px solid #d2d2d7}
+  .tab{padding:8px 20px;font-size:13px;cursor:pointer;border:none;background:none;color:#86868b;border-bottom:2px solid transparent;transition:all .15s}
+  .tab.active{color:#0071e3;border-bottom-color:#0071e3;font-weight:600}
+  .tab:hover{color:#1d1d1f}
+  .toolbar{display:flex;gap:8px;align-items:center;flex-wrap:wrap;margin-bottom:12px}
+  .toolbar .status-badge{padding:2px 10px;border-radius:12px;font-size:11px;font-weight:500;background:#e8e8ed;color:#555}
+  .toolbar .status-badge.running{background:#0071e3;color:#fff}
+  .toolbar .status-badge.done{background:#30d158;color:#fff}
+  .toolbar .status-badge.error{background:#ff3b30;color:#fff}
+  .output-area{background:#1d1d1f;border-radius:10px;padding:16px;font-family:ui-monospace,"SF Mono",Menlo,Consolas,monospace;font-size:12px;line-height:1.6;color:#e8e8ed;max-height:500px;overflow:auto;white-space:pre-wrap;word-break:break-all;position:relative}
+  .output-area .line{padding:1px 0;display:flex}
+  .output-area .line .tag{flex:0 0 85px;padding:0 6px;border-radius:4px;font-size:11px;font-weight:500;text-align:center;margin-right:8px}
+  .tag-start{background:#5e5ce6;color:#fff}
+  .tag-progress{background:#0071e3;color:#fff}
+  .tag-end{background:#30d158;color:#1d1d1f}
+  .tag-error{background:#ff3b30;color:#fff}
+  .tag-llm{background:#ff9f0a;color:#1d1d1f}
+  .tag-info{background:#48484a;color:#e8e8ed}
+  .output-placeholder{color:#48484a;font-style:italic}
+  .hidden{display:none !important}
+  .clear-btn{position:absolute;top:8px;right:8px;background:#48484a;border:none;color:#e8e8ed;font-size:11px;padding:4px 10px;border-radius:6px;cursor:pointer;opacity:.6;transition:opacity .15s}
+  .clear-btn:hover{opacity:1}
+</style>
+</head>
+<body>
+<div class="container">
+  <h1>🛠️ Developer Playground</h1>
+  <p class="sub">Invoke tools and agents, observe SSE events in real-time</p>
+
+  <div class="card">
+    <div class="tabs">
+      <button class="tab active" data-tab="tool" onclick="switchTab('tool')">Tool</button>
+      <button class="tab" data-tab="agent" onclick="switchTab('agent')">Agent</button>
+    </div>
+
+    <div id="panel-tool">
+      <div class="row">
+        <div class="col">
+          <label>Tool</label>
+          <select id="tool-select" onchange="onToolChange()"><option value="">— select —</option></select>
+        </div>
+      </div>
+      <div class="params-area" id="tool-params"></div>
+    </div>
+
+    <div id="panel-agent" class="hidden">
+      <div class="row">
+        <div class="col">
+          <label>Agent</label>
+          <select id="agent-select" onchange="onAgentChange()"><option value="">— select —</option></select>
+        </div>
+      </div>
+      <div class="params-area" id="agent-params"></div>
+    </div>
+
+    <div class="toolbar" style="margin-top:16px">
+      <button class="btn btn-primary" id="invoke-btn" onclick="invoke()">▶ Invoke</button>
+      <button class="btn btn-danger hidden" id="cancel-btn" onclick="cancelInvoke()">■ Cancel</button>
+      <span class="status-badge hidden" id="status-badge">Idle</span>
+    </div>
+  </div>
+
+  <div class="card" style="position:relative">
+    <div class="card-title">Output (SSE Stream)</div>
+    <div class="output-area" id="output"><span class="output-placeholder">Select an endpoint and click Invoke to see results…</span></div>
+    <button class="clear-btn" onclick="clearOutput()">✕ Clear</button>
+  </div>
+</div>
+
+<script>
+let currentAbort = null;
+let allTools = [];
+let allAgents = [];
+
+async function init() {
+  try {
+    const [tools, agents] = await Promise.all([
+      fetch('/tools').then(r => r.json()),
+      fetch('/agents').then(r => r.json()),
+    ]);
+    allTools = tools;
+    allAgents = agents;
+
+    const toolSel = document.getElementById('tool-select');
+    toolSel.innerHTML = '<option value="">— select —</option>' + tools.map(t =>
+      `<option value="${t.name}">${t.display_name}</option>`
+    ).join('');
+
+    const agentSel = document.getElementById('agent-select');
+    agentSel.innerHTML = '<option value="">— select —</option>' + agents.map(a =>
+      `<option value="${a.name}">${a.display_name}</option>`
+    ).join('');
+
+    const params = new URLSearchParams(location.search);
+    if (params.get('tab') === 'agent') switchTab('agent');
+    if (params.get('tool')) { toolSel.value = params.get('tool'); onToolChange(); }
+    if (params.get('agent')) { agentSel.value = params.get('agent'); switchTab('agent'); onAgentChange(); }
+  } catch(e) {
+    appendLine('error', 'Failed to load tools/agents: ' + e.message);
+  }
+}
+
+function switchTab(tab) {
+  document.querySelectorAll('.tab').forEach(t => t.classList.toggle('active', t.dataset.tab === tab));
+  document.getElementById('panel-tool').classList.toggle('hidden', tab !== 'tool');
+  document.getElementById('panel-agent').classList.toggle('hidden', tab !== 'agent');
+}
+
+function onToolChange() {
+  const sel = document.getElementById('tool-select');
+  const tool = allTools.find(t => t.name === sel.value);
+  renderParams('tool-params', tool ? tool.parameters : null);
+}
+
+function onAgentChange() {
+  const sel = document.getElementById('agent-select');
+  const agent = allAgents.find(a => a.name === sel.value);
+  const area = document.getElementById('agent-params');
+  if (!agent) { area.innerHTML = ''; return; }
+  area.innerHTML = `
+    <div class="param-row">
+      <label>User Input <span class="param-type">string</span></label>
+      <textarea rows="3" id="agent-text" placeholder="Enter your message for the agent...">${agent.description ? 'Tell me about ' + agent.name : 'Hello'}</textarea>
+    </div>
+    <div class="param-row">
+      <label>System Prompt (optional) <span class="param-type">string</span></label>
+      <textarea rows="2" id="agent-system-prompt" placeholder="Leave empty to use default"></textarea>
+    </div>
+  `;
+}
+
+function renderParams(containerId, params) {
+  const area = document.getElementById(containerId);
+  if (!params || !params.properties) { area.innerHTML = ''; return; }
+  const required = new Set(params.required || []);
+  area.innerHTML = Object.entries(params.properties).map(([key, prop]) => {
+    const isObj = prop.type === 'object' || prop.type === 'array'
+      || (prop.anyOf && prop.anyOf.some(s => s.type === 'object' || s.type === 'array'))
+      || prop.additionalProperties !== undefined;
+    const isEnum = prop.enum && prop.enum.length > 0;
+    const req = required.has(key) ? ' *' : '';
+    const desc = prop.description ? `<div class="param-desc">${prop.description}</div>` : '';
+    const typeInfo = (prop.enum ? prop.enum.join(' | ') : prop.type)
+      || (isObj ? 'object' : 'string');
+
+    let input = '';
+    if (isObj) {
+      const isArray = prop.type === 'array'
+        || (prop.anyOf && prop.anyOf.some(s => s.type === 'array'));
+      input = `<textarea rows="3" id="param-${key}" placeholder='${isArray ? '["item1","item2"]' : '{"key":"value"}'}'>${prop.default ? JSON.stringify(prop.default, null, 2) : ''}</textarea>`;
+    } else if (isEnum) {
+      const opts = prop.enum.map(v => `<option value="${v}"${prop.default === v ? ' selected' : ''}>${v}</option>`).join('');
+      input = `<select id="param-${key}"><option value="">— select —</option>${opts}</select>`;
+    } else {
+      input = `<input type="text" id="param-${key}" placeholder="${prop.type || 'value'}" value="${prop.default || ''}">`;
+    }
+
+    return `<div class="param-row">
+      <label>${key}${req} <span class="param-type">${typeInfo}</span></label>
+      ${input}
+      ${desc}
+    </div>`;
+  }).join('');
+}
+
+function collectParams(containerId) {
+  const area = document.getElementById(containerId);
+  const inputs = area.querySelectorAll('[id^="param-"]');
+  const args = {};
+  inputs.forEach(el => {
+    const key = el.id.replace('param-', '');
+    let val = el.value;
+    if (el.tagName === 'TEXTAREA') {
+      try { val = JSON.parse(val); } catch(e) {}
+    }
+    args[key] = val;
+  });
+  return args;
+}
+
+function isActiveTab(tab) {
+  return document.querySelector('.tab.active').dataset.tab === tab;
+}
+
+function getActiveEndpoint() {
+  if (isActiveTab('tool')) {
+    const sel = document.getElementById('tool-select');
+    return sel.value ? { type: 'tool', name: sel.value } : null;
+  }
+  const sel = document.getElementById('agent-select');
+  return sel.value ? { type: 'agent', name: sel.value } : null;
+}
+
+async function invoke() {
+  const ep = getActiveEndpoint();
+  if (!ep) { appendLine('error', 'Please select an endpoint first'); return; }
+
+  clearOutput();
+  setRunning(true);
+
+  let url, body;
+  if (ep.type === 'tool') {
+    url = '/tools/' + encodeURIComponent(ep.name) + '/execute';
+    body = { args: collectParams('tool-params') };
+  } else {
+    url = '/agent/' + encodeURIComponent(ep.name) + '/run';
+    const text = document.getElementById('agent-text')?.value || '';
+    const sysPrompt = document.getElementById('agent-system-prompt')?.value || '';
+    body = { user_input: [{ type: 'text', text }] };
+    if (sysPrompt) body.system_prompt = sysPrompt;
+  }
+
+  currentAbort = new AbortController();
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: currentAbort.signal,
+    });
+
+    if (!resp.ok) {
+      appendLine('error', `HTTP ${resp.status}: ${resp.statusText}`);
+      setRunning(false, 'error');
+      return;
+    }
+
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            const evt = JSON.parse(line.slice(6));
+            appendEvent(evt);
+          } catch { /* skip malformed */ }
+        }
+      }
+    }
+    setRunning(false, 'done');
+  } catch (e) {
+    if (e.name === 'AbortError') {
+      appendLine('info', '— Cancelled —');
+    } else {
+      appendLine('error', 'Error: ' + e.message);
+    }
+    setRunning(false, 'error');
+  }
+  currentAbort = null;
+}
+
+function cancelInvoke() {
+  if (currentAbort) {
+    currentAbort.abort();
+    currentAbort = null;
+  }
+}
+
+function appendEvent(evt) {
+  const t = evt.type || '';
+  let tagClass = 'tag-info';
+  if (t === 'tool_start' || t === 'agent_start' || t === 'execution_start') tagClass = 'tag-start';
+  else if (t === 'tool_progress' || t === 'llm_chunk') tagClass = 'tag-progress';
+  else if (t === 'tool_end' || t === 'execution_end' || t === 'agent_end') tagClass = 'tag-end';
+  else if (t.includes('error') || t.includes('Error')) tagClass = 'tag-error';
+  else if (t.startsWith('llm_')) tagClass = 'tag-llm';
+
+  const content = JSON.stringify(evt, null, 2);
+  appendLine(tagClass, `<span class="tag ${tagClass}">${t}</span>${escapeHtml(content)}`);
+}
+
+function appendLine(tag, html) {
+  const out = document.getElementById('output');
+  const placeholder = out.querySelector('.output-placeholder');
+  if (placeholder) placeholder.remove();
+  const div = document.createElement('div');
+  div.className = 'line';
+  div.innerHTML = html;
+  out.appendChild(div);
+  out.scrollTop = out.scrollHeight;
+}
+
+function escapeHtml(s) {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+function clearOutput() {
+  document.getElementById('output').innerHTML = '<span class="output-placeholder">Select an endpoint and click Invoke to see results…</span>';
+}
+
+function setRunning(running, status) {
+  const btn = document.getElementById('invoke-btn');
+  const cancelBtn = document.getElementById('cancel-btn');
+  const badge = document.getElementById('status-badge');
+  btn.disabled = running;
+  btn.classList.toggle('hidden', running);
+  cancelBtn.classList.toggle('hidden', !running);
+  badge.classList.toggle('hidden', !running && !status);
+  badge.classList.remove('running', 'done', 'error');
+  if (running) {
+    badge.textContent = 'Running…';
+    badge.classList.add('running');
+  } else if (status) {
+    const labels = { done: 'Done', error: 'Error' };
+    badge.textContent = labels[status] || status;
+    badge.classList.add(status);
+  }
+}
+
+document.addEventListener('DOMContentLoaded', init);
+</script>
+</body>
+</html>"""

mh_service_kit-0.1.0/src/mh_service_kit/sse.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def sse_line(event: str, data: Any) -> str:
+    return f"data: {json.dumps({'type': event, 'data': data}, ensure_ascii=False, default=str)}\n\n"