llm-tuner 0.1.0 → 0.2.0

package/README.es.md

@@ -2,122 +2,245 @@
 
 [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.
+[![npm version](https://img.shields.io/npm/v/llm-tuner.svg)](https://www.npmjs.com/package/llm-tuner)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+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» mediante perfiles de carga deterministas: velocidad, equilibrio o máxima calidad de respuestas.
+
+Ningún LLM decide la configuración. LLM Tuner lee la topología de tu hardware y los metadatos GGUF del modelo, calcula matemáticamente qué cabe en la VRAM, mide empíricamente las mejores configuraciones candidatas en hardware real y guarda la ganadora como un **preset** persistente. La próxima vez que cargues ese modelo con ese contexto y perfil, el preset se aplica directamente (en ~20 s) sin volver a medir.
+
+---
+
+## Tabla de contenidos
+
+- [Características](#características)
+- [Cómo funciona](#cómo-funciona)
+- [Perfiles de carga](#perfiles-de-carga)
+- [Instalación](#instalación)
+- [Uso](#uso)
+  - [Asistente interactivo](#asistente-interactivo)
+  - [Aplicación de escritorio](#aplicación-de-escritorio)
+  - [Modo CLI no interactivo](#modo-cli-no-interactivo)
+  - [Referencia de opciones CLI](#referencia-de-opciones-cli)
+- [Qué se prueba](#qué-se-prueba)
+- [Dónde se guardan los presets](#dónde-se-guardan-los-presets)
+- [Estado por plataforma](#estado-por-plataforma)
+- [Arquitectura del proyecto](#arquitectura-del-proyecto)
+- [Desarrollo y pruebas](#desarrollo-y-pruebas)
+- [Notas y solución de problemas](#notas-y-solución-de-problemas)
+- [Licencia](#licencia)
+
+---
+
+## Características
+
+- **Optimización determinista**: Basada en metadatos reales de tensores GGUF, ancho de banda PCIe y pruebas empíricas de velocidad de generación, sin que ninguna IA adivine parámetros.
+- **Detección multitarjeta y topología**: Reparte capas inteligentemente priorizando la GPU con mayor enlace PCIe y sin monitor conectado.
+- **Perfiles de carga a medida**: Optimiza para velocidad pura (`speed`), equilibrio ponderado por calidad (`balanced`) o retención íntegra en GPU sin pérdidas (`quality`).
+- **Soporte de motores locales**: Compatibilidad directa con LM Studio (a través de `llama-server`) y Ollama (instancias privadas aisladas).
+- **Presets persistentes**: Mide una única vez por combinación de hardware, modelo, contexto y perfil. Invalida presets automáticamente si el hardware o el archivo del modelo cambian.
+- **Doble interfaz**: Asistente en consola (`llm-tuner`) y aplicación gráfica de escritorio (`llm-tuner-desktop`).
+- **Bilingüe**: Localización completa en español e inglés tanto en terminal como en entorno gráfico.
+
+---
+
+## Cómo funciona
+
+1. **Motor**: Eliges LM Studio u Ollama. Si no está instalado, la app ofrece planes de instalación oficiales.
+2. **Modelo y contexto**: Eliges uno de tus modelos descargados y defines el tamaño de contexto deseado (p. ej. 16.384 tokens).
+3. **Perfil de carga**: Eliges qué optimizar: `speed`, `balanced` (predeterminado) o `quality`. La app resalta una recomendación según la VRAM libre.
 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.
+   - **Preset existente**: Si ya existe un preset para ese modelo, contexto, perfil y hardware, se aplica de inmediato y se carga el modelo (~20 s).
+   - **Sin preset**: Descarga modelos previos para liberar VRAM, prueba las configuraciones más prometedoras (2–3 min), guarda la mejor como preset y carga el modelo.
 
-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`.
+Solo se vuelve a medir cuando cambias el contexto o el perfil, cambia el hardware (GPU, VRAM, PCIe), cambia el archivo del modelo o se modifican las variantes descargadas (en `speed` y `quality`). También puedes forzar una nueva medición 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.
+Más tokens por segundo no siempre significa mejores respuestas. El perfil decide cuánta calidad de respuestas se puede ceder a cambio de velocidad o memoria:
 
-| Perfil | Qué optimiza | Qué cuesta |
+| Perfil | Qué optimiza | Comportamiento y compensaciones |
 |---|---|---|
-| `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`. |
+| `speed` (Velocidad) | Tokens por segundo al máximo. | Usa la variante descargada más ligera y cualquier tipo de caché KV (incluyendo `q4_0`). |
+| `balanced` (Equilibrado) | Velocidad ponderada por calidad de caché KV. *(Predeterminado)* | Término medio: usa la variante seleccionada y pondera la velocidad según la precisión de la caché. |
+| `quality` (Calidad) | Mínima pérdida que aún se ejecuta por completo en GPU. | Elige la variante descargada más pesada que quepa en VRAM con caché KV precisa (`f16` o `q8_0`). Si nada cabe completo en GPU, recurre a la regla de `balanced`. |
 
-Las optimizaciones que no pierden nada (reparto de capas entre GPUs, orden de las GPUs, hilos) se aplican en todos los perfiles.
+Las optimizaciones sin pérdida (reparto de capas entre GPUs, orden de tarjetas, hilos de CPU) se aplican siempre en todos los perfiles.
 
-Antes de cargar, la app también te indica:
+### Selección de variantes
 
-- **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.
+- **Ollama**: La app puede elegir automáticamente la variante (etiqueta) óptima para el perfil y cargarla entre las etiquetas que reconozca como el mismo modelo.
+- **LM Studio**: Dado que LM Studio no permite seleccionar variantes por API externa, la app optimiza la variante activa y te avisa cuando otra variante se ajusta mejor al perfil seleccionado.
 
-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
 
+Instalación global vía npm:
+
 ```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.
+Requisitos previos:
+- **Node.js**: versión 22 o posterior (`node >= 22`).
+- **Motor local**: LM Studio (0.4.25+) u Ollama instalado (o instalarlo mediante las opciones del asistente).
+
+---
 
 ## Uso
 
-Modo no interactivo:
+### Asistente interactivo
+
+Ejecuta el asistente en la terminal:
+
+```bash
+llm-tuner
+```
+
+Te guiará paso a paso en la selección de motor, modelo, contexto, perfil recomendado y carga afinada.
+
+### Aplicación de escritorio
+
+Ejecuta la interfaz de escritorio:
+
+```bash
+llm-tuner-desktop
+```
+
+> **Nota**: El entorno de ejecución de Electron se descarga la primera vez que ejecutas `llm-tuner-desktop`. Se requiere conexión a internet en esa primera ejecución.
+
+### Modo CLI no interactivo
+
+Útil para automatizaciones, scripts y entornos desatendidos:
 
 ```bash
+# Ejecución básica con perfil balanced
 llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --yes
+
+# Especificando perfil de carga
 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`.
+# Listar presets guardados
+llm-tuner --presets
 
-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í.
+# Configurar idioma o tema
+llm-tuner /settings
+```
 
-## Qué se prueba
+### Referencia de opciones CLI
 
-Para cada tipo de caché KV que admite el perfil (`f16`, `q8_0`, `q4_0`; `quality` excluye `q4_0`) el estimador calcula:
+| Opción | Descripción | Valor predeterminado |
+|---|---|---|
+| `--engine <lmstudio\|ollama>` | Motor local objetivo. | Preguntado interactivamente |
+| `--model <key>` | Clave del modelo (LM Studio) o nombre/etiqueta (Ollama). | Preguntado interactivamente |
+| `--ctx <tokens>` | Tamaño de contexto en tokens (ej. `16384`). | Preguntado interactivamente |
+| `--profile <speed\|balanced\|quality>` | Perfil de carga a optimizar. | `balanced` |
+| `--force` | Forzar nueva medición aunque exista un preset. | `false` |
+| `--candidates <n>` | Número de configuraciones candidatas a medir. | `3` |
+| `--yes` | Ejecutar sin pedir confirmación. | `false` |
+| `--dry-run` | Medir sin aplicar cambios ni guardar presets. | `false` |
+| `--presets` | Listar presets guardados. | — |
+| `--json` | Salida en formato JSON. | `false` |
+| `--lang <en\|es>` | Establece y guarda el idioma de la interfaz. | Sistema / `en` |
+| `--theme <system\|light\|dark>` | Establece y guarda el tema de la interfaz. | `system` |
+| `/settings` | Menú interactivo de configuración. | — |
+| `--help` | Muestra la ayuda de comandos. | — |
+
+---
 
-- **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.
+## Qué se prueba
 
-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.
+Para cada tipo de caché KV admitido por el perfil (`f16`, `q8_0`, `q4_0`):
 
-- **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).
+1. **Inspección de tensores GGUF**: Lectura directa de tensores para conocer el peso exacto por capa.
+2. **Modelado de memoria de contexto**: Cálculo de la caché KV según atención, cabezas, dimensiones y ventana deslizante (SWA).
+3. **Reparto en múltiples GPUs**: Distribución proporcional al margen libre de VRAM, priorizando enlaces PCIe más anchos y excluyendo monitores.
+4. **Descarga en modelos MoE**: En modelos con Mixture of Experts que exceden la VRAM, determina cuántos expertos pueden operar en RAM (`--n-cpu-moe`).
+5. **Medición empírica**: Pruebas con un prompt corto y otro que ocupa ~50% del contexto.
+6. **Aplicación de configuración**:
+   - **LM Studio**: Escribe la configuración por modelo en `~/.lmstudio/.internal/user-concrete-model-default-config/` y actualiza `hardware-config.json`.
+   - **Ollama**: Genera un Modelfile específico (`<modelo>-tuned-<ctx>`) y ajusta las variables de entorno del servidor. Siempre se crea una copia de respaldo `*.bak-llm-tuner-*` antes de modificar archivos.
 
-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.
+Existe un preset por cada combinación de motor, modelo, contexto y perfil:
 
-- Linux: `~/.config/llm-tuner/presets/`
-- macOS: `~/Library/Application Support/llm-tuner/presets/`
-- Windows: `%APPDATA%\llm-tuner\presets\`
+- **Linux**: `~/.config/llm-tuner/presets/`
+- **macOS**: `~/Library/Application Support/llm-tuner/presets/`
+- **Windows**: `%APPDATA%\llm-tuner\presets\`
+
+---
 
 ## Estado por plataforma
 
-| | Probado | Notas |
+| Plataforma y Motor | Estado | 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 |
+| **Linux + NVIDIA + LM Studio** | ✅ Verificado | Calibrado con mediciones reales (2× RTX 5070, Ryzen 7 5800X). |
+| **Linux + Ollama** | ✅ Verificado | Comprobado mediante instancias privadas y suite de pruebas unitarias. |
+| **Windows / macOS** | 🧪 Soportado | Rutas oficiales, comandos del sistema y detección implementados. |
+| **AMD ROCm / Apple Silicon / Intel Arc** | 🧪 Soportado | Detección de VRAM activa; ancho de banda estimado por tabla de especificaciones. |
+
+---
+
+## Arquitectura del proyecto
 
-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.
+```
+llmtuner/
+├── src/
+│   ├── core/           # Núcleo del afinador, estimador, detección de hardware, presets y perfiles
+│   │   ├── engines/    # Controladores de LM Studio y Ollama
+│   │   ├── estimator.js# Modelado matemático de memoria y VRAM
+│   │   ├── gguf.js     # Parser de tensores GGUF
+│   │   ├── hardware.js # Detección de GPU, enlaces PCIe y estado de VRAM
+│   │   ├── presets.js  # Lógica de guardado e invalidación de presets
+│   │   └── profiles.js # Reglas de perfiles speed, balanced y quality
+│   ├── cli/            # Asistente interactivo y análisis de argumentos CLI
+│   ├── i18n/           # Catálogos de internacionalización en español e inglés
+│   └── web/            # Servidor HTTP/SSE embebido que alimenta la interfaz gráfica
+├── electron/           # Lanzador y proceso principal de Electron
+├── test/               # Suite de pruebas unitarias de Node.js
+└── docs/               # Especificaciones técnicas, mediciones reales y notas
+```
 
-## Desarrollo
+---
+
+## Desarrollo y pruebas
+
+Clonar y preparar el repositorio local:
 
 ```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
+# Iniciar asistente CLI
+npm start
 
-```bash
+# Iniciar aplicación de escritorio
+npm run desktop
+
+# Ejecutar suite de pruebas
 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.
+La suite incluye pruebas de regresión que verifican los resultados reales de doble RTX 5070 con Qwen2.5-Coder-32B.
+
+---
+
+## Notas y solución de problemas
+
+- **Descarga inicial de Electron**: Electron se descarga al ejecutar por primera vez `llm-tuner-desktop`. En entornos cerrados sin conexión, extrae `electron-v*.zip` en la carpeta `dist/` del paquete instalado de `electron` y crea `path.txt` con el texto `electron`.
+- **Instalaciones con sudo / permisos**: Evita instalar con permisos de superusuario desalineados (`sudo npm install -g`), ya que Electron podría no poder descomprimir sus binarios en la carpeta del usuario.
+- **Compatibilidad con LM Studio**: Verificado y calibrado con LM Studio 0.4.25+.
+
+---
 
-## Notas
+## Licencia
 
-- 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.
+[MIT](LICENSE) © Ronald Daniel Acuña Arias

package/README.md

@@ -2,122 +2,245 @@
 
 **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.
+[![npm version](https://img.shields.io/npm/v/llm-tuner.svg)](https://www.npmjs.com/package/llm-tuner)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+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 through deterministic load profiles: speed, a balanced trade-off, or maximum answer quality.
+
+No LLM decides the configuration. LLM Tuner reads your hardware topology and model GGUF metadata, mathematically calculates what fits into VRAM, benchmarks the top candidate configurations on real hardware, and saves the winner as a persistent **preset**. The next time you load that model with the same context and profile, the preset is applied instantly (in ~20s) without re-measuring.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [Load Profiles](#load-profiles)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Interactive Wizard](#interactive-wizard)
+  - [Desktop App](#desktop-app)
+  - [Non-Interactive CLI](#non-interactive-cli)
+  - [CLI Options Reference](#cli-options-reference)
+- [Tuning Pipeline](#tuning-pipeline)
+- [Preset Storage](#preset-storage)
+- [Platform Support](#platform-support)
+- [Project Architecture](#project-architecture)
+- [Development & Testing](#development--testing)
+- [Notes & Troubleshooting](#notes--troubleshooting)
+- [License](#license)
+
+---
+
+## Features
+
+- **Deterministic Optimization**: Uses GGUF tensor-level metadata, PCIe bandwidth measurements, and real token-generation benchmarks—never an AI guessing parameters.
+- **Multi-GPU & Topology Aware**: Splits layers intelligently, prioritizing the GPU with the widest PCIe link and no display server attached.
+- **Tailored Load Profiles**: Optimize for raw tokens/second (`speed`), quality-weighted speed (`balanced`), or zero-loss GPU retention (`quality`).
+- **Engine Support**: First-class support for both LM Studio (direct `llama-server` management) and Ollama (isolated private benchmarks).
+- **Persistent Presets**: Measures once per hardware, model, context, and profile. Automatically invalidates presets if hardware or model weights change.
+- **Dual Interfaces**: Interactive terminal wizard (`llm-tuner`) and cross-platform desktop UI (`llm-tuner-desktop`).
+- **Bilingual**: Full English and Spanish localization for both terminal and desktop interfaces.
+
+---
+
+## How It Works
+
+1. **Engine Selection**: Select LM Studio or Ollama. If not installed, LLM Tuner provides official installer commands.
+2. **Model & Context**: Pick any locally downloaded model and set the desired context window (e.g. 16,384 tokens).
+3. **Load Profile**: Choose between `speed`, `balanced` (default), or `quality`. The system highlights a recommended profile based on free VRAM.
 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.
+   - **Preset Hit**: If a preset exists for that exact model, context, profile, and hardware, it applies immediately and loads the model (~20s).
+   - **Preset Miss**: Unloads existing models to free VRAM, evaluates top candidate configurations (2–3 min), benchmarks actual generation speeds, saves the best preset, and loads the model.
 
-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`.
+Benchmarks run again only if the context or profile changes, the hardware changes (GPU, VRAM, PCIe link), the model file changes, or downloaded variants change (for `speed` and `quality`). You can also force a benchmark run 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.
+## Load Profiles
 
-| Profile | What it optimizes | What it costs |
+More tokens per second does not always equal better answers. Profiles let you decide when answer quality can be traded for speed or memory efficiency:
+
+| Profile | Optimization Goal | Trade-offs & Behaviour |
 |---|---|---|
-| `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`. |
+| `speed` | Maximum tokens per second. | Uses the lightest downloaded quantization variant and any KV cache type (including `q4_0`). |
+| `balanced` | Speed weighted by KV cache quality. *(Default)* | Balanced trade-off; runs with the selected variant and weighs speed by KV precision. |
+| `quality` | Zero degradation that still fits fully on GPU. | Keeps the heaviest downloaded variant that fits entirely into VRAM, using precise KV cache (`f16` or `q8_0`). Falls back to `balanced` if no full offload is possible. |
+
+Lossless optimizations (layer distribution across GPUs, thread count, GPU selection order) are applied across all profiles.
 
-Optimizations that lose nothing (layer split across GPUs, GPU order, threads) are applied in every profile.
+### Variant Switching
 
-Before you load, the app also tells you:
+- **Ollama**: Automatically selects and loads the best tag variant for the active profile among tags identified as the same model.
+- **LM Studio**: Since LM Studio cannot switch variants programmatically, LLM Tuner optimizes the active variant and advises you when another variant better suits your chosen profile.
 
-- **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.
+## Installation
 
-## Install
+Install globally via npm:
 
 ```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.
+Prerequisites:
+- **Node.js**: version 22 or higher (`node >= 22`).
+- **Local Engine**: LM Studio (0.4.25+) or Ollama installed (or let the wizard guide installation).
+
+---
 
 ## Usage
 
-Non-interactive mode:
+### Interactive Wizard
+
+Launch the terminal wizard:
+
+```bash
+llm-tuner
+```
+
+Guides you interactively through engine selection, model selection, context length, profile recommendation, and automatic tuning.
+
+### Desktop App
+
+Launch the desktop interface:
+
+```bash
+llm-tuner-desktop
+```
+
+> **Note**: Electron downloads automatically during the first launch of `llm-tuner-desktop`. A working network connection is required for that initial launch.
+
+### Non-Interactive CLI
+
+Run directly in headless, scripted, or CI environments:
 
 ```bash
+# Basic run with balanced profile
 llm-tuner --engine lmstudio --model qwen/qwen2.5-coder-32b --ctx 16384 --yes
+
+# Specify load profile
 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
+
+# List saved presets
+llm-tuner --presets
+
+# Configure language and theme
+llm-tuner /settings
 ```
 
-`--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`.
+### CLI Options Reference
 
-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.
+| Flag | Description | Default |
+|---|---|---|
+| `--engine <lmstudio\|ollama>` | Target engine. | Interactive prompt |
+| `--model <key>` | Model key or Ollama tag. | Interactive prompt |
+| `--ctx <tokens>` | Context length in tokens (e.g. `16384`). | Interactive prompt |
+| `--profile <speed\|balanced\|quality>` | Load profile to optimize for. | `balanced` |
+| `--force` | Force re-measurement even if a valid preset exists. | `false` |
+| `--candidates <n>` | Number of top candidate configurations to benchmark. | `3` |
+| `--yes` | Run non-interactively without confirmation prompts. | `false` |
+| `--dry-run` | Measure without saving presets or modifying engine configurations. | `false` |
+| `--presets` | List all saved presets. | — |
+| `--json` | Output results as JSON. | `false` |
+| `--lang <en\|es>` | Set and persist interface language. | System / `en` |
+| `--theme <system\|light\|dark>` | Set and persist interface theme. | `system` |
+| `/settings` | Open interactive settings menu. | — |
+| `--help` | Show usage instructions. | — |
 
-## What gets tried
+---
 
-For each KV cache type the profile allows (`f16`, `q8_0`, `q4_0`; `quality` leaves out `q4_0`) the estimator computes:
+## Tuning Pipeline
 
-- **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.
+For each KV cache type allowed by the selected profile (`f16`, `q8_0`, `q4_0`):
 
-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.
+1. **GGUF Tensor Inspection**: Parses GGUF tensors to obtain actual byte sizes per layer.
+2. **Context Memory Modeling**: Models KV cache size taking into account attention heads, dimensions, and sliding window attention (SWA).
+3. **Multi-GPU Split**: Allocates layers proportionally to VRAM headroom, ordering GPUs by PCIe bandwidth and avoiding active display adapters.
+4. **MoE Offloading**: For Mixture of Experts (MoE) architectures that exceed VRAM, calculates the exact expert count that can reside in system RAM (`--n-cpu-moe`).
+5. **Empirical Benchmarks**: Benchmarks candidates using both a short prompt and a deep prompt filling ~50% of the context.
+6. **Configuration Application**:
+   - **LM Studio**: Updates per-model config in `~/.lmstudio/.internal/user-concrete-model-default-config/` and updates `hardware-config.json`.
+   - **Ollama**: Creates an optimized Modelfile (`<model>-tuned-<ctx>`) and sets system server environment variables. A backup (`*.bak-llm-tuner-*`) is created before changing files.
 
-- **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.
+## Preset Storage
 
-## Where presets are stored
+Presets are stored deterministically per engine, model, context, and profile:
 
-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\`
 
-- Linux: `~/.config/llm-tuner/presets/`
-- macOS: `~/Library/Application Support/llm-tuner/presets/`
-- Windows: `%APPDATA%\llm-tuner\presets\`
+---
 
-## Platform status
+## Platform Support
 
-| | Tested | Notes |
+| Platform & Engine | Status | 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 |
+| **Linux + NVIDIA + LM Studio** | ✅ Verified | Calibrated with real measurements (2× RTX 5070, Ryzen 7 5800X). |
+| **Linux + Ollama** | ✅ Verified | Tested via private instance harnesses and unit test suite. |
+| **Windows / macOS** | 🧪 Supported | Official paths, system commands, and detection logic implemented. |
+| **AMD ROCm / Apple Silicon / Intel Arc** | 🧪 Supported | Hardware VRAM detection enabled; memory bandwidth sourced from lookup tables. |
+
+---
+
+## Project Architecture
+
+```
+llmtuner/
+├── src/
+│   ├── core/           # Core tuning engine, estimator, hardware detection, presets, profiles
+│   │   ├── engines/    # LM Studio and Ollama driver adapters
+│   │   ├── estimator.js# Mathematical memory and VRAM modeling
+│   │   ├── gguf.js     # GGUF tensor parser
+│   │   ├── hardware.js # GPU detection, PCIe links, VRAM monitoring
+│   │   ├── presets.js  # Preset persistence and invalidation logic
+│   │   └── profiles.js # Speed, balanced, and quality profile rules
+│   ├── cli/            # Interactive wizard and CLI argument parsing
+│   ├── i18n/           # English and Spanish localization catalogs
+│   └── web/            # Embedded HTTP/SSE server powering the desktop GUI
+├── electron/           # Desktop launcher and main process wrapper
+├── test/               # Node.js native test suite
+└── docs/               # Technical specs, real benchmark measurements, and notes
+```
+
+---
 
-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 & Testing
 
-## Development
+Clone and set up locally:
 
 ```bash
 git clone https://github.com/ronald32acunadev/llmtuner.git
 cd llmtuner
 npm install
-npm start               # terminal wizard
-npm run desktop         # desktop app
-```
 
-## Tests
+# Start CLI wizard
+npm start
 
-```bash
+# Start Desktop app
+npm run desktop
+
+# Run test suite
 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.
+The test suite includes regression tests verifying real dual-RTX 5070 measurements with Qwen2.5-Coder-32B.
+
+---
+
+## Notes & Troubleshooting
+
+- **Desktop Runtime Download**: The Electron runtime is downloaded on the first execution of `llm-tuner-desktop`. If downloading in a restricted offline environment, extract `electron-v*.zip` into the `dist/` directory of the installed `electron` package and create `path.txt` with the content `electron`.
+- **Root / Sudo Installs**: Avoid running `npm install -g --unsafe-perm` under root without proper directory ownership, as Electron may fail to unpack its binary into user space.
+- **LM Studio Compatibility**: Internal config paths are calibrated and tested against LM Studio 0.4.25+.
+
+---
 
-## Notes
+## License
 
-- 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.
+[MIT](LICENSE) © Ronald Daniel Acuña Arias