localpi 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ Localpi is a local Pi launcher for open-weight models.
 
 By default, Localpi discovers available local providers, lets you choose when more than one model is loaded, points Pi at the selected model, and writes Pi config for the other discovered models so `/model` can switch among them during the session.
 
-Localpi supports LM Studio, vLLM, custom OpenAI-compatible servers, and a managed `llama-server` fallback.
+Localpi supports LM Studio, vLLM, custom OpenAI-compatible servers, and an optional managed `llama-server` fallback.
 
 Localpi is intentionally generic. It does not contain classifier prompts, dataset workflows, GitHub routing logic, or final-schema output machinery. Structured classifier runs belong in caller tools such as `localpager-agent`.
 
@@ -38,7 +38,7 @@ Target default:
 localpi --model gemma-12b
 ```
 
-This uses the default `auto` runtime. If exactly one model is loaded locally, Localpi selects it. If multiple models are loaded in an interactive terminal, Localpi boots Pi with a temporary default and opens Pi's native model selector. If no external model is loaded, Localpi can fall back to the managed `llama-server` default. Thinking starts as `off` unless `--thinking` or `LOCALPI_THINKING` sets another startup level.
+This uses the default `auto` runtime. If exactly one model is loaded locally, Localpi selects it. If multiple models are loaded in an interactive terminal, Localpi boots Pi with a temporary default and opens Pi's native model selector. If no external model is loaded and `llama-server` is installed, Localpi can fall back to the managed `llama-server` default. Thinking starts as `off` unless `--thinking` or `LOCALPI_THINKING` sets another startup level.
 
 LM Studio is explicit:
 

package/dist/src/localpi/catalog.js

@@ -1,5 +1,5 @@
 import { listModels } from "../llm/openai.js";
-import { getManagedLlamaServerMetadata, getLlamaServerModels, llamaBaseUrl } from "./llama-server.js";
+import { getManagedLlamaServerMetadata, getLlamaServerModels, llamaBaseUrl, managedLlamaServerUnavailableMessage } from "./llama-server.js";
 import { listModelAliases, resolveLlamaModel } from "./models.js";
 import { providerConfigs } from "./provider-registry.js";
 export async function discoverModelCatalog(options) {
@@ -40,7 +40,14 @@ async function discoverOpenAiCompatibleProvider(config, options) {
         if (explicitOpenAiProviderSelected(options, config.id)) {
             throw error;
         }
-        return { models: [], warnings: [`${config.name} is not responding at ${config.baseUrl}`] };
+        return {
+            models: [],
+            warnings: [
+                catalogWarning(config.id, config.name, "provider-not-responding", {
+                    message: `not responding at ${config.baseUrl}`
+                })
+            ]
+        };
     }
 }
 function openAiCatalogModel(config, model, options) {
@@ -81,10 +88,18 @@ async function discoverManagedLlamaProvider(config, options) {
     const baseUrl = llamaBaseUrl(options);
     const aliases = await listModelAliases();
     const loaded = await loadedLlamaModels(config, options, baseUrl, aliases);
+    const unavailableMessage = await managedLlamaServerUnavailableMessage(options);
     const startable = await startableLlamaModels(config, options, baseUrl, loaded.models, aliases);
     return {
         models: [...loaded.models, ...startable],
-        warnings: loaded.warnings
+        warnings: unavailableMessage === undefined
+            ? loaded.warnings
+            : [
+                ...loaded.warnings,
+                catalogWarning(config.id, config.name, "managed-command-unavailable", {
+                    message: unavailableMessage
+                })
+            ]
     };
 }
 async function loadedLlamaModels(config, options, baseUrl, aliases) {
@@ -162,6 +177,26 @@ export function managedModelSupportsReasoning(modelId) {
         normalized.includes("gpt-oss") ||
         normalized.includes("gemma-4"));
 }
+export function runtimeCatalogWarning(providerId, providerName, message) {
+    return catalogWarning(providerId, providerName, "runtime-warning", { message });
+}
+export function formatCatalogWarning(warning) {
+    switch (warning.code) {
+        case "provider-not-responding":
+            return `${warning.providerName} is ${warning.message}`;
+        case "managed-command-unavailable":
+        case "runtime-warning":
+            return warning.message;
+    }
+}
+function catalogWarning(providerId, providerName, code, options) {
+    return {
+        providerId,
+        providerName,
+        code,
+        message: options.message
+    };
+}
 function isDeepSeekThinkingModel(normalizedModelId) {
     return (normalizedModelId.includes("deepseek") &&
         (hasModelToken(normalizedModelId, "r1") ||

package/dist/src/localpi/llama-server.js

@@ -1,6 +1,6 @@
 import { execFile, spawn } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { closeSync, constants, openSync } from "node:fs";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { listModels, normalizeBaseUrl } from "../llm/openai.js";
 export async function ensureLlamaServer(options, model) {
@@ -23,6 +23,12 @@ export async function ensureLlamaServer(options, model) {
         contextWindow: requestedContextWindow(options, model)
     };
 }
+export async function managedLlamaServerUnavailableMessage(options) {
+    if (await executableExists(options.serverCommand)) {
+        return undefined;
+    }
+    return `llama-server command ${options.serverCommand} is not available; managed llama-server fallback disabled`;
+}
 async function handleExistingServer(options, model, baseUrl, warnings) {
     const state = await existingServerState(options, baseUrl);
     if (state.existing === undefined) {
@@ -118,6 +124,7 @@ function rejectExternalModelConflict(baseUrl, existing, requestedModel) {
     throw new Error(`server at ${baseUrl} is already serving ${ids.join(", ")}; stop it or choose that model before starting ${requestedModel}`);
 }
 async function startManagedServer(options, model) {
+    await assertManagedLlamaServerAvailable(options);
     await mkdir(serverDir(options), { recursive: true });
     const logPath = path.join(serverDir(options), "llama-server.log");
     const logFd = openSync(logPath, "a");
@@ -158,6 +165,36 @@ async function startManagedServer(options, model) {
         closeSync(logFd);
     }
 }
+async function assertManagedLlamaServerAvailable(options) {
+    if (await executableExists(options.serverCommand)) {
+        return;
+    }
+    throw new Error(`failed to start llama-server: executable not found: ${options.serverCommand}; install llama-server or pass --server-command`);
+}
+async function executableExists(command) {
+    if (command.length === 0) {
+        return false;
+    }
+    if (command.includes("/") || command.includes("\\")) {
+        return canExecute(command);
+    }
+    const entries = (process.env["PATH"] ?? "").split(path.delimiter).filter((entry) => entry !== "");
+    for (const entry of entries) {
+        if (await canExecute(path.join(entry, command))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function canExecute(filePath) {
+    try {
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function serverArgs(options, model) {
     const endpoint = managedEndpoint(options);
     return [

package/dist/src/localpi/managed-runtime.js

@@ -1,5 +1,5 @@
 import { ensureLlamaServer, getManagedLlamaServerMetadata, getLlamaServerModels, llamaBaseUrl, managedLlamaServerNeedsRestart, stopManagedLlamaServer } from "./llama-server.js";
-import { managedModelSupportsReasoning } from "./catalog.js";
+import { managedModelSupportsReasoning, runtimeCatalogWarning } from "./catalog.js";
 import { catalogModelFromModelInfo, catalogRuntimeConnection, connectionCatalogModels, modelChoiceList, optionalContextWindow, replaceManagedLoadedModels } from "./runtime-connection.js";
 import { defaultLlamaModelName, findModelAlias, resolveLlamaModel } from "./models.js";
 export async function resolveLlamaRuntime(options) {
@@ -32,7 +32,10 @@ export async function resolveSelectedLlamaRuntime(options, selected, catalog) {
         const selectedModel = managedCatalogModelFromConnection(options, selected, existing);
         return catalogRuntimeConnection(options, selectedModel, {
             models: replaceManagedLoadedModels(catalog.models, selected, existing.catalogModels),
-            warnings: [...catalog.warnings, ...existing.warnings]
+            warnings: [
+                ...catalog.warnings,
+                ...runtimeWarnings("llama-server", "llama-server", existing.warnings)
+            ]
         });
     }
     return startSelectedLlamaRuntime(options, selected, catalog);
@@ -175,7 +178,10 @@ async function startSelectedLlamaRuntime(options, selected, catalog) {
     const loadedSelected = runtimeSelectedCatalogModel(options, selected, runtime);
     return catalogRuntimeConnection(options, loadedSelected, {
         models: replaceManagedLoadedModels(catalog.models, selected, [loadedSelected]),
-        warnings: [...catalog.warnings, ...runtime.warnings]
+        warnings: [
+            ...catalog.warnings,
+            ...runtimeWarnings("llama-server", "llama-server", runtime.warnings)
+        ]
     });
 }
 async function assertDirectLlamaStartIsSafe(options, model) {
@@ -217,6 +223,9 @@ function assertNoLoadedExternalModels(catalog) {
     }
     throw new Error(`external local models are already loaded; choose one or unload them before starting llama-server:\n${modelChoiceList(external)}`);
 }
+function runtimeWarnings(providerId, providerName, warnings) {
+    return warnings.map((warning) => runtimeCatalogWarning(providerId, providerName, warning));
+}
 function isGgufPathRequest(value) {
     return value.endsWith(".gguf") || value.includes("/") || value.includes("\\");
 }

package/dist/src/localpi/runtime-connection.js

@@ -1,4 +1,4 @@
-import { managedModelSupportsReasoning } from "./catalog.js";
+import { formatCatalogWarning, managedModelSupportsReasoning } from "./catalog.js";
 export function connectionStatus(connection) {
     return ([
         `runtime: ${connection.runtime}`,
@@ -25,7 +25,7 @@ export function catalogRuntimeConnection(options, selected, catalog) {
         model: selected.modelId,
         availableModels: providerModels.map((model) => model.modelId),
         catalogModels: catalog.models.filter((model) => model.availability === "loaded"),
-        warnings: catalog.warnings,
+        warnings: catalog.warnings.map(formatCatalogWarning),
         ...optionalContextWindow(options.contextWindow ?? selected.contextWindow)
     };
 }

package/dist/src/localpi/runtime-selection.js

@@ -16,7 +16,7 @@ export async function selectCatalogModel(options, catalog) {
     if (selection.model !== "auto") {
         return selectExplicitCatalogModel(options, providerFiltered, selection.provider, selection.model);
     }
-    return selectAutomaticCatalogModel(providerFiltered, catalog.warnings);
+    return selectAutomaticCatalogModel(providerFiltered, warningsForProvider(catalog.warnings, selection.provider));
 }
 async function selectExplicitCatalogModel(options, models, provider, requested) {
     const matches = matchingCatalogModels(models, requested);
@@ -39,11 +39,11 @@ function selectAutomaticCatalogModel(models, warnings) {
     if (onlyLoaded !== undefined) {
         return onlyLoaded;
     }
-    const fallback = startableFallback(models);
+    const fallback = startableFallback(models, warnings);
     if (fallback !== undefined) {
         return fallback;
     }
-    throw new Error(`no loaded models available${warnings.length === 0 ? "" : `; ${warnings.join("; ")}`}`);
+    throw new Error(noLoadedModelsMessage(models, warnings));
 }
 function modelsForProvider(models, provider) {
     return provider === undefined ? models : models.filter((model) => model.providerId === provider);
@@ -69,7 +69,73 @@ function matchingCatalogModels(models, requested) {
 function isGgufFilePathRequest(value) {
     return value.toLowerCase().endsWith(".gguf") || value.includes("\\");
 }
-function startableFallback(models) {
-    const startable = models.filter((model) => model.availability === "startable");
+function startableFallback(models, warnings) {
+    const startable = models.filter((model) => model.availability === "startable" &&
+        (model.runtime !== "managed-llama-server" || managedLlamaFallbackAvailable(warnings)));
     return (startable.find((model) => model.aliases.includes(defaultLlamaModelName()) || model.modelId === defaultLlamaModelName()) ?? startable[0]);
 }
+function managedLlamaFallbackAvailable(warnings) {
+    return !warnings.some((warning) => warning.providerId === "llama-server" && warning.code === "managed-command-unavailable");
+}
+function noLoadedModelsMessage(models, warnings) {
+    const sections = engineSections(models, warnings);
+    if (sections.length === 0) {
+        return "no loaded models available\n\nTried engines:\n\n- none reported usable models";
+    }
+    return [
+        "no loaded models available",
+        "",
+        "Tried engines:",
+        "",
+        sections.map(formatEngineSection).join("\n\n")
+    ].join("\n");
+}
+function engineSections(models, warnings) {
+    const sections = new Map();
+    for (const model of models) {
+        const section = ensureEngineSection(sections, model.providerId, model.providerName);
+        const entry = `${model.providerId}/${model.modelId}`;
+        const updated = model.availability === "loaded"
+            ? { ...section, loaded: [...section.loaded, entry] }
+            : { ...section, startable: [...section.startable, entry] };
+        sections.set(model.providerId, updated);
+    }
+    for (const warning of warnings) {
+        const section = ensureEngineSection(sections, warning.providerId, warning.providerName);
+        sections.set(warning.providerId, {
+            ...section,
+            warnings: [...section.warnings, warning.message]
+        });
+    }
+    return [...sections.values()];
+}
+function ensureEngineSection(sections, key, title) {
+    const existing = sections.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const section = { title, loaded: [], startable: [], warnings: [] };
+    sections.set(key, section);
+    return section;
+}
+function formatEngineSection(section) {
+    const lines = [`${section.title}:`];
+    if (section.loaded.length === 0) {
+        lines.push("- loaded models: none");
+    }
+    else {
+        lines.push(`- loaded models: ${section.loaded.join(", ")}`);
+    }
+    if (section.startable.length > 0) {
+        lines.push(`- startable models: ${section.startable.join(", ")}`);
+    }
+    for (const warning of section.warnings) {
+        lines.push(`- ${warning}`);
+    }
+    return lines.join("\n");
+}
+function warningsForProvider(warnings, provider) {
+    return provider === undefined
+        ? warnings
+        : warnings.filter((warning) => warning.providerId === provider);
+}

package/dist/src/localpi/runtime.js

@@ -1,4 +1,4 @@
-import { discoverModelCatalog } from "./catalog.js";
+import { discoverModelCatalog, formatCatalogWarning } from "./catalog.js";
 import { llamaBaseUrl, llamaServerStatus, stopManagedLlamaServer } from "./llama-server.js";
 import { listModelAliases } from "./models.js";
 import { catalogRuntimeConnection, connectionStatus, statusModelList } from "./runtime-connection.js";
@@ -75,7 +75,7 @@ async function catalogStatusOutput(options) {
         `runtime: ${options.runtime}`,
         `loaded models: ${statusModelList(loaded)}`,
         `startable models: ${statusModelList(startable)}`,
-        ...catalog.warnings.map((warning) => `warning: ${warning}`)
+        ...catalog.warnings.map((warning) => `warning: ${formatCatalogWarning(warning)}`)
     ].join("\n") + "\n");
 }
 function requiredOpenAiBaseUrl(options) {

package/docs/runtime-specification.md

@@ -9,7 +9,7 @@ It should make the common local-model path one command while keeping the selecte
 - Run Pi against local open-weight models without hand-editing Pi config.
 - Discover local providers by default and select from the loaded model catalog.
 - Support LM Studio and vLLM as built-in OpenAI-compatible providers.
-- Keep managed `llama-server` as the fallback when no external model is loaded.
+- Keep managed `llama-server` as an optional fallback when no external model is loaded.
 - Keep the tool generic: no classifier prompts, topic schemas, dataset generation, or final-schema output.
 - Keep large model memory usage predictable by managing only one localpi-owned `llama-server` process at a time.
 
@@ -23,11 +23,12 @@ Localpi:
 
 - probes built-in LM Studio and vLLM endpoints
 - loads configured OpenAI-compatible providers from `--providers-file`, `LOCALPI_PROVIDERS_FILE`, or `LOCALPI_MODELS_FILE`
-- includes the localpi-owned `llama-server` catalog as startable fallback entries
+- includes the localpi-owned `llama-server` catalog as startable fallback entries when available
 - selects the only loaded model automatically
 - opens Pi's native model selector when multiple loaded models are available in an interactive TTY
 - never prompts in non-interactive runs; automation can pin a model with concrete `--provider` and `--model` values
 - treats `--provider` without `--model` as catalog scoping, not as a concrete model choice
+- skips automatic managed `llama-server` fallback when the configured `llama-server` command is unavailable
 - writes Pi config for all launch-time loaded catalog entries so Pi `/model` can switch among them
 
 ### `llama-server`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localpi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi-compatible local model launcher with managed llama-server support.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,9 @@
     "url": "https://github.com/dutifuldev/localpi/issues"
   },
   "homepage": "https://github.com/dutifuldev/localpi#readme",
+  "publishConfig": {
+    "access": "public"
+  },
   "bin": {
     "localpi": "dist/src/cli/main.js"
   },
@@ -45,7 +48,7 @@
     "@vitest/coverage-v8": "^3.0.0",
     "eslint": "^9.0.0",
     "prettier": "^3.0.0",
-    "slophammer-ts": "^0.3.0",
+    "slophammer-ts": "0.4.0",
     "tsx": "^4.19.4",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",