Metadata-Version: 2.4
Name: agk
Version: 0.5.0
Summary: app-gui-kit Python server SDK — Flask server + framework-less Web Components shell for simulation/agent app GUIs (SSE streaming, HITL gates, pluggable viewers)
Author: ToPo-ToPo-ToPo
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/ToPo-ToPo-ToPo/app-gui-kit
Keywords: gui,sse,agent,simulation,flask,web-components
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Flask
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.1
Dynamic: license-file

# 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).

```python
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()
```

```html
<!-- 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

```sh
agk new my-sim-app --viewer field2d          # Python app
agk new my-jl-app --lang julia --viewer gltf # Julia app (AppGuiKit.jl)
```

## 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](https://threejs.org)
  (MIT, © Three.js Authors); its license banner is retained in the bundle.
