agk — app-gui-kit Python server SDK

A small framework for building local, single-user GUIs for simulation / agent applications. One AgkApp gives you a Flask server implementing the app-gui-kit protocol, and the bundled frontend kit (framework-less Web Components) gives you a ready-made shell — composer, streaming task log, and pluggable result viewers (glTF / STL / FEM mesh / 2D fields / WebGPU / media / cards / markdown / deck).

from agk import AgkApp

def runner(req, ctx):
    ctx.emit.task("t1", "running", title="Analyze")
    ctx.emit.text("working…")
    if req.get("options", {}).get("step"):
        ctx.gate("Proceed?")                     # human-in-the-loop gate
    ctx.emit.artifact("gltf", url="/artifact/result.glb")
    ctx.emit.task("t1", "done")
    ctx.emit.done(summary="finished")

AgkApp("My Agent App", runner, capabilities=("step",)).run()

<!-- index.html — zero build step -->
<link rel="stylesheet" href="/agk/agk.css">
<script type="module" src="/agk/agk.js"></script>
<script type="module" src="/agk/agk-viewer-gltf.js"></script>
<agk-shell app="My Agent App"></agk-shell>

What AgkApp provides

• POST /stream — SSE event streaming (single-flight), plus a polling transport for clients that cannot use SSE
• POST /cancel / POST /reset / POST /intervene (HITL gates)
• GET /artifact/<path> (traversal-safe) and POST /upload
• GET /agk/<path> — serves the bundled frontend kit
• /alive + /bye window-lifecycle watchdog (auto-exit when the tab closes)
• /agent/* remote-job queue for headless (LLM) driving
• /voice_status + /transcribe with a pluggable transcriber

Scaffolding

agk new my-sim-app --viewer field2d          # Python app

Notes

• The protocol, endpoints, design tokens and viewer interface are specified in the app-gui-kit repository (spec/).
• The bundled frontend (agk/static/) includes three.js (MIT, © Three.js Authors); its license banner is retained in the bundle.