luaskills-sdk 0.2.3__tar.gz

luaskills_sdk-0.2.3/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include examples *.py

luaskills_sdk-0.2.3/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: luaskills-sdk
+Version: 0.2.3
+Summary: Python SDK for integrating the LuaSkills runtime through the public JSON FFI surface.
+Author: LuaSkills
+License-Expression: MIT
+Project-URL: Repository, https://github.com/LuaSkills/luaskills
+Keywords: lua,skills,ffi,runtime,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# luaskills-sdk
+
+Python SDK，用于通过公共 `_json` FFI 集成 LuaSkills 运行时。
+
+SDK 封装了动态库加载、`FfiBorrowedBuffer` / `FfiOwnedBuffer`、JSON 包络、engine 生命周期、root helper、authority、skill-config、普通管理面与 system 管理面。宿主不需要在业务代码中重复手写 ctypes buffer。
+
+## 安装
+
+```bash
+pip install luaskills-sdk
+```
+
+当前包不内置 `luaskills` 原生动态库。调用时需要通过 `library_path` 或 `LUASKILLS_LIB` 指向动态库：
+
+```powershell
+$env:LUASKILLS_LIB = "D:\path\to\luaskills.dll"
+```
+
+## 基础用法
+
+```python
+from luaskills import Authority, LuaSkillsClient, RuntimeRoots
+
+runtime_root = "D:/runtime/luaskills"
+roots = RuntimeRoots.standard(runtime_root)
+
+with LuaSkillsClient(library_path="D:/path/to/luaskills.dll", runtime_root=runtime_root) as client:
+    client.load_from_roots(roots)
+    entries = client.list_entries(Authority.DELEGATED_TOOL)
+    result = client.call_skill("demo-standard-ffi-skill-ping", {"note": "python-sdk"})
+
+    print(entries)
+    print(result["content"])
+```
+
+## CLI
+
+安装后可使用：
+
+```bash
+luaskills install-runtime --database vldb-controller --runtime-root D:\runtime\luaskills
+luaskills install-runtime --database vldb-direct --runtime-root D:\runtime\luaskills
+luaskills install-runtime --database none --runtime-root D:\runtime\luaskills
+luaskills version --lib D:\path\to\luaskills.dll
+luaskills list --lib D:\path\to\luaskills.dll --runtime-root D:\runtime\luaskills
+luaskills call demo-standard-ffi-skill-ping "{\"note\":\"python\"}" --lib D:\path\to\luaskills.dll
+```
+
+`install-runtime` 会按当前平台下载并安装 Lua runtime、LuaSkills FFI 与可选数据库资产，并写入 `resources/luaskills-sdk-runtime-manifest.json`：
+
+- `none`：安装 `lua-runtime-{platform}.tar.gz` 与 LuaSkills FFI SDK 资产，不安装数据库 provider。
+- `vldb-controller`：下载 `vldb-controller-{version}-{target}`，用于 `space_controller` provider mode。
+- `vldb-direct`：下载 `vldb-sqlite-lib-{version}-{target}` 与 `vldb-lancedb-lib-{version}-{target}`，用于 `dynamic_library` provider mode。
+- `host-callback`：不下载 VLDB 资产，生成 `host_callback + json` 的 host option patch。
+
+`lua-runtime-{platform}.tar.gz` 默认安装 `lua_packages`、运行时 `libs`、`resources` 与授权材料。如果宿主已经自行管理 Lua runtime，可使用 `--skip-lua-runtime` 跳过。
+
+排查发布资产名时可先使用：
+
+```bash
+luaskills install-runtime --database vldb-direct --dry-run
+luaskills install-runtime --database none --skip-lua-runtime --dry-run
+```
+
+安装完成后，`LuaSkillsClient(runtime_root=...)` 会自动从 `runtime_root/libs` 解析 LuaSkills 动态库，并读取该 manifest 把数据库 provider 的 host option patch 合入默认配置；宿主仍可通过显式 `library_path` 与 `host_options` 覆盖。
+
+管理命令示例：
+
+```bash
+luaskills install LuaSkills/luaskills-demo-skill --target-root USER
+luaskills update LuaSkills/luaskills-demo-skill --target-root USER
+luaskills uninstall luaskills-demo-skill --target-root USER
+```
+
+system 管理入口必须由宿主决定 authority：
+
+```bash
+luaskills system-install LuaSkills/luaskills-demo-skill --target-root ROOT --authority system
+```
+
+如果 system 工具封装给普通 tools，应固定使用 `--authority delegated_tool`。
+
+## JSON Provider Callback
+
+SQLite / LanceDB 的 `host_callback + json` 模式可以直接通过 SDK 注册，宿主无需在业务代码中重复手写 ctypes buffer：
+
+```python
+from luaskills import LuaSkillsClient, LuaSkillsJsonFfi
+
+ffi = LuaSkillsJsonFfi("D:/path/to/luaskills.dll")
+
+
+def sqlite_provider(request):
+    return {"ok": True, "request": request}
+
+
+ffi.set_sqlite_provider_json_callback(sqlite_provider)
+
+try:
+    client = LuaSkillsClient(
+        library_path="D:/path/to/luaskills.dll",
+        runtime_root="D:/runtime/luaskills",
+        host_options={
+            "sqlite_provider_mode": "host_callback",
+            "sqlite_callback_mode": "json",
+        },
+    )
+    client.close()
+finally:
+    ffi.clear_sqlite_provider_json_callback()
+```
+
+callback 必须在 `engine_new` 前注册；engine 创建后再切换 callback 不会 retroactive 影响已存在 engine。
+
+pip 安装后的 wheel 内置可运行示例：
+
+```bash
+python -m luaskills.examples.basic
+python -m luaskills.examples.provider_callback
+```
+
+源码仓库中同样保留 `examples/basic.py` 与 `examples/provider_callback.py`，便于直接阅读。
+
+## 权限与边界
+
+- 查询类接口默认使用 `DelegatedTool`，因此不会返回 `ROOT` skills。
+- `System` 只表示可管理 ROOT 层，不表示可绕过 ROOT 同名占用规则。
+- `call_skill` 与 `run_lua` 是运行时执行面，不作为 ROOT 可见性过滤。
+- skill-config 按 `skill_id + key` 读写，只有 Lua skill 实际读取配置时才影响行为。
+- 如果宿主不希望用户执行任意 Lua，不应直接暴露 `run_lua`。
+
+## 验证
+
+源码环境可运行：
+
+```bash
+python -m compileall sdk/python/src
+PYTHONPATH=sdk/python/src python -m luaskills.cli version --lib target/debug/luaskills.dll
+```

luaskills_sdk-0.2.3/README.md

@@ -0,0 +1,139 @@
+# luaskills-sdk
+
+Python SDK，用于通过公共 `_json` FFI 集成 LuaSkills 运行时。
+
+SDK 封装了动态库加载、`FfiBorrowedBuffer` / `FfiOwnedBuffer`、JSON 包络、engine 生命周期、root helper、authority、skill-config、普通管理面与 system 管理面。宿主不需要在业务代码中重复手写 ctypes buffer。
+
+## 安装
+
+```bash
+pip install luaskills-sdk
+```
+
+当前包不内置 `luaskills` 原生动态库。调用时需要通过 `library_path` 或 `LUASKILLS_LIB` 指向动态库：
+
+```powershell
+$env:LUASKILLS_LIB = "D:\path\to\luaskills.dll"
+```
+
+## 基础用法
+
+```python
+from luaskills import Authority, LuaSkillsClient, RuntimeRoots
+
+runtime_root = "D:/runtime/luaskills"
+roots = RuntimeRoots.standard(runtime_root)
+
+with LuaSkillsClient(library_path="D:/path/to/luaskills.dll", runtime_root=runtime_root) as client:
+    client.load_from_roots(roots)
+    entries = client.list_entries(Authority.DELEGATED_TOOL)
+    result = client.call_skill("demo-standard-ffi-skill-ping", {"note": "python-sdk"})
+
+    print(entries)
+    print(result["content"])
+```
+
+## CLI
+
+安装后可使用：
+
+```bash
+luaskills install-runtime --database vldb-controller --runtime-root D:\runtime\luaskills
+luaskills install-runtime --database vldb-direct --runtime-root D:\runtime\luaskills
+luaskills install-runtime --database none --runtime-root D:\runtime\luaskills
+luaskills version --lib D:\path\to\luaskills.dll
+luaskills list --lib D:\path\to\luaskills.dll --runtime-root D:\runtime\luaskills
+luaskills call demo-standard-ffi-skill-ping "{\"note\":\"python\"}" --lib D:\path\to\luaskills.dll
+```
+
+`install-runtime` 会按当前平台下载并安装 Lua runtime、LuaSkills FFI 与可选数据库资产，并写入 `resources/luaskills-sdk-runtime-manifest.json`：
+
+- `none`：安装 `lua-runtime-{platform}.tar.gz` 与 LuaSkills FFI SDK 资产，不安装数据库 provider。
+- `vldb-controller`：下载 `vldb-controller-{version}-{target}`，用于 `space_controller` provider mode。
+- `vldb-direct`：下载 `vldb-sqlite-lib-{version}-{target}` 与 `vldb-lancedb-lib-{version}-{target}`，用于 `dynamic_library` provider mode。
+- `host-callback`：不下载 VLDB 资产，生成 `host_callback + json` 的 host option patch。
+
+`lua-runtime-{platform}.tar.gz` 默认安装 `lua_packages`、运行时 `libs`、`resources` 与授权材料。如果宿主已经自行管理 Lua runtime，可使用 `--skip-lua-runtime` 跳过。
+
+排查发布资产名时可先使用：
+
+```bash
+luaskills install-runtime --database vldb-direct --dry-run
+luaskills install-runtime --database none --skip-lua-runtime --dry-run
+```
+
+安装完成后，`LuaSkillsClient(runtime_root=...)` 会自动从 `runtime_root/libs` 解析 LuaSkills 动态库，并读取该 manifest 把数据库 provider 的 host option patch 合入默认配置；宿主仍可通过显式 `library_path` 与 `host_options` 覆盖。
+
+管理命令示例：
+
+```bash
+luaskills install LuaSkills/luaskills-demo-skill --target-root USER
+luaskills update LuaSkills/luaskills-demo-skill --target-root USER
+luaskills uninstall luaskills-demo-skill --target-root USER
+```
+
+system 管理入口必须由宿主决定 authority：
+
+```bash
+luaskills system-install LuaSkills/luaskills-demo-skill --target-root ROOT --authority system
+```
+
+如果 system 工具封装给普通 tools，应固定使用 `--authority delegated_tool`。
+
+## JSON Provider Callback
+
+SQLite / LanceDB 的 `host_callback + json` 模式可以直接通过 SDK 注册，宿主无需在业务代码中重复手写 ctypes buffer：
+
+```python
+from luaskills import LuaSkillsClient, LuaSkillsJsonFfi
+
+ffi = LuaSkillsJsonFfi("D:/path/to/luaskills.dll")
+
+
+def sqlite_provider(request):
+    return {"ok": True, "request": request}
+
+
+ffi.set_sqlite_provider_json_callback(sqlite_provider)
+
+try:
+    client = LuaSkillsClient(
+        library_path="D:/path/to/luaskills.dll",
+        runtime_root="D:/runtime/luaskills",
+        host_options={
+            "sqlite_provider_mode": "host_callback",
+            "sqlite_callback_mode": "json",
+        },
+    )
+    client.close()
+finally:
+    ffi.clear_sqlite_provider_json_callback()
+```
+
+callback 必须在 `engine_new` 前注册；engine 创建后再切换 callback 不会 retroactive 影响已存在 engine。
+
+pip 安装后的 wheel 内置可运行示例：
+
+```bash
+python -m luaskills.examples.basic
+python -m luaskills.examples.provider_callback
+```
+
+源码仓库中同样保留 `examples/basic.py` 与 `examples/provider_callback.py`，便于直接阅读。
+
+## 权限与边界
+
+- 查询类接口默认使用 `DelegatedTool`，因此不会返回 `ROOT` skills。
+- `System` 只表示可管理 ROOT 层，不表示可绕过 ROOT 同名占用规则。
+- `call_skill` 与 `run_lua` 是运行时执行面，不作为 ROOT 可见性过滤。
+- skill-config 按 `skill_id + key` 读写，只有 Lua skill 实际读取配置时才影响行为。
+- 如果宿主不希望用户执行任意 Lua，不应直接暴露 `run_lua`。
+
+## 验证
+
+源码环境可运行：
+
+```bash
+python -m compileall sdk/python/src
+PYTHONPATH=sdk/python/src python -m luaskills.cli version --lib target/debug/luaskills.dll
+```

luaskills_sdk-0.2.3/examples/basic.py

@@ -0,0 +1,33 @@
+"""
+Basic Python SDK version query example.
+Python SDK 基础版本查询示例。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from luaskills import LuaSkillsClient
+
+
+def resolve_library_path() -> Path:
+    """
+    Resolve the demo LuaSkills dynamic library path.
+    解析演示用 LuaSkills 动态库路径。
+    """
+
+    return Path(os.environ.get("LUASKILLS_LIB") or Path(__file__).resolve().parents[3] / "target" / "debug" / "luaskills.dll")
+
+
+def main() -> None:
+    """
+    Print the LuaSkills JSON FFI version through the Python SDK.
+    通过 Python SDK 输出 LuaSkills JSON FFI 版本。
+    """
+
+    print(LuaSkillsClient.version(library_path=resolve_library_path()))
+
+
+if __name__ == "__main__":
+    main()

luaskills_sdk-0.2.3/examples/provider_callback.py

@@ -0,0 +1,59 @@
+"""
+Python SDK JSON provider callback registration example.
+Python SDK JSON provider callback 注册示例。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from luaskills import LuaSkillsClient, LuaSkillsJsonFfi
+
+
+def resolve_library_path() -> Path:
+    """
+    Resolve the demo LuaSkills dynamic library path.
+    解析演示用 LuaSkills 动态库路径。
+    """
+
+    return Path(os.environ.get("LUASKILLS_LIB") or Path(__file__).resolve().parents[3] / "target" / "debug" / "luaskills.dll")
+
+
+def sqlite_provider(request: Any) -> dict[str, Any]:
+    """
+    Return one minimal host-side SQLite provider response for demo requests.
+    为演示请求返回一个最小宿主侧 SQLite provider 响应。
+    """
+
+    return {"ok": True, "request": request}
+
+
+def main() -> None:
+    """
+    Register one SQLite JSON provider callback before engine creation.
+    在创建引擎前注册单个 SQLite JSON provider callback。
+    """
+
+    library_path = resolve_library_path()
+    runtime_root = Path(os.environ.get("LUASKILLS_RUNTIME_ROOT") or Path(__file__).resolve().parent / "luaskills-runtime")
+    ffi = LuaSkillsJsonFfi(library_path)
+    ffi.set_sqlite_provider_json_callback(sqlite_provider)
+    try:
+        client = LuaSkillsClient(
+            library_path=library_path,
+            runtime_root=runtime_root,
+            host_options={
+                "sqlite_provider_mode": "host_callback",
+                "sqlite_callback_mode": "json",
+            },
+        )
+        client.close()
+        print("SQLite JSON provider callback registered before engine creation.")
+    finally:
+        ffi.clear_sqlite_provider_json_callback()
+
+
+if __name__ == "__main__":
+    main()

luaskills_sdk-0.2.3/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "luaskills-sdk"
+version = "0.2.3"
+description = "Python SDK for integrating the LuaSkills runtime through the public JSON FFI surface."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "LuaSkills" }
+]
+keywords = ["lua", "skills", "ffi", "runtime", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.scripts]
+luaskills = "luaskills.cli:main"
+
+[project.urls]
+Repository = "https://github.com/LuaSkills/luaskills"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+luaskills = ["py.typed"]

luaskills_sdk-0.2.3/setup.cfg

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

luaskills_sdk-0.2.3/src/luaskills/__init__.py

@@ -0,0 +1,58 @@
+"""
+Python SDK for integrating LuaSkills through the public JSON FFI surface.
+通过公共 JSON FFI 表面集成 LuaSkills 的 Python SDK。
+"""
+
+from .client import (
+    LuaSkillsClient,
+    SkillConfigClient,
+    SkillManagementClient,
+    SystemSkillManagementClient,
+    create_engine_options,
+    default_host_options,
+    default_pool_config,
+    default_space_controller_options,
+)
+from .ffi import JsonProviderCallback, LuaSkillsError, LuaSkillsJsonFfi, resolve_library_path
+from .roots import RuntimeRoots
+from .runtime_assets import (
+    RuntimeDatabasePreset,
+    build_runtime_install_manifest,
+    host_options_from_runtime_manifest,
+    install_runtime_assets,
+    load_runtime_install_manifest,
+    resolve_luaskills_library_path_from_runtime,
+    resolve_runtime_platform_target,
+    runtime_manifest_path,
+    write_runtime_install_manifest,
+)
+from .types import Authority, LuaInvocationContext, RuntimeSkillRoot, SkillInstallSourceType
+
+__all__ = [
+    "Authority",
+    "JsonProviderCallback",
+    "LuaInvocationContext",
+    "LuaSkillsClient",
+    "LuaSkillsError",
+    "LuaSkillsJsonFfi",
+    "RuntimeRoots",
+    "RuntimeSkillRoot",
+    "RuntimeDatabasePreset",
+    "SkillConfigClient",
+    "SkillInstallSourceType",
+    "SkillManagementClient",
+    "SystemSkillManagementClient",
+    "create_engine_options",
+    "default_host_options",
+    "default_pool_config",
+    "default_space_controller_options",
+    "build_runtime_install_manifest",
+    "host_options_from_runtime_manifest",
+    "install_runtime_assets",
+    "load_runtime_install_manifest",
+    "resolve_luaskills_library_path_from_runtime",
+    "resolve_runtime_platform_target",
+    "resolve_library_path",
+    "runtime_manifest_path",
+    "write_runtime_install_manifest",
+]