llm-tuner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronald Daniel Acuña Arias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,123 @@
+# LLM Tuner
+
+[English](README.md) · **Español**
+
+Carga un LLM local con la mejor configuración para el contexto que necesitas, en LM Studio u Ollama, en Windows, macOS y Linux. Tú eliges qué significa «mejor» con un perfil de carga: velocidad, un equilibrio o calidad de las respuestas.
+
+Ningún LLM decide la configuración. La app lee tu hardware y los metadatos del modelo, estima qué cabe en la VRAM, mide de verdad las mejores opciones y guarda la ganadora como **preset**. La próxima vez que cargues ese modelo con ese contexto y ese perfil se usa el preset directamente, sin volver a medir.
+
+## Flujo
+
+1. **Motor**: eliges LM Studio u Ollama. Si no está instalado, la app lo instala con el método oficial (winget, Homebrew o el script de instalación).
+2. **Modelo y contexto**: eliges uno de tus modelos y escribes el contexto que quieres.
+3. **Perfil**: eliges qué optimizar: `speed`, `balanced` o `quality`. La app marca uno como recomendado.
+4. **Cargar**:
+   - Si hay un preset para ese modelo, contexto, perfil y hardware, se aplica y se carga el modelo (unos 20 s).
+   - Si no lo hay, se prueban 3 configuraciones (2–3 min), se guarda la mejor como preset, se aplica y se carga.
+
+Solo se vuelve a medir cuando cambias el contexto o el perfil, cambia el hardware (GPU, VRAM, CPU o enlace PCIe) o cambia el archivo del modelo. Con `speed` y `quality` también se vuelve a medir cuando descargas o eliminas una variante del modelo. También puedes forzarlo con «Volver a medir aunque exista un preset» o con `--force`.
+
+## Perfiles de carga
+
+Más tokens por segundo no significa mejores respuestas. El perfil decide cuánta calidad de las respuestas se puede ceder a cambio de velocidad o memoria.
+
+| Perfil | Qué optimiza | Qué cuesta |
+|---|---|---|
+| `speed` (Velocidad) | Los tokens por segundo. Usa la variante más ligera del modelo que tengas descargada y cualquier tipo de caché KV. | Calidad de las respuestas: se admiten los pesos y la caché más comprimidos. |
+| `balanced` (Equilibrado) | La velocidad ponderada por la calidad de la caché KV, con la variante que has seleccionado. Es el perfil predeterminado. | Un término medio: ni el más rápido ni el más preciso. |
+| `quality` (Calidad) | La menor pérdida que aún se ejecuta por completo en GPU: la variante descargada más pesada que cabe, con una caché KV precisa (`f16` o `q8_0`). | Velocidad. Si nada cabe por completo en GPU, lo indica y elige la ganadora como `balanced`. |
+
+Las optimizaciones que no pierden nada (reparto de capas entre GPUs, orden de las GPUs, hilos) se aplican en todos los perfiles.
+
+Antes de cargar, la app también te indica:
+
+- **Qué perfil se recomienda**: el de mayor calidad que aún se ejecuta por completo en tus GPUs.
+- **Si cabría una variante más pesada**: por ejemplo, que Q8_0 no está descargada y cabría por completo en tus GPUs. El tamaño es una estimación, y la app nunca descarga nada.
+- **Si la vista previa es conservadora**: se calcula con la VRAM que está libre en ese momento, así que la app te avisa cuando la VRAM está en uso. Al cargar, primero se descargan de la memoria los modelos del motor y después se hace la elección real.
+
+Los motores se diferencian en una cosa. **Ollama** permite que la app elija la variante (etiqueta) para el perfil y la cargue, entre las etiquetas que puede identificar como el mismo modelo. **LM Studio** no puede cargar una variante concreta a petición, así que ahí el perfil se aplica a la variante seleccionada en LM Studio, y la app te indica cuál seleccionar cuando otra se ajusta mejor al perfil.
+
+## Instalación
+
+```bash
+npm install -g llm-tuner
+llm-tuner               # asistente en la terminal
+llm-tuner-desktop       # app de escritorio
+```
+
+Necesita Node.js 22 o posterior. La app de escritorio descarga su entorno de ejecución (Electron) la primera vez que ejecutas `llm-tuner-desktop`, así que esa primera ejecución necesita conexión a la red y tarda más. El asistente de terminal funciona sin él.
+
+## Uso
+
+Modo no interactivo:
+
+```bash
+llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --yes
+llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --profile quality --yes
+llm-tuner --presets          # lista los presets guardados
+llm-tuner --help
+llm-tuner --lang <en|es>     # idioma de la interfaz; se guarda para la próxima vez
+```
+
+`--profile <speed|balanced|quality>` establece el perfil de carga para esa ejecución. El asistente lo pregunta y recuerda tu elección. Sin la opción, una ejecución con `--yes`, con `--json` o con motor, modelo y contexto indicados usa `balanced`.
+
+La app de escritorio tiene un selector EN/ES en la barra lateral, y la elección se guarda en `llm-tuner/settings.json`, junto a los presets. El perfil que eliges en el asistente o en la app también se guarda ahí.
+
+## Qué se prueba
+
+Para cada tipo de caché KV que admite el perfil (`f16`, `q8_0`, `q4_0`; `quality` excluye `q4_0`) el estimador calcula:
+
+- **Memoria por capa**, leída del GGUF (tamaño real de cada tensor).
+- **Caché de contexto** según capas con atención, cabezas KV, dimensión y ventana deslizante (SWA).
+- **Reparto de capas entre GPUs**, con prioridad a la GPU con el enlace PCIe más ancho y sin monitor, y el margen libre igualado entre tarjetas.
+- **En modelos MoE que no caben**, cuántas capas de expertos pueden quedarse en la RAM (`--n-cpu-moe`).
+- **Velocidad esperada**, según el ancho de banda de memoria.
+
+Las mejores opciones se miden con un prompt corto y otro que llena ~50 % del contexto. El perfil decide la ganadora: en `balanced`, la más rápida con contexto lleno, ponderada por la calidad del tipo de KV.
+
+- **LM Studio**: se ejecuta el mismo `llama-server` que usa LM Studio con los parámetros exactos. El resultado se escribe en la config del modelo (`~/.lmstudio/.internal/user-concrete-model-default-config/…`) y en `hardware-config.json`. LM Studio solo se reinicia si cambia la config de hardware.
+- **Ollama**: cada opción se mide en un `ollama serve` privado en otro puerto, porque el tipo de KV y Flash Attention son globales. Se crea el modelo `<modelo>-tuned-16k` con `num_ctx`, `num_gpu` y `num_thread`, y se configuran las variables del servidor (systemd en Linux, `setx` en Windows, `launchctl` en macOS).
+
+Antes de modificar cualquier archivo se guarda una copia `*.bak-llm-tuner-*`.
+
+## Dónde se guardan los presets
+
+Hay un preset por motor, modelo, contexto y perfil.
+
+- Linux: `~/.config/llm-tuner/presets/`
+- macOS: `~/Library/Application Support/llm-tuner/presets/`
+- Windows: `%APPDATA%\llm-tuner\presets\`
+
+## Estado por plataforma
+
+| | Probado | Notas |
+|---|---|---|
+| Linux + NVIDIA + LM Studio | ✅ 2× RTX 5070, Ryzen 7 5800X | Calibrado con mediciones reales |
+| Linux + Ollama | Pruebas unitarias | Falta probarlo con Ollama instalado |
+| Windows / macOS | Sin probar | Rutas, instaladores y detección implementados |
+| AMD (ROCm) / Apple Silicon / Intel | Sin probar | Detección de VRAM incluida; ancho de banda por tabla |
+
+Los perfiles de carga están cubiertos por pruebas unitarias y se comprobaron con una carga real por perfil en LM Studio (Linux, 2× RTX 5070). La elección entre varias variantes descargadas de un modelo, y los perfiles en Ollama, aún no se han probado en hardware real.
+
+## Desarrollo
+
+```bash
+git clone https://github.com/ronald32acunadev/llmtuner.git
+cd llmtuner
+npm install
+npm start               # asistente en la terminal
+npm run desktop         # app de escritorio
+```
+
+## Pruebas
+
+```bash
+npm test
+```
+
+Incluye como regresión los resultados reales de 2× RTX 5070 con Qwen2.5-Coder-32B: 16K y 20K con q8_0 caben enteros, 24K no; 32K cabe solo con q4_0.
+
+## Notas
+
+- Electron no se descarga al instalar el paquete: lo descarga la primera ejecución de la app de escritorio. Si esa descarga falla, extrae `~/.cache/electron/*/electron-*.zip` en la carpeta `dist` del paquete `electron` instalado y crea `path.txt` junto a ella con el texto `electron`. La app de escritorio desactiva el sandbox de Chromium solo cuando no puede funcionar (no hay `chrome-sandbox` con setuid de root).
+- Los archivos internos de LM Studio no son una API pública. Esta versión está verificada con LM Studio 0.4.25.

package/README.md

@@ -0,0 +1,123 @@
+# LLM Tuner
+
+**English** · [Español](README.es.md)
+
+Load a local LLM with the best configuration for the context you need, on LM Studio or Ollama, on Windows, macOS and Linux. You choose what "best" means with a load profile: speed, a balance, or answer quality.
+
+No LLM decides the configuration. The app reads your hardware and the model's metadata, estimates what fits in VRAM, actually measures the best options and saves the winner as a **preset**. The next time you load that model with that context and profile, the preset is used directly, without measuring again.
+
+## Flow
+
+1. **Engine**: you choose LM Studio or Ollama. If it isn't installed, the app installs it with the official method (winget, Homebrew or the install script).
+2. **Model and context**: you choose one of your models and enter the context you want.
+3. **Profile**: you choose what to optimize for: `speed`, `balanced` or `quality`. The app marks one as recommended.
+4. **Load**:
+   - If there's a preset for that model, context, profile and hardware, it's applied and the model is loaded (about 20 s).
+   - If there isn't one, 3 configurations are tried (2–3 min), the best one is saved as a preset, applied and loaded.
+
+It only measures again when you change the context or the profile, the hardware changes (GPU, VRAM, CPU or PCIe link) or the model file changes. With `speed` and `quality` it also measures again when you download or remove a variant of the model. You can also force it with "Measure again even if a preset exists" or with `--force`.
+
+## Load profiles
+
+More tokens per second does not mean better answers. The profile decides how much answer quality may be traded for speed or memory.
+
+| Profile | What it optimizes | What it costs |
+|---|---|---|
+| `speed` | Tokens per second. It uses the lightest variant of the model you have downloaded and any KV cache type. | Answer quality: the most compressed weights and cache are allowed. |
+| `balanced` | Speed weighted by the quality of the KV cache, with the variant you selected. It is the default. | A middle ground: neither the fastest nor the most precise. |
+| `quality` | The least loss that still runs fully on GPU: the heaviest downloaded variant that fits, with a precise KV cache (`f16` or `q8_0`). | Speed. If nothing fits fully on GPU, it says so and picks the winner like `balanced`. |
+
+Optimizations that lose nothing (layer split across GPUs, GPU order, threads) are applied in every profile.
+
+Before you load, the app also tells you:
+
+- **Which profile is recommended**: the highest-quality one that still runs fully on your GPUs.
+- **Whether a heavier variant would fit**: for example, that Q8_0 is not downloaded and would fit fully on your GPUs. The size is an estimate, and the app never downloads anything.
+- **Whether the preview is conservative**: it is computed with the VRAM that is free at that moment, so the app warns you when VRAM is in use. Loading unloads the engine's models first and then makes the real choice.
+
+The engines differ in one thing. **Ollama** lets the app pick the variant (tag) for the profile and load it, among the tags it can tell are the same model. **LM Studio** cannot load a specific variant on request, so there the profile applies to the variant selected in LM Studio, and the app tells you which one to select when another suits the profile better.
+
+## Install
+
+```bash
+npm install -g llm-tuner
+llm-tuner               # terminal wizard
+llm-tuner-desktop       # desktop app
+```
+
+It needs Node.js 22 or later. The desktop app downloads its runtime (Electron) the first time you run `llm-tuner-desktop`, so that first run needs a network connection and takes longer. The terminal wizard works without it.
+
+## Usage
+
+Non-interactive mode:
+
+```bash
+llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --yes
+llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --profile quality --yes
+llm-tuner --presets          # lists the saved presets
+llm-tuner --help
+llm-tuner --lang <en|es>     # UI language; saved for next time
+```
+
+`--profile <speed|balanced|quality>` sets the load profile for that run. The wizard asks for it and remembers your choice. Without the flag, a run with `--yes`, with `--json`, or with engine, model and context all given uses `balanced`.
+
+The desktop app has an EN/ES selector in the side rail, and the choice is saved in `llm-tuner/settings.json`, next to the presets. The profile you choose in the wizard or in the app is saved there too.
+
+## What gets tried
+
+For each KV cache type the profile allows (`f16`, `q8_0`, `q4_0`; `quality` leaves out `q4_0`) the estimator computes:
+
+- **Memory per layer**, read from the GGUF (the real size of each tensor).
+- **Context cache** based on layers with attention, KV heads, dimension and sliding window (SWA).
+- **Layer split across GPUs**, prioritizing the GPU with the widest PCIe link and no monitor attached, with free headroom balanced evenly across cards.
+- **For MoE models that don't fit**, how many expert layers can stay in RAM (`--n-cpu-moe`).
+- **Expected speed**, based on memory bandwidth.
+
+The best options are measured with a short prompt and another that fills ~50% of the context. The profile decides the winner: in `balanced`, the fastest one with a full context, weighted by the quality of the KV type.
+
+- **LM Studio**: it runs the same `llama-server` that LM Studio uses, with the exact same parameters. The result is written to the model's config (`~/.lmstudio/.internal/user-concrete-model-default-config/…`) and to `hardware-config.json`. LM Studio only restarts if the hardware config changes.
+- **Ollama**: each option is measured on a private `ollama serve` on another port, because the KV type and Flash Attention are global. The model `<model>-tuned-16k` is created with `num_ctx`, `num_gpu` and `num_thread`, and the server variables are configured (systemd on Linux, `setx` on Windows, `launchctl` on macOS).
+
+A `*.bak-llm-tuner-*` copy is saved before modifying any file.
+
+## Where presets are stored
+
+There is one preset per engine, model, context and profile.
+
+- Linux: `~/.config/llm-tuner/presets/`
+- macOS: `~/Library/Application Support/llm-tuner/presets/`
+- Windows: `%APPDATA%\llm-tuner\presets\`
+
+## Platform status
+
+| | Tested | Notes |
+|---|---|---|
+| Linux + NVIDIA + LM Studio | ✅ 2× RTX 5070, Ryzen 7 5800X | Calibrated with real measurements |
+| Linux + Ollama | Unit tests | Still needs testing with Ollama installed |
+| Windows / macOS | Untested | Paths, installers and detection implemented |
+| AMD (ROCm) / Apple Silicon / Intel | Untested | VRAM detection included; bandwidth from table |
+
+Load profiles are covered by unit tests and were checked with one real load per profile on LM Studio (Linux, 2× RTX 5070). Choosing between several downloaded variants of a model, and the profiles on Ollama, have not been exercised on real hardware yet.
+
+## Development
+
+```bash
+git clone https://github.com/ronald32acunadev/llmtuner.git
+cd llmtuner
+npm install
+npm start               # terminal wizard
+npm run desktop         # desktop app
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+Includes as regression the real results of 2× RTX 5070 with Qwen2.5-Coder-32B: 16K and 20K with q8_0 fit entirely, 24K doesn't; 32K only fits with q4_0.
+
+## Notes
+
+- Electron is not downloaded when the package is installed: the first run of the desktop app downloads it. If that download fails, extract `~/.cache/electron/*/electron-*.zip` into the `dist` folder of the installed `electron` package and create `path.txt` next to it with the text `electron`. The desktop app disables the Chromium sandbox only when it can't work (no `chrome-sandbox` with root setuid).
+- LM Studio's internal files are not a public API. This version is verified with LM Studio 0.4.25.

package/electron/launch.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Starts the desktop app. On Linux, Chromium's SUID sandbox helper must be
+// root-owned with mode 4755; that's impossible on NTFS/exFAT drives or in an
+// npm install, so the sandbox is disabled only in that case. The
+// window only loads this app's own local server.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+// Says why the desktop app could not start, in the saved UI language, and exits.
+async function fail(error) {
+  const { readSettings } = await import('../src/core/settings.js');
+  const { t } = await import('../src/i18n/index.js');
+  const { lang } = await readSettings();
+  console.error(t(lang, 'cli.desktopStartFailed', { error: error?.message ?? String(error) }));
+  process.exit(1);
+}
+
+// Requiring `electron` returns the path of its executable. It downloads the
+// runtime first when it is missing, which happens on the first launch.
+let electron;
+try {
+  electron = createRequire(import.meta.url)('electron');
+} catch (error) {
+  await fail(error);
+}
+const env = { ...process.env };
+
+if (process.platform === 'linux') {
+  try {
+    const st = fs.statSync(path.join(path.dirname(electron), 'chrome-sandbox'));
+    if (st.uid !== 0 || !(st.mode & 0o4000)) env.ELECTRON_DISABLE_SANDBOX = '1';
+  } catch {
+    env.ELECTRON_DISABLE_SANDBOX = '1';
+  }
+
+  // Ensure Linux desktop entry exists
+  ensureLinuxDesktopEntry();
+}
+
+const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
+const child = spawn(electron, [main], { stdio: 'inherit', env });
+child.on('error', fail);
+child.on('exit', (code) => process.exit(code ?? 0));
+
+function ensureLinuxDesktopEntry() {
+  try {
+    const appsDir = process.env.XDG_DATA_HOME
+      ? path.join(process.env.XDG_DATA_HOME, 'applications')
+      : path.join(os.homedir(), '.local', 'share', 'applications');
+
+    fs.mkdirSync(appsDir, { recursive: true });
+
+    const desktopFilePath = path.join(appsDir, 'llm-tuner.desktop');
+    const iconPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'icon.png');
+
+    const desktopContent = `[Desktop Entry]
+Type=Application
+Name=LLM Tuner
+Comment=Find the fastest configuration to run local LLMs
+Exec=${process.execPath} ${fileURLToPath(import.meta.url)}
+Icon=${iconPath}
+Terminal=false
+StartupWMClass=llm-tuner
+Categories=Development;Utility;
+`;
+
+    // Only write if file doesn't exist or content differs
+    let currentContent = '';
+    try {
+      currentContent = fs.readFileSync(desktopFilePath, 'utf8');
+    } catch {
+      // File doesn't exist, so we'll write it
+    }
+
+    if (currentContent !== desktopContent) {
+      fs.writeFileSync(desktopFilePath, desktopContent);
+    }
+  } catch {
+    // Failures are ignored to avoid preventing app launch
+  }
+}

package/electron/main.js

@@ -0,0 +1,63 @@
+import { app, BrowserWindow, shell, nativeImage } from 'electron';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startServer } from '../src/web/server.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Set app name early
+app.name = 'LLM Tuner';
+
+if (process.platform === 'win32') {
+  app.setAppUserModelId('dev.llm-tuner.app');
+} else if (process.platform === 'linux') {
+  if (typeof app.setDesktopName === 'function') {
+    app.setDesktopName('llm-tuner.desktop');
+  }
+}
+
+// The desktop app is the web UI in a native window, served on a random local port.
+let server;
+
+async function createWindow() {
+  const started = await startServer({ port: 0 });
+  server = started.server;
+
+  const iconFile = process.platform === 'win32' ? 'icon.ico' : 'icon.png';
+  const icon = nativeImage.createFromPath(path.join(__dirname, iconFile));
+
+  const win = new BrowserWindow({
+    width: 1200,
+    height: 860,
+    minWidth: 420,
+    title: 'LLM Tuner',
+    icon: !icon.isEmpty() ? icon : path.join(__dirname, iconFile),
+    autoHideMenuBar: true,
+    webPreferences: { contextIsolation: true, sandbox: true },
+  });
+
+  // External links open in the system browser.
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+
+  await win.loadURL(started.url);
+}
+
+app.whenReady().then(async () => {
+  if (process.platform === 'darwin' && app.dock) {
+    const iconFile = 'icon.png';
+    const icon = nativeImage.createFromPath(path.join(__dirname, iconFile));
+    if (!icon.isEmpty()) {
+      app.dock.setIcon(icon);
+    }
+  }
+
+  await createWindow();
+});
+
+app.on('window-all-closed', () => {
+  server?.close();
+  app.quit();
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "llm-tuner",
+  "version": "0.1.0",
+  "description": "Detects your hardware and finds the fastest configuration to run local LLMs with LM Studio or Ollama.",
+  "keywords": [
+    "llm",
+    "lm-studio",
+    "ollama",
+    "gguf",
+    "llama.cpp",
+    "benchmark",
+    "gpu",
+    "vram"
+  ],
+  "homepage": "https://github.com/ronald32acunadev/llmtuner#readme",
+  "bugs": {
+    "url": "https://github.com/ronald32acunadev/llmtuner/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ronald32acunadev/llmtuner.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "src/core/index.js",
+  "bin": {
+    "llm-tuner": "src/cli/index.js",
+    "llm-tuner-desktop": "electron/launch.js"
+  },
+  "files": [
+    "src/",
+    "electron/",
+    "README.es.md"
+  ],
+  "scripts": {
+    "start": "node src/cli/index.js",
+    "desktop": "node electron/launch.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "electron": "^44.5.1",
+    "systeminformation": "^5.23.0"
+  }
+}