@rhizomatics/signalk-einklabel-genai-plugin 0.1.2 → 0.3.2

package/CHANGELOG.md

@@ -1,16 +1,31 @@
-# [1.0.2]
+# [0.3.2]
+
+- Fix: a disabled plugin no longer calls the LLM. Repaints of `(GenAI)` templates now fail fast with "not running" (core shows its fallback warning) instead of making paid LLM calls with the last config, or failing with a misleading "no LLM model configured" after a restart. Templates stay listed, so saved device choices are kept (#28)
+- Fix: parallel renders of the same template to several labels no longer share one cached SVG file, which could paint one label with another's content at the wrong size (#28)
+- `@rhizomatics/signalk-einklabel-plugin` is no longer an npm `dependency`, only `signalk.requires` (and a `devDependency` for types/tests) - the App Store installs it flat in `~/.signalk/node_modules`, so the plugin always registers with the one running copy rather than a possible nested duplicate
+- Extension docs updated to match: provider packages should declare this plugin the same way
+
+# [0.3.1]
+
+- New `describeContent` API implemented to support debug use
+
+# [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
 
-# [1.0.1]
+# [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,28 +1,46 @@
-# 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.
+[![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk) [![managed by hq](https://raw.githubusercontent.com/rhizomatics/hq/main/assets/badge-managed-by-hq.svg)](https://github.com/rhizomatics/hq)
+
+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.
 
-### Customizing Prompts
+### Expanded Example
 
-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.
+#### Forecast
 
-All prompts also get a generated appendix to the prompt that gives details about the eInk label, including manufacturer, name, pixel height and width, colour range, and the description provided in the main plugin.
+> 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
 
-### Full Example
+#### Target Guidance
+
+The following has been automatically added to the end of the standard prompt, with information specific to which label is being targetted.
 
-> 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
->
 > 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.
+> 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
 
-CAUTION: Be careful with GenAI generated content, it will often be very good but may be prone to hallucinations or omissions.
+Be careful with GenAI generated content, it will often be very good but may be prone to hallucinations or omissions.
+
+### 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.
+
+All prompts also get a generated appendix to the prompt that gives details about the eInk label, including manufacturer, name, pixel height and width, colour range, and the description provided in the main plugin.
 
 ## Installation
 
@@ -111,4 +129,4 @@ import genai from "@rhizomatics/signalk-einklabel-genai-plugin";
 genai.registerLlmProvider("my-provider", (settings) => myOwnModelFactory(settings));
 ```
 
-Declare this package as a regular npm `dependency` (**not** a `peerDependency` - see the core plugin's own README for why) plus `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-genai-plugin"] }` in your extension's `package.json`.
+Don't list this package in your extension's `dependencies` (or `peerDependencies`) - declare it via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-genai-plugin"] }` in your extension's `package.json` instead, and add it as a `devDependency` for types and tests. The App Store installs required plugins flat in `~/.signalk/node_modules`, so your `require` still resolves at runtime, to the same copy the running plugin uses - see the core plugin's [Extending](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/docs/extending.md) docs for why.

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.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/index.d.ts

@@ -2,7 +2,7 @@ import { ServerAPI, Plugin } from "@signalk/server-api";
 import { registerLlmProvider as registerLlmProviderImpl, getLlmProvider as getLlmProviderImpl } from "./llmProviderRegistry";
 import type { LlmProviderFactory as LlmProviderFactoryType, LlmSettings as LlmSettingsType } from "./llmProviderRegistry";
 /**
- * On `start()`, registers this plugin's `TemplateProvider` with the core `signalk-einklabel-plugin`
+ * When constructed, registers this plugin's `TemplateProvider` with the core `signalk-einklabel-plugin`
  * (`esl.registerTemplateProvider`, see `./templateProvider.ts` and `./plugin.ts`) - so its prompts show
  * up in the core plugin's own "Template" picker, suffixed "(GenAI)".
  */
@@ -12,8 +12,8 @@ declare namespace plugin {
      * Public extension point for a package adding support for an LLM provider this plugin doesn't
      * already bundle - see `registerLlmProvider`'s own doc comment (`./llmProviderRegistry.ts`) for the
      * full contract, and the core plugin's own `registerVendorDriver` doc comment for the dependency
-     * convention to follow (a regular npm `dependency` plus `"signalk": { "requires": [...] }`, **not** a
-     * `peerDependency`).
+     * convention to follow (`"signalk": { "requires": [...] }` plus a `devDependency` for types/tests,
+     * **not** a regular `dependency` or `peerDependency`).
      */
     const registerLlmProvider: typeof registerLlmProviderImpl;
     const getLlmProvider: typeof getLlmProviderImpl;

package/dist/index.js

@@ -2,7 +2,7 @@
 const plugin_1 = require("./plugin");
 const llmProviderRegistry_1 = require("./llmProviderRegistry");
 /**
- * On `start()`, registers this plugin's `TemplateProvider` with the core `signalk-einklabel-plugin`
+ * When constructed, registers this plugin's `TemplateProvider` with the core `signalk-einklabel-plugin`
  * (`esl.registerTemplateProvider`, see `./templateProvider.ts` and `./plugin.ts`) - so its prompts show
  * up in the core plugin's own "Template" picker, suffixed "(GenAI)".
  */
@@ -14,8 +14,8 @@ function plugin(app) {
      * Public extension point for a package adding support for an LLM provider this plugin doesn't
      * already bundle - see `registerLlmProvider`'s own doc comment (`./llmProviderRegistry.ts`) for the
      * full contract, and the core plugin's own `registerVendorDriver` doc comment for the dependency
-     * convention to follow (a regular npm `dependency` plus `"signalk": { "requires": [...] }`, **not** a
-     * `peerDependency`).
+     * convention to follow (`"signalk": { "requires": [...] }` plus a `devDependency` for types/tests,
+     * **not** a regular `dependency` or `peerDependency`).
      */
     plugin.registerLlmProvider = llmProviderRegistry_1.registerLlmProvider;
     plugin.getLlmProvider = llmProviderRegistry_1.getLlmProvider;

package/dist/llmGateway.d.ts

@@ -29,16 +29,39 @@ export declare function isPackageInstalled(moduleName: string): boolean;
  * check for those.
  */
 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;
+}
 /**
- * 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.
+ * `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 declare function callLlm(settings: LlmSettings, prompt: string): Promise<string>;
+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

@@ -3,6 +3,7 @@ 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");
@@ -147,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);
@@ -168,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

@@ -18,9 +18,10 @@ export type LlmProviderFactory = (settings: LlmSettings) => LlmModel;
  * forking this plugin - `resolveModel` in `./llmGateway.ts` checks this registry first, by `llmProvider`
  * name, before falling through to the built-in switch. Call this from your own SignalK plugin's
  * `start()` (or `esl-cli --require <module>`, loaded before parsing per the core plugin's own CLI
- * extension timing - see its README). Declare this package as a regular npm `dependency` (not a
- * `peerDependency` - see the core plugin's own `registerVendorDriver` doc comment for why) so npm
- * resolves a real copy to register into.
+ * extension timing - see its README). Declare this package via `"signalk": { "requires": [...] }` plus
+ * a `devDependency` for types/tests - not a regular `dependency` or `peerDependency`, so `require`
+ * resolves the one copy the App Store installed (see the core plugin's own `registerVendorDriver`
+ * doc comment for why).
  */
 export declare function registerLlmProvider(name: string, factory: LlmProviderFactory): void;
 export declare function getLlmProvider(name: string): LlmProviderFactory | undefined;

package/dist/llmProviderRegistry.js

@@ -14,9 +14,10 @@ const providers = new Map();
  * forking this plugin - `resolveModel` in `./llmGateway.ts` checks this registry first, by `llmProvider`
  * name, before falling through to the built-in switch. Call this from your own SignalK plugin's
  * `start()` (or `esl-cli --require <module>`, loaded before parsing per the core plugin's own CLI
- * extension timing - see its README). Declare this package as a regular npm `dependency` (not a
- * `peerDependency` - see the core plugin's own `registerVendorDriver` doc comment for why) so npm
- * resolves a real copy to register into.
+ * extension timing - see its README). Declare this package via `"signalk": { "requires": [...] }` plus
+ * a `devDependency` for types/tests - not a regular `dependency` or `peerDependency`, so `require`
+ * resolves the one copy the App Store installed (see the core plugin's own `registerVendorDriver`
+ * doc comment for why).
  */
 function registerLlmProvider(name, factory) {
     providers.set(name, factory);

package/dist/plugin.js

@@ -21,8 +21,11 @@ const TEST_PROMPT = 'Reply with exactly the word "OK", nothing else.';
 async function runConnectionTest(app, config) {
     const label = `${config.llmProvider ?? "openrouter"}/${config.llmModel ?? "(no model configured)"}`;
     try {
-        const reply = await (0, retry_1.withRetries)(config.llmRetries, () => (0, llmGateway_1.callLlm)(config, TEST_PROMPT));
-        app.setPluginStatus(`LLM test OK (${label}): ${reply.trim().slice(0, 200)}`);
+        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}`);
@@ -38,12 +41,14 @@ 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));
+    // know or care that anything changed on this side. `undefined` while the plugin isn't running: the
+    // provider stays registered (the core plugin has no way to unregister one, and the server constructs
+    // every installed plugin, enabled or not), so `render()` uses this to refuse LLM calls while disabled.
+    let 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",
@@ -115,6 +120,8 @@ function createPlugin(app) {
                 runConnectionTest(app, currentConfig).catch((err) => app.debug(`connection test failed unexpectedly: ${err.message}`));
             }
         },
-        stop() { },
+        stop() {
+            currentConfig = undefined;
+        },
     };
 }

package/dist/templateProvider.d.ts

@@ -1,11 +1,22 @@
+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. */
 export declare const SUFFIX = "(GenAI)";
 /**
  * The `esl.TemplateProvider` this plugin registers with the core plugin (`esl.registerTemplateProvider`,
- * called from `./plugin.ts`'s `start()`). `listTemplates`/`describeBindings`/`render` all resolve the
+ * called when `./plugin.ts`'s `createPlugin` constructs the plugin, whether or not it is enabled). `listTemplates`/`describeBindings`/`render` all resolve the
  * 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;
+/**
+ * `esl.TemplateProvider` with its optional `describeContent` made required, so callers (and tests) can
+ * use it without a guard. Core logs it to debug output before each `render()`, so you can see what the
+ * LLM is sent; a future core feature (e.g. emailing a label) could reuse it too. Older core versions
+ * without `describeContent` simply never call it.
+ */
+export type GenAiTemplateProvider = esl.TemplateProvider & {
+    describeContent(request: esl.TemplateRenderRequest): string;
+};
+/** `getConfig` returns `undefined` while the plugin isn't running: templates are still listed, but `render()` rejects without calling the LLM. */
+export declare function createTemplateProvider(app: ServerAPI, getConfig: () => PluginConfig | undefined): GenAiTemplateProvider;

package/dist/templateProvider.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUFFIX = void 0;
 exports.createTemplateProvider = createTemplateProvider;
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const signalk_einklabel_plugin_1 = __importDefault(require("@rhizomatics/signalk-einklabel-plugin"));
@@ -18,15 +19,10 @@ const GUIDANCE_NAME = (0, path_1.join)(".assets", "target_guidance.md");
 function promptNameFor(templateName) {
     return `${templateName.slice(0, templateName.length - ` ${exports.SUFFIX}`.length)}.md`;
 }
-/**
- * The `esl.TemplateProvider` this plugin registers with the core plugin (`esl.registerTemplateProvider`,
- * called from `./plugin.ts`'s `start()`). `listTemplates`/`describeBindings`/`render` all resolve the
- * 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) {
+/** `getConfig` returns `undefined` while the plugin isn't running: templates are still listed, but `render()` rejects without calling the LLM. */
+function createTemplateProvider(app, getConfig) {
     function promptsDir() {
-        return (0, config_1.resolvePromptsDir)(getConfig().promptsDir);
+        return (0, config_1.resolvePromptsDir)((getConfig() ?? (0, config_1.defaultConfig)()).promptsDir);
     }
     function promptPathFor(templateName) {
         const dir = promptsDir();
@@ -35,6 +31,13 @@ function createTemplateProvider(getConfig) {
             guidancePath: (0, config_1.resolvePromptPath)(dir, GUIDANCE_NAME),
         };
     }
+    /** Shared by `render` (sent to the LLM) and `describeContent` (for debugging what the LLM is sent) - the prompt+guidance text with every `{...}` placeholder substituted against `context`. */
+    function buildPrompt(templateName, context) {
+        const { promptPath, guidancePath } = promptPathFor(templateName);
+        const promptText = (0, fs_1.readFileSync)(promptPath, "utf-8");
+        const guidanceText = (0, fs_1.readFileSync)(guidancePath, "utf-8");
+        return `${signalk_einklabel_plugin_1.default.substituteBindingsInText(promptText, context).trim()}\n\n${signalk_einklabel_plugin_1.default.substituteBindingsInText(guidanceText, context).trim()}\n`;
+    }
     return {
         suffix: exports.SUFFIX,
         listTemplates() {
@@ -46,14 +49,15 @@ function createTemplateProvider(getConfig) {
             const guidanceText = (0, fs_1.readFileSync)(guidancePath, "utf-8");
             return signalk_einklabel_plugin_1.default.findBindingsInText(promptText, guidanceText);
         },
+        describeContent(request) {
+            return buildPrompt(request.templateName, request.context);
+        },
         async render(request) {
-            const { promptPath, guidancePath } = promptPathFor(request.templateName);
-            const promptText = (0, fs_1.readFileSync)(promptPath, "utf-8");
-            const guidanceText = (0, fs_1.readFileSync)(guidancePath, "utf-8");
-            const prompt = `${signalk_einklabel_plugin_1.default.substituteBindingsInText(promptText, request.context).trim()}\n\n${signalk_einklabel_plugin_1.default
-                .substituteBindingsInText(guidanceText, request.context)
-                .trim()}\n`;
             const config = getConfig();
+            if (!config) {
+                throw new Error('signalk-einklabel-genai-plugin is not running - enable it to render "(GenAI)" templates');
+            }
+            const prompt = buildPrompt(request.templateName, request.context);
             const llmSettings = {
                 llmProvider: config.llmProvider,
                 llmApiKey: config.llmApiKey,
@@ -61,17 +65,32 @@ 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
             // reused unchanged, rather than needing its own copy of that logic.
             const cacheDir = (0, path_1.join)(promptsDir(), ".genai-cache");
             (0, fs_1.mkdirSync)(cacheDir, { recursive: true });
-            const cachePath = (0, path_1.join)(cacheDir, `${Buffer.from(request.templateName).toString("hex")}.svg`);
+            // One file per render: core repaints a device's targets in parallel, so a name shared by every
+            // render of the same template could be overwritten by another target's SVG before it is read.
+            const cachePath = (0, path_1.join)(cacheDir, `${Buffer.from(request.templateName).toString("hex")}-${(0, crypto_1.randomUUID)()}.svg`);
             (0, fs_1.writeFileSync)(cachePath, svg);
-            return renderer.render(cachePath, request.context, request.width, request.height);
+            try {
+                return await renderer.render(cachePath, request.context, request.width, request.height);
+            }
+            finally {
+                (0, fs_1.rmSync)(cachePath, { force: true });
+            }
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-genai-plugin",
-  "version": "0.1.2",
+  "version": "0.3.2",
   "description": "GenAI prompt generated labels for the eInk Electronic Shelf Label plugin. Contributes prompts as an alternative to hand-authored SVG templates.",
   "keywords": [
     "eink",
@@ -52,14 +52,14 @@
   },
   "dependencies": {
     "@openrouter/ai-sdk-provider": "^3.0.0",
-    "@rhizomatics/signalk-einklabel-plugin": "^1.0.0",
     "ai": "^7.0.37"
   },
   "devDependencies": {
+    "@rhizomatics/signalk-einklabel-plugin": "^1.0.0",
     "@signalk/server-api": "^2.28.0",
-    "@types/node": "^20.14.0",
-    "commander": "^12.1.0",
-    "oxfmt": "^0.59.0",
+    "@types/node": "^26.6.2",
+    "commander": "^15.0.0",
+    "oxfmt": "^0.74.0",
     "oxlint": "^1.74.0",
     "oxlint-tsgolint": "^7.0.0",
     "ts-node": "^10.9.2",
@@ -72,14 +72,15 @@
     "@ai-sdk/moonshotai": "^3.0.17",
     "@ai-sdk/openai": "^4.0.20",
     "@ai-sdk/openai-compatible": "^3.0.14",
-    "@ai-sdk/xai": "^4.0.18",
+    "@ai-sdk/xai": "^5.0.4",
     "ai-sdk-ollama": "^4.1.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22",
+    "signalk-server": ">=2.25.0"
   },
   "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}