signalk-ai-bridge 0.1.0-beta.1

package/README.md

@@ -0,0 +1,142 @@
+# signalk-ai-bridge
+
+`signalk-ai-bridge` is a Signal K plugin that adds an `Ask AI` panel to the Signal K web UI.
+
+It lets you send selected Signal K vessel data to a local Ollama model such as Gemma, then read the response directly in the browser.
+
+## Experimental Plugin
+
+This is an experimental study plugin.
+
+It is intended for testing, evaluation, and local experimentation with AI-assisted vessel summaries inside Signal K. It should not be treated as a safety-critical navigation system, an authoritative decision-maker, or a production-hardened marine control feature.
+
+## What It Is
+
+This plugin is a bridge between:
+
+- Signal K vessel data
+- a local Ollama AI model
+- a simple web UI inside Signal K
+
+It is meant for local, operator-facing use. You choose which Signal K paths are shared with the AI, write a question in plain language, and the plugin sends that question plus the selected vessel context to Ollama.
+
+## What It Does
+
+With this plugin you can:
+
+- ask for a vessel-state summary in plain language
+- send selected Signal K paths to AI instead of the full data tree
+- review the AI response in a readable panel
+- see a history of previous AI requests
+- inspect the actual request that was sent to the model
+- check whether Ollama and the configured model are available
+
+## What You Need
+
+- a running Signal K server
+- this plugin installed in Signal K
+- a running Ollama server
+- a locally available Ollama model, for example `gemma4:e2b`
+
+## Quick Start
+
+1. Start Ollama.
+2. Make sure the model you want to use is available.
+3. Open the plugin configuration in Signal K.
+4. Set the Ollama URL and model name.
+5. Choose which Signal K paths should be sent to AI.
+6. Open the plugin web UI and press `Ask AI`.
+
+## Ollama With Docker Compose
+
+If you do not already have Ollama running, you can use the included compose file:
+
+[`docker-compose.gemma.yml`](https://github.com/KEGustafsson/signalk-ai-bridge/blob/main/docker-compose.gemma.yml)
+
+Start it with:
+
+```bash
+docker compose -f docker-compose.gemma.yml up -d
+```
+
+This compose setup already pulls `gemma4:e2b` during startup, so you do not need to run a separate `ollama pull` command.
+
+If Signal K runs on the host, the default Ollama URL `http://localhost:11434` is usually correct.
+
+If Signal K runs in another container, use an address reachable from that container, for example `http://ollama:11434` on a shared Docker network.
+
+## Normal Use
+
+In the web UI you will see:
+
+- `Signal K`: login state and vessel self ID
+- `Ollama / Gemma`: backend URL, model, AI status, and timeout
+- `AI Path Selection`: which Signal K paths are currently sent to AI
+- `AI Response`: the latest answer from the model
+- `Ask AI History`: previous prompts and results
+
+If AI is unavailable, the web UI also shows a help link that opens the Ollama setup instructions.
+
+## Important Plugin Settings
+
+These are the settings most users will care about:
+
+- `baseUrl`
+  Ollama server URL. Default: `http://localhost:11434`
+
+- `model`
+  Ollama model name. Example: `gemma4:e2b`
+
+- `aiDataPaths`
+  The Signal K self paths that will be sent to AI. You can use exact paths like `navigation.position` and simple wildcards like `navigation.*`
+
+- `requestTimeoutMs`
+  How long the plugin waits for Ollama. Set `0` to disable the timeout
+
+- `systemPrompt`
+  Extra instructions sent to the model before your question
+
+- `temperature`
+  Lower values are more stable and literal. Higher values are more varied
+
+- `topP`
+  Additional output randomness control
+
+- `maxTokens`
+  The output/context budget forwarded to Ollama
+
+## Notes About Model Names
+
+The plugin defaults to the Gemma 4 family.
+
+If you configure `gemma4` but Ollama only has a tagged variant installed, such as `gemma4:e2b`, the plugin will try to resolve and use the installed tagged model automatically.
+
+If you already know the exact installed model name, configuring that exact name is the clearest option.
+
+## Development
+
+For local development:
+
+```bash
+npm install
+npm run dev
+```
+
+Useful checks:
+
+```bash
+npm run test
+npm run check
+```
+
+To remove generated build output:
+
+```bash
+npm run clean
+```
+
+To build the packaged web UI:
+
+```bash
+npm run build
+```

package/index.cjs

@@ -0,0 +1,239 @@
+'use strict';
+
+const {
+  DEFAULT_AI_BASE_URL,
+  DEFAULT_AI_MODEL,
+  DEFAULT_SYSTEM_PROMPT,
+  getAiAvailability,
+  normalizeAiConfig,
+  queryAiModel,
+  readJsonBody
+} = require('./lib/ai-service.cjs');
+const { createBridgeService } = require('./lib/bridge-service.cjs');
+
+module.exports = function createPlugin(app, dependencies = {}) {
+  let pluginOptions = {};
+  let routesRegistered = false;
+  const bridgeService = createBridgeService(app, dependencies);
+
+  function normalizeServerConfig(options = {}) {
+    const aiDataPaths = Array.isArray(options.aiDataPaths)
+      ? options.aiDataPaths.map((item) => String(item || '').trim()).filter(Boolean)
+      : [];
+
+    return {
+      aiDataPaths
+    };
+  }
+
+  const getConfig = () => ({
+    ...normalizeAiConfig(pluginOptions),
+    ...normalizeServerConfig(pluginOptions)
+  });
+
+  const schema = () => ({
+    type: 'object',
+    properties: {
+      enabled: {
+        type: 'boolean',
+        title: 'Enable AI pipeline',
+        default: true
+      },
+      baseUrl: {
+        type: 'string',
+        title: 'Ollama host',
+        description:
+          'Ollama host URL. Leave blank to use AI_MODEL_URL or the default local Ollama server.',
+        default: DEFAULT_AI_BASE_URL
+      },
+      model: {
+        type: 'string',
+        title: 'AI model',
+        description: 'Ollama model name to send in chat requests.',
+        default: DEFAULT_AI_MODEL
+      },
+      systemPrompt: {
+        type: 'string',
+        title: 'System prompt',
+        description: 'Passed as a native Ollama system message before the operator request.',
+        default: DEFAULT_SYSTEM_PROMPT
+      },
+      requestTimeoutMs: {
+        type: 'integer',
+        title: 'Request timeout (ms)',
+        description: 'How long to wait for Ollama before failing. Set to 0 to disable the timeout.',
+        default: 120000,
+        minimum: 0,
+        maximum: 300000
+      },
+      temperature: {
+        type: 'number',
+        title: 'Temperature',
+        default: 0.2,
+        minimum: 0,
+        maximum: 2
+      },
+      topP: {
+        type: 'number',
+        title: 'Top-p',
+        default: 0.95,
+        minimum: 0,
+        maximum: 1
+      },
+      maxTokens: {
+        type: 'integer',
+        title: 'Max output tokens',
+        default: 131072,
+        minimum: 64,
+        maximum: 131072
+      },
+      aiDataPaths: {
+        type: 'array',
+        title: 'AI data paths',
+        description:
+          'Signal K self paths to collect and send to AI. Exact paths and simple wildcards ending in .* are supported. You can type your own paths, for example navigation.position, navigation.*, environment.wind.speedApparent, or notifications.',
+        uniqueItems: true,
+        default: [
+          'navigation.position',
+          'navigation.speedOverGround',
+          'navigation.courseOverGroundTrue',
+          'notifications'
+        ],
+        items: {
+          type: 'string',
+          title: 'Signal K path'
+        }
+      }
+    }
+  });
+
+  const statusHandler = async (req, res) => {
+    try {
+      const config = getConfig();
+      const availability = await getAiAvailability(config, dependencies);
+      res.status(200).json({
+        enabled: config.enabled,
+        baseUrl: config.baseUrl,
+        model: config.model,
+        requestTimeoutMs: config.requestTimeoutMs,
+        maxTokens: config.maxTokens,
+        aiDataPaths: config.aiDataPaths,
+        signalKSelfId: typeof app.selfId === 'string' ? app.selfId : undefined,
+        aiAvailable: availability.available,
+        ollamaReachable: availability.backendReachable,
+        modelAvailable: availability.modelAvailable,
+        resolvedModel: availability.resolvedModel,
+        availabilityMessage: availability.message
+      });
+    } catch (error) {
+      res.status(500).json({
+        error: {
+          code: 'unknown',
+          message: error instanceof Error ? error.message : 'Unknown AI status failure.'
+        }
+      });
+    }
+  };
+
+  const queryHandler = async (req, res) => {
+    try {
+      const config = getConfig();
+      const body = await readJsonBody(req);
+      const payload = await bridgeService.buildAiPayload(body, config);
+      const result = await queryAiModel(payload, config, dependencies);
+      res.status(200).json(result);
+    } catch (error) {
+      const statusCode =
+        typeof error === 'object' &&
+        error !== null &&
+        'statusCode' in error &&
+        typeof error.statusCode === 'number'
+          ? error.statusCode
+          : error && error.code === 'unauthorized'
+            ? 401
+          : error && error.code === 'validation-failed'
+            ? 400
+            : error && error.code === 'disabled'
+              ? 503
+              : error && error.code === 'timeout'
+                ? 504
+                : 502;
+
+      res.status(statusCode).json({
+        error: {
+          code:
+            typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+              ? error.code
+              : 'unknown',
+          message: error instanceof Error ? error.message : 'Unknown AI backend failure.'
+        }
+      });
+    }
+  };
+
+  const bridgeExecuteHandler = async (req, res) => {
+    try {
+      const config = getConfig();
+      const body = await readJsonBody(req);
+      const result = await bridgeService.executeTool(body, config);
+      res.status(200).json(result);
+    } catch (error) {
+      const statusCode =
+        typeof error === 'object' &&
+        error !== null &&
+        'statusCode' in error &&
+        typeof error.statusCode === 'number'
+          ? error.statusCode
+          : error && error.code === 'unauthorized'
+            ? 401
+            : error && error.code === 'validation-failed'
+              ? 400
+              : 500;
+
+      res.status(statusCode).json({
+        error: {
+          code:
+            typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+              ? error.code
+              : 'unknown',
+          message: error instanceof Error ? error.message : 'Unknown bridge failure.'
+        }
+      });
+    }
+  };
+
+  return {
+    id: 'signalk-ai-bridge',
+    name: 'AI Bridge',
+    description: 'Signal K Ask AI plugin with embedded web UI for Ollama and Gemma.',
+    schema,
+    start: (options = {}) => {
+      pluginOptions = options;
+      bridgeService.reset();
+      const config = getConfig();
+      if (typeof app.setPluginStatus === 'function') {
+        app.setPluginStatus(
+          config.enabled
+            ? `AI Bridge ready: ${config.model} via ${config.baseUrl}`
+            : 'AI Bridge webapp assets available. AI pipeline disabled.'
+        );
+      }
+    },
+    registerWithRouter: (router) => {
+      if (routesRegistered) {
+        return;
+      }
+      router.get('/ai/status', statusHandler);
+      router.post('/ai/query', queryHandler);
+      router.post('/bridge/execute', bridgeExecuteHandler);
+      routesRegistered = true;
+    },
+    stop: () => {
+      if (typeof app.setPluginStatus === 'function') {
+        app.setPluginStatus('AI Bridge stopped.');
+      }
+      bridgeService.reset();
+      pluginOptions = {};
+    }
+  };
+};