agk 0.1.0__py3-none-any.whl

agk/__init__.py

@@ -0,0 +1,23 @@
+"""app-gui-kit Python サーバ SDK。
+
+シミュレーションエージェント系アプリの Flask 定型(SSE ストリーミング、
+単一フライト、ライフサイクル watchdog、成果物配信、remote-job キュー、
+アップロード、HITL ゲート、起動処理)を提供する。
+
+使い方::
+
+    from agk import AgkApp
+
+    def runner(req, ctx):
+        ctx.emit.text("hello")
+        ctx.emit.done(summary="finished")
+
+    AgkApp("my-app", runner).run()
+"""
+
+from .core import AgkApp, AgkContext
+from .events import EventSink
+from .gates import GateHub
+
+__all__ = ["AgkApp", "AgkContext", "EventSink", "GateHub", "__version__"]
+__version__ = "0.1.0"

agk/cli.py

@@ -0,0 +1,189 @@
+"""agk CLI — アプリのスキャフォールド生成。
+
+使い方::
+
+    agk new <name> [--lang python|julia]
+                   [--viewer media|cards|field2d|gltf|mesh|webgpu|none]
+                   [--dir .]
+
+`agk/templates/<lang>/` の ``*.tmpl`` を ``str.format`` 置換
+({name} / {viewer_script} / {viewer_example} / {viewer_note})で展開する。
+テンプレート内の literal な波括弧は ``{{`` / ``}}`` でエスケープする。
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+__all__ = ["main"]
+
+TEMPLATES_DIR = Path(__file__).resolve().parent / "templates"
+LANGS = ("python", "julia")
+VIEWERS = ("media", "cards", "field2d", "gltf", "mesh", "webgpu", "none")
+
+NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+# viewer 名 → dist 配布モジュール(/agk/ 配下)。none はインポートなし。
+_VIEWER_MODULES = {v: f"agk-viewer-{v}.js" for v in VIEWERS if v != "none"}
+
+# viewer 名 → app.py に埋めるコメント付き成果物例(protocol.md §5)。
+_PY_EXAMPLES = {
+    "media": '''\
+    # --- 成果物(media ビューア: image / video)---------------------------
+    # png = ctx.workspace / "plot.png"
+    # png.write_bytes(...)  # 画像を生成
+    # ctx.emit.artifact("image", url="/artifact/plot.png", mime="image/png")
+''',
+    "cards": '''\
+    # --- 成果物(cards ビューア)------------------------------------------
+    # import json
+    # cards = [{"title": "result A", "snippet": "...", "badges": ["ok"]}]
+    # path = ctx.workspace / "cards.json"
+    # path.write_text(json.dumps(cards, ensure_ascii=False), encoding="utf-8")
+    # ctx.emit.artifact("cards", url="/artifact/cards.json",
+    #                   mime="application/json", replace=False)
+''',
+    "field2d": '''\
+    # --- 成果物(field2d ビューア: 2D スカラー場グリッド)------------------
+    # import json
+    # nx, ny = 32, 32
+    # data = {"nx": nx, "ny": ny,
+    #         "fields": [{"name": "u", "data": [0.0] * (nx * ny)}]}
+    # path = ctx.workspace / "field.json"
+    # path.write_text(json.dumps(data), encoding="utf-8")
+    # ctx.emit.artifact("field2d", url="/artifact/field.json",
+    #                   mime="application/json")
+''',
+    "gltf": '''\
+    # --- 成果物(gltf ビューア: GLB / glTF)--------------------------------
+    # glb = ctx.workspace / "model.glb"
+    # glb.write_bytes(...)  # GLB を生成
+    # ctx.emit.artifact("gltf", url="/artifact/model.glb",
+    #                   mime="model/gltf-binary", meta={"up": "z"})
+''',
+    "mesh": '''\
+    # --- 成果物(mesh ビューア: FEM メッシュ+結果)-------------------------
+    # path = ctx.workspace / "mesh.json"
+    # path.write_text(...)  # メッシュ+フィールドを書き出す
+    # ctx.emit.artifact("mesh", url="/artifact/mesh.json",
+    #                   meta={"fields": [{"name": "stress", "unit": "MPa"}]})
+''',
+    "webgpu": '''\
+    # --- 成果物(webgpu ビューア: 大規模粒子/格子の GPU 描画)---------------
+    # 標準 kind(field2d 等)かアプリ固有 kind("x-<app>.<name>")を送る。
+    # ctx.emit.artifact("field2d", url="/artifact/field.json",
+    #                   mime="application/json")
+''',
+    "none": '''\
+    # --- 成果物(組み込みビューア: markdown / image / video)---------------
+    # md = ctx.workspace / "result.md"
+    # md.write_text("## 結果\\n", encoding="utf-8")
+    # ctx.emit.artifact("markdown", url="/artifact/result.md",
+    #                   mime="text/markdown")
+''',
+}
+
+# viewer 名 → app.jl に埋めるコメント例。
+_JL_EXAMPLES = {
+    "none": '''\
+    #   path = joinpath(ctx.workspace, "result.md")
+    #   write(path, "## 結果\\n")
+    #   emit(ctx, "artifact"; kind="markdown", url="/artifact/result.md",
+    #        mime="text/markdown")''',
+}
+
+
+def _jl_example(viewer: str) -> str:
+    if viewer in _JL_EXAMPLES:
+        return _JL_EXAMPLES[viewer]
+    return (
+        f'    #   emit(ctx, "artifact"; kind="{viewer if viewer != "media" else "image"}",\n'
+        f'    #        url="/artifact/result", mime="application/octet-stream")'
+    )
+
+
+def _viewer_script(viewer: str) -> str:
+    """index.html に挿す viewer モジュールの <script> 行(none は空)。"""
+    module = _VIEWER_MODULES.get(viewer)
+    if module is None:
+        return ""
+    return f'<script type="module" src="/agk/{module}"></script>\n'
+
+
+def _viewer_note(viewer: str) -> str:
+    """README に挿す viewer の補足(none は空)。"""
+    module = _VIEWER_MODULES.get(viewer)
+    if module is None:
+        return ""
+    return (
+        f"\n## ビューア\n\n"
+        f"`{viewer}` ビューア(`/agk/{module}`)を index.html でインポート済み。\n"
+        f"対応する artifact イベントの契約は `spec/protocol.md` §5 を参照。\n"
+    )
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    if not NAME_RE.match(args.name):
+        print(f"agk new: 不正なアプリ名です: {args.name!r} "
+              "(英数字で始まり、英数字と . _ - のみ使用可)", file=sys.stderr)
+        return 2
+
+    src_dir = TEMPLATES_DIR / args.lang
+    if not src_dir.is_dir():
+        print(f"agk new: テンプレートが見つかりません: {src_dir}", file=sys.stderr)
+        return 2
+
+    target = Path(args.dir).expanduser().resolve() / args.name
+    if target.exists() and any(target.iterdir()):
+        print(f"agk new: 出力先が空ではありません: {target}", file=sys.stderr)
+        return 2
+
+    subs = {
+        "name": args.name,
+        "viewer_kind": args.viewer,
+        "viewer_script": _viewer_script(args.viewer),
+        "viewer_note": _viewer_note(args.viewer),
+        "viewer_example": (_PY_EXAMPLES[args.viewer] if args.lang == "python"
+                           else _jl_example(args.viewer)),
+    }
+
+    target.mkdir(parents=True, exist_ok=True)
+    created: list[str] = []
+    for tmpl in sorted(src_dir.glob("*.tmpl")):
+        out = target / tmpl.name.removesuffix(".tmpl")
+        out.write_text(tmpl.read_text(encoding="utf-8").format(**subs),
+                       encoding="utf-8")
+        created.append(out.name)
+
+    print(f"created: {target}")
+    for name in created:
+        print(f"  {name}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agk", description="app-gui-kit CLI(アプリのスキャフォールド生成)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    new = sub.add_parser("new", help="新規アプリの雛形を生成する")
+    new.add_argument("name", help="アプリ名(生成するディレクトリ名)")
+    new.add_argument("--lang", choices=LANGS, default="python",
+                     help="サーバ言語(既定: python)")
+    new.add_argument("--viewer", choices=VIEWERS, default="none",
+                     help="使用する標準ビューア(既定: none)")
+    new.add_argument("--dir", default=".",
+                     help="生成先の親ディレクトリ(既定: カレント)")
+
+    args = parser.parse_args(argv)
+    if args.command == "new":
+        return cmd_new(args)
+    parser.error(f"unknown command: {args.command}")
+    return 2  # unreachable
+
+
+if __name__ == "__main__":
+    sys.exit(main())