Metadata-Version: 2.4
Name: splent_feature_generator
Version: 0.4.3
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: splent_framework>=1.30.0
Dynamic: license-file

# splent_feature_generator

The `generator` feature of a [SPLENT](https://splent.io) product line.

A SPLENT feature is a Python package that a product composes with others:
its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
`[tool.splent.contract]` section of `pyproject.toml`, which
`splent feature:contract --write` keeps in sync with the source.

## Use it in a product

```bash
splent feature:add splent_feature_generator
```

The pages (the landing, the six steps of the random generator and the LLM
generator) extend `shell('app')`, so a product that points the application
shell at another layout (`SPLENT_SHELL_APP`) moves them with it.

They are written in Bootstrap 5.2 and draw their icons with feather, and
take both from the shell: its stylesheet, `window.bootstrap` and
`window.feather`, as AdminKit brings them. The generator starts its own
tooltips and draws the icons of each step the wizard swaps in. What
Bootstrap has no class for (the list of steps, the sliders, the result
list, the UVL preview) is in `assets/css/generator.css`, which the pages
link themselves.

## In the browser

Both generators run in the visitor's browser, so a batch of models costs
the server nothing. What runs there is the feature's frontend
(`frontend/package.json`), built by the SPLENT toolchain into
`assets/dist`:

| Entry | What it is |
|-------|------------|
| `generator` | The Pyodide runtime: it loads Pyodide, installs the wheels (`WHEELS` in `assets/js/scripts.js`) and runs `fmgen_wrapper.py`; the sliders, and the ZIP download (jszip, file-saver, nouislider) |
| `ui`, `wizard`, `wizard_spa` | Icons and tooltips, the wizard's helpers, and the in-place navigation that keeps the runtime alive across steps |
| `uvl_editor` | CodeMirror 5 and the UVL mode of the "View" dialogs |
| `llm_page` | The LLM page, and the module worker that runs WebLLM (`llm-worker.js`), a chunk of its own that loads only when the page first needs it |

Every entry is a module, drawn with `feature_script` in the order the
pages need them. jszip, file-saver, nouislider, codemirror,
`@mlc-ai/web-llm` and `pyodide` come from npm, at exact versions, and
nothing loads from another site but the model weights.

The Pyodide runtime is npm's, copied unmodified (MPL-2.0) into
`assets/dist/pyodide/` (`frontend/webpack.extra.js`), with
`fmgen_wrapper.py` from `frontend/pyodide/`. The Python wheels it
installs go beside it. They are declared in `splent.vendored`, each with
its version, licence, source and sha256:

- From PyPI, or from Pyodide's own index for micropip, packaging and
  python-sat. `feature:compile` and the release fetch them with
  `pip download` into `frontend/vendored/` (never versioned) and check
  each against its sha256; the release fetches them again.
- Kept in `frontend/wheels/`: fm_generator, built from `vendor/`, and
  astutils and dd, which PyPI publishes as sdists only. They are checked
  against their sha256 too.

python-sat is the build Pyodide's index lists for the runtime shipped: it
is what "Ensure satisfiable" asks, and each model then says whether the
solver found it satisfiable, found it not to be after 20 tries, or could
not check it. `frontend/licenses/` has the terms of the wheels that carry
none of their own, Pyodide's notices, and the SAT solvers compiled into
python-sat, which `splent.licenseTexts` puts in `assets/meta/third_party.json`.

### Content-Security-Policy

The pages ask, in `splent.csp`, for what a product approves in
`[tool.splent.csp]`:

| Directive | Source | Why |
|-----------|--------|-----|
| `script-src` | `'wasm-unsafe-eval'` | Pyodide compiles WebAssembly on the page |
| `connect-src` | `https://huggingface.co` | The model configs and tokenizers of WebLLM |
| `connect-src` | `https://*.huggingface.co`, `https://*.hf.co` | Where Hugging Face redirects the weight shards (`us.aws.cdn.hf.co`, `cdn-lfs*.huggingface.co`) |
| `connect-src` | `https://raw.githubusercontent.com` | The model libraries (`mlc-ai/binary-mlc-llm-libs`) |

```toml
[tool.splent.csp]
generator = [
    "script-src 'wasm-unsafe-eval'",
    "connect-src https://huggingface.co https://*.huggingface.co https://*.hf.co https://raw.githubusercontent.com",
]
```

The weights are downloaded by the worker, which runs under the policy of
its own script and not of the page; the hosts are listed for when that
policy is composed too.

The random wizard keeps its parameters in the session, only the keys and
limits `params.py` declares, and opens step 6 once every step before it
passed its validator.

## Menus

generator registers one entry in the framework's menu registry.

| Key | Section | Order | Icon | Opens | Shown to |
|-----|---------|-------|------|-------|----------|
| `generator` | `site` | 40 | `cpu` | `/generator`, and is current on every generator page | Everyone |

A product hides or reorders it by key in its `[tool.splent.layout.menu]`.
The generator has no sidebar hook any more: a shell that still fills its
sidebar from `layout.sidebar.top` shows no Generate models entry until it
draws the registry.

## Develop

```bash
splent feature:test splent_feature_generator
splent feature:contract splent_feature_generator
```

## Release

```bash
splent feature:release splent_feature_generator --dry-run --bump patch
splent feature:release splent_feature_generator
```

The first command rehearses the release and changes nothing. The second
publishes it to the git forge and to PyPI, and a PyPI version is permanent.
