@rhizomatics/signalk-einklabel-genai-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,85 @@
+# eInk Label GenAI Rendering
+
+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.
+
+This is deliberately a separate plugin, not a feature of the core one: the core plugin has nothing to do with any LLM SDK or API key, so installing it never pulls in GenAI dependencies unless you also explicitly install and enable this one - useful for anyone on a small/constrained install, or who'd simply rather not have any GenAI code in their install at all.
+
+## How it fits together
+
+This plugin registers a `TemplateProvider` with the core plugin (the same extension mechanism a new vendor's hardware driver uses - see the core plugin's README, "Extending"). Once both plugins are installed and enabled:
+
+- Its prompts show up as ordinary entries in the core plugin's own "Template" picker, suffixed `(GenAI)` - pick one exactly like you'd pick a `.svg` file. No separate "render mode" setting.
+- All LLM provider/model/API-key configuration lives in **this** plugin's own config screen - the core plugin knows nothing about any of that.
+- If the LLM call fails (network/API error, exhausted retries) or its response isn't a renderable SVG, the **core** plugin pushes its own generic fallback-warning template instead of leaving the previous, possibly now-wrong, content on screen - the same safety net a broken hand-authored template gets. The next scheduled repaint retries automatically.
+
+Since each repaint may call a (usually paid) LLM API, a GenAI-backed device should use Repaint Trigger `interval`, not `subscription`.
+
+## 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:
+
+```bash
+npm install ai @ai-sdk/openai          # llmProvider: "openai"
+npm install ai @ai-sdk/anthropic       # llmProvider: "anthropic"
+npm install ai @ai-sdk/google          # llmProvider: "google"
+npm install ai @ai-sdk/xai             # llmProvider: "xai"
+npm install ai @ai-sdk/deepseek        # llmProvider: "deepseek"
+npm install ai @ai-sdk/moonshotai      # llmProvider: "moonshotai"
+npm install ai ai-sdk-ollama           # llmProvider: "ollama"
+npm install ai @ai-sdk/openai-compatible  # llmProvider: "local" (LM Studio, vLLM, ...)
+```
+
+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`.
+
+## Configuration
+
+- `llmProvider` - `openai`, `anthropic`, `google`, `xai`, `deepseek`, `moonshotai`, `ollama`, or `local` (any other OpenAI-compatible server)
+- `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)
+
+### Adding another LLM provider
+
+The provider list above is `resolveModel`'s (`src/llmGateway.ts`) built-in switch, but you're not limited to it: call `registerLlmProvider(name, factory)` (exported from this plugin, mirroring the core plugin's own extension points) from your own SignalK plugin's `start()` to add support for a provider this plugin doesn't bundle, without forking it. A registered name takes priority over the built-in switch, so it can even replace one of the names above.
+
+```ts
+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`.
+
+## Writing Prompts
+
+A prompt (`.md` file) is just prose, with the same `{...}` binding syntax as a template's `<desc>` in the core plugin (see its README, "Template Source Specification") - a bare path like `{design.length.overall}`, or the full `source=...,path=...,format=...` grammar, resolve exactly the way they would in a template. One more source is available here, `source=label`, giving facts about the physical label the LLM needs to design for:
+
+- `path=width`/`path=height` - exact pixel size the returned SVG must match
+- `path=colours` - the label's colour palette (add `format=csv` for a plain comma-separated list)
+- `path=fonts` - the three font-family keywords the renderer can actually display (also supports `format=csv`)
+- `path=description` - the device's own configured Location/description field
+- `path=manufacturer`/`path=label` - the panel's real-world brand and its own size label (e.g. `3.7"`)
+- `path=position` - the vessel's current GPS position, pre-formatted as decimal degrees with hemisphere letters
+
+A placeholder that doesn't resolve to any value becomes `???` in the prompt text - a visible gap the LLM can reason around, rather than a silent, misleading blank. Add `default=<value>` to any binding to use that value instead when the data is missing.
+
+Every prompt also has a bundled `.assets/target_guidance.md` fragment appended automatically, telling the model the exact size/colour/font constraints and that it must respond with nothing but a single self-contained `<svg>...</svg>` document. Override it the same way you'd override any bundled prompt - put your own `.assets/target_guidance.md` in your `promptsDir`.
+
+## Testing Prompts from the CLI
+
+This plugin contributes `prompt`/`generate` subcommands to the core plugin's `esl-cli`, loaded via `-r`:
+
+```bash
+esl-cli -r node_modules/@rhizomatics/signalk-einklabel-genai-plugin/dist/cliExtension.js prompt forecast -e examples
+esl-cli -r node_modules/@rhizomatics/signalk-einklabel-genai-plugin/dist/cliExtension.js generate forecast -e examples -o forecast.png --llm-provider ollama --llm-model llama3.2
+```
+
+- `prompt [name]` - resolve a prompt's placeholders against a live SignalK server (or example data) and print the exact text an LLM would be sent, with no LLM call
+- `generate [name]` - call the configured LLM and write the rendered SVG's PNG, optionally saving the raw SVG too with `--save-svg`
+
+The optional `[name]` argument names a prompt the same way the config UI's picker does - a full path also works. Use `--help` on either for the full option list.
+
+## Publishing note
+
+This plugin's own `package.json` currently points its `@rhizomatics/signalk-einklabel-plugin` dependency at a local `file:` path for development against an unpublished core plugin - update it to a real semver range once both are published.

package/dist/cliExtension.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cliExtension.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Contributes `prompt`/`generate` subcommands to the core plugin's `esl-cli`, for testing prompts
+ * without a device or a live SignalK server. Load via `esl-cli -r <path-to-this-file's-dist> prompt ...`
+ * - the core CLI pre-scans `-r`/`--require` and loads those modules *before* building its own command
+ * tree (see its own README/source for why), which is what makes adding a brand-new subcommand from here
+ * possible at all, unlike a module that only registers a vendor driver/template provider.
+ *
+ * A plain top-level `require()` (rather than a static `import`) of the core CLI module is deliberate -
+ * it makes the load-time side effect (adding commands to an already-running CLI process) obvious to a
+ * reader, and avoids a static import accidentally triggering a *second*, unrelated full execution of
+ * that module (including its own `parseAsync(process.argv)`) if this file were ever `require()`'d
+ * outside of `esl-cli -r`'s intended flow - within that flow, the core CLI module is already
+ * mid-execution and cached, so this just reads back the shared `program`/helpers it already exported.
+ */
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+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");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const cli = require("@rhizomatics/signalk-einklabel-plugin/dist/cli/index.js");
+const DEFAULT_GUIDANCE_PATH = (0, path_1.join)(config_1.BUNDLED_PROMPTS_DIR, ".assets", "target_guidance.md");
+/** Shared -p/-g/-w/--height/--colours/-d/--manufacturer/--label/-u/-e options for `prompt` and `generate`. */
+function addPromptOptions(command) {
+    return command
+        .option("-p, --prompt <path>", "path to a .md prompt file", (0, path_1.join)(config_1.BUNDLED_PROMPTS_DIR, config_1.DEFAULT_PROMPT_NAME))
+        .option("-g, --guidance <path>", "path to the target-guidance fragment appended after the prompt", DEFAULT_GUIDANCE_PATH)
+        .option("-u, --url <url>", "SignalK server base URL - if omitted, tries each of " + cli.DEFAULT_SIGNALK_URLS.join(", ") + " in turn")
+        .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> instead of a live SignalK server")
+        .option("-w, --width <px>", "value for {source=label,path=width}", "416")
+        .option("--height <px>", "value for {source=label,path=height}", "240")
+        .option("--colours <code>", "value for {source=label,path=colours}: BW, BWR, or BWRY", "BWRY")
+        .option("-d, --description <text>", "value for {source=label,path=description} (a label's configured location/notes)")
+        .option("--manufacturer <name>", "value for {source=label,path=manufacturer}", "preview")
+        .option("--label <name>", "value for {source=label,path=label} (the panel's own size label, e.g. '3.7\"')", "preview");
+}
+/**
+ * Resolves the optional positional `[name]` argument (e.g. `esl-cli prompt forecast`) to a prompt file
+ * path, overriding `-p/--prompt` when given - a bare name (no extension) is resolved as a prompt name
+ * via `resolvePromptPath`/`resolvePromptsDir` (the same lookup a real device's prompt gets).
+ */
+function resolvePromptArg(name, promptOption) {
+    if (!name)
+        return promptOption;
+    if ((0, fs_1.existsSync)(name))
+        return name;
+    const fileName = /\.[a-z0-9]+$/i.test(name) ? name : `${name}.md`;
+    return (0, config_1.resolvePromptPath)((0, config_1.resolvePromptsDir)(""), fileName);
+}
+/**
+ * Resolves a prompt+guidance fragment's placeholders against a live SignalK server (or example data),
+ * building the same `context.label` (`esl.buildLabel`) a real repaint would - shared by `prompt` and
+ * `generate`. `navigation.position` is always fetched (even if no other binding references it) so
+ * `{source=label,path=position}` works without the caller needing to name it explicitly.
+ */
+async function resolvePrompt(opts) {
+    const promptText = await (0, promises_1.readFile)(opts.prompt, "utf-8");
+    const guidanceText = await (0, promises_1.readFile)(opts.guidance, "utf-8");
+    const positionBinding = { source: "signalk", context: "self", path: "navigation.position" };
+    const bindings = [...signalk_einklabel_plugin_1.default.findBindingsInText(promptText, guidanceText), positionBinding];
+    const context = await cli.assembleContext(opts, bindings);
+    const rawPosition = context.signalk?.self?.navigation?.position;
+    const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
+        ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
+        : undefined;
+    const label = signalk_einklabel_plugin_1.default.buildLabel({
+        manufacturer: opts.manufacturer,
+        label: opts.label,
+        width: Number(opts.width),
+        height: Number(opts.height),
+        colours: cli.parseColours(opts.colours),
+        description: opts.description,
+        position,
+    });
+    const promptContext = { ...context, label };
+    return `${signalk_einklabel_plugin_1.default.substituteBindingsInText(promptText, promptContext).trim()}\n\n${signalk_einklabel_plugin_1.default.substituteBindingsInText(guidanceText, promptContext).trim()}\n`;
+}
+addPromptOptions(cli.program
+    .command("prompt")
+    .argument("[name]", 'prompt name (e.g. "forecast") or path - overrides -p/--prompt if given')
+    .description("Resolve a prompt file's placeholders against a live SignalK server (or example data) and print the exact text an LLM would be sent - no LLM call")).action(async (name, opts) => {
+    console.log(await resolvePrompt({ ...opts, prompt: resolvePromptArg(name, opts.prompt) }));
+});
+addPromptOptions(cli.program
+    .command("generate")
+    .argument("[name]", 'prompt name (e.g. "forecast") or path - overrides -p/--prompt if given')
+    .description("Call an LLM with a resolved prompt and write the rendered SVG's PNG, without needing a device"))
+    .requiredOption("-o, --output <path>", "output PNG path")
+    .option("--save-svg <path>", "also write the LLM's raw SVG response to this path (feed it straight into the core plugin's `paint -t`/`render -t` afterwards)")
+    .option("--llm-provider <name>", "openai, anthropic, google, xai, deepseek, moonshotai, ollama, or local", "openai")
+    .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-retries <n>", "LLM call attempts before giving up", "2")
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    .action(async (name, opts) => {
+    const prompt = await resolvePrompt({ ...opts, prompt: resolvePromptArg(name, opts.prompt) });
+    const llmSettings = {
+        llmProvider: opts.llmProvider,
+        llmApiKey: opts.llmApiKey,
+        llmModel: opts.llmModel,
+        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 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);
+    const height = Number(opts.height);
+    const renderer = new signalk_einklabel_plugin_1.default.Renderer();
+    const bitmap = await renderer.render(svgPath, { meta: { repainted: new Date().toISOString(), description: opts.description ?? "" } }, width, height);
+    await (0, promises_1.writeFile)(opts.output, signalk_einklabel_plugin_1.default.bitmapToPng(bitmap));
+    console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})${opts.saveSvg ? `, svg saved to ${opts.saveSvg}` : ""}`);
+});

package/dist/config.d.ts

@@ -0,0 +1,50 @@
+export interface PluginConfig {
+    /**
+     * Which LLM gateway a prompt is sent to - see `./llmGateway.ts`. `"ollama"`/`"local"` both go through
+     * the generic OpenAI-compatible provider; any other value not in this list is looked up in the
+     * `registerLlmProvider` registry (`./llmProviderRegistry.ts`) before giving up - so someone keen can
+     * add support for another provider entirely without forking this plugin. Defaults to `"openai"`.
+     */
+    llmProvider?: "openai" | "anthropic" | "google" | "xai" | "deepseek" | "moonshotai" | "ollama" | "local";
+    /** Ignored for `llmProvider: "ollama"`/`"local"` unless the server itself requires one. */
+    llmApiKey?: string;
+    /** Provider-specific model id, e.g. `"gpt-4o"`, `"claude-sonnet-4-5"`, `"gemini-2.5-flash"`, or an Ollama/local model tag. */
+    llmModel?: string;
+    /**
+     * An OpenAI-compatible endpoint. Optional for `llmProvider: "ollama"` - defaults to Ollama's own
+     * standard local address, `http://localhost:11434/v1`; only needed there to point at a differently
+     * configured/remote Ollama instance. Required for `llmProvider: "local"` (any other OpenAI-compatible
+     * server, e.g. LM Studio/vLLM), which has no such universal default.
+     */
+    llmBaseUrl?: string;
+    /** How long to wait for the LLM's response before giving up on an attempt. */
+    llmTimeoutSeconds: number;
+    /** How many times to attempt the LLM call (including the first try) before giving up (the core plugin then shows its own generic fallback warning). */
+    llmRetries: number;
+    /**
+     * Directory this plugin scans for `.md` prompt files - same convention as the core plugin's own
+     * `templatesDir`: empty for the default, a relative path resolved against `~/.signalk`, or an
+     * absolute path. Use `resolvePromptsDir` to turn this into an actual path.
+     */
+    promptsDir: string;
+}
+/**
+ * This package's own bundled `prompts/` directory (ships alongside `dist/`, see package.json's
+ * `files`) - `forecast.md` (the built-in default) and the always-appended
+ * `.assets/target_guidance.md` fragment live here. A same-named file in the user's `promptsDir` takes
+ * priority, letting users add or override their own prompts.
+ */
+export declare const BUNDLED_PROMPTS_DIR: string;
+/** Bundled prompt used when `promptName` is left unset. */
+export declare const DEFAULT_PROMPT_NAME = "forecast.md";
+export declare function defaultConfig(): PluginConfig;
+/** Mirrors the core plugin's `resolveTemplatesDir` - see its own doc comment. */
+export declare function resolvePromptsDir(promptsDir: string | undefined): string;
+/** Local prompts take priority over a same-named bundled one; both show up as options. */
+export declare function promptNameOptions(promptsDir: string): string[];
+/**
+ * Resolves a prompt name (or the `.assets/target_guidance.md` fragment, passed as
+ * `".assets/target_guidance.md"`) to an actual file - a local file under `promptsDir` overrides the
+ * bundled one of the same name.
+ */
+export declare function resolvePromptPath(promptsDir: string, name: string): string;

package/dist/config.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROMPT_NAME = exports.BUNDLED_PROMPTS_DIR = void 0;
+exports.defaultConfig = defaultConfig;
+exports.resolvePromptsDir = resolvePromptsDir;
+exports.promptNameOptions = promptNameOptions;
+exports.resolvePromptPath = resolvePromptPath;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/**
+ * This package's own bundled `prompts/` directory (ships alongside `dist/`, see package.json's
+ * `files`) - `forecast.md` (the built-in default) and the always-appended
+ * `.assets/target_guidance.md` fragment live here. A same-named file in the user's `promptsDir` takes
+ * priority, letting users add or override their own prompts.
+ */
+exports.BUNDLED_PROMPTS_DIR = (0, path_1.join)(__dirname, "..", "prompts");
+/** Bundled prompt used when `promptName` is left unset. */
+exports.DEFAULT_PROMPT_NAME = "forecast.md";
+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,
+        llmRetries: 2,
+        promptsDir: "",
+    };
+}
+/** Mirrors the core plugin's `resolveTemplatesDir` - see its own doc comment. */
+function resolvePromptsDir(promptsDir) {
+    const trimmed = promptsDir?.trim();
+    if (!trimmed)
+        return DEFAULT_PROMPTS_DIR;
+    return (0, path_1.isAbsolute)(trimmed) ? trimmed : (0, path_1.join)(SIGNALK_HOME_DIR, trimmed);
+}
+function listMarkdownFiles(dir) {
+    try {
+        return (0, fs_1.readdirSync)(dir).filter((name) => name.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+}
+/** Local prompts take priority over a same-named bundled one; both show up as options. */
+function promptNameOptions(promptsDir) {
+    const local = listMarkdownFiles(promptsDir);
+    const bundled = listMarkdownFiles(exports.BUNDLED_PROMPTS_DIR).filter((name) => !local.includes(name));
+    return [...local, ...bundled];
+}
+/**
+ * Resolves a prompt name (or the `.assets/target_guidance.md` fragment, passed as
+ * `".assets/target_guidance.md"`) to an actual file - a local file under `promptsDir` overrides the
+ * bundled one of the same name.
+ */
+function resolvePromptPath(promptsDir, name) {
+    const localPath = (0, path_1.join)(promptsDir, name);
+    return (0, fs_1.existsSync)(localPath) ? localPath : (0, path_1.join)(exports.BUNDLED_PROMPTS_DIR, name);
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+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`
+ * (`esl.registerTemplateProvider`, see `./templateProvider.ts` and `./plugin.ts`) - so its prompts show
+ * up in the core plugin's own "Template" picker, suffixed "(GenAI)".
+ */
+declare function plugin(app: ServerAPI): Plugin;
+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`).
+     */
+    const registerLlmProvider: typeof registerLlmProviderImpl;
+    const getLlmProvider: typeof getLlmProviderImpl;
+    type LlmProviderFactory = LlmProviderFactoryType;
+    type LlmSettings = LlmSettingsType;
+}
+export = plugin;

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+const plugin_1 = require("./plugin");
+const llmProviderRegistry_1 = require("./llmProviderRegistry");
+/**
+ * On `start()`, 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)".
+ */
+function plugin(app) {
+    return (0, plugin_1.createPlugin)(app);
+}
+(function (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`).
+     */
+    plugin.registerLlmProvider = llmProviderRegistry_1.registerLlmProvider;
+    plugin.getLlmProvider = llmProviderRegistry_1.getLlmProvider;
+})(plugin || (plugin = {}));
+module.exports = plugin;

package/dist/llmGateway.d.ts

@@ -0,0 +1,30 @@
+import { PluginConfig } from "./config";
+import { LlmSettings as RegistryLlmSettings } from "./llmProviderRegistry";
+export type LlmSettings = RegistryLlmSettings & {
+    llmTimeoutSeconds?: number;
+};
+/**
+ * `ai` and every `@ai-sdk/*`/`ai-sdk-ollama` provider package are `optionalDependencies` (see
+ * package.json), not plain `dependencies` - a 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 packages has to be a `require()` reached
+ * only when `callLlm` actually needs it - a top-level `import` would be resolved eagerly the moment this
+ * module loads, throwing before any config is even read. Types are still fully checked via
+ * `typeof import(...)` at each call site, which - unlike a value `import` - is erased entirely at
+ * compile time and leaves no runtime trace for `tsc` to eagerly require.
+ */
+export declare function loadOptional<M>(moduleName: string): M;
+/**
+ * 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.
+ */
+export declare function callLlm(settings: LlmSettings, prompt: string): Promise<string>;
+/**
+ * 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.
+ */
+export declare function extractSvg(raw: string): string;
+export type { PluginConfig };

package/dist/llmGateway.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOptional = loadOptional;
+exports.callLlm = callLlm;
+exports.extractSvg = extractSvg;
+const llmProviderRegistry_1 = require("./llmProviderRegistry");
+/**
+ * `ai` and every `@ai-sdk/*`/`ai-sdk-ollama` provider package are `optionalDependencies` (see
+ * package.json), not plain `dependencies` - a 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 packages has to be a `require()` reached
+ * only when `callLlm` actually needs it - a top-level `import` would be resolved eagerly the moment this
+ * module loads, throwing before any config is even read. Types are still fully checked via
+ * `typeof import(...)` at each call site, which - unlike a value `import` - is erased entirely at
+ * compile time and leaves no runtime trace for `tsc` to eagerly require.
+ */
+function loadOptional(moduleName) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require(moduleName);
+    }
+    catch (err) {
+        throw new Error(`LLM provider support needs the optional dependency "${moduleName}", which isn't installed - run "npm install ${moduleName}" (${err.message})`);
+    }
+}
+/** Ollama's own default local listen address - see the `"ollama"` case in `resolveModel` below. */
+const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
+/**
+ * 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
+ * built-in switch - so a custom-registered provider can even *replace* one of the names below if it
+ * wants to. `"ollama"` uses the dedicated `ai-sdk-ollama` package (defaults its own base URL to Ollama's
+ * standard local address, so no config is needed beyond a model tag); `"local"` uses the generic
+ * `@ai-sdk/openai-compatible` provider for anything else OpenAI-compatible (LM Studio, vLLM, ...), which
+ * has no such universal default, so `llmBaseUrl` is required there.
+ *
+ * Returns `any` deliberately - this bridges several different concrete SDK provider packages' own
+ * model-handle types (each an implementation of `ai`'s `LanguageModel`, but not literally the same
+ * type reference) plus the registry's own `unknown`-typed `LlmModel`; `generateText` below still
+ * validates the value at the one place it's actually used.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function resolveModel(settings) {
+    const model = settings.llmModel;
+    if (!model) {
+        throw new Error("no LLM model configured (llmModel)");
+    }
+    const provider = settings.llmProvider ?? "openai";
+    const registered = (0, llmProviderRegistry_1.getLlmProvider)(provider);
+    if (registered)
+        return registered(settings);
+    switch (provider) {
+        case "anthropic": {
+            const { createAnthropic } = loadOptional("@ai-sdk/anthropic");
+            return createAnthropic({ apiKey: settings.llmApiKey })(model);
+        }
+        case "google": {
+            const { createGoogleGenerativeAI } = loadOptional("@ai-sdk/google");
+            return createGoogleGenerativeAI({ apiKey: settings.llmApiKey })(model);
+        }
+        case "xai": {
+            const { createXai } = loadOptional("@ai-sdk/xai");
+            return createXai({ apiKey: settings.llmApiKey })(model);
+        }
+        case "deepseek": {
+            const { createDeepSeek } = loadOptional("@ai-sdk/deepseek");
+            return createDeepSeek({ apiKey: settings.llmApiKey })(model);
+        }
+        case "moonshotai": {
+            const { createMoonshotAI } = loadOptional("@ai-sdk/moonshotai");
+            return createMoonshotAI({ apiKey: settings.llmApiKey })(model);
+        }
+        case "ollama": {
+            const { createOllama } = loadOptional("ai-sdk-ollama");
+            return createOllama({ baseURL: settings.llmBaseUrl || DEFAULT_OLLAMA_BASE_URL, apiKey: settings.llmApiKey })(model);
+        }
+        case "local": {
+            if (!settings.llmBaseUrl) {
+                throw new Error('llmBaseUrl is required when llmProvider is "local"');
+            }
+            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
+            return createOpenAICompatible({ name: "local", baseURL: settings.llmBaseUrl, apiKey: settings.llmApiKey })(model);
+        }
+        case "openai":
+        default: {
+            const { createOpenAI } = loadOptional("@ai-sdk/openai");
+            return createOpenAI({ apiKey: settings.llmApiKey })(model);
+        }
+    }
+}
+/**
+ * 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.
+ */
+async function callLlm(settings, prompt) {
+    const model = resolveModel(settings);
+    const { generateText } = loadOptional("ai");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 30) * 1000);
+    try {
+        const { text } = await generateText({ model, prompt, abortSignal: controller.signal });
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 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.
+ */
+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');
+    }
+    return raw.slice(start, end + "</svg>".length);
+}

package/dist/llmProviderRegistry.d.ts

@@ -0,0 +1,25 @@
+import { PluginConfig } from "./config";
+/**
+ * Settings a registered LLM provider factory needs - a subset of `PluginConfig`, shared with the
+ * built-in providers in `./llmGateway.ts`.
+ */
+export type LlmSettings = Pick<PluginConfig, "llmProvider" | "llmApiKey" | "llmModel" | "llmBaseUrl">;
+/** Vercel AI SDK's own `LanguageModel` type, loosened to `unknown` here to avoid a hard dependency on `ai`'s types in this always-loaded module - see `./llmGateway.ts`'s `loadOptional`. */
+export type LlmModel = unknown;
+/** Builds a Vercel AI SDK model handle for one custom provider name - see `registerLlmProvider`. */
+export type LlmProviderFactory = (settings: LlmSettings) => LlmModel;
+/**
+ * Public extension point mirroring the core `signalk-einklabel-plugin`'s own `registerVendorDriver`/
+ * `registerTemplateProvider` pattern, one level down: this plugin already bundles support for several
+ * providers (`./llmGateway.ts`'s built-in switch: openai/anthropic/google/xai/deepseek/moonshotai/
+ * ollama/local) as `optionalDependencies`, but someone wanting a provider not in that list (a bespoke
+ * wrapper, a provider with no official `@ai-sdk/*` package yet) can register one of their own without
+ * 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.
+ */
+export declare function registerLlmProvider(name: string, factory: LlmProviderFactory): void;
+export declare function getLlmProvider(name: string): LlmProviderFactory | undefined;

package/dist/llmProviderRegistry.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLlmProvider = registerLlmProvider;
+exports.getLlmProvider = getLlmProvider;
+const providers = new Map();
+/**
+ * Public extension point mirroring the core `signalk-einklabel-plugin`'s own `registerVendorDriver`/
+ * `registerTemplateProvider` pattern, one level down: this plugin already bundles support for several
+ * providers (`./llmGateway.ts`'s built-in switch: openai/anthropic/google/xai/deepseek/moonshotai/
+ * ollama/local) as `optionalDependencies`, but someone wanting a provider not in that list (a bespoke
+ * wrapper, a provider with no official `@ai-sdk/*` package yet) can register one of their own without
+ * 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.
+ */
+function registerLlmProvider(name, factory) {
+    providers.set(name, factory);
+}
+function getLlmProvider(name) {
+    return providers.get(name);
+}

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+import { Plugin, ServerAPI } from "@signalk/server-api";
+export declare function createPlugin(app: ServerAPI): Plugin;

package/dist/plugin.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 templateProvider_1 = require("./templateProvider");
+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));
+    return {
+        id: "signalk-einklabel-genai-plugin",
+        name: "eInk Label GenAI Rendering",
+        description: "Contributes LLM-generated prompts as an alternative to hand-authored SVG templates for signalk-einklabel-plugin",
+        schema: () => ({
+            type: "object",
+            properties: {
+                llmProvider: {
+                    type: "string",
+                    title: "LLM provider",
+                    description: "Which LLM gateway to call - each (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: ["openai", "anthropic", "google", "xai", "deepseek", "moonshotai", "ollama", "local"],
+                    default: "openai",
+                },
+                llmApiKey: {
+                    type: "string",
+                    title: "LLM API key",
+                    description: 'Not required for "ollama"/"local" unless the server itself checks one.',
+                },
+                llmModel: {
+                    type: "string",
+                    title: "LLM model",
+                    description: 'Provider-specific model id/name, e.g. "gpt-4o", "claude-sonnet-4-5", "gemini-2.5-flash", "grok-4", or an Ollama/local model tag.',
+                },
+                llmBaseUrl: {
+                    type: "string",
+                    title: 'LLM base URL (required if LLM provider is "local")',
+                    description: 'An OpenAI-compatible endpoint. Optional for "ollama" (defaults to "http://localhost:11434/v1") - set this only if Ollama runs elsewhere.',
+                },
+                llmTimeoutSeconds: {
+                    type: "number",
+                    title: "LLM call timeout (seconds)",
+                    description: "How long to wait for the LLM's response before giving up on an attempt.",
+                    minimum: 1,
+                    default: (0, config_1.defaultConfig)().llmTimeoutSeconds,
+                },
+                llmRetries: {
+                    type: "number",
+                    title: "LLM call retries",
+                    description: "How many times to attempt the LLM call (including the first try) before giving up - the core plugin then shows " +
+                        "its own generic fallback warning instead of leaving stale content on screen.",
+                    minimum: 1,
+                    default: (0, config_1.defaultConfig)().llmRetries,
+                },
+                promptsDir: {
+                    type: "string",
+                    title: "Prompts directory",
+                    description: "Relative path from ~/.signalk, or an absolute path. Leave empty for the default. Holds .md prompt files - a prompt " +
+                        "here with the same name as a bundled one takes priority. Prompts show up in the core plugin's own Template " +
+                        'picker, suffixed "(GenAI)".',
+                    default: (0, config_1.defaultConfig)().promptsDir,
+                },
+            },
+        }),
+        uiSchema: () => ({ llmApiKey: { "ui:widget": "password" } }),
+        start(config) {
+            currentConfig = { ...(0, config_1.defaultConfig)(), ...config };
+            app.debug(`eInk Label GenAI plugin started (llmProvider=${currentConfig.llmProvider ?? "openai"})`);
+        },
+        stop() { },
+    };
+}

package/dist/retry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
+ * mirrors the core plugin's own `withRetries` (`src/devices/bleDiscovery.ts`), duplicated here rather
+ * than imported since that one isn't part of the core plugin's public `esl` export surface.
+ */
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetries = withRetries;
+/**
+ * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
+ * mirrors the core plugin's own `withRetries` (`src/devices/bleDiscovery.ts`), duplicated here rather
+ * than imported since that one isn't part of the core plugin's public `esl` export surface.
+ */
+async function withRetries(attempts, fn) {
+    let lastErr;
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}

package/dist/templateProvider.d.ts

@@ -0,0 +1,11 @@
+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
+ * 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;

package/dist/templateProvider.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUFFIX = void 0;
+exports.createTemplateProvider = createTemplateProvider;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const signalk_einklabel_plugin_1 = __importDefault(require("@rhizomatics/signalk-einklabel-plugin"));
+const retry_1 = require("./retry");
+const config_1 = require("./config");
+const llmGateway_1 = require("./llmGateway");
+/** Appended to every prompt name this plugin offers in the core plugin's "Template" dropdown. */
+exports.SUFFIX = "(GenAI)";
+const GUIDANCE_NAME = (0, path_1.join)(".assets", "target_guidance.md");
+/** Strips ` (GenAI)` back off a dropdown entry to get the bare prompt file name, e.g. `"forecast (GenAI)"` -> `"forecast.md"`. */
+function promptNameFor(templateName) {
+    return templateName.slice(0, templateName.length - ` ${exports.SUFFIX}`.length);
+}
+/**
+ * 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) {
+    function promptsDir() {
+        return (0, config_1.resolvePromptsDir)(getConfig().promptsDir);
+    }
+    function promptPathFor(templateName) {
+        const dir = promptsDir();
+        return {
+            promptPath: (0, config_1.resolvePromptPath)(dir, promptNameFor(templateName)),
+            guidancePath: (0, config_1.resolvePromptPath)(dir, GUIDANCE_NAME),
+        };
+    }
+    return {
+        suffix: exports.SUFFIX,
+        listTemplates() {
+            return (0, config_1.promptNameOptions)(promptsDir()).map((name) => `${name} ${exports.SUFFIX}`);
+        },
+        describeBindings(templateName) {
+            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.findBindingsInText(promptText, guidanceText);
+        },
+        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();
+            const llmSettings = {
+                llmProvider: config.llmProvider,
+                llmApiKey: config.llmApiKey,
+                llmModel: config.llmModel,
+                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);
+            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`);
+            (0, fs_1.writeFileSync)(cachePath, svg);
+            return renderer.render(cachePath, request.context, request.width, request.height);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@rhizomatics/signalk-einklabel-genai-plugin",
+  "version": "0.1.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",
+    "esl",
+    "genai",
+    "llm",
+    "signalk-category-hardware",
+    "signalk-category-instruments",
+    "signalk-node-server-plugin"
+  ],
+  "homepage": "https://github.com/rhizomatics/signalk-einklabel-genai-plugin",
+  "bugs": {
+    "url": "https://github.com/rhizomatics/signalk-einklabel-genai-plugin/issues"
+  },
+  "license": "APACHE-2.0",
+  "author": "jey burrows",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhizomatics/signalk-einklabel-genai-plugin.git"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "README.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "node scripts/run-tests.js",
+    "coverage": "node scripts/run-tests.js --coverage",
+    "prepublishOnly": "npm run build",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint"
+  },
+  "dependencies": {
+    "@rhizomatics/signalk-einklabel-plugin": "file:../signalk-einklabel-plugin"
+  },
+  "devDependencies": {
+    "@signalk/server-api": "^2.28.0",
+    "@types/node": "^20.14.0",
+    "commander": "^12.1.0",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "oxlint-tsgolint": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.0"
+  },
+  "optionalDependencies": {
+    "@ai-sdk/anthropic": "^4.0.21",
+    "@ai-sdk/deepseek": "^3.0.13",
+    "@ai-sdk/google": "^4.0.24",
+    "@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": "^7.0.37",
+    "ai-sdk-ollama": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "signalk": {
+    "displayName": "eInk Label GenAI Rendering",
+    "requires": [
+      "@rhizomatics/signalk-einklabel-plugin"
+    ]
+  }
+}

package/prompts/.assets/target_guidance.md

@@ -0,0 +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}.
+
+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.
+
+{source=label,path=description}

package/prompts/forecast.md

@@ -0,0 +1 @@
+Summarize the maritime weather outlook for the next 24 hours, appropriate for the sailor of a {design.length.overall}m {design.aisShipType.name} craft positioned at latitude {navigation.position.latitude}, longitude {navigation.position.longitude}