llama-launcher 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. llama_launcher-0.1.0/LICENSE +21 -0
  2. llama_launcher-0.1.0/PKG-INFO +130 -0
  3. llama_launcher-0.1.0/README.md +100 -0
  4. llama_launcher-0.1.0/llama_launcher/__init__.py +0 -0
  5. llama_launcher-0.1.0/llama_launcher/__main__.py +89 -0
  6. llama_launcher-0.1.0/llama_launcher/args.py +140 -0
  7. llama_launcher-0.1.0/llama_launcher/catalog.py +181 -0
  8. llama_launcher-0.1.0/llama_launcher/cmdimport.py +435 -0
  9. llama_launcher-0.1.0/llama_launcher/config.py +339 -0
  10. llama_launcher-0.1.0/llama_launcher/controller.py +294 -0
  11. llama_launcher-0.1.0/llama_launcher/errors.py +88 -0
  12. llama_launcher-0.1.0/llama_launcher/gguf.py +109 -0
  13. llama_launcher-0.1.0/llama_launcher/launch.py +322 -0
  14. llama_launcher-0.1.0/llama_launcher/logs.py +47 -0
  15. llama_launcher-0.1.0/llama_launcher/paths.py +62 -0
  16. llama_launcher-0.1.0/llama_launcher/runtimes.py +156 -0
  17. llama_launcher-0.1.0/llama_launcher/server.py +370 -0
  18. llama_launcher-0.1.0/llama_launcher/server_flags.py +28 -0
  19. llama_launcher-0.1.0/llama_launcher/single_instance.py +57 -0
  20. llama_launcher-0.1.0/llama_launcher/startup.py +37 -0
  21. llama_launcher-0.1.0/llama_launcher/ui/__init__.py +0 -0
  22. llama_launcher-0.1.0/llama_launcher/ui/icons.py +169 -0
  23. llama_launcher-0.1.0/llama_launcher/ui/marquee.py +54 -0
  24. llama_launcher-0.1.0/llama_launcher/ui/profile_editor.py +228 -0
  25. llama_launcher-0.1.0/llama_launcher/ui/settings_window.py +131 -0
  26. llama_launcher-0.1.0/llama_launcher/ui/tabs/__init__.py +0 -0
  27. llama_launcher-0.1.0/llama_launcher/ui/tabs/base.py +28 -0
  28. llama_launcher-0.1.0/llama_launcher/ui/tabs/folders.py +116 -0
  29. llama_launcher-0.1.0/llama_launcher/ui/tabs/general.py +75 -0
  30. llama_launcher-0.1.0/llama_launcher/ui/tabs/global_options.py +44 -0
  31. llama_launcher-0.1.0/llama_launcher/ui/tabs/profiles.py +168 -0
  32. llama_launcher-0.1.0/llama_launcher/ui/tabs/runtimes.py +112 -0
  33. llama_launcher-0.1.0/llama_launcher/ui/toast.py +68 -0
  34. llama_launcher-0.1.0/llama_launcher/ui/tray.py +356 -0
  35. llama_launcher-0.1.0/llama_launcher/ui/widgets.py +110 -0
  36. llama_launcher-0.1.0/llama_launcher/winjob.py +70 -0
  37. llama_launcher-0.1.0/llama_launcher.egg-info/PKG-INFO +130 -0
  38. llama_launcher-0.1.0/llama_launcher.egg-info/SOURCES.txt +42 -0
  39. llama_launcher-0.1.0/llama_launcher.egg-info/dependency_links.txt +1 -0
  40. llama_launcher-0.1.0/llama_launcher.egg-info/entry_points.txt +2 -0
  41. llama_launcher-0.1.0/llama_launcher.egg-info/requires.txt +11 -0
  42. llama_launcher-0.1.0/llama_launcher.egg-info/top_level.txt +1 -0
  43. llama_launcher-0.1.0/pyproject.toml +62 -0
  44. llama_launcher-0.1.0/setup.cfg +4 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 hhuangpanda
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.4
2
+ Name: llama-launcher
3
+ Version: 0.1.0
4
+ Summary: Windows tray app to manage and launch local GGUF models with llama-server, using per-model profiles and your own llama.cpp builds
5
+ Author: hhuangpanda
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/hhuangpanda/llama-launcher
8
+ Keywords: llama.cpp,llama-server,gguf,llm,tray,windows
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Win32 (MS Windows)
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
16
+ Classifier: Topic :: Utilities
17
+ Requires-Python: >=3.13
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: PySide6-Essentials>=6.12
21
+ Requires-Dist: tomlkit>=0.15
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=9; extra == "dev"
24
+ Requires-Dist: pytest-qt>=4.5; extra == "dev"
25
+ Requires-Dist: pytest-timeout>=2.4; extra == "dev"
26
+ Requires-Dist: ruff>=0.14; extra == "dev"
27
+ Provides-Extra: build
28
+ Requires-Dist: pyinstaller>=6; extra == "build"
29
+ Dynamic: license-file
30
+
31
+ # llama-launcher <img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/logo.png" alt="" width="40" align="right">
32
+
33
+ Windows tray app that runs local GGUF models through llama-server, one at a time,
34
+ with per-model launch profiles and your own llama.cpp builds.
35
+
36
+ ## Requirements
37
+
38
+ - Windows 10 or later, Python 3.13 (to run from source).
39
+ - A llama.cpp `llama-server` build (a release zip or your own); the app does not ship one.
40
+ - GGUF models.
41
+
42
+ ## Run
43
+
44
+ ```powershell
45
+ py -3.13 -m venv .venv
46
+ .venv\Scripts\python.exe -m pip install -e .[dev]
47
+ .venv\Scripts\pythonw.exe -m llama_launcher
48
+
49
+ # packaged build: dist\llama-launcher\llama-launcher.exe
50
+ .venv\Scripts\python.exe -m pip install -e .[build]
51
+ .venv\Scripts\python.exe tools\build.py
52
+ ```
53
+
54
+ Settings, profiles and logs live in `%LOCALAPPDATA%\llama-launcher\`
55
+ (override with `LLAMA_LAUNCHER_HOME`).
56
+
57
+ ## Screenshots
58
+
59
+ <p>
60
+ <a href="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/tray-menu.png"><img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/tray-menu.png" alt="Tray menu with a running model and its profiles" width="49%"></a>
61
+ <a href="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/settings-profiles.png"><img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/settings-profiles.png" alt="Settings: editing a profile, with the resulting command line" width="49%"></a>
62
+ </p>
63
+
64
+ ## Concepts
65
+
66
+ - **Runtime**: a folder with `llama-server.exe` and its DLLs (a release zip or your own build).
67
+ One is the default; a profile can pick another.
68
+ - **Model folders**: scanned recursively.
69
+ GGUF headers decide what each file is:
70
+ models,
71
+ mmproj files (paired when `clip.vision.projection_dim` equals the model's `embedding_length`)
72
+ and draft heads (`<arch>-assistant`).
73
+ A sidecar is attached automatically only when exactly one fits in the model's own folder.
74
+ - **Profile**: one way to launch a model.
75
+ A model can have several.
76
+ Every scanned model has an implicit `default_profile` until you save one.
77
+ - **Flags** are layered, later wins per flag
78
+ (aliases like `-c`/`--ctx-size` and `--x`/`--no-x` count as one flag):
79
+ model fields, global K/V and idle, global args, profile `unset`, profile fields, profile args,
80
+ then the context picked in the tray.
81
+ `--host`, `--port`, `--api-key` and `--model` are managed by the app.
82
+ Flags the selected build doesn't know are rejected before launch.
83
+ - **Idle**: `sleep` passes `--sleep-idle-seconds` (VRAM freed, next request reloads),
84
+ `stop` ends the process once llama-server reports it is asleep,
85
+ `off` keeps the model loaded.
86
+
87
+ ## Files
88
+
89
+ `settings.toml` and `profiles.toml` are meant to be hand-editable;
90
+ the app reloads them on change and keeps the last good version if an edit doesn't parse.
91
+ Logs: `logs\server.log` (current or last server run, with the full command line)
92
+ and `server.prev.log`, `app.log` and `app.prev.log`.
93
+
94
+ ## Importing existing launch commands
95
+
96
+ Profiles can be created from llama-server command lines you already use (`.bat` files, scripts):
97
+
98
+ ```powershell
99
+ .venv\Scripts\python.exe -m llama_launcher.cmdimport commands.json # dry run: shows what would change
100
+ .venv\Scripts\python.exe -m llama_launcher.cmdimport commands.json --write # apply
101
+ ```
102
+
103
+ `commands.json` is a list of `{"name": "...", "command": [...]}`,
104
+ where `command` is the full llama-server command line (exe first), as a list or one string;
105
+ `-` reads it from stdin.
106
+
107
+ - The exe's folder becomes a runtime;
108
+ `-m`, `--mmproj`, `-md`, `--alias`, `-c`, `-ctk`, `-ctv` become model/profile fields;
109
+ everything else goes to the profile's args.
110
+ - When global args are empty, flags every command shares become the global args.
111
+ - Runtimes and model folders are matched by path.
112
+ A profile that exists with other settings is reported as a conflict and skipped unless `--replace` is given;
113
+ re-running adds nothing.
114
+ - Each result says whether the profile rebuilds exactly the flags of the original command.
115
+
116
+ ## Tests
117
+
118
+ ```powershell
119
+ .venv\Scripts\python.exe -m pytest # unit, integration (fake server), UI
120
+ ```
121
+
122
+ `pytest -m real` loads real models;
123
+ set `LLAMA_LAUNCHER_TEST_MODELS` (a model folder)
124
+ and `LLAMA_LAUNCHER_TEST_RUNTIMES` (llama-server folders, `;`-separated) first,
125
+ in the environment or in a git-ignored `.env` (copy `.env.example`).
126
+ Test IDs are listed in [docs/test-cases.md](https://github.com/hhuangpanda/llama-launcher/blob/main/docs/test-cases.md).
127
+
128
+ ## License
129
+
130
+ MIT, see [LICENSE](https://github.com/hhuangpanda/llama-launcher/blob/main/LICENSE).
@@ -0,0 +1,100 @@
1
+ # llama-launcher <img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/logo.png" alt="" width="40" align="right">
2
+
3
+ Windows tray app that runs local GGUF models through llama-server, one at a time,
4
+ with per-model launch profiles and your own llama.cpp builds.
5
+
6
+ ## Requirements
7
+
8
+ - Windows 10 or later, Python 3.13 (to run from source).
9
+ - A llama.cpp `llama-server` build (a release zip or your own); the app does not ship one.
10
+ - GGUF models.
11
+
12
+ ## Run
13
+
14
+ ```powershell
15
+ py -3.13 -m venv .venv
16
+ .venv\Scripts\python.exe -m pip install -e .[dev]
17
+ .venv\Scripts\pythonw.exe -m llama_launcher
18
+
19
+ # packaged build: dist\llama-launcher\llama-launcher.exe
20
+ .venv\Scripts\python.exe -m pip install -e .[build]
21
+ .venv\Scripts\python.exe tools\build.py
22
+ ```
23
+
24
+ Settings, profiles and logs live in `%LOCALAPPDATA%\llama-launcher\`
25
+ (override with `LLAMA_LAUNCHER_HOME`).
26
+
27
+ ## Screenshots
28
+
29
+ <p>
30
+ <a href="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/tray-menu.png"><img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/tray-menu.png" alt="Tray menu with a running model and its profiles" width="49%"></a>
31
+ <a href="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/settings-profiles.png"><img src="https://raw.githubusercontent.com/hhuangpanda/llama-launcher/main/docs/images/settings-profiles.png" alt="Settings: editing a profile, with the resulting command line" width="49%"></a>
32
+ </p>
33
+
34
+ ## Concepts
35
+
36
+ - **Runtime**: a folder with `llama-server.exe` and its DLLs (a release zip or your own build).
37
+ One is the default; a profile can pick another.
38
+ - **Model folders**: scanned recursively.
39
+ GGUF headers decide what each file is:
40
+ models,
41
+ mmproj files (paired when `clip.vision.projection_dim` equals the model's `embedding_length`)
42
+ and draft heads (`<arch>-assistant`).
43
+ A sidecar is attached automatically only when exactly one fits in the model's own folder.
44
+ - **Profile**: one way to launch a model.
45
+ A model can have several.
46
+ Every scanned model has an implicit `default_profile` until you save one.
47
+ - **Flags** are layered, later wins per flag
48
+ (aliases like `-c`/`--ctx-size` and `--x`/`--no-x` count as one flag):
49
+ model fields, global K/V and idle, global args, profile `unset`, profile fields, profile args,
50
+ then the context picked in the tray.
51
+ `--host`, `--port`, `--api-key` and `--model` are managed by the app.
52
+ Flags the selected build doesn't know are rejected before launch.
53
+ - **Idle**: `sleep` passes `--sleep-idle-seconds` (VRAM freed, next request reloads),
54
+ `stop` ends the process once llama-server reports it is asleep,
55
+ `off` keeps the model loaded.
56
+
57
+ ## Files
58
+
59
+ `settings.toml` and `profiles.toml` are meant to be hand-editable;
60
+ the app reloads them on change and keeps the last good version if an edit doesn't parse.
61
+ Logs: `logs\server.log` (current or last server run, with the full command line)
62
+ and `server.prev.log`, `app.log` and `app.prev.log`.
63
+
64
+ ## Importing existing launch commands
65
+
66
+ Profiles can be created from llama-server command lines you already use (`.bat` files, scripts):
67
+
68
+ ```powershell
69
+ .venv\Scripts\python.exe -m llama_launcher.cmdimport commands.json # dry run: shows what would change
70
+ .venv\Scripts\python.exe -m llama_launcher.cmdimport commands.json --write # apply
71
+ ```
72
+
73
+ `commands.json` is a list of `{"name": "...", "command": [...]}`,
74
+ where `command` is the full llama-server command line (exe first), as a list or one string;
75
+ `-` reads it from stdin.
76
+
77
+ - The exe's folder becomes a runtime;
78
+ `-m`, `--mmproj`, `-md`, `--alias`, `-c`, `-ctk`, `-ctv` become model/profile fields;
79
+ everything else goes to the profile's args.
80
+ - When global args are empty, flags every command shares become the global args.
81
+ - Runtimes and model folders are matched by path.
82
+ A profile that exists with other settings is reported as a conflict and skipped unless `--replace` is given;
83
+ re-running adds nothing.
84
+ - Each result says whether the profile rebuilds exactly the flags of the original command.
85
+
86
+ ## Tests
87
+
88
+ ```powershell
89
+ .venv\Scripts\python.exe -m pytest # unit, integration (fake server), UI
90
+ ```
91
+
92
+ `pytest -m real` loads real models;
93
+ set `LLAMA_LAUNCHER_TEST_MODELS` (a model folder)
94
+ and `LLAMA_LAUNCHER_TEST_RUNTIMES` (llama-server folders, `;`-separated) first,
95
+ in the environment or in a git-ignored `.env` (copy `.env.example`).
96
+ Test IDs are listed in [docs/test-cases.md](https://github.com/hhuangpanda/llama-launcher/blob/main/docs/test-cases.md).
97
+
98
+ ## License
99
+
100
+ MIT, see [LICENSE](https://github.com/hhuangpanda/llama-launcher/blob/main/LICENSE).
File without changes
@@ -0,0 +1,89 @@
1
+ """Entry point: single-instance check, then the tray app. `--quit` asks a running instance to quit."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import sys
7
+
8
+ from PySide6.QtGui import QCursor
9
+ from PySide6.QtWidgets import QApplication, QSystemTrayIcon
10
+
11
+ from llama_launcher import paths
12
+ from llama_launcher.controller import Controller
13
+ from llama_launcher.logs import setup_app_log
14
+ from llama_launcher.single_instance import QUIT, InstanceServer, notify_existing
15
+ from llama_launcher.ui.icons import app_icon
16
+
17
+ log = logging.getLogger("llama_launcher")
18
+
19
+
20
+ class App:
21
+ def __init__(self, controller: Controller, instance_name: str | None = None):
22
+ from llama_launcher.ui.settings_window import SettingsWindow
23
+ from llama_launcher.ui.tray import Tray
24
+
25
+ self._window_cls = SettingsWindow
26
+ self.c = controller
27
+ self.window = None
28
+ self.instance = InstanceServer(instance_name)
29
+ self.instance.message.connect(self._on_message)
30
+ self.tray = Tray(controller, self.open_settings, self.quit)
31
+ controller.manager.watch_port(controller.port_target)
32
+
33
+ def _on_message(self, message: str) -> None:
34
+ if message == QUIT.decode():
35
+ self.quit() # same as the tray's Quit: unsaved Settings changes are asked about first
36
+ else:
37
+ self.open_settings()
38
+
39
+ def show_started(self) -> None:
40
+ from llama_launcher.ui.toast import Toast
41
+
42
+ self._toast = Toast(
43
+ "llama-launcher is running",
44
+ "Check system tray. Click here to see menu.",
45
+ lambda: self.tray.menu.popup(QCursor.pos()),
46
+ )
47
+ self._toast.popup()
48
+
49
+ def open_settings(self):
50
+ if self.window is None:
51
+ self.window = self._window_cls(self.c)
52
+ self.window.bring_to_front()
53
+ return self.window
54
+
55
+ def quit(self) -> None:
56
+ if self.window is not None and self.window.isVisible() and not self.window.close():
57
+ return
58
+ self.tray.icon.hide()
59
+ self.c.shutdown()
60
+ QApplication.quit()
61
+
62
+
63
+ def main() -> int:
64
+ app = QApplication(sys.argv)
65
+ app.setQuitOnLastWindowClosed(False)
66
+ app.setApplicationName("llama-launcher")
67
+ app.setWindowIcon(app_icon())
68
+ if "--quit" in sys.argv[1:]:
69
+ return 0 if notify_existing(message=QUIT) else 1 # 1: none running
70
+ if notify_existing():
71
+ return 0
72
+ setup_app_log(paths.logs_dir())
73
+ log.info("starting")
74
+ if not QSystemTrayIcon.isSystemTrayAvailable():
75
+ log.error("no system tray available")
76
+ controller = Controller()
77
+ a = App(controller)
78
+ a.tray.show()
79
+ if not controller.settings.runtimes or not controller.settings.model_folders:
80
+ a.open_settings()
81
+ else:
82
+ a.show_started()
83
+ code = app.exec()
84
+ log.info("exiting")
85
+ return code
86
+
87
+
88
+ if __name__ == "__main__":
89
+ sys.exit(main())
@@ -0,0 +1,140 @@
1
+ """Tokenizing raw argument strings and merging layered flags (pure)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass
7
+
8
+ from llama_launcher.runtimes import HelpTable
9
+ from llama_launcher.server_flags import RESERVED
10
+
11
+ _NUMBER = re.compile(r"^-\d|^-\.\d")
12
+
13
+
14
+ class ArgError(ValueError):
15
+ pass
16
+
17
+
18
+ def tokenize(text: str) -> list[str]:
19
+ """Split like a shell, but keep backslashes literal (Windows paths).
20
+ Single quotes are fully literal; inside double quotes \\" is a quote."""
21
+ tokens: list[str] = []
22
+ cur: list[str] = []
23
+ in_token = False
24
+ i, n = 0, len(text or "")
25
+ while i < n:
26
+ c = text[i]
27
+ if c.isspace():
28
+ if in_token:
29
+ tokens.append("".join(cur))
30
+ cur, in_token = [], False
31
+ i += 1
32
+ elif c in "'\"":
33
+ end = i + 1
34
+ buf = []
35
+ while end < n and text[end] != c:
36
+ if c == '"' and text[end] == "\\" and end + 1 < n and text[end + 1] == '"':
37
+ buf.append('"')
38
+ end += 2
39
+ continue
40
+ buf.append(text[end])
41
+ end += 1
42
+ if end >= n:
43
+ raise ArgError(f"unclosed {c} quote starting at position {i + 1}")
44
+ cur.extend(buf)
45
+ in_token = True
46
+ i = end + 1
47
+ else:
48
+ cur.append(c)
49
+ in_token = True
50
+ i += 1
51
+ if in_token:
52
+ tokens.append("".join(cur))
53
+ return tokens
54
+
55
+
56
+ @dataclass
57
+ class Flag:
58
+ flag: str
59
+ value: str | None
60
+ layer: str = ""
61
+
62
+
63
+ def _is_flag(tok: str) -> bool:
64
+ return tok.startswith("-") and len(tok) > 1 and not _NUMBER.match(tok)
65
+
66
+
67
+ def parse(tokens: list[str], help_table: HelpTable, layer: str = "") -> list[Flag]:
68
+ out: list[Flag] = []
69
+ i = 0
70
+ while i < len(tokens):
71
+ tok = tokens[i]
72
+ if not _is_flag(tok):
73
+ raise ArgError(f"{layer}: unexpected value '{tok}' (no flag before it)")
74
+ if tok.startswith("--") and "=" in tok:
75
+ name, val = tok.split("=", 1)
76
+ out.append(Flag(name, val, layer))
77
+ i += 1
78
+ continue
79
+ needs = help_table.needs_value(tok)
80
+ nxt = tokens[i + 1] if i + 1 < len(tokens) else None
81
+ if needs is True or (needs is None and nxt is not None and not _is_flag(nxt)):
82
+ if nxt is None:
83
+ raise ArgError(f"{layer}: {tok} needs a value")
84
+ out.append(Flag(tok, nxt, layer))
85
+ i += 2
86
+ else:
87
+ out.append(Flag(tok, None, layer))
88
+ i += 1
89
+ return out
90
+
91
+
92
+ def parse_text(text: str, help_table: HelpTable, layer: str) -> list[Flag]:
93
+ try:
94
+ return parse(tokenize(text), help_table, layer)
95
+ except ArgError as e:
96
+ msg = str(e)
97
+ raise ArgError(msg if msg.startswith(layer) else f"{layer}: {msg}") from None
98
+
99
+
100
+ def reserved_in(flags: list[Flag], help_table: HelpTable) -> list[str]:
101
+ res = {help_table.canonical(r) for r in RESERVED}
102
+ return [f.flag for f in flags if help_table.canonical(f.flag) in res]
103
+
104
+
105
+ class Merger:
106
+ """Ordered flag set; a later flag replaces any earlier spelling of the same canonical flag."""
107
+
108
+ def __init__(self, help_table: HelpTable):
109
+ self.help_table = help_table
110
+ self._items: dict[str, Flag] = {}
111
+
112
+ def add(self, flags: list[Flag]) -> None:
113
+ for f in flags:
114
+ self._items[self.help_table.canonical(f.flag)] = f
115
+
116
+ def remove(self, flag: str) -> bool:
117
+ return self._items.pop(self.help_table.canonical(flag), None) is not None
118
+
119
+ def get(self, flag: str) -> Flag | None:
120
+ return self._items.get(self.help_table.canonical(flag))
121
+
122
+ def flags(self) -> list[Flag]:
123
+ return list(self._items.values())
124
+
125
+ def argv(self) -> list[str]:
126
+ out: list[str] = []
127
+ for f in self._items.values():
128
+ out.append(f.flag)
129
+ if f.value is not None:
130
+ out.append(f.value)
131
+ return out
132
+
133
+
134
+ def format_argv(argv: list[str]) -> str:
135
+ """Readable one-line command for logs and the preview box."""
136
+
137
+ def q(a: str) -> str:
138
+ return f'"{a}"' if (not a or any(c.isspace() for c in a)) else a
139
+
140
+ return " ".join(q(a) for a in argv)
@@ -0,0 +1,181 @@
1
+ """Model folder scanning, file classification and sidecar suggestions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import re
8
+ import stat
9
+ from dataclasses import dataclass, field
10
+ from enum import Enum
11
+ from pathlib import Path
12
+
13
+ from llama_launcher.gguf import GGUFError, GGUFInfo, info_from_metadata, read_metadata
14
+ from llama_launcher.paths import norm
15
+
16
+ _SHARD_RE = re.compile(r"-(\d{5})-of-(\d{5})\.gguf$", re.IGNORECASE)
17
+ _DRAFT_PREFIXES = ("mtp-", "dspark-", "dflash-")
18
+
19
+
20
+ class Kind(Enum):
21
+ MODEL = "model"
22
+ MMPROJ = "mmproj"
23
+ DRAFT = "draft"
24
+ UNREADABLE = "unreadable"
25
+
26
+
27
+ @dataclass
28
+ class FileEntry:
29
+ path: str
30
+ kind: Kind
31
+ info: GGUFInfo | None = None
32
+ error: str = ""
33
+ shard_count: int = 1
34
+
35
+ @property
36
+ def directory(self) -> str:
37
+ return os.path.normcase(os.path.dirname(self.path))
38
+
39
+ @property
40
+ def stem(self) -> str:
41
+ name = os.path.basename(self.path)
42
+ m = _SHARD_RE.search(name)
43
+ return name[: m.start()] if m else name[: -len(".gguf")]
44
+
45
+
46
+ @dataclass
47
+ class Suggestion:
48
+ mmproj: str | None
49
+ draft: str | None
50
+ builtin_mtp: bool
51
+ mmproj_candidates: list[str] = field(default_factory=list)
52
+ draft_candidates: list[str] = field(default_factory=list)
53
+
54
+
55
+ def classify(info: GGUFInfo, filename: str) -> Kind:
56
+ if info.type == "mmproj" or info.arch == "clip":
57
+ return Kind.MMPROJ
58
+ if info.arch.endswith("-assistant") or filename.lower().startswith(_DRAFT_PREFIXES):
59
+ return Kind.DRAFT
60
+ return Kind.MODEL
61
+
62
+
63
+ class InfoCache:
64
+ """GGUF info keyed by path + size + mtime, optionally persisted as JSON."""
65
+
66
+ def __init__(self, path: Path | None = None):
67
+ self.path = path
68
+ self._data: dict[str, dict] = {}
69
+ self._dirty = False
70
+ if path and path.exists():
71
+ try:
72
+ self._data = json.loads(path.read_text(encoding="utf-8"))
73
+ except (OSError, ValueError):
74
+ self._data = {}
75
+
76
+ def get(self, path: str) -> GGUFInfo:
77
+ st = os.stat(path)
78
+ key = norm(path)
79
+ sig = [st.st_size, st.st_mtime_ns]
80
+ hit = self._data.get(key)
81
+ if hit and hit["sig"] == sig:
82
+ return GGUFInfo(**{**hit["info"], "path": path, "projection_dims": tuple(hit["info"]["projection_dims"])})
83
+ info = info_from_metadata(path, read_metadata(path))
84
+ self._data[key] = {"sig": sig, "info": {**info.__dict__, "projection_dims": list(info.projection_dims)}}
85
+ self._dirty = True
86
+ return info
87
+
88
+ def save(self) -> None:
89
+ if self.path and self._dirty:
90
+ try:
91
+ self.path.parent.mkdir(parents=True, exist_ok=True)
92
+ self.path.write_text(json.dumps(self._data), encoding="utf-8")
93
+ self._dirty = False
94
+ except OSError:
95
+ pass
96
+
97
+
98
+ def _walk(root: str):
99
+ """Yield .gguf file paths under root; directory reparse points (junctions, links) are not followed."""
100
+ stack = [root]
101
+ while stack:
102
+ d = stack.pop()
103
+ try:
104
+ with os.scandir(d) as it:
105
+ entries = list(it)
106
+ except OSError:
107
+ continue
108
+ for e in sorted(entries, key=lambda e: e.name.lower()):
109
+ try:
110
+ if e.is_dir(follow_symlinks=False):
111
+ attrs = e.stat(follow_symlinks=False).st_file_attributes
112
+ if not attrs & stat.FILE_ATTRIBUTE_REPARSE_POINT:
113
+ stack.append(e.path)
114
+ elif e.name.lower().endswith(".gguf") and e.is_file():
115
+ yield e.path
116
+ except OSError:
117
+ continue
118
+
119
+
120
+ def scan(folders: list[str], cache: InfoCache | None = None) -> list[FileEntry]:
121
+ cache = cache or InfoCache()
122
+ seen: set[str] = set()
123
+ out: list[FileEntry] = []
124
+ for root in folders:
125
+ if not root or not os.path.isdir(root):
126
+ continue
127
+ for path in _walk(root):
128
+ key = norm(path)
129
+ if key in seen:
130
+ continue
131
+ seen.add(key)
132
+ m = _SHARD_RE.search(os.path.basename(path))
133
+ if m and m.group(1) != "00001":
134
+ continue
135
+ try:
136
+ info = cache.get(path)
137
+ except (GGUFError, OSError) as e:
138
+ out.append(FileEntry(path, Kind.UNREADABLE, error=str(e)))
139
+ continue
140
+ entry = FileEntry(path, classify(info, os.path.basename(path)), info)
141
+ if m:
142
+ entry.shard_count = int(m.group(2))
143
+ out.append(entry)
144
+ cache.save()
145
+ out.sort(key=lambda e: e.path.lower())
146
+ return out
147
+
148
+
149
+ def mmproj_fits(model: GGUFInfo, mmproj: GGUFInfo) -> bool:
150
+ return model.embedding_length is not None and model.embedding_length in mmproj.projection_dims
151
+
152
+
153
+ def draft_fits(model: GGUFInfo, draft: GGUFInfo) -> bool:
154
+ return draft.arch in (f"{model.arch}-assistant", model.arch)
155
+
156
+
157
+ def _pick(model: FileEntry, candidates: list[FileEntry]) -> str | None:
158
+ """Auto-attach only when exactly one fitting file sits in the model's own folder."""
159
+ local = [c for c in candidates if c.directory == model.directory]
160
+ return local[0].path if len(local) == 1 else None
161
+
162
+
163
+ def _rank(model: FileEntry, candidates: list[FileEntry]) -> list[str]:
164
+ return [c.path for c in sorted(candidates, key=lambda c: (c.directory != model.directory, c.path.lower()))]
165
+
166
+
167
+ def suggest(model: FileEntry, entries: list[FileEntry]) -> Suggestion:
168
+ assert model.info is not None
169
+ mm = [e for e in entries if e.kind is Kind.MMPROJ and mmproj_fits(model.info, e.info)]
170
+ dr = [e for e in entries if e.kind is Kind.DRAFT and e.path != model.path and draft_fits(model.info, e.info)]
171
+ return Suggestion(
172
+ mmproj=_pick(model, mm),
173
+ draft=_pick(model, dr),
174
+ builtin_mtp=model.info.nextn_layers > 0,
175
+ mmproj_candidates=_rank(model, mm),
176
+ draft_candidates=_rank(model, dr),
177
+ )
178
+
179
+
180
+ def models(entries: list[FileEntry]) -> list[FileEntry]:
181
+ return [e for e in entries if e.kind is Kind.MODEL]