llm_meta_widget 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c9ff9a76f254cfd3096189703db3546a3089661a02de5848c98130732933e87
-  data.tar.gz: 5091614c56ea8d2e31e26d32286114505c30cc26edd5b9f4b0e66b9a779f5805
+  metadata.gz: 1590b5b56f4d164501425b88c2fddd28a07a19a229e6d3a6737a00a1f78b2a31
+  data.tar.gz: f8ba25f792c18736fd031757b18d8e2be7bdd85155f084e92f2cc683218a69c0
 SHA512:
-  metadata.gz: 94afd5f3ac2861a419b283e48c0fb49483ea0c128e1b3a68b0ab23b6da0b29d852274d7b4bba906826ee1f06196a5a5aa09f5209ef192b85341735962fed0e09
-  data.tar.gz: f0faabb00220362e70218e8685bb30bb0d201ea9d8963772e60cb95d5f4a7fac2e42691cf1b75e404b14ce34f4148204c46d30768a983ffa7db597b22ceb1de6
+  metadata.gz: 7cb9aad1047fca745e0c50c47e00c3c3504aaa34a104d2662ce1b2818abed81cddfdc7437a272b99629f4c61afba8b81a49deec8f97aff1f28a53ab29058410a
+  data.tar.gz: b5c75d48fc1e0583cf2e417e4f57f609742bf7342524f85a344c5ee89cb778db5b38f7703e15ebfc1d5f6a54d7b5bb2aab3c82765bbfadfc780104830712bd25

data/README.md

@@ -4,7 +4,7 @@ Embeddable browser chat widget for the [llm_meta](https://github.com/pubannotati
 
 Client-orchestrated: the widget fetches host-side action schemas + host-published `.well-known/mcp.json` manifests at boot, dispatches tool_calls locally (page-embedded actions) or directly to MCP endpoints (host-wide well-known), and consumes the meta-server's SSE `single_llm_calls` API. Ships as a custom element in one self-contained ES module — on npm for any host, and in a Rails gem whose helper serves the identical file.
 
-**No** Devise, DB migrations, ChatManager, or PromptNavigator. Adds only `rails >= 8.0` as a runtime dep — so hosts that haven't bumped to 8.1 can adopt it without a Rails upgrade.
+**No** Devise, DB migrations, ChatManager, or PromptNavigator. The gem adds only `rails >= 8.0` as a runtime dep — so hosts that haven't bumped to 8.1 can adopt it without a Rails upgrade — and hosts that are not Rails at all skip the gem entirely.
 
 ## What you need first
 
@@ -22,13 +22,26 @@ answers the chat, or use no hub at all. Page actions and your own
 Nothing else is required: no database, no migrations, no JavaScript build
 step, no Node at runtime.
 
-| Requirement | Version |
-|---|---|
-| Ruby | >= 3.2 |
-| Rails | >= 8.0 (8.1 not required) |
-| An llm_meta_server **or** an Ollama | any |
+| Requirement | Version | Needed when |
+|---|---|---|
+| A browser with custom elements + ES modules | any current | always |
+| An llm_meta_server **or** an Ollama | any | always — something has to answer the chat |
+| Ruby | >= 3.2 | only if you install the gem |
+| Rails | >= 8.0 (8.1 not required) | only if you install the gem |
+
+## Two ways to add the widget — choose one
+
+You do **not** need both. Pick the row that matches your app, then read only
+that section.
+
+| Your app | What you add | What you write |
+|---|---|---|
+| **Rails** | the gem, one line in your `Gemfile` | one helper call in a view. The helper writes the `<llm-meta-widget>` tag for you, so you never write that tag yourself |
+| **Anything else** — Python, Go, PHP, plain HTML… | one `<script>` tag from the CDN | the `<llm-meta-widget>` tag yourself |
+
+Both ways load the same file and run the same widget.
 
-## Installation
+## Rails apps: install the gem
 
 ```ruby
 # Gemfile
@@ -44,7 +57,27 @@ deliberately skips `isolate_namespace`, so the helper is included into
 ActionView and the asset routes appear at the host's top level on their own.
 There are no migrations and no generators to run.
 
-## Minimal working example
+**Why install the gem?** The gem gives you the same widget as the CDN — the
+same file, byte for byte. It does not add features. What it gives you is a
+simpler way to deliver and configure the widget:
+
+- **Your own server sends the file**, at
+  `/llm_meta_widget_assets/llm-meta-widget.js`. The page makes no request to
+  any other site. If the CDN is down, your page still works, and the widget
+  also works behind a firewall or on a network with no internet access.
+- **Bundler manages the version**, like every other gem. You update it with
+  `bundle update`. With the CDN, the version is part of a URL that someone
+  has to remember to change.
+- **You write Ruby, not HTML attributes.** The helper takes normal Ruby
+  values and converts them for you. That matters most where the attributes
+  are easy to get wrong: `nil` and `[]` mean different things for
+  `well_known_urls:`, the allowlists take arrays, and the pickers take real
+  `true`/`false`. Written by hand, all three must be encoded correctly as
+  text.
+- **The defaults are set for you**, so your view names only the options you
+  want to change.
+
+## Rails apps: a minimal working example
 
 Put this on any view — a fresh `pages/demo.html.erb` is fine:
 
@@ -79,7 +112,12 @@ 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
+## Non-Rails hosts: write the element yourself
+
+**If your app is Rails, you can skip this section.** The gem already does
+everything described here: its helper writes this tag for you and its engine
+sends this file. Read on if your app is not Rails — or if you use Rails but
+prefer the CDN to the gem, which the `element_path:` option allows.
 
 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
@@ -87,11 +125,16 @@ 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"
+<llm-meta-widget llm-url="https://your-meta-server.example"
+                 model="qwen3-6-35b-fast"
                  greeting="Hi — ask me anything about this page."></llm-meta-widget>
 ```
 
+This is the same configuration as the Rails example above, written in HTML
+instead of ERB. Both produce the same widget, so the advice in that section
+— CORS, a reachable `llm_url`, the hub's name for the model — applies here
+too.
+
 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.
 
@@ -105,10 +148,11 @@ Three ways to get that one file, in descending order of convenience:
 - **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).
+Going without the gem removes the Rails pieces — the helper and the partial.
+It does not remove your page's own contract, because those parts belong to the
+page rather than to Rails: 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:
@@ -248,7 +292,7 @@ By default the widget renders two pickers below the input textarea:
 - **Model dropdown** — populated from the hub's `GET /api/llms` (anon path returns Ollama-only, since the widget's LLM calls use `api_key_uuid: "ollama-local"`).
 - **Tool picker** — populated from the hub's `GET /api/mcp_servers` (anon path returns `public_to_anonymous: true` servers). Two-level UX: server bulk-toggle + individual tool checkboxes on expand.
 
-Both pickers require **CORS**: the meta-server must allow the host's origin on its `/api/*` resource. That allowlist is an environment variable, not code — `CORS_ORIGINS`, a comma-separated list — so adding a host is a deployment change and a restart, with no commit and nothing about one deployment's hosts published in the repo. Without CORS the fetch is silently blocked and the pickers stay empty.
+Both pickers require **CORS**, the same way the chat itself does: the hub must list your page's origin in its `CORS_ORIGINS` environment variable for the `/api/*` resource. Without that the fetches are blocked silently and both pickers simply stay empty.
 
 To adjust picker behavior at the helper call site:
 
@@ -274,6 +318,11 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 
 ## All helper options
 
+These are the gem helper's keyword options. If you write the element by hand,
+each one has an attribute of the same name in kebab-case — `llm_url:` becomes
+`llm-url`, and so on. The attribute table above lists the few that do not
+translate directly.
+
 | Option | Default | Purpose |
 |---|---|---|
 | `llm_url:` | required | Who answers the chat — an llm_meta_server, or an Ollama |

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

@@ -299,7 +299,11 @@ function boot(cfg) {
   	// baseline (if any), then the level-1 picker adds/removes entries as
   	// the visitor toggles server checkboxes. Passed to runChatLoop on
   	// every submit so the current selection is respected turn-by-turn.
-  	var remoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  	// Keep the baseline separately: refreshRemoteToolsFromPicker() rebuilds
+  	// remoteTools wholesale, so without a pristine copy the pre-configured
+  	// tools vanish the moment the picker first renders.
+  	var baselineRemoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  	var remoteTools = baselineRemoteTools.slice();
 
   	// Level-1 picker caches. hubMcpServers[] is the list of anon-visible
   	// servers fetched from GET /api/mcp_servers; each server has an
@@ -310,6 +314,10 @@ function boot(cfg) {
   	// state (all-on / indeterminate / all-off).
   	var hubMcpServers = [];
   	var selectedToolIds = new Set();
+  	// A pre-configured tool IS a selection: seed the set so the picker renders
+  	// it checked and the visitor can turn it off, rather than the picker
+  	// silently overriding the page.
+  	baselineRemoteTools.forEach(function(t) { selectedToolIds.add(t.id); });
 
   	function anyAllowedByAllowlist(name, allowlist) {
   		return allowlist === null || allowlist.indexOf(name) >= 0;
@@ -319,9 +327,11 @@ function boot(cfg) {
   		// Flatten every SELECTED tool (across all servers) into remoteTools,
   		// adapted to runChatLoop's expected { id, name, description, input_schema }.
   		var flat = [];
+  		var seen = {};
   		hubMcpServers.forEach(function(s) {
   			(s.tools || []).forEach(function(t) {
   				if (!selectedToolIds.has(t.id)) return;
+  				seen[t.id] = true;
   				flat.push({
   					id:           t.id,
   					name:         t.name,
@@ -330,6 +340,12 @@ function boot(cfg) {
   				});
   			});
   		});
+  		// A baseline tool whose server the picker never listed (not anon-visible,
+  		// or the fetch failed) has no checkbox to be found through — keep it
+  		// unless the visitor explicitly turned it off.
+  		baselineRemoteTools.forEach(function(t) {
+  			if (!seen[t.id] && selectedToolIds.has(t.id)) { flat.push(t); seen[t.id] = true; }
+  		});
   		remoteTools = flat;
   		if (toolsCountEl) {
   			toolsCountEl.textContent = flat.length;

data/app/assets/javascripts/llm_meta_widget/llm-meta-widget.js

@@ -3765,17 +3765,23 @@ function boot(cfg) {
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   var localTools = actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);
-  var remoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  var baselineRemoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
+  var remoteTools = baselineRemoteTools.slice();
   var hubMcpServers = [];
   var selectedToolIds = /* @__PURE__ */ new Set();
+  baselineRemoteTools.forEach(function(t) {
+    selectedToolIds.add(t.id);
+  });
   function anyAllowedByAllowlist(name, allowlist) {
     return allowlist === null || allowlist.indexOf(name) >= 0;
   }
   function refreshRemoteToolsFromPicker() {
     var flat = [];
+    var seen = {};
     hubMcpServers.forEach(function(s) {
       (s.tools || []).forEach(function(t) {
         if (!selectedToolIds.has(t.id)) return;
+        seen[t.id] = true;
         flat.push({
           id: t.id,
           name: t.name,
@@ -3784,6 +3790,12 @@ function boot(cfg) {
         });
       });
     });
+    baselineRemoteTools.forEach(function(t) {
+      if (!seen[t.id] && selectedToolIds.has(t.id)) {
+        flat.push(t);
+        seen[t.id] = true;
+      }
+    });
     remoteTools = flat;
     if (toolsCountEl) {
       toolsCountEl.textContent = flat.length;

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.7.4"
+  VERSION = "0.7.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_meta_widget
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 platform: ruby
 authors:
 - jdkim