@rhizomatics/signalk-einklabel-genai-plugin 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,11 +1,20 @@
-# [1.0.1]
+# [0.3.0]
+
+- Update timeout to 60 seconds to handle slower local or free models
+- Better handle retry for responses that don't have cleanly extractable SVG
+- OpenRouter model and token usage now logged
+- Strip HTML punctuation that breaks XML before converting SVG
+
+# [0.2.0]
+
+- AI providers drop-down now restricted to available AI SDK plugins
+- Test option added to validate AI configuration, keys and connectivity
+
+# [0.1.1]
 
 - Packaging fixes
-- Simplified adding GenAI support to `esl-cli`
-- Added `openrouter` as the default built-in AI provider
-  - Other providers are available by `npm install`
 
-# [1.0.0]
+# [0.1.0]
 
 - Initial release with support for major cloud GenAI services and local LLMs
 - As an alternative to a template, an image can be generated by an LLM based on customized prompt

package/README.md

@@ -1,13 +1,21 @@
-# eInk Label GenAI Rendering
+# eInk Label GenAI Templates
 
-A companion plugin for [`@rhizomatics/signalk-einklabel-plugin`](https://github.com/rhizomatics/signalk-einklabel-plugin) that generates a device's content from an LLM prompt, as an alternative to a hand-authored SVG template.
+A companion plugin for [`@rhizomatics/signalk-einklabel-plugin`](https://github.com/rhizomatics/signalk-einklabel-plugin) that generates an image to paint on shelf label entirely from an LLM prompt, as an alternative to a hand-authored SVG template.
 
 By default it uses [OpenRouter](https://openrouter.ai), however it can use any of the [Vercel AI SDK providers](https://ai-sdk.dev/providers/ai-sdk-providers) directly, including local LLMs like Ollama.
 
+![Example Forecast](docs/assets/screenshots/example_weather_openai.png)
+
 ## Working Example
 
 This plugin comes with a marine weather forecast example prompt. When installed, and SignalK server restarted, you should see this appear as a template to choose in the main eInk Label plugin.
 
+### Testing on your server
+
+If you don't already have an AI account, get a [free API key from OpenRouter](https://openrouter.ai/openrouter/free) - set the _model_ to one of the [specific free models](https://openrouter.ai/openrouter/free), or `openrouter/free`, OpenRouter's free-tier routing alias, although note you will get a random model every time it is called, some of which are specialized (e.g. "content safety") and will not generate an image. Free models may not lookup web pages or APIs, so guess things like weather, and the image quality will likely be much poorer than using a mainstream LLM.
+
+Use the `esl-cli` CLI to see generated prompts or create test PNGs.
+
 ### Customizing Prompts
 
 Prompts have the same template syntax as the SVG images, so the weather forecast will give the current GPS position, and the length and type of boat.
@@ -16,17 +24,25 @@ All prompts also get a generated appendix to the prompt that gives details about
 
 ### Full Example
 
-```markdown
-Summarize the maritime weather outlook for the next 24 hours, appropriate for the sailor of a 13.6m Sailing craft positioned at latitude 40.689247, longitude -74.044502
+#### Forecast
 
-Generate an SVG image for the result suitable for a ZhunyCo 4.13" eInk Electronic Shelf Label display with pixel height 240 and width 416. Available colours are black (#000000), white (#FFFFFF), red (#FF0000), yellow (#FFFF00). Fonts available are serif, sans-serif, monospace.
+> Summarize the maritime weather outlook for the next 24 hours, appropriate for the sailor of a 13.6m Sailing craft positioned at latitude 40.689247, longitude -74.044502
 
-Use graphics to make it easier to read and use the space better, and use colour and layout to draw attention to safety critical information. Include in minimal size font the source of the information.
-```
+#### Target Guidance
+
+The following has been automatically added to the end of the standard prompt, with information specific to which label is being targetted.
+
+> Generate an SVG image for the result suitable for a ZhunyCo 4.13" eInk Electronic Shelf Label display with pixel height 240 and width 416. Available colours are black (#000000), white (#FFFFFF), red (#FF0000), yellow (#FFFF00). Fonts available are serif, sans-serif, monospace.
+>
+> Use graphics to make it easier to read and use the space better, and use colour and layout to draw attention to safety critical information. Include in minimal size font the source of the information and generation timestamp.
+
+### CAUTION
+
+Be careful with GenAI generated content, it will often be very good but may be prone to hallucinations or omissions.
 
 ## Installation
 
-Install both plugins from the SignalK AppStore (or `npm install @rhizomatics/signalk-einklabel-plugin @rhizomatics/signalk-einklabel-genai-plugin`), then install whichever LLM provider package(s) you'll actually use - these are `optionalDependencies`, not installed automatically, since a user only ever needs one. `openrouter` is the one exception: `@openrouter/ai-sdk-provider` is a regular `dependency`, so it's already installed and needs no extra step, as is the base `ai` package:
+Install both plugins from the SignalK AppStore (or `npm install @rhizomatics/signalk-einklabel-plugin @rhizomatics/signalk-einklabel-genai-plugin`), then install whichever LLM provider package(s) you'll actually use - these are `optionalDependencies`, not installed automatically, since most people will likely only ever need one. `openrouter` is the one exception: `@openrouter/ai-sdk-provider` is a regular `dependency`, so it's already installed and needs no extra step, as is the base `ai` package:
 
 ```bash
 npm install ai @ai-sdk/openai          # llmProvider: "openai"
@@ -41,14 +57,21 @@ npm install ai @ai-sdk/openai-compatible  # llmProvider: "local" (LM Studio, vLL
 
 If the package for your configured provider isn't installed, a GenAI-backed device falls back to the core plugin's warning template with a log message naming exactly which package to `npm install`.
 
+### Local LLMs
+
+Many Raspberry Pi type tiny computers either have an onboard NPU for AI work, or an add-on 'hat', like the [Raspberry Pi AI Kit](https://www.raspberrypi.com/products/ai-kit/).
+
+Combined with a distilled model, for example Llama 3.2 3B, Phi-4 Mini 3.8B, or Qwen3.5-4B, it is possible to have something reasonable in 8Gb, and the eInk use case is ideal, since it runs in the background a couple of times a day, so slow token generation isn't an issue.
+
 ## Configuration
 
-- `llmProvider` - `openai`, `anthropic`, `google`, `xai`, `deepseek`, `moonshotai`, `openrouter`, `ollama`, or `local` (any other OpenAI-compatible server)
+- `llmProvider` - `openai`, `anthropic`, `google`, `xai`, `deepseek`, `moonshotai`, `openrouter`, `ollama`, or `local` (any other OpenAI-compatible server). The config screen's dropdown only lists providers whose package is actually installed (`openrouter` always is) - install another one's optional package and reopen the page to add it.
 - `llmApiKey` - not needed for `ollama`/`local` unless your server itself checks one
 - `llmModel` - provider-specific model id, e.g. `gpt-4o`, `claude-sonnet-4-5`, `gemini-2.5-flash`, `grok-4`, or an Ollama/local model tag
 - `llmBaseUrl` - required for `local`; optional for `ollama` (defaults to `http://localhost:11434/v1`)
 - `llmTimeoutSeconds`/`llmRetries` - how long to wait, and how many attempts, before giving up (the core plugin then shows its fallback warning)
 - `promptsDir` - where to look for your own `.md` prompt files, same convention as the core plugin's `templatesDir` (empty for the default, a relative path resolves against `~/.signalk`, absolute used as-is)
+- `testConnection` - not a persistent setting, just a one-shot checkbox: check it and save to send one test message to the LLM settings above as soon as the plugin (re)starts. The result (success, or the error) shows up on this plugin's own entry on the Plugin Config page - the checkbox clears itself afterwards, so it won't refire on the next ordinary restart.
 
 ## Writing Prompts
 

package/dist/cliExtension.js

@@ -106,7 +106,7 @@ addPromptOptions(cli.program
     .option("--llm-api-key <key>", "LLM API key - falls back to the provider's usual environment variable if omitted")
     .requiredOption("--llm-model <name>", "provider-specific model id/name, e.g. gpt-4o, claude-sonnet-4-5, gemini-2.5-flash, grok-4, or a local/ollama model tag")
     .option("--llm-base-url <url>", 'OpenAI-compatible endpoint - required if --llm-provider is "local"; for "ollama" defaults to http://localhost:11434/v1')
-    .option("--llm-timeout <seconds>", "LLM call timeout", "30")
+    .option("--llm-timeout <seconds>", "LLM call timeout", "60")
     .option("--llm-retries <n>", "LLM call attempts before giving up", "2")
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     .action(async (name, opts) => {
@@ -118,8 +118,13 @@ addPromptOptions(cli.program
         llmBaseUrl: opts.llmBaseUrl,
         llmTimeoutSeconds: Number(opts.llmTimeout),
     };
-    const raw = await (0, retry_1.withRetries)(Number(opts.llmRetries), () => (0, llmGateway_1.callLlm)(llmSettings, prompt));
-    const svg = (0, llmGateway_1.extractSvg)(raw);
+    const { text: svg, model, usage, } = await (0, retry_1.withRetries)(Number(opts.llmRetries), async () => {
+        const result = await (0, llmGateway_1.callLlm)(llmSettings, prompt);
+        return { ...result, text: (0, llmGateway_1.extractSvg)(result.text) };
+    });
+    if ((0, llmGateway_1.isOpenRouterProvider)(llmSettings.llmProvider)) {
+        console.log(`openrouter model=${model ?? "unknown"} usage=${JSON.stringify(usage)}`);
+    }
     const svgPath = opts.saveSvg ?? (0, path_1.join)((0, os_1.tmpdir)(), `esl-cli-generate-${Date.now()}.svg`);
     await (0, promises_1.writeFile)(svgPath, svg);
     const width = Number(opts.width);

package/dist/config.d.ts

@@ -29,6 +29,13 @@ export interface PluginConfig {
      * absolute path. Use `resolvePromptsDir` to turn this into an actual path.
      */
     promptsDir: string;
+    /**
+     * When `true`, `start()` sends one test message to the configured LLM and reports the result via
+     * `app.setPluginStatus`/`setPluginError` (visible on the server's Plugin Config page) - then clears
+     * itself back to `false` via `savePluginOptions` so it doesn't refire on every ordinary restart. Not
+     * a persistent setting, just a one-shot "test connection now" checkbox - see `plugin.ts`'s `start()`.
+     */
+    testConnection?: boolean;
 }
 /**
  * This package's own bundled `prompts/` directory (ships alongside `dist/`, see package.json's

package/dist/config.js

@@ -21,7 +21,7 @@ const SIGNALK_HOME_DIR = (0, path_1.join)((0, os_1.homedir)(), ".signalk");
 const DEFAULT_PROMPTS_DIR = (0, path_1.join)(SIGNALK_HOME_DIR, "einklabel-genai", "prompts");
 function defaultConfig() {
     return {
-        llmTimeoutSeconds: 30,
+        llmTimeoutSeconds: 60,
         llmRetries: 2,
         promptsDir: "",
     };

package/dist/llmGateway.d.ts

@@ -5,7 +5,7 @@ export type LlmSettings = RegistryLlmSettings & {
 };
 /**
  * `ai` and every `@ai-sdk/*`/`ai-sdk-ollama` provider package (other than `@openrouter/ai-sdk-provider`,
- * see below) are `optionalDependencies` (see package.json), not plain `dependencies` - a user picks
+ * see below) are `optionalDependencies` (see package.json), not plain `dependencies` - user picks
  * exactly one provider, so there's no reason to force every one of them to install, and an install that
  * fails to fetch one it doesn't even use (a network hiccup, `npm install --omit=optional`, an unsupported
  * platform) must not break this plugin for everyone else. That means every reference to one of these
@@ -15,16 +15,53 @@ export type LlmSettings = RegistryLlmSettings & {
  * is erased entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
  */
 export declare function loadOptional<M>(moduleName: string): M;
+/** Whether `moduleName` resolves at all - cheaper than `loadOptional`, since it never actually evaluates the module. */
+export declare function isPackageInstalled(moduleName: string): boolean;
 /**
- * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
- * validated as SVG, see `extractSvg`. Wrapped in its own timeout (`AbortController`) since this is the
- * one genuinely slow/unreliable network call in this plugin.
+ * Every `llmProvider` name actually usable right now, for the plugin config screen's `llmProvider`
+ * dropdown (`plugin.ts`'s `schema()`) - so a provider whose package isn't installed doesn't even show
+ * up as pickable. Rather than a second hardcoded provider-to-package table duplicating `resolveModel`'s
+ * switch, this reads this plugin's own `optionalDependencies` straight out of `package.json` (the
+ * actual, already-curated list of installable provider packages - `require.resolve`-able but never
+ * `require()`'d, so a failed optional install can't crash this) and checks each with `isPackageInstalled`.
+ * `"openrouter"` is always included (it's a regular `dependency`, see this module's top doc comment);
+ * any name added via `registerLlmProvider` is included unconditionally too, since there's no package to
+ * check for those.
  */
-export declare function callLlm(settings: LlmSettings, prompt: string): Promise<string>;
+export declare function availableProviders(): string[];
+/** Token counts for one `callLlm` call, straight off the Vercel AI SDK's own normalized `usage` - see `CallLlmResult`. */
+export interface LlmUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+/**
+ * `callLlm`'s result - `text` is the raw response (not yet extracted/validated as SVG, see `extractSvg`).
+ * `model`/`usage` are mainly useful for `"openrouter"`, where `llmModel` is often a routing alias (e.g.
+ * the `"openrouter/free"` default - see `DEFAULT_OPENROUTER_MODEL`) that resolves to a *different* actual
+ * model each call - callers that care (see `isOpenRouterProvider`) can log which one actually answered
+ * and how many tokens it used.
+ */
+export interface CallLlmResult {
+    text: string;
+    model?: string;
+    usage?: LlmUsage;
+}
+/** Whether `provider` (or its default) is `"openrouter"` - gates the model/usage debug logging `CallLlmResult` exists for for, since that detail is really only interesting there (see `CallLlmResult`'s doc comment). */
+export declare function isOpenRouterProvider(provider?: string): boolean;
+/**
+ * Calls the configured LLM gateway with `prompt`. Wrapped in its own timeout (`AbortController`) since
+ * this is the one genuinely slow/unreliable network call in this plugin.
+ */
+export declare function callLlm(settings: LlmSettings, prompt: string): Promise<CallLlmResult>;
 /**
  * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
  * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
- * side, despite the target-guidance fragment telling it not to.
+ * side, despite the target-guidance fragment telling it not to. Also swaps any `&nbsp;` for the literal
+ * U+00A0 character it means - `&nbsp;` isn't one of XML's five predefined entities (only
+ * `&amp;`/`&lt;`/`&gt;`/`&apos;`/`&quot;` are), so a model used to writing HTML emits it anyway, and the
+ * core plugin's `@xmldom/xmldom` DOMParser then fails to parse the document at all over one undefined
+ * entity reference. The raw character needs no entity encoding, so this sidesteps the problem entirely.
  */
 export declare function extractSvg(raw: string): string;
 export type { PluginConfig };

package/dist/llmGateway.js

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadOptional = loadOptional;
+exports.isPackageInstalled = isPackageInstalled;
+exports.availableProviders = availableProviders;
+exports.isOpenRouterProvider = isOpenRouterProvider;
 exports.callLlm = callLlm;
 exports.extractSvg = extractSvg;
+const fs_1 = require("fs");
+const path_1 = require("path");
 const ai_sdk_provider_1 = require("@openrouter/ai-sdk-provider");
 const llmProviderRegistry_1 = require("./llmProviderRegistry");
 /**
  * `ai` and every `@ai-sdk/*`/`ai-sdk-ollama` provider package (other than `@openrouter/ai-sdk-provider`,
- * see below) are `optionalDependencies` (see package.json), not plain `dependencies` - a user picks
+ * see below) are `optionalDependencies` (see package.json), not plain `dependencies` - user picks
  * exactly one provider, so there's no reason to force every one of them to install, and an install that
  * fails to fetch one it doesn't even use (a network hiccup, `npm install --omit=optional`, an unsupported
  * platform) must not break this plugin for everyone else. That means every reference to one of these
@@ -27,6 +32,56 @@ function loadOptional(moduleName) {
 }
 /** Ollama's own default local listen address - see the `"ollama"` case in `resolveModel` below. */
 const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
+/** Whether `moduleName` resolves at all - cheaper than `loadOptional`, since it never actually evaluates the module. */
+function isPackageInstalled(moduleName) {
+    try {
+        require.resolve(moduleName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A package name from this plugin's own `optionalDependencies` doesn't always match the `llmProvider`
+ * id `resolveModel`'s switch uses it for: `ai-sdk-ollama` isn't under the `@ai-sdk/` scope at all, and
+ * `@ai-sdk/openai-compatible` backs `"local"`, not a provider literally named "openai-compatible".
+ * Every other optional package *does* match `@ai-sdk/<id>` (see `resolveModel`'s cases), so only these
+ * two irregular ones need spelling out - everything else is derived by stripping the scope below.
+ */
+const PACKAGE_TO_PROVIDER_ID = {
+    "ai-sdk-ollama": "ollama",
+    "@ai-sdk/openai-compatible": "local",
+};
+/** Preferred dropdown order - purely cosmetic; anything not listed here (a future package, a custom-registered name) sorts after these, alphabetically. */
+const PROVIDER_DISPLAY_ORDER = ["openrouter", "openai", "anthropic", "google", "xai", "deepseek", "moonshotai", "ollama", "local"];
+function byDisplayOrder(a, b) {
+    const ai = PROVIDER_DISPLAY_ORDER.indexOf(a);
+    const bi = PROVIDER_DISPLAY_ORDER.indexOf(b);
+    if (ai === -1 && bi === -1)
+        return a.localeCompare(b);
+    if (ai === -1 || bi === -1)
+        return ai === -1 ? 1 : -1;
+    return ai - bi;
+}
+/**
+ * Every `llmProvider` name actually usable right now, for the plugin config screen's `llmProvider`
+ * dropdown (`plugin.ts`'s `schema()`) - so a provider whose package isn't installed doesn't even show
+ * up as pickable. Rather than a second hardcoded provider-to-package table duplicating `resolveModel`'s
+ * switch, this reads this plugin's own `optionalDependencies` straight out of `package.json` (the
+ * actual, already-curated list of installable provider packages - `require.resolve`-able but never
+ * `require()`'d, so a failed optional install can't crash this) and checks each with `isPackageInstalled`.
+ * `"openrouter"` is always included (it's a regular `dependency`, see this module's top doc comment);
+ * any name added via `registerLlmProvider` is included unconditionally too, since there's no package to
+ * check for those.
+ */
+function availableProviders() {
+    const packageJson = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, "..", "package.json"), "utf-8"));
+    const installed = Object.keys(packageJson.optionalDependencies ?? {})
+        .filter(isPackageInstalled)
+        .map((pkg) => PACKAGE_TO_PROVIDER_ID[pkg] ?? pkg.replace(/^@ai-sdk\//, ""));
+    return [...new Set(["openrouter", ...installed, ...(0, llmProviderRegistry_1.listRegisteredProviders)()])].sort(byDisplayOrder);
+}
 /**
  * Resolves `settings` to a Vercel AI SDK model handle. Checks `registerLlmProvider`'s registry
  * (`./llmProviderRegistry.ts`) first, by exact `llmProvider` name, before falling through to this
@@ -93,19 +148,26 @@ function resolveModel(settings) {
         }
     }
 }
+/** Whether `provider` (or its default) is `"openrouter"` - gates the model/usage debug logging `CallLlmResult` exists for for, since that detail is really only interesting there (see `CallLlmResult`'s doc comment). */
+function isOpenRouterProvider(provider) {
+    return (provider ?? "openrouter") === "openrouter";
+}
 /**
- * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
- * validated as SVG, see `extractSvg`. Wrapped in its own timeout (`AbortController`) since this is the
- * one genuinely slow/unreliable network call in this plugin.
+ * Calls the configured LLM gateway with `prompt`. Wrapped in its own timeout (`AbortController`) since
+ * this is the one genuinely slow/unreliable network call in this plugin.
  */
 async function callLlm(settings, prompt) {
-    const model = resolveModel(settings);
+    const languageModel = resolveModel(settings);
     const { generateText } = loadOptional("ai");
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 30) * 1000);
+    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 60) * 1000);
     try {
-        const { text } = await generateText({ model, prompt, abortSignal: controller.signal });
-        return text;
+        const { text, response, usage } = await generateText({ model: languageModel, prompt, abortSignal: controller.signal });
+        return {
+            text,
+            model: response.modelId,
+            usage: { promptTokens: usage.inputTokens, completionTokens: usage.outputTokens, totalTokens: usage.totalTokens },
+        };
     }
     finally {
         clearTimeout(timer);
@@ -114,13 +176,17 @@ async function callLlm(settings, prompt) {
 /**
  * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
  * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
- * side, despite the target-guidance fragment telling it not to.
+ * side, despite the target-guidance fragment telling it not to. Also swaps any `&nbsp;` for the literal
+ * U+00A0 character it means - `&nbsp;` isn't one of XML's five predefined entities (only
+ * `&amp;`/`&lt;`/`&gt;`/`&apos;`/`&quot;` are), so a model used to writing HTML emits it anyway, and the
+ * core plugin's `@xmldom/xmldom` DOMParser then fails to parse the document at all over one undefined
+ * entity reference. The raw character needs no entity encoding, so this sidesteps the problem entirely.
  */
 function extractSvg(raw) {
     const start = raw.indexOf("<svg");
     const end = raw.lastIndexOf("</svg>");
     if (start === -1 || end === -1 || end < start) {
-        throw new Error('LLM response did not contain a "<svg>...</svg>" document');
+        throw new Error(`LLM response did not contain a "<svg>...</svg>" document - first 512 chars: ${raw.slice(0, 512)}`);
     }
-    return raw.slice(start, end + "</svg>".length);
+    return raw.slice(start, end + "</svg>".length).replace(/&nbsp;/gi, " ");
 }

package/dist/llmProviderRegistry.d.ts

@@ -24,3 +24,5 @@ export type LlmProviderFactory = (settings: LlmSettings) => LlmModel;
  */
 export declare function registerLlmProvider(name: string, factory: LlmProviderFactory): void;
 export declare function getLlmProvider(name: string): LlmProviderFactory | undefined;
+/** Names of every custom provider registered via `registerLlmProvider` - see `llmGateway.ts`'s `availableProviders`. */
+export declare function listRegisteredProviders(): string[];

package/dist/llmProviderRegistry.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerLlmProvider = registerLlmProvider;
 exports.getLlmProvider = getLlmProvider;
+exports.listRegisteredProviders = listRegisteredProviders;
 const providers = new Map();
 /**
  * Public extension point mirroring the core `signalk-einklabel-plugin`'s own `registerVendorDriver`/
@@ -23,3 +24,7 @@ function registerLlmProvider(name, factory) {
 function getLlmProvider(name) {
     return providers.get(name);
 }
+/** Names of every custom provider registered via `registerLlmProvider` - see `llmGateway.ts`'s `availableProviders`. */
+function listRegisteredProviders() {
+    return [...providers.keys()];
+}

package/dist/plugin.js

@@ -6,17 +6,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPlugin = createPlugin;
 const signalk_einklabel_plugin_1 = __importDefault(require("@rhizomatics/signalk-einklabel-plugin"));
 const config_1 = require("./config");
+const llmGateway_1 = require("./llmGateway");
+const retry_1 = require("./retry");
 const templateProvider_1 = require("./templateProvider");
+/** Sent by the `testConnection` checkbox - short and cheap on tokens, just enough to prove the round trip works. */
+const TEST_PROMPT = 'Reply with exactly the word "OK", nothing else.';
+/**
+ * Runs one test call against `config`'s LLM settings and reports the outcome via
+ * `setPluginStatus`/`setPluginError` - both shown on the server's Plugin Config page - then clears the
+ * one-shot `testConnection` flag via `savePluginOptions` so it doesn't refire on the next ordinary
+ * restart. Fire-and-forget from `start()`: failures are reported through `setPluginError`, not thrown,
+ * since nothing in `start()`'s own contract is waiting on this.
+ */
+async function runConnectionTest(app, config) {
+    const label = `${config.llmProvider ?? "openrouter"}/${config.llmModel ?? "(no model configured)"}`;
+    try {
+        const { text, model, usage } = await (0, retry_1.withRetries)(config.llmRetries, () => (0, llmGateway_1.callLlm)(config, TEST_PROMPT));
+        if ((0, llmGateway_1.isOpenRouterProvider)(config.llmProvider)) {
+            app.debug(`openrouter model=${model ?? "unknown"} usage=${JSON.stringify(usage)}`);
+        }
+        app.setPluginStatus(`LLM test OK (${label}): ${text.trim().slice(0, 200)}`);
+    }
+    catch (err) {
+        app.setPluginError(`LLM test failed (${label}): ${err.message}`);
+    }
+    finally {
+        app.savePluginOptions({ ...config, testConnection: false }, (err) => {
+            if (err)
+                app.debug(`failed to clear testConnection flag: ${err.message}`);
+        });
+    }
+}
 function createPlugin(app) {
     // Updated by `start()` on every (re)start - `createTemplateProvider`'s functions all read through
     // this closure rather than capturing one fixed config object, so a saved config change takes effect
     // on the *next* repaint without needing the core plugin (which holds the actual repaint schedule) to
     // know or care that anything changed on this side.
     let currentConfig = (0, config_1.defaultConfig)();
-    signalk_einklabel_plugin_1.default.registerTemplateProvider((0, templateProvider_1.createTemplateProvider)(() => currentConfig));
+    signalk_einklabel_plugin_1.default.registerTemplateProvider((0, templateProvider_1.createTemplateProvider)(app, () => currentConfig));
     return {
         id: "signalk-einklabel-genai-plugin",
-        name: "eInk Label GenAI Rendering",
+        name: "eInk Label GenAI Templates",
         description: "Contributes LLM-generated prompts as an alternative to hand-authored SVG templates for signalk-einklabel-plugin",
         schema: () => ({
             type: "object",
@@ -24,11 +54,12 @@ function createPlugin(app) {
                 llmProvider: {
                     type: "string",
                     title: "LLM provider",
-                    description: 'Which LLM gateway to call - "OpenRouter" is bundled and needs no extra install; every other option ' +
-                        "(other than local/ollama) needs its own optional npm package installed, e.g. `npm install ai @ai-sdk/anthropic` " +
-                        '(see README). "Ollama" defaults to a local Ollama server with no further config; "Local" is any other ' +
-                        'OpenAI-compatible endpoint (e.g. LM Studio) and needs "LLM base URL" below.',
-                    enum: ["openrouter", "openai", "anthropic", "google", "xai", "deepseek", "moonshotai", "ollama", "local"],
+                    description: "Which LLM gateway to call - only providers whose npm package is actually installed are listed here; " +
+                        "install another one's optional package (e.g. `npm install ai @ai-sdk/anthropic`, see README) and reopen " +
+                        'this page to add it. "OpenRouter" is bundled and needs no extra install. "Ollama" defaults to a local ' +
+                        'Ollama server with no further config; "Local" is any other OpenAI-compatible endpoint (e.g. LM Studio) ' +
+                        'and needs "LLM base URL" below.',
+                    enum: (0, llmGateway_1.availableProviders)(),
                     default: "openrouter",
                 },
                 llmApiKey: {
@@ -69,12 +100,23 @@ function createPlugin(app) {
                         'picker, suffixed "(GenAI)".',
                     default: (0, config_1.defaultConfig)().promptsDir,
                 },
+                testConnection: {
+                    type: "boolean",
+                    title: "Test connection now",
+                    description: "Check this and save to send one test message to the LLM settings above as soon as the plugin (re)starts. " +
+                        "Watch this plugin's entry on the Plugin Config page for the result (success or the error) - the checkbox " +
+                        "clears itself afterwards, so it won't refire on the next ordinary restart.",
+                    default: false,
+                },
             },
         }),
         uiSchema: () => ({ llmApiKey: { "ui:widget": "password" } }),
         start(config) {
             currentConfig = { ...(0, config_1.defaultConfig)(), ...config };
             app.debug(`eInk Label GenAI plugin started (llmProvider=${currentConfig.llmProvider ?? "openrouter"})`);
+            if (currentConfig.testConnection) {
+                runConnectionTest(app, currentConfig).catch((err) => app.debug(`connection test failed unexpectedly: ${err.message}`));
+            }
         },
         stop() { },
     };

package/dist/templateProvider.d.ts

@@ -1,3 +1,4 @@
+import { ServerAPI } from "@signalk/server-api";
 import esl from "@rhizomatics/signalk-einklabel-plugin";
 import { PluginConfig } from "./config";
 /** Appended to every prompt name this plugin offers in the core plugin's "Template" dropdown. */
@@ -8,4 +9,4 @@ export declare const SUFFIX = "(GenAI)";
  * current `promptsDir` fresh each time, rather than once at startup, so adding/editing a `.md` prompt
  * file takes effect without a plugin restart - same as the core plugin's own template directory.
  */
-export declare function createTemplateProvider(getConfig: () => PluginConfig): esl.TemplateProvider;
+export declare function createTemplateProvider(app: ServerAPI, getConfig: () => PluginConfig): esl.TemplateProvider;

package/dist/templateProvider.js

@@ -24,7 +24,7 @@ function promptNameFor(templateName) {
  * current `promptsDir` fresh each time, rather than once at startup, so adding/editing a `.md` prompt
  * file takes effect without a plugin restart - same as the core plugin's own template directory.
  */
-function createTemplateProvider(getConfig) {
+function createTemplateProvider(app, getConfig) {
     function promptsDir() {
         return (0, config_1.resolvePromptsDir)(getConfig().promptsDir);
     }
@@ -61,8 +61,16 @@ function createTemplateProvider(getConfig) {
                 llmBaseUrl: config.llmBaseUrl,
                 llmTimeoutSeconds: config.llmTimeoutSeconds,
             };
-            const raw = await (0, retry_1.withRetries)(config.llmRetries, () => (0, llmGateway_1.callLlm)(llmSettings, prompt));
-            const svg = (0, llmGateway_1.extractSvg)(raw);
+            // `extractSvg` runs inside the retry loop, not after it - an unparseable response (the model
+            // wrapped its SVG oddly, got cut off, whatever) gets a fresh attempt the same way a network/
+            // timeout failure does, rather than failing the whole render on one bad completion.
+            const { text: svg, model, usage, } = await (0, retry_1.withRetries)(config.llmRetries, async () => {
+                const result = await (0, llmGateway_1.callLlm)(llmSettings, prompt);
+                return { ...result, text: (0, llmGateway_1.extractSvg)(result.text) };
+            });
+            if ((0, llmGateway_1.isOpenRouterProvider)(config.llmProvider)) {
+                app.debug(`openrouter model=${model ?? "unknown"} usage=${JSON.stringify(usage)}`);
+            }
             const renderer = new signalk_einklabel_plugin_1.default.Renderer();
             // `esl.Renderer.render()` reads its template from a file path, not a string - the LLM's SVG is
             // written out as one so the exact same rasterization path a bundled/local template gets is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-genai-plugin",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "GenAI prompt generated labels for the eInk Electronic Shelf Label plugin. Contributes prompts as an alternative to hand-authored SVG templates.",
   "keywords": [
     "eink",
@@ -79,7 +79,7 @@
     "node": ">=18"
   },
   "signalk": {
-    "displayName": "eInk Label GenAI Rendering",
+    "displayName": "eInk Label GenAI Templates",
     "appIcon": "docs/assets/icons/icon_tmp.png",
     "screenshots": [
       "docs/assets/screenshots/example_weather_openai.png"

package/prompts/.assets/target_guidance.md

@@ -1,5 +1,5 @@
-Generate an SVG image for the result suitable for a {source=label,path=manufacturer,default=} {source=label,path=label,default=} eInk Electronic Shelf Label display with pixel height {source=label,path=height} and width {source=label,path=width}. Available colours are {source=label,path=colours,format=csv}. Fonts available are {source=label,path=fonts,format=csv}.
+Generate an SVG image for the result suitable for a {source=label,path=manufacturer,default=} {source=label,path=label,default=} eInk Electronic Shelf Label display with pixel height {source=label,path=height} and width {source=label,path=width}. Available colours are {source=label,path=colours,format=csv}. Fonts available are {source=label,path=fonts,format=csv}, use text no smaller than 9pt.
 
-Use graphics to make it easier to read and use the space better, and use colour and layout to draw attention to safety critical information. Include in minimal size font the source of the information.
+Use graphics to make it easier to read and use the space better, and use colour and layout to draw attention to safety critical information. Always use high contrast for text. Include in minimal size font the source of the information and generation timestamp.
 
 {source=label,path=description}