@settinghead/voxlert 0.3.7 → 0.3.8

package/README.md

@@ -241,6 +241,22 @@ flowchart TD
 5. The chosen phrase is synthesized by the configured TTS backend.
 6. Audio is optionally post-processed, cached, then played through a serialized queue.
 
+### What does it cost?
+
+The LLM step (turning events into in-character phrases) uses a small, cheap model — not Claude. Each notification costs a fraction of a cent via OpenRouter, or **zero** if you use a local LLM. TTS and audio run entirely on your machine at zero cost. You can also skip the LLM entirely and use only fallback phrases from the voice pack (no API key needed).
+
+### Fully local mode (no cloud at all)
+
+Voxlert supports local LLM servers for the phrase generation step. Run `voxlert setup` and choose **"Local LLM (Ollama / LM Studio / llama.cpp)"**. Any OpenAI-compatible local server works:
+
+| Server | Default URL |
+|--------|------------|
+| [Ollama](https://ollama.ai) | `http://localhost:11434/v1` |
+| [LM Studio](https://lmstudio.ai) | `http://localhost:1234/v1` |
+| [llama.cpp server](https://github.com/ggerganov/llama.cpp) | `http://localhost:8080/v1` |
+
+Combined with local TTS (Qwen3-TTS), this gives you a completely offline setup — no API keys, no cloud, no cost.
+
 ## Configuration
 
 Run `voxlert config path` to find `config.json`. You can edit it directly or use `voxlert setup` and `voxlert config set`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@settinghead/voxlert",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "LLM-generated voice notifications for Claude Code, Cursor, OpenAI Codex, and OpenClaw, spoken by game characters like the StarCraft Adjutant, Kerrigan, C&C EVA, SHODAN, and more.",
   "repository": {
     "type": "git",

package/src/llm.js

@@ -91,7 +91,7 @@ function generatePhraseCloud(context, config, style, llmTemperature, examples) {
     if (!provider) return resolve({ phrase: null, fallbackReason: "unknown_provider", detail: backendId });
 
     const apiKey = getApiKey(config);
-    if (!apiKey) return resolve({ phrase: null, fallbackReason: "no_api_key" });
+    if (!apiKey && !provider.local) return resolve({ phrase: null, fallbackReason: "no_api_key" });
 
     const model = getModel(config);
     const messages = [

package/src/providers.js

@@ -11,6 +11,16 @@ export const LLM_PROVIDERS = {
     authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
     format: "openai",
   },
+  local: {
+    name: "Local LLM (Ollama / LM Studio / llama.cpp)",
+    description: "fully offline, no API key needed",
+    baseUrl: "http://localhost:11434/v1",
+    defaultModel: "qwen3:8b",
+    signupUrl: null,
+    authHeader: () => ({}),
+    format: "openai",
+    local: true,
+  },
   openai: {
     name: "OpenAI",
     description: "GPT-4o-mini",

package/src/setup.js

@@ -102,6 +102,28 @@ function validateApiKey(providerId, apiKey) {
   });
 }
 
+/**
+ * Quick connectivity check for a local LLM server.
+ * Tries GET /v1/models — works for Ollama, LM Studio, llama.cpp, etc.
+ */
+function validateLocalLlm(baseUrl) {
+  return new Promise((resolve) => {
+    try {
+      const url = new URL("/v1/models", baseUrl);
+      const reqFn = url.protocol === "https:" ? https.request : http.request;
+      const req = reqFn(url, { method: "GET", timeout: 3000 }, (res) => {
+        res.resume();
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 500 });
+      });
+      req.on("error", (err) => resolve({ ok: false, error: err.message }));
+      req.on("timeout", () => { req.destroy(); resolve({ ok: false, error: "timeout" }); });
+      req.end();
+    } catch (err) {
+      resolve({ ok: false, error: err.message });
+    }
+  });
+}
+
 /**
  * Fetch a URL and return the response body as a Buffer.
  * Rejects on non-2xx or network error.
@@ -243,7 +265,7 @@ export async function runSetup({ nonInteractive = false } = {}) {
   const chosenProvider = await select({
     message: "Which LLM provider would you like to use?",
     choices: providerChoices,
-    default: currentBackend !== "local" ? currentBackend : "openrouter",
+    default: currentBackend || "openrouter",
   });
 
   let apiKey = null;
@@ -253,69 +275,104 @@ export async function runSetup({ nonInteractive = false } = {}) {
 
     const provider = getProvider(chosenProvider);
 
-    // --- Step 2: API Key ---
-    console.log("");
-    printStep(2, "API Key");
-    printStatus("Get a key at:", provider.signupUrl);
-    console.log("");
+    if (provider.local) {
+      // --- Step 2: Local LLM Server ---
+      console.log("");
+      printStep(2, "Local LLM Server");
+      printStatus("Supported", "Ollama, LM Studio, llama.cpp, vLLM, LocalAI");
+      printStatus("Default ports", "Ollama :11434 · LM Studio :1234 · llama.cpp :8080");
+      console.log("");
 
-    const existingKey = config.llm_api_key ?? config.openrouter_api_key ?? "";
-    const maskedExisting = existingKey
-      ? `${existingKey.slice(0, 4)}…${existingKey.slice(-4)}`
-      : "";
-
-    apiKey = (await input({
-      message: "Paste your API key:",
-      default: existingKey || undefined,
-      transformer: (val) => {
-        if (!val) return maskedExisting || "";
-        if (val === existingKey) return maskedExisting;
-        if (val.length <= 8) return "****";
-        return val.slice(0, 4) + "…" + val.slice(-4);
-      },
-    })).trim();
+      const existingUrl = config.local_api?.base_url || provider.baseUrl;
+      const localUrl = (await input({
+        message: "Server URL:",
+        default: existingUrl,
+      })).trim();
+
+      const existingModel = config.local_api?.model || provider.defaultModel;
+      const localModel = (await input({
+        message: "Model name (must be already pulled/loaded):",
+        default: existingModel,
+      })).trim();
+
+      config.local_api = {
+        ...config.local_api,
+        base_url: localUrl,
+        model: localModel,
+      };
+      config.llm_model = localModel;
+      config.llm_api_key = null;
+      config.openrouter_api_key = null;
 
-    if (apiKey) {
-      process.stdout.write("  Validating key... ");
-      const result = await validateApiKey(chosenProvider, apiKey);
-      if (result.ok) {
-        console.log("valid!\n");
-      } else {
-        console.log(`could not validate (${result.error || "unknown error"})`);
-        const proceed = await confirm({
-          message: "Use this key anyway?",
-          default: true,
-        });
-        if (!proceed) {
-          apiKey = null;
-          printWarning("Skipped. Set it later with: voxlert config set llm_api_key <key>");
-          console.log("");
-        } else {
-          console.log("");
-        }
+      // Quick connectivity check
+      process.stdout.write("  Checking server... ");
+      const result = await validateLocalLlm(localUrl);
+      console.log(result.ok ? "connected!" : `not reachable (${result.error})`);
+      if (!result.ok) {
+        printWarning("Server not detected. Voxlert will use fallback phrases until the server is running.");
       }
+      console.log("");
+    } else {
+      // --- Step 2: API Key ---
+      console.log("");
+      printStep(2, "API Key");
+      printStatus("Get a key at:", provider.signupUrl);
+      console.log("");
+
+      const existingKey = config.llm_api_key ?? config.openrouter_api_key ?? "";
+      const maskedExisting = existingKey
+        ? `${existingKey.slice(0, 4)}…${existingKey.slice(-4)}`
+        : "";
+
+      apiKey = (await input({
+        message: "Paste your API key:",
+        default: existingKey || undefined,
+        transformer: (val) => {
+          if (!val) return maskedExisting || "";
+          if (val === existingKey) return maskedExisting;
+          if (val.length <= 8) return "****";
+          return val.slice(0, 4) + "…" + val.slice(-4);
+        },
+      })).trim();
 
       if (apiKey) {
-        config.llm_api_key = apiKey;
-        if (chosenProvider === "openrouter") {
-          config.openrouter_api_key = apiKey;
+        process.stdout.write("  Validating key... ");
+        const result = await validateApiKey(chosenProvider, apiKey);
+        if (result.ok) {
+          console.log("valid!\n");
+        } else {
+          console.log(`could not validate (${result.error || "unknown error"})`);
+          const proceed = await confirm({
+            message: "Use this key anyway?",
+            default: true,
+          });
+          if (!proceed) {
+            apiKey = null;
+            printWarning("Skipped. Set it later with: voxlert config set llm_api_key <key>");
+            console.log("");
+          } else {
+            console.log("");
+          }
+        }
+
+        if (apiKey) {
+          config.llm_api_key = apiKey;
+          if (chosenProvider === "openrouter") {
+            config.openrouter_api_key = apiKey;
+          }
+        } else {
+          config.llm_api_key = null;
+          config.openrouter_api_key = null;
         }
-    
       } else {
         config.llm_api_key = null;
         config.openrouter_api_key = null;
-    
       }
-    } else {
-      config.llm_api_key = null;
-      config.openrouter_api_key = null;
-  
-    }
 
-    // Set default model for chosen provider
-    if (!config.llm_model && !config.openrouter_model) {
-      config.llm_model = provider.defaultModel;
-  
+      // Set default model for chosen provider
+      if (!config.llm_model && !config.openrouter_model) {
+        config.llm_model = provider.defaultModel;
+      }
     }
   } else {
     config.llm_api_key = null;