ks-app-sdk 0.1.0__tar.gz

ks_app_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: ks-app-sdk
+Version: 0.1.0
+Summary: Keystone 平台 MCP Service SDK（Python）
+Author: Keystone Team
+License: MIT
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: starlette>=0.37
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+
+# ks-app-sdk
+
+Keystone MCP Service SDK for Python.
+
+## 安装
+
+pip install ks-app-sdk
+
+## 使用
+
+from ks_app import App
+
+app = App("my-app")
+
+@app.tool("greet", "打招呼")
+async def greet(name: str = "world"):
+    return {"message": f"Hello, {name}!"}
+
+app.run()  # 监听 0.0.0.0:8080
+
+## API
+
+### App(app_id: str)
+
+创建应用实例。
+
+### @app.tool(name: str, description: str)
+
+注册工具（装饰器）。handler 必须是 async 函数。
+
+### app.run()
+
+启动 uvicorn 服务器。
+
+## 端点
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| /healthz | GET | 存活探针 |
+| /readyz | GET | 就绪探针 |
+| /meta | GET | 应用元信息 + 工具列表 |
+| /mcp/tools/list | GET | 已注册工具列表 |
+| /mcp/tools/call | POST | 调用工具 |
+
+## 配置
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| KS_APP_PORT | 8080 | 监听端口 |
+| KS_APP_HOST | 0.0.0.0 | 监听地址 |

ks_app_sdk-0.1.0/README.md

@@ -0,0 +1,50 @@
+# ks-app-sdk
+
+Keystone MCP Service SDK for Python.
+
+## 安装
+
+pip install ks-app-sdk
+
+## 使用
+
+from ks_app import App
+
+app = App("my-app")
+
+@app.tool("greet", "打招呼")
+async def greet(name: str = "world"):
+    return {"message": f"Hello, {name}!"}
+
+app.run()  # 监听 0.0.0.0:8080
+
+## API
+
+### App(app_id: str)
+
+创建应用实例。
+
+### @app.tool(name: str, description: str)
+
+注册工具（装饰器）。handler 必须是 async 函数。
+
+### app.run()
+
+启动 uvicorn 服务器。
+
+## 端点
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| /healthz | GET | 存活探针 |
+| /readyz | GET | 就绪探针 |
+| /meta | GET | 应用元信息 + 工具列表 |
+| /mcp/tools/list | GET | 已注册工具列表 |
+| /mcp/tools/call | POST | 调用工具 |
+
+## 配置
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| KS_APP_PORT | 8080 | 监听端口 |
+| KS_APP_HOST | 0.0.0.0 | 监听地址 |

ks_app_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ks-app-sdk"
+version = "0.1.0"
+description = "Keystone 平台 MCP Service SDK（Python）"
+authors = [{name = "Keystone Team"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["uvicorn>=0.30", "starlette>=0.37", "pyyaml>=6.0"]
+classifiers = [
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "httpx>=0.27"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

ks_app_sdk-0.1.0/setup.cfg

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

ks_app_sdk-0.1.0/src/ks_app/__init__.py

@@ -0,0 +1,14 @@
+from .app import App
+from .context import ToolContext, get_context
+from .llm import ChatResponse, LLMClient
+from .tool import Param, tool
+
+__all__ = [
+    "App",
+    "tool",
+    "Param",
+    "get_context",
+    "ToolContext",
+    "LLMClient",
+    "ChatResponse",
+]

ks_app_sdk-0.1.0/src/ks_app/app.py

@@ -0,0 +1,111 @@
+import inspect
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+from .health import health_routes
+from .config import load_config
+from .llm import LLMClient
+from .mcp_handler import mcp_route
+
+
+class App:
+    def __init__(self, app_id: str):
+        self.app_id = app_id
+        self._tools: dict[str, dict] = {}
+        self._config = load_config()
+        self._llm = LLMClient()
+        self._health_checks: list[tuple[str, callable]] = []
+        self._middlewares: list = []
+        self._custom_routes: list[Route] = []
+
+    def llm(self) -> LLMClient:
+        """返回 Keystone LLM Relay 客户端（已在 __init__ 中预初始化）。
+
+        要求 manifest 中 llm_mode 为 keystone_relay，Keystone 会注入
+        KS_RELAY_TOKEN 环境变量。本地开发时开发者需自行设置 KS_RELAY_TOKEN。
+        """
+        return self._llm
+
+    def tool(self, name: str, description: str):
+        def decorator(func):
+            if not inspect.iscoroutinefunction(func):
+                raise TypeError(
+                    f"tool {name!r} 的 handler 必须是 async 函数，"
+                    f"收到的是同步函数 {func.__qualname__}"
+                )
+            if name in self._tools:
+                raise ValueError(f"tool {name!r} 已经注册过了，禁止重复注册")
+            self._tools[name] = {"handler": func, "description": description}
+            return func
+        return decorator
+
+    def handle(self, path: str, endpoint, methods: list[str] | None = None):
+        """注册自定义路由（如 REST API、WebSocket 等）。返回 self 支持链式调用。"""
+        self._custom_routes.append(Route(path, endpoint, methods=methods))
+        return self
+
+    def use(self, middleware_cls, **kwargs):
+        """注册 Starlette 中间件（类形式）。返回 self 支持链式调用。
+
+        用��: app.use(CORSMiddleware, allow_origins=["*"])
+        """
+        self._middlewares.append((middleware_cls, kwargs))
+        return self
+
+    def health_check(self, name: str, check_fn):
+        """注册自定义健康检查项。check_fn() 无异��表示健康，抛异常表示不健康。
+
+        /healthz 端点��聚合所有检查项，任一失败返回 503。
+        返回 self 支持链式调用。
+        """
+        self._health_checks.append((name, check_fn))
+        return self
+
+    def create_app(self) -> Starlette:
+        """构建并返回 Starlette 实例，供需要自行管理生命周期的高级��景使用。"""
+        routes = health_routes(self.app_id, self._tools, self._health_checks) + [
+            Route("/mcp/tools/call", self._handle_tool_call, methods=["POST"]),
+            Route("/mcp/tools/list", self._handle_tools_list, methods=["GET"]),
+            mcp_route(self.app_id, "0.1.0", self._tools),
+        ] + self._custom_routes
+
+        app = Starlette(routes=routes)
+
+        for middleware_cls, kwargs in self._middlewares:
+            app.add_middleware(middleware_cls, **kwargs)
+
+        return app
+
+    def run(self):
+        """启动 HTTP 服务器，阻塞直到进程收到信号。
+
+        如需自行管理生命周期（如后台任务协调），使用 create_app() 获取 Starlette 实例
+        后自行调用 uvicorn.run() 或其他 ASGI 服务器。
+        """
+        app = self.create_app()
+        uvicorn.run(app, host=self._config["host"], port=self._config["port"])
+
+    async def _handle_tool_call(self, request):
+        try:
+            body = await request.json()
+        except Exception as e:
+            return JSONResponse({"error": f"invalid json: {e}"}, status_code=400)
+        name = body.get("name")
+        params = body.get("params", {})
+        tool = self._tools.get(name)
+        if not tool:
+            return JSONResponse({"error": f"tool {name} not found"}, status_code=404)
+        try:
+            result = await tool["handler"](**params)
+            return JSONResponse({"result": result})
+        except Exception as e:
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    async def _handle_tools_list(self, request):
+        tools = [
+            {"name": name, "description": info["description"]}
+            for name, info in self._tools.items()
+        ]
+        return JSONResponse({"tools": tools})

ks_app_sdk-0.1.0/src/ks_app/config.py

@@ -0,0 +1,9 @@
+import os
+
+
+def load_config() -> dict:
+    """从环境变量加载配置。Phase 2 暂不读取 YAML 文件。"""
+    return {
+        "port": int(os.environ.get("KS_APP_PORT", "8080")),
+        "host": os.environ.get("KS_APP_HOST", "0.0.0.0"),
+    }

ks_app_sdk-0.1.0/src/ks_app/context.py

@@ -0,0 +1,107 @@
+"""Keystone 运行时上下文注入。
+
+通过 contextvars 在 MCP tools/call 调用期间为 handler 注入运行时元信息
+（resource_scope / execution_id 等），开发者通过 get_context() 非侵入式
+获取，handler 函数签名无需变更。
+
+设计要点：
+- ContextVar 默认值统一为空字符串 ""，避免开发者写 None 检查
+- _set_meta 将 _meta 中的非 string 值通过 str() 强制转成 string（MCP 协议允许
+  任意 JSON 值，但 SDK 内部统一按 string 暴露）。注意这与 Go SDK 的行为 **不同**：
+  Go 用 type assertion `v.(string)` 对非 string 值静默 drop；Python 则 coerce，
+  例如 int 42 会变成 "42"、bool True 会变成 "True"。Python 选择 coerce 的理由
+  是更实用 —— 工具 handler 有时合法地使用 int/bool（例如数值型租户 ID），
+  coerce 后的 string 形式仍可用。如未来需要严格匹配 Go 行为，可改为
+  `if isinstance(meta[key], str)` 拦截。
+- _reset_meta 必须在 tools/call 的 finally 中调用，防止上下文泄漏到下一个请求
+"""
+
+from contextvars import ContextVar
+
+
+# 模块级 ContextVar，每个字段独立存放，未注入时返回空字符串。
+_ks_resource_scope: ContextVar[str] = ContextVar("ks_resource_scope", default="")
+_ks_execution_id: ContextVar[str] = ContextVar("ks_execution_id", default="")
+_ks_task_id: ContextVar[str] = ContextVar("ks_task_id", default="")
+_ks_task_name: ContextVar[str] = ContextVar("ks_task_name", default="")
+_ks_trigger_type: ContextVar[str] = ContextVar("ks_trigger_type", default="")
+
+
+class ToolContext:
+    """tools/call 调用期间可获取的 Keystone 运行时上下文。
+
+    所有字段均为只读 string；当 MCP 客户端未注入对应 _meta 字段时，对应属性
+    返回空字符串而非 None，以简化 handler 端的判空逻辑。
+    """
+
+    @property
+    def resource_scope(self) -> str:
+        """资源作用域。多租户隔离的关键字段，不同实例调用同一工具时通过它区分数据边界。"""
+        return _ks_resource_scope.get()
+
+    @property
+    def execution_id(self) -> str:
+        """当前执行 ID。"""
+        return _ks_execution_id.get()
+
+    @property
+    def task_id(self) -> str:
+        """当前任务 ID。"""
+        return _ks_task_id.get()
+
+    @property
+    def task_name(self) -> str:
+        """当前任务名称。"""
+        return _ks_task_name.get()
+
+    @property
+    def trigger_type(self) -> str:
+        """触发类型（manual / cron / webhook / event 等）。"""
+        return _ks_trigger_type.get()
+
+
+def get_context() -> ToolContext:
+    """获取当前 tools/call 调用的 Keystone 运行时上下文。
+
+    在 handler 函数体内调用，返回的 ToolContext 反映 MCP 请求 _meta 字段
+    中注入的值。在非 tools/call 路径下调用，所有字段均为空字符串。
+    """
+    return ToolContext()
+
+
+def _set_meta(meta: dict | None) -> None:
+    """将 MCP _meta 字段写入 ContextVars。
+
+    None 或空 dict 时为 no-op；对每个字段通过 str() 强制 coerce 成 string，
+    使 int/bool/None 等非 string 值也能以 string 形式暴露给 handler。
+
+    与 Go SDK 的差异：Go `withMeta` 用 type assertion `v.(string)` 对非 string
+    值静默 drop（完全忽略该字段），Python 则 coerce（`42` -> `"42"`、
+    `True` -> `"True"`、`None` -> `"None"`）。这是刻意的分歧 —— Python 侧
+    更宽松，保留 int/bool 租户 ID 等合法场景的可用性。
+    """
+    if not meta:
+        return
+    if "ks_resource_scope" in meta:
+        _ks_resource_scope.set(str(meta["ks_resource_scope"]))
+    if "ks_execution_id" in meta:
+        _ks_execution_id.set(str(meta["ks_execution_id"]))
+    if "ks_task_id" in meta:
+        _ks_task_id.set(str(meta["ks_task_id"]))
+    if "ks_task_name" in meta:
+        _ks_task_name.set(str(meta["ks_task_name"]))
+    if "ks_trigger_type" in meta:
+        _ks_trigger_type.set(str(meta["ks_trigger_type"]))
+
+
+def _reset_meta() -> None:
+    """清空所有 ContextVar，必须在 tools/call 的 finally 中调用。
+
+    避免 handler 异常或正常返回后遗留的上下文被下一个请求读取（在共享
+    event loop 的 ASGI 服务下，ContextVar 不会自动重置）。
+    """
+    _ks_resource_scope.set("")
+    _ks_execution_id.set("")
+    _ks_task_id.set("")
+    _ks_task_name.set("")
+    _ks_trigger_type.set("")

ks_app_sdk-0.1.0/src/ks_app/health.py

@@ -0,0 +1,51 @@
+import logging
+
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+logger = logging.getLogger(__name__)
+
+
+def health_routes(app_id: str, tools: dict, health_checks: list | None = None) -> list:
+    """返回 /healthz、/readyz、/meta 三个路由。
+
+    health_checks: [(name, check_fn), ...] 列表。check_fn 返回 None 表示健康，
+    抛异常表示不健康。
+    """
+    checks = health_checks or []
+
+    async def healthz(request):
+        if not checks:
+            return JSONResponse({"status": "ok"})
+
+        failures = {}
+        for name, check_fn in checks:
+            try:
+                check_fn()
+            except Exception as e:
+                failures[name] = str(e)
+
+        if failures:
+            return JSONResponse(
+                {"status": "unhealthy", "checks": failures},
+                status_code=503,
+            )
+        return JSONResponse({"status": "ok"})
+
+    async def readyz(request):
+        return JSONResponse({"status": "ok"})
+
+    async def meta(request):
+        return JSONResponse({
+            "app_id": app_id,
+            "tools": [
+                {"name": name, "description": info["description"]}
+                for name, info in tools.items()
+            ],
+        })
+
+    return [
+        Route("/healthz", healthz, methods=["GET"]),
+        Route("/readyz", readyz, methods=["GET"]),
+        Route("/meta", meta, methods=["GET"]),
+    ]

ks_app_sdk-0.1.0/src/ks_app/llm.py

@@ -0,0 +1,104 @@
+"""Keystone LLM Relay 客户端。
+
+通过 Keystone 网关调用大模型，无需自行管理 API key。
+要求 manifest 中 llm_mode 为 keystone_relay，Keystone 安装应用时会注入
+KS_RELAY_TOKEN 环境变量。
+
+注意：chat 抛出的 RuntimeError 错误消息可能包含网关响应 body 原文（用于本地调试）。
+如果 tool handler 需要把错误信息透传给 MCP 客户端，应先脱敏或仅返回固定消息，
+与 Task 3 建立的 handler 错误处理约定一致。
+"""
+import asyncio
+import json
+import os
+from dataclasses import dataclass, field
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+
+@dataclass
+class ChatResponse:
+    """聊天响应。"""
+    id: str = ""
+    model: str = ""
+    choices: list = field(default_factory=list)
+    usage: dict = field(default_factory=dict)
+
+
+class LLMClient:
+    """Keystone LLM Relay 客户端。
+
+    使用示例：
+        client = app.llm()
+        resp = await client.chat([{"role": "user", "content": "你好"}])
+        print(resp.choices[0]["message"]["content"])
+    """
+
+    def __init__(self):
+        self._gateway_url = os.environ.get("KS_GATEWAY_URL", "http://localhost:9988")
+        self._relay_token = os.environ.get("KS_RELAY_TOKEN", "")
+
+    async def chat(
+        self,
+        messages: list[dict],
+        *,
+        model: str = "",
+        temperature: float | None = None,
+        max_tokens: int = 0,
+    ) -> ChatResponse:
+        """发送聊天请求到 Keystone LLM 网关。
+
+        messages: OpenAI 风格的消息列表，每条消息是带 role/content 的 dict。
+        model: 可选指定模型名；留空时由网关按 manifest 策略选择。
+        temperature/max_tokens: 可选生成参数。
+
+        未设置 KS_RELAY_TOKEN 时直接抛 RuntimeError。
+        """
+        if not self._relay_token:
+            raise RuntimeError(
+                "KS_RELAY_TOKEN 未设置，请确认 manifest 中 llm_mode 为 keystone_relay"
+            )
+
+        body: dict = {"messages": messages}
+        if model:
+            body["model"] = model
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens > 0:
+            body["max_tokens"] = max_tokens
+
+        url = f"{self._gateway_url}/v1/gateway/relay/chat"
+        data = json.dumps(body).encode()
+        req = Request(url, data=data, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Authorization", f"Bearer {self._relay_token}")
+
+        # urllib 是同步 API，直接在 async 函数里调用会阻塞事件循环。
+        # asyncio.to_thread 把同步调用放到线程池执行，保持异步语义。
+        # 60s 超时与 Go 侧对齐，防止 hung gateway 长时间阻塞 tool handler。
+        def _do_request() -> dict:
+            try:
+                with urlopen(req, timeout=60) as resp:
+                    raw = resp.read()
+            except HTTPError as e:
+                # 读取 body 时可能因连接已关闭而失败，做防御处理
+                try:
+                    body = e.read().decode(errors="replace")
+                except Exception:
+                    body = ""
+                raise RuntimeError(
+                    f"LLM 网关返回 {e.code}: {body}"
+                ) from e
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError as e:
+                raise RuntimeError(f"解析响应失败: {e}") from e
+
+        resp_data = await asyncio.to_thread(_do_request)
+
+        return ChatResponse(
+            id=resp_data.get("id", ""),
+            model=resp_data.get("model", ""),
+            choices=resp_data.get("choices", []),
+            usage=resp_data.get("usage", {}),
+        )