lllm2 0.2.0__tar.gz

lllm2-0.2.0/.github/scripts/check_dist.py

@@ -0,0 +1,31 @@
+"""Smoke-test the installed wheel with Python's isolated mode (-I)."""
+
+import json
+import os
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+
+package = files('lllm2')
+for name in ('models.json', 'recommendations.json'):
+    assert json.loads(package.joinpath(name).read_text()), name
+for name in ('static/index.html', 'static/panel.js', 'static/panel.css',
+             'templates/qwen3.8-27b.jinja'):
+    assert package.joinpath(name).read_text().strip(), name
+
+installed_version = version('lllm2')
+if os.environ.get('GITHUB_REF_TYPE') == 'tag':
+    tag = os.environ['GITHUB_REF_NAME']
+    assert tag.removeprefix('v') == installed_version, (
+        f'Tag {tag} does not match package version {installed_version}'
+    )
+
+with tempfile.TemporaryDirectory() as directory:
+    subprocess.run([sys.executable, '-I', '-m', 'lllm2', '--help'],
+                   cwd=directory, check=True)
+    subprocess.run([str(Path(sys.executable).with_name('lllm2')), '--help'],
+                   cwd=directory, check=True)
+print(f'Installed lllm2 {installed_version}: CLI and package assets OK')

lllm2-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.venv-dist/
+dist/
+docs/_build/

lllm2-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lllm2-0.2.0/NOTICE

@@ -0,0 +1,7 @@
+lllm2 includes GGUF inspection, model catalogue data and downloads adapted from
+gilesknap/lllm3090, revision e56c8d0fb19f76a254b5453bf7f206b229705d6a.
+Copyright Giles Knap and contributors. Licensed under Apache License 2.0.
+Modifications: isolated configuration, robust download resume streamlined catalogue, inherited launch defaults and calibrated context planning.
+The Qwen3.8 chat-template override is also retained from that revision.
+Claude Code session environment configuration is adapted from the lllm3090
+Claude launcher, with live engine context discovery and bounded output tokens.

lllm2-0.2.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: lllm2
+Version: 0.2.0
+Summary: Local NVIDIA LLM experimentation workbench
+Project-URL: GitHub, https://github.com/gilesknap/lllm2
+Project-URL: Documentation, https://gilesknap.github.io/lllm2/
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Requires-Dist: typer<1,>=0.16
+Description-Content-Type: text/markdown
+
+# lllm2
+
+A local NVIDIA LLM workbench: download GGUF models, run llama.cpp, compare
+settings and save measured results from a browser panel.
+
+## Install and run
+
+On Linux with Python 3.11+ and a working NVIDIA driver,
+[install uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv tool install lllm2
+lllm2 engines install cuda
+lllm2
+```
+
+The engine build needs Git, CMake, a C++ compiler and the CUDA toolkit; install
+those separately. Existing builds can also be discovered. Open
+<http://127.0.0.1:8082>, download a model and click **Start**. The model API
+listens at `http://127.0.0.1:1920/v1`.
+
+[Documentation](https://gilesknap.github.io/lllm2/) covers
+[getting started](docs/tutorial.md), [common tasks](docs/how-to.md),
+[reference](docs/reference.md), [measurements](docs/explanation.md) and
+[development and releases](docs/development.md).

lllm2-0.2.0/README.md

@@ -0,0 +1,25 @@
+# lllm2
+
+A local NVIDIA LLM workbench: download GGUF models, run llama.cpp, compare
+settings and save measured results from a browser panel.
+
+## Install and run
+
+On Linux with Python 3.11+ and a working NVIDIA driver,
+[install uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv tool install lllm2
+lllm2 engines install cuda
+lllm2
+```
+
+The engine build needs Git, CMake, a C++ compiler and the CUDA toolkit; install
+those separately. Existing builds can also be discovered. Open
+<http://127.0.0.1:8082>, download a model and click **Start**. The model API
+listens at `http://127.0.0.1:1920/v1`.
+
+[Documentation](https://gilesknap.github.io/lllm2/) covers
+[getting started](docs/tutorial.md), [common tasks](docs/how-to.md),
+[reference](docs/reference.md), [measurements](docs/explanation.md) and
+[development and releases](docs/development.md).

lllm2-0.2.0/docs/conf.py

@@ -0,0 +1,21 @@
+"""Sphinx configuration, using the same theme as lllm3090."""
+
+from importlib.metadata import version as package_version
+
+project = 'lllm2'
+author = 'Giles Knap'
+copyright = '2026, Giles Knap'
+release = package_version(project)
+version = release
+extensions = ['myst_parser', 'sphinx_copybutton']
+myst_heading_anchors = 3
+nitpicky = True
+exclude_patterns = ['_build']
+html_theme = 'pydata_sphinx_theme'
+html_title = f'{project} {release}'
+html_theme_options = {
+    'logo': {'text': project},
+    'github_url': 'https://github.com/gilesknap/lllm2',
+    'navbar_end': ['theme-switcher', 'navbar-icon-links'],
+    'show_toc_level': 2,
+}

lllm2-0.2.0/docs/development.md

@@ -0,0 +1,68 @@
+# Development and releases
+
+## Local checks
+
+From a checkout, run:
+
+```bash
+uv sync --locked --group docs
+uv run --locked python -m unittest discover -s tests -v
+node tests/test_ui_browser.cjs
+uv run --locked sphinx-build -W --keep-going -b html docs docs/_build/html
+uv run --locked python -m build
+uv run --locked twine check --strict dist/*
+```
+
+Browser checks need Node.js 22 and Chrome; set `CHROME_BIN` if Chrome is not
+at `/opt/google/chrome/chrome`. Tests use mocked engines and browser data;
+no GPU or model download is required. Preview the built documentation with
+`uv run python -m http.server --directory docs/_build/html`.
+
+## CI and publishing setup
+
+Pull requests, pushes to `main` and all tags run Python tests, browser tests,
+a strict docs build and distribution checks. CI installs the built wheel in
+isolation and checks its CLI, catalogue, recommendations and UI/template assets.
+Successful `main` builds deploy documentation; version tags publish the same
+checked distribution artifacts to PyPI.
+
+Configure these once in the hosting accounts:
+
+1. In GitHub **Settings → Pages**, select **GitHub Actions** as the build source
+   ([Pages instructions](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)).
+2. Create the repository environment `release`.
+3. Add a [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
+   for project `lllm2` (or a pending publisher for the first release):
+
+| Field | Value |
+| --- | --- |
+| Owner | `gilesknap` |
+| Repository | `lllm2` |
+| Workflow | `_pypi.yml` |
+| Environment | `release` |
+
+The reusable publishing workflow is `_pypi.yml`; use that filename when
+registering the publisher. [Trusted publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+uses the workflow identity, with no PyPI API token in repository secrets.
+
+## Release
+
+Run the checks above and merge the changes to `main`. Tag the merged commit
+with the new version and push it, for example:
+
+```bash
+git switch main
+git pull --ff-only
+git tag 0.1.2
+git push origin refs/tags/0.1.2
+```
+
+Hatch derives the package version from Git using `hatch-vcs`: `0.1.2` and
+`v0.1.2` both build version `0.1.2`. There is no version string to update in
+`pyproject.toml` or `uv.lock` for a release. Builds between tags get a development
+version. CI checks that the built wheel matches the release tag. Each release
+needs a new version. Once published, users install with `uv tool install lllm2`
+or upgrade with `uv tool upgrade lllm2`.
+
+The tagged commit must contain the workflow changes: fixing `main` does not
+rerun an existing tag.

lllm2-0.2.0/docs/explanation.md

@@ -0,0 +1,22 @@
+# Defaults and measurements
+
+Defaults are starting points. A matching measured profile can supply tuning;
+otherwise the workbench uses inherited estimates or generic settings. The
+panel records the source and qualifications. Changing the GPU, checkpoint
+or engine can invalidate a measurement; a speed observed on one card is
+not a prediction for another.
+
+**Context** is the total allocation shared across **slots**. More slots allow
+concurrent conversations but leave less context for each one. Weights, KV
+cache and runtime buffers all compete for VRAM. Automatic placement can put
+weights in system RAM when the engine supports it, with a possible speed cost.
+
+**Prefill** measures prompt processing; **decode** measures output generation.
+Warm runs can reuse prompt tokens, so compare them with like-for-like runs.
+A completed speed test alone does not establish quality or stability. Read
+the workload checks and failure evidence too.
+
+Context search tests large prompts and an output budget, retaining failed
+probes. A timeout is inconclusive, rather than proof of a memory limit.
+Recommended context applies headroom to a successful probe; it remains an
+estimate for other workloads.

lllm2-0.2.0/docs/how-to.md

@@ -0,0 +1,76 @@
+# Common tasks
+
+## Use your own GGUF or engine
+
+Put GGUF files under `~/models`, or set a different directory before starting:
+
+```bash
+LLLM2_MODELS_DIR=/data/models lllm2
+```
+
+Choose the checkpoint in **All models**. Under **Customize settings**, select
+the llama-server binary, backend and GPU. To discover engines elsewhere, set
+`LLLM2_ENGINE_ROOTS` to colon-separated directories.
+
+## Serve from the terminal
+
+```bash
+lllm2 models
+lllm2 engines list
+lllm2 launch --model /data/models/model.gguf --engine /path/to/llama-server
+```
+
+With no selection options, `lllm2 launch` looks for a compatible installed
+recommendation. It runs in the foreground; Ctrl-C stops the engine.
+
+## Connect a client
+
+Start a model first. OpenAI-compatible clients use
+`http://127.0.0.1:1920/v1`; query `/v1/models` for the served model ID.
+
+If their CLIs are installed, these wrappers configure a local session and
+forward additional arguments:
+
+```bash
+lllm2 claude
+lllm2 codex
+lllm2 pi
+```
+
+The wrappers read the running model's context and slots. Relaunch the client
+after changing server context. Use `lllm2 claude -- --help` (or the equivalent
+wrapper) to read the client's own help.
+
+## Compare and save settings
+
+In **Experiments**, choose workloads and run a baseline. Change settings and
+add combinations, or run **Baseline + single options**. **Discover usable
+context** adds context probes; long prompts can take several minutes.
+
+Inspect completed results and their evidence before loading a configuration
+into **Launch**. Click **Save my settings** to keep it. Launch and experiment
+drafts are separate; loading a result does not save it or restart the model.
+Export results as CSV for comparison or JSON for the full record.
+
+## Access over SSH
+
+Forward the panel and API ports from your client machine:
+
+```bash
+ssh -N -L 8082:127.0.0.1:8082 -L 1920:127.0.0.1:1920 user@gpu-host
+```
+
+Open the usual localhost URL. `lllm2 panel --host 0.0.0.0` also exposes the
+panel on a trusted LAN, with no login or TLS; anyone who can reach it can
+control the workbench.
+
+## Troubleshoot
+
+- **No engine:** check `lllm2 engines list` and the configured search roots;
+  build CUDA or Vulkan if needed.
+- **No GPU:** check `nvidia-smi` and the selected engine's device probe.
+- **Startup fails:** read the engine log, reduce context or GPU layers, and
+  disable unsupported acceleration options. Automatic placement needs an
+  engine with memory-fitting support.
+- **Client exceeds context:** increase context or reduce slots, then restart
+  the model and client. Available memory still limits the allocation.

lllm2-0.2.0/docs/index.md

@@ -0,0 +1,22 @@
+# lllm2
+
+Run local models and measure what works on your NVIDIA GPU. The browser panel
+downloads GGUF checkpoints, controls llama.cpp and compares speed, context
+capacity and settings. Launch a model for everyday use, or use **Experiments**
+to test changes before saving them.
+
+- **[Tutorial](tutorial.md):** install and serve your first model.
+- **[How-to](how-to.md):** use your own models, connect clients and compare settings.
+- **[Reference](reference.md):** commands, paths and ports.
+- **[Explanation](explanation.md):** what the measurements and defaults mean.
+- **[Development](development.md):** run checks and publish a release.
+
+```{toctree}
+:hidden:
+
+tutorial
+how-to
+reference
+explanation
+development
+```

lllm2-0.2.0/docs/reference.md

@@ -0,0 +1,38 @@
+# Reference
+
+## Commands
+
+Run `lllm2 COMMAND --help` for all options.
+
+| Command | Purpose |
+| --- | --- |
+| `lllm2` or `lllm2 panel` | Start the panel; `--host` and `--port` control its listener. |
+| `lllm2 models [--json]` | List installed GGUF checkpoints. |
+| `lllm2 engines list [--json]` | List discovered llama-server builds. |
+| `lllm2 engines install cuda\|vulkan` | Build an engine; accepts `--ref`, `--name`, `--jobs` and `--cuda-architectures`. |
+| `lllm2 launch` | Serve in the foreground; accepts `--model`, `--engine`, `--backend CUDA\|Vulkan`, `--device` and `--timeout`. |
+| `lllm2 claude`, `lllm2 codex`, `lllm2 pi` | Connect an installed coding-agent CLI to the running model. |
+
+## Paths and ports
+
+Set environment variables before starting the workbench or a client wrapper.
+
+| Variable | Default | Contents |
+| --- | --- | --- |
+| `LLLM2_MODELS_DIR` | `~/models` | GGUF checkpoints and downloads. |
+| `LLLM2_STATE_DIR` | `~/.local/state/lllm2` | `workbench.sqlite3` and the panel lock. |
+| `LLLM2_ENGINE_HOME` | `~/.local/share/lllm2/engines` | Newly compiled engines. |
+| `LLLM2_ENGINE_ROOTS` | Engine home and `~/.local/share/lllm3090` | Colon-separated engine search roots; setting it replaces the defaults. |
+| `LLLM2_ENGINE_PORT` | `1920` | Model server port on loopback. |
+
+The panel defaults to `127.0.0.1:8082`. Its controls use `/api/*`; model
+clients connect to the separate llama.cpp server on port 1920. Protocol
+support depends on the selected engine build.
+
+## Packaged data
+
+`lllm2/models.json` contains the downloadable catalogue;
+`lllm2/recommendations.json` records measured recommendations and their
+provenance. The package also includes the panel's HTML, CSS and JavaScript
+and model-specific chat templates. User settings and experiment results
+live in the state directory.

lllm2-0.2.0/docs/tutorial.md

@@ -0,0 +1,45 @@
+# Install and serve a model
+
+You need Linux, Python 3.11+, a working NVIDIA driver and enough RAM and disk
+space for your chosen model. Install [uv](https://docs.astral.sh/uv/getting-started/installation/),
+then install the workbench:
+
+```bash
+uv tool install lllm2
+```
+
+## Prepare an engine
+
+Existing llama-server builds under the [engine search paths](reference.md#paths-and-ports)
+are discovered automatically. Otherwise install Git, CMake, a C++ compiler,
+the NVIDIA CUDA toolkit and a compiler compatible with that toolkit, then run:
+
+```bash
+lllm2 engines install cuda
+lllm2 engines list
+```
+
+This compiles llama.cpp into your user directory. System prerequisites are
+installed separately; missing build tools produce installation hints.
+For Vulkan, use `lllm2 engines install vulkan` with Vulkan development
+libraries and `glslc` installed. Use `--ref TAG` to choose a particular
+llama.cpp revision; the default is `master`.
+
+## Start the panel
+
+```bash
+lllm2
+```
+
+1. Open <http://127.0.0.1:8082> and choose a model from the catalogue.
+2. Download it, or select an installed checkpoint in **All models**.
+3. Review **Customize settings** if needed, then click **Start**.
+4. When ready, connect a client to `http://127.0.0.1:1920/v1`, or use one of
+   the [coding-agent launchers](how-to.md#connect-a-client).
+
+Use **Stop** to release the GPU. Keep the panel process running while serving.
+
+## Upgrade
+
+Stop the panel and any foreground launch, run `uv tool upgrade lllm2`, then
+start the panel again. Engine builds and model downloads are managed separately.

lllm2-0.2.0/lllm2/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())