Metadata-Version: 2.3
Name: llming-stage
Version: 0.1.4
Summary: Shared frontend foundation and SPA app shell for the llming ecosystem — vendor JS, fonts, icons, and a lazy-loading client-side router
License: MIT
Keywords: spa,frontend,assets,vue,quasar,starlette,lazy-loading
Author: Michael Ikemann
Requires-Python: >=3.14,<4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Provides-Extra: debug
Requires-Dist: llming-com (>=0.1.5,<0.2)
Requires-Dist: psutil (>=5.9) ; extra == "debug"
Requires-Dist: starlette (>=0.27)
Requires-Dist: uvicorn[standard] (>=0.27)
Project-URL: Author, https://github.com/Alyxion
Project-URL: Homepage, https://github.com/Alyxion/llming-stage
Project-URL: Repository, https://github.com/Alyxion/llming-stage
Description-Content-Type: text/markdown

<p align="center"><img src="https://raw.githubusercontent.com/Alyxion/llming-stage/main/media/llming-stage-logo-small.png" alt="LLMing Stage" width="400"></p>

# llming-stage

[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Alyxion/llming-stage/blob/main/LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/llming-stage.svg)](https://pypi.org/project/llming-stage/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-purple.svg)](https://github.com/astral-sh/ruff)

### Build Vue + Quasar UIs that AI can build, drive, and debug.

`llming-stage` is the SPA foundation for AI-assisted frontend work. You write a real Vue + Quasar app, not a Python shim. Reactive traffic and sessions flow through [`llming-com`](https://github.com/Alyxion/llming-com), and that's the same channel an AI assistant uses to inspect state, invoke commands, and push events into the running page.

<p align="center"><img src="https://raw.githubusercontent.com/Alyxion/llming-stage/main/media/readme-showcase.webp" alt="llming-stage sample showcase" width="760"></p>

`llming-com` ships the sessions, auth, command dispatcher, and the debug surface — without it, the AI side of the picture goes away. When you eventually deploy and the app no longer needs server reactivity, the same shell + view modules can ship as a static bundle to any CDN.

---

### What you get

- **An AI-debuggable runtime** — every reactive command, session, and event is browseable, invokable, and observable through one HTTP / MCP surface.
- **FastAPI-native app mounting** — create your own `FastAPI()` app and attach `Stage(app)`, or let `Stage()` create the default FastAPI app for compact demos. The internal `/_stage` routes and development reload are ensured once; server startup stays normal FastAPI/ASGI (`uvicorn main:app --reload`, deployment servers, etc.).
- **Modern frontend, zero boilerplate** — Vue 3 + Quasar 2 + bundled Tailwind utilities with a lazy-load orchestrator and an SPA router that keeps the WebSocket and view state alive across navigations.
- **Per-user sessions out of the box** — `llming-com` runs the wire and the auth; you write JS views and Python handlers.
- **Static-deployable** — when there's no server-side reactivity at runtime, the same code ships to GitHub Pages, S3, or any CDN.
- **No third-party network** — every asset is vendored. A page loaded from an `llming-stage` app makes zero requests to Google Fonts, jsDelivr, or any other external host. Privacy/GDPR-friendly by default; enforced by static and runtime tests.

---

### See it in action

```bash
poetry install
./samples/run.sh        # opens a web gallery at http://localhost:8000
```

Fourteen sample apps — from a tiny static app to generated decorator views, llming-com reactive loops, a Three.js particle tornado, an 8-chart ECharts dashboard, Plotly full-bundle charts, a core component workbench, and an optional-extension workbench — with dark/light theme, hot reload, and AI-debug control.

---

### Minimal app

```python
from llming_stage import Stage

if __name__ == "__main__":
    Stage(title="Hello world").add_view("/", "hello.vue").run()
```

```vue
<template>
  <main class="min-h-screen grid place-items-center p-8">
    <h1 class="text-5xl font-bold">Hello llming-stage</h1>
  </main>
</template>
```

For a purely static app, no Python file is needed:

```bash
llming-stage serve hello.vue
```

`Stage()` mounts the bundled assets, the Vue + Quasar shell, the SPA
router, bundled Tailwind utilities, and content-hash development reload
by default.

`stage.run()` is a thin local-development wrapper around `uvicorn.run`.
If you need workers, custom logging, TLS, or deployment process
management, run the same app directly with normal ASGI tooling.

Reactive apps add a typed session router and let Stage mount the
conventional session routes:

```python
from fastapi import FastAPI
from llming_stage import Stage

app = FastAPI()
stage = Stage(app)
sessions = stage.session()
counter = sessions.add_router("counter")

@counter.handler("inc")
async def inc(session, by: int = 1):
    value = int(session.state.get("count", 0)) + by
    session.state["count"] = value
    await session.call("home.setCounter", value)
    return {"ok": True}

stage.add_view("/", "home.vue")
```

The browser gets a real Vue + Quasar SPA from `.vue` view files.
`llming-com` carries the wire, the sessions, and the debug surface the
AI uses.

---

### Learn more

Full docs in [`docs/content/`](docs/content):

- [Quick start](docs/content/installation.md) · [Stage apps](docs/content/stage.md) · [App shell](docs/content/shell.md) · [Communication model](docs/content/communication-model.md)
- [llming-com integration](docs/content/llming-com.md) · [Assets & lazy loading](docs/content/lazy-loading.md)
- [Security](docs/content/security.md) · [API reference](docs/content/api.md)

<p align="center"><img src="https://raw.githubusercontent.com/Alyxion/llming-stage/main/media/runtime-architecture.png" alt="llming-stage runtime architecture" width="760"></p>

---

MIT licensed. © 2026 [Michael Ikemann](https://github.com/Alyxion). Bundled third-party files are listed in [`THIRD_PARTY.md`](THIRD_PARTY.md); no AGPL/GPL/LGPL is ever permitted.

