llm_meta_widget 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eea94229b42018fa2725d28578dd49970e9d0d3b2bc9bf095b9ac8fced1dcf80
-  data.tar.gz: 1b3c95b8632aa46d0bb6e8b338fae6ae2166356912629294e68db480e9124abf
+  metadata.gz: 8c33302ad656efdecb39d20c27c5a9a04aa888b1ac297c4d6554ddd59c3d0a2a
+  data.tar.gz: 423222703ab4ca5511498829df6dd259b16d82a54f8377014e175707e256d916
 SHA512:
-  metadata.gz: 7b6a4f6ac17d8601544fdb3ca94396b3482e66e13f3d5ba765c6d5839b608b17e692af5d7df16b51008a39ad527229193a8ce8d44345eb92feb98c31550f96b5
-  data.tar.gz: d8785730a6294fbfe926353c07ed3737add9ea8577a81cfc55471d020cfef51c641fdc735d5297a6701ab9cefe4b5a295df74c75897c84bac0e5f2c30e92f6d9
+  metadata.gz: 3db09535d1fb922382bb85a267c69b941ac52accfe4e8c11297d73fb0a6642820adf6501b8508016a1a675436cd854562ffdea1d8b32bfcfcb1cd2c27b127640
+  data.tar.gz: 4499b65309c28d304439e267d7d4d1d5e2cf620a531f79b61011f1ef873ed7c9e6477a6b4e4337a9defb2330c1277862fbb8e0866d25e8bd936ff8559d890dc2

data/README.md

@@ -79,6 +79,65 @@ Once that works, the widget can converse but cannot *do* anything. To let the
 LLM act on your page or call your own services, declare tools using any of the
 **three tool classes** below.
 
+## Any host: the custom element
+
+The widget is a custom element in a single self-contained ES module, so a host
+that is not Rails needs no gem, no template engine and no asset pipeline — two
+lines of HTML:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.7"></script>
+<llm-meta-widget llm-url="https://your-hub.example"
+                 model="qwen3-8-27b-fast"
+                 greeting="Hi — ask me anything about this page."></llm-meta-widget>
+```
+
+Nothing else is needed: the stylesheets and the markdown renderer are bundled
+in, and the element injects its own styles. The host serves no CSS and no JS.
+
+Three ways to get that one file, in descending order of convenience:
+
+- **the CDN**, as above — `@aibranch/llm-meta-widget` on npm, no path needed
+  because the package's `main` is the bundle;
+- **the gem**, which serves the identical file at
+  `/llm_meta_widget_assets/llm-meta-widget.js` for Rails hosts, and is what the
+  `llm_meta_widget` helper points at;
+- **self-hosted** — copy it out of the package or the gem and serve it as a
+  static asset, if you would rather not depend on a CDN.
+
+The two Rails-specific pieces are gone from the host's side of the contract.
+What is NOT gone is the host page's own contract, because those pieces belong to
+the host: the `#ai-actions` JSON block, `window.aiState` and `window.aiActions`
+are declared exactly as they are under Rails (see the three tool classes below).
+
+**Attributes** map one-to-one onto the helper's keyword options. Three are not
+obvious and are the ones that bite:
+
+| attribute | notes |
+|---|---|
+| `llm-url`, `model` | required |
+| `tool-hub-url` | omit for no Class 1; `""` is the same as omitting |
+| `llm-provider` | `llm_meta_server` (default) or `ollama` |
+| `api-key-uuid`, `greeting`, `max-rounds` | as the helper options |
+| `actions-schema-id`, `state-global`, `actions-global`, `remote-tools-schema-id` | as the helper options |
+| `models`, `hub-tools` | comma-separated. Omitted **or empty** means no allowlist — an allowlist permitting nothing is never what anyone meant |
+| `enable-model-picker`, `enable-tool-picker` | **value attributes, not boolean attributes.** They default to true, so presence cannot mean true. Disable with `enable-tool-picker="false"`; any other value is true |
+| `well-known-urls` | **tri-state**, because an attribute cannot express nil-versus-empty: omitted = auto-discover same-origin `/.well-known/mcp.json`; `""` = discovery off; `"a,b"` = fetch those |
+
+That last one is the quiet failure to watch for: expecting discovery off and
+getting a same-origin fetch looks like nothing at all, except a 404 in the
+console.
+
+One widget per page. The panel uses fixed element ids, so a second
+`<llm-meta-widget>` is ignored with a console warning rather than fighting the
+first over every lookup.
+
+**Building it.** `npm run build` bundles `element.js`, `config.js`,
+`orchestrator.js`, the vendored `marked` and both stylesheets with esbuild. The
+result is committed and shipped in the gem, because a gem cannot run a build
+step on install — and `npm test` fails if the committed bundle has drifted from
+its sources.
+
 ## Three tool classes
 
 The widget classifies every tool_call the LLM emits by name and dispatches to one of three execution paths. Each class has a different declaration, different visibility to the LLM, and different execution semantics.
@@ -90,7 +149,10 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 **Declaration** — three script blocks on the view:
 
 ```html
-<!-- (a) Tool schemas the LLM sees. JSON Schema (draft-2020-12 subset). -->
+<!-- (a) Tool schemas the LLM sees. JSON Schema vocabulary — in practice
+     type, properties, required, description, items, enum. No $schema is
+     declared and nothing here validates one: the object is forwarded to
+     the provider as-is, and each provider accepts its own subset. -->
 <script type="application/json" id="ai-actions">
 [
   { "name": "add_dictionaries",
@@ -219,7 +281,7 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 | `tool_hub_url:` | `nil` | An llm_meta_server whose registered MCP tools to offer. Absent = none (page actions and your own `.well-known` MCP are unaffected) |
 | `model:` | required | Initial model (also the fallback when picker is disabled) |
 | `api_key_uuid:` | `"ollama-local"` | Hub API-key uuid to invoke |
-| `orchestrator_path:` | `"/llm_meta_widget_assets/orchestrator.js"` | Served by the gem's engine; rarely overridden |
+| `element_path:` | `"/llm_meta_widget_assets/llm-meta-widget.js"` | The bundled element the page loads. Served by the gem's engine; override to load it from elsewhere |
 | `actions_schema_id:` | `"ai-actions"` | DOM id of the Class-3 schema block |
 | `state_global:` | `"aiState"` | Global window object holding Class-3 state readers |
 | `actions_global:` | `"aiActions"` | Global window object holding Class-3 implementations |

data/app/assets/javascripts/llm_meta_widget/config.js

@@ -0,0 +1,79 @@
+// Attribute reading for <llm-meta-widget>.
+//
+// Separate from element.js so it can be unit-tested without a DOM and without
+// the bundler: it takes anything with hasAttribute/getAttribute, so the tests
+// pass a plain object. The panel's own logic has never had unit tests — this is
+// the half of the custom-element move that can have them, so it does.
+//
+// Three cases are not obvious, and are the ones adopters get wrong:
+//
+//   * The pickers default to TRUE, so they cannot be HTML boolean attributes
+//     (presence-means-true would be backwards — you would have to add an
+//     attribute to get the default). They are value attributes: disable with
+//     enable-tool-picker="false". Any other value, including "", is true.
+//   * well-known-urls is TRI-state, because the Ruby option distinguished nil
+//     (auto-discover same-origin /.well-known/mcp.json) from [] (discovery off)
+//     from an explicit list, and attributes cannot express nil versus empty:
+//       absent  -> null  (auto-discover)
+//       ""      -> []    (off)
+//       "a,b"   -> ["a","b"]
+//   * models / hub-tools treat "" as absent rather than as an empty allowlist,
+//     because an allowlist that permits nothing is never what anyone meant.
+//
+// Key names are the UPPER_CASE ones the panel logic already used, so that logic
+// moved across untouched.
+
+export const DEFAULTS = Object.freeze({
+  API_KEY_UUID:           "ollama-local",
+  ACTIONS_SCHEMA_ID:      "ai-actions",
+  STATE_GLOBAL:           "aiState",
+  ACTIONS_GLOBAL:         "aiActions",
+  REMOTE_TOOLS_SCHEMA_ID: "remote-mcp-tools",
+  LLM_PROVIDER:           "llm_meta_server",
+  MAX_ROUNDS:             3,
+});
+
+const splitList = (v) => v.split(",").map((s) => s.trim()).filter(Boolean);
+
+export function readConfig(el) {
+  const raw = (n) => (el && el.hasAttribute(n) ? el.getAttribute(n) : null);
+  const str = (n, d) => { const v = raw(n); return v === null ? d : v; };
+  const bool = (n, d) => { const v = raw(n); return v === null ? d : v !== "false"; };
+  const int = (n, d) => {
+    const v = raw(n);
+    if (v === null) return d;
+    const i = parseInt(v, 10);
+    return Number.isNaN(i) ? d : i;
+  };
+  const list = (n) => {
+    const v = raw(n);
+    return v === null || v.trim() === "" ? null : splitList(v);
+  };
+
+  const toolHub = str("tool-hub-url", null) || null;   // "" collapses to null
+  const wellKnown = raw("well-known-urls");
+
+  return {
+    LLM_BASE:               str("llm-url", null),
+    TOOL_HUB_BASE:          toolHub,
+    API_KEY_UUID:           str("api-key-uuid", DEFAULTS.API_KEY_UUID),
+    MODEL:                  str("model", null),
+    ACTIONS_SCHEMA_ID:      str("actions-schema-id", DEFAULTS.ACTIONS_SCHEMA_ID),
+    GREETING:               str("greeting", null),
+    STATE_GLOBAL:           str("state-global", DEFAULTS.STATE_GLOBAL),
+    ACTIONS_GLOBAL:         str("actions-global", DEFAULTS.ACTIONS_GLOBAL),
+    REMOTE_TOOLS_SCHEMA_ID: str("remote-tools-schema-id", DEFAULTS.REMOTE_TOOLS_SCHEMA_ID),
+    MAX_ROUNDS:             int("max-rounds", DEFAULTS.MAX_ROUNDS),
+    WELL_KNOWN_URLS:        wellKnown === null
+                              ? null
+                              : (wellKnown.trim() === "" ? [] : splitList(wellKnown)),
+    LLM_PROVIDER:           str("llm-provider", DEFAULTS.LLM_PROVIDER),
+    ENABLE_MODEL_PICKER:    bool("enable-model-picker", true),
+    // Class 1 tools are registered on a hub, so the picker needs one — which is
+    // independent of who answers the chat. Page actions and the host's own
+    // .well-known MCP work regardless.
+    ENABLE_TOOL_PICKER:     bool("enable-tool-picker", true) && toolHub !== null,
+    MODEL_ALLOWLIST:        list("models"),
+    HUB_TOOLS_ALLOWLIST:    list("hub-tools"),
+  };
+}