llm_meta_widget 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2503371d1d6229fbe6e57a807fb8d672190de589ccdb877d2a90a06feae20be0
-  data.tar.gz: bce91755bb903ab02f886be7e9ab90733566699359e468624f3244f1202ad17a
+  metadata.gz: e6113516f03758b2dc602dd4f2e62b515206821b710c646c07faf474e1f9aa48
+  data.tar.gz: 5d65ceb25848ba253dfc61f92f04ed6f1110581fa5c3b7640c26718f2c4c4e51
 SHA512:
-  metadata.gz: d833790ba0fcdb48cb291a9cde65ab45e2c07284a18a9699c755289a2ded830695e84b3125e552f770c66db8e9930e9c28410baaef2c5e0459d75ef9b93636a4
-  data.tar.gz: 819cd9aa17be97c44b3828980b9faa6a3f79476a2802337b3e59a4149c17a45058a0355a7e5a29f39594ed8c8dfae373cb6040dde762795b6c031b9467d70128
+  metadata.gz: 6b255c67fa8f44ccc1a7fcb71a2ccb149bf1e02f1441c7bbda31a22502f98c491902dd978c7817e411af5865a54557a89581ec36dbd64e41ada6a1722397d04d
+  data.tar.gz: dd5fa208a4fbb758fdcf7b9683f6102ea49b99270fd5a0e49182ab7eb21966705b6aca5ae7ee746694dd3a019ef6bdf662d0d24f57551dd2a8b86e0921cee0cd

data/README.md

@@ -8,19 +8,25 @@ Client-orchestrated: the widget fetches host-side action schemas + host-publishe
 
 ## What you need first
 
-The widget is a browser front end. It does not talk to OpenAI, Anthropic or
-Ollama itself — it talks to **[llm_meta_server](https://github.com/pubannotation)**,
-a hub that holds the provider credentials and streams responses back over SSE.
-So adopting the widget means either running a hub or being given the URL of one.
+The widget is a browser front end: it needs something to answer the chat. That
+can be **[llm_meta_server](https://github.com/pubannotation)** — a hub that
+holds provider credentials and streams responses back — or **an Ollama**,
+which the widget talks to directly with no server component of ours in
+between.
 
-Nothing else is required: no database, no migrations, no JavaScript build step,
-no Node at runtime. The gem ships plain ES modules that the engine serves.
+Those are separate from where tools come from. A hub also registers MCP tools
+(Class 1 below), and you can point at one for tools while a local Ollama
+answers the chat, or use no hub at all. Page actions and your own
+`.well-known/mcp.json` never involve a hub either way.
+
+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) |
-| A reachable llm_meta_server | any |
+| An llm_meta_server **or** an Ollama | any |
 
 ## Installation
 
@@ -45,7 +51,7 @@ Put this on any view — a fresh `pages/demo.html.erb` is fine:
 ```erb
 <h1>Demo</h1>
 
-<%= llm_meta_widget(base_url: "https://your-meta-server.example",
+<%= llm_meta_widget(llm_url:  "https://your-meta-server.example",
                     model:    "qwen3-6-35b-fast",
                     greeting: "Hi — ask me anything about this page.") %>
 ```
@@ -63,8 +69,9 @@ says so explicitly.
 
 Two more things worth knowing before you go further:
 
-- `base_url` must be reachable from your visitors' browsers, not just from
-  your server. `localhost` works only while you are the visitor.
+- `llm_url` must be reachable from your visitors' browsers, not just from
+  your server. `localhost` works only while you are the visitor — which is
+  fine when each visitor runs their own Ollama.
 - The model name is the hub's name for it (`GET /api/llms` lists them), not
   the provider's.
 
@@ -185,7 +192,8 @@ To adjust picker behavior at the helper call site:
 
 ```erb
 <%= llm_meta_widget(
-      base_url:            "https://your-meta-server.example",
+      llm_url:             "https://your-meta-server.example",
+      tool_hub_url:        "https://your-meta-server.example",
       model:               "qwen3-6-35b-fast",   # initial selection
       enable_model_picker: true,                 # false → hide picker, use fixed `model:`
       enable_tool_picker:  true,                 # false → hide picker, no Class-1 tools
@@ -197,7 +205,7 @@ To adjust picker behavior at the helper call site:
 To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely (level-0 mode — Class 2 & 3 still work):
 
 ```erb
-<%= llm_meta_widget(base_url: "…", model: "…",
+<%= llm_meta_widget(llm_url: "…", model: "…",
                     enable_model_picker: false,
                     enable_tool_picker:  false) %>
 ```
@@ -206,7 +214,9 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 
 | Option | Default | Purpose |
 |---|---|---|
-| `base_url:` | required | Meta-server URL |
+| `llm_url:` | required | Who answers the chat — an llm_meta_server, or an Ollama |
+| `llm_provider:` | `:llm_meta_server` | What `llm_url` speaks. `:ollama` talks to Ollama's `/api/chat` directly |
+| `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 |
@@ -222,6 +232,45 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 | `models:` | `nil` | Model-name allowlist; `nil` = all anon-available |
 | `hub_tools:` | `nil` | MCP-server-name allowlist; `nil` = all anon-public |
 
+## Choosing what answers the chat, and whose tools to offer
+
+Two independent settings, because they are two jobs. Neither implies the
+other, so there is nothing to disable and nothing to inherit — what a widget
+does is what its call site says.
+
+```erb
+<%# a hub answers the chat; its registered tools are offered too %>
+<% hub = "https://your-meta-server.example" %>
+<%= llm_meta_widget(llm_url: hub, tool_hub_url: hub, model: "qwen3-6-35b-fast") %>
+
+<%# a hub answers the chat; no hub-registered tools %>
+<%= llm_meta_widget(llm_url: hub, model: "qwen3-6-35b-fast") %>
+
+<%# the visitor's own Ollama answers; a hub still supplies its tools %>
+<%= llm_meta_widget(llm_url: "http://localhost:11434", llm_provider: :ollama,
+                    tool_hub_url: hub, model: "qwen3.8:27b") %>
+
+<%# nothing of ours in the path at all %>
+<%= llm_meta_widget(llm_url: "http://localhost:11434", llm_provider: :ollama,
+                    model: "qwen3.8:27b") %>
+```
+
+**The Ollama path.** The widget POSTs to `{llm_url}/api/chat` and reads
+Ollama's NDJSON stream; tool schemas go over as OpenAI-shaped functions and
+`tool_calls` come back, so Class 2 and Class 3 tools work exactly as they do
+against a hub. The model picker lists `{llm_url}/api/tags`. Ollama must be
+told to accept your page's origin — `OLLAMA_ORIGINS=https://your-site.example`
+— which is the same CORS story as the hub, configured elsewhere.
+
+What you give up without a `tool_hub_url` is Class 1 only: tools registered on
+somebody's hub. That is not "no tools" — page actions and your own
+`.well-known/mcp.json` are untouched, and they are the interesting ones for an
+assistant embedded in your page.
+
+**Why anyone would want the last shape:** with a local Ollama and local MCP
+endpoints, nothing a visitor types leaves the machine. No credentials to hold,
+no retention policy to write.
+
 ## Declaring resources and prompts (static-primitives extension)
 
 If you operate the MCP endpoint behind your `.well-known/mcp.json`, you can

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

@@ -325,6 +325,14 @@ export async function runChatLoop(opts) {
     remoteTools = [],
     hostWideTools = [],
     maxRounds = 10,
+    // "hub" (default) talks to llm_meta_server; "ollama" talks straight to an
+    // Ollama, with no server component of ours in between. The loop is the
+    // same either way — only the call is swapped.
+    provider = "hub",
+    // Where Class 1 (hub-registered) tools are proxied. Usually the same
+    // llm_meta_server that answers the chat, but not when the chat goes
+    // straight to an Ollama — the tools still belong to the hub.
+    toolHubUrl,
     signal,
     onRoundStart,
     onTextDelta,
@@ -399,7 +407,9 @@ export async function runChatLoop(opts) {
     if (signal?.aborted) throw new DOMException("aborted", "AbortError")
     onRoundStart?.(round)
 
-    const turnResult = await singleLlmCall({
+    // The loop is the same whoever answers; only the call differs.
+    const call = provider === "ollama" ? ollamaChatCall : singleLlmCall
+    const turnResult = await call({
       ...singleOpts,
       messages,
       toolIds,
@@ -490,7 +500,7 @@ export async function runChatLoop(opts) {
       const args = coerceArguments(tc.arguments)
       try {
         const value = await dispatchRemoteToolCall({
-          baseUrl:     singleOpts.baseUrl,
+          baseUrl:     toolHubUrl || singleOpts.baseUrl,
           bearerToken: singleOpts.bearerToken,
           toolId:      tool.id,
           args:        args,
@@ -1006,3 +1016,172 @@ export function promptButtonProps(prompt) {
   }
 }
 
+
+// ---- direct-to-Ollama provider ------------------------------------------
+//
+// The smallest adoption: a Rails app and an Ollama, with no hub of ours in
+// between. Ollama's /api/chat already does the hard part — it takes tool
+// schemas and returns tool_calls — so what differs from the hub path is the
+// envelope: NDJSON rather than SSE, and its own request shape.
+//
+// What an adopter gives up is Class 1 (hub-registered MCP), which is the
+// hub's job by definition. Page actions and the host's own .well-known MCP
+// both work unchanged, and nothing the visitor types leaves their machine.
+//
+// Ollama must be told to accept the page's origin (OLLAMA_ORIGINS), the same
+// CORS story as the hub, configured elsewhere.
+
+export async function* parseNdjsonStream(readableStream, signal) {
+  const reader = readableStream.getReader()
+  const decoder = new TextDecoder("utf-8")
+  let buffer = ""
+
+  const onAbort = () => { try { reader.cancel() } catch { /* noop */ } }
+  signal?.addEventListener("abort", onAbort)
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+
+      let nl
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl).trim()
+        buffer = buffer.slice(nl + 1)
+        if (!line) continue
+        try {
+          yield JSON.parse(line)
+        } catch (e) {
+          // A truncated or non-JSON line is not worth aborting a stream for.
+        }
+      }
+    }
+    const tail = buffer.trim()
+    if (tail) { try { yield JSON.parse(tail) } catch (e) { /* ignore */ } }
+  } finally {
+    signal?.removeEventListener("abort", onAbort)
+    try { reader.releaseLock() } catch { /* noop */ }
+  }
+}
+
+// Tool schemas travel as MCP-flavoured `input_schema`; Ollama wants OpenAI's
+// function shape.
+function toolsForOllama(localTools) {
+  return (localTools || []).map((t) => ({
+    type: "function",
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.input_schema || t.inputSchema || { type: "object", properties: {} }
+    }
+  }))
+}
+
+// The hub's history carries `tool_call_id`; Ollama identifies a result by the
+// tool's name instead, and rejects unknown keys on some versions.
+function messagesForOllama(messages) {
+  return (messages || []).map((m) => {
+    if (m.role === "tool") {
+      return { role: "tool", tool_name: m.name, content: m.content }
+    }
+    if (m.tool_calls) {
+      return {
+        role: m.role,
+        content: m.content || "",
+        tool_calls: m.tool_calls.map((tc) => ({
+          function: { name: tc.name, arguments: coerceArguments(tc.arguments) }
+        }))
+      }
+    }
+    return { role: m.role, content: m.content }
+  })
+}
+
+// Same signature and return shape as singleLlmCall, so runChatLoop does not
+// care which provider answered.
+export async function ollamaChatCall({
+  baseUrl,
+  modelName,
+  messages,
+  localTools = [],
+  generationSettings = {},
+  onTextDelta,
+  onThinkingDelta,
+  onToolCall,
+  onPhase,
+  signal,
+}) {
+  if (!baseUrl || !modelName) throw new Error("ollamaChatCall: baseUrl and modelName are required")
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new Error("ollamaChatCall: messages must be a non-empty array")
+  }
+
+  const { think, ...options } = generationSettings || {}
+  const body = { model: modelName, messages: messagesForOllama(messages), stream: true }
+  if (localTools && localTools.length) body.tools = toolsForOllama(localTools)
+  if (think !== undefined) body.think = think
+  if (Object.keys(options).length) body.options = options
+
+  const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/chat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal
+  })
+  if (!response.ok) {
+    const text = await response.text().catch(() => "")
+    throw new Error(`ollamaChatCall: HTTP ${response.status} ${response.statusText}${text ? " — " + text.slice(0, 200) : ""}`)
+  }
+  if (!response.body) throw new Error("ollamaChatCall: response has no body (streaming unsupported?)")
+
+  const toolCalls = []
+  let content = ""
+  let finishReason = null
+  let announcedPhase = null
+
+  const phase = (name) => {
+    if (announcedPhase === name) return
+    announcedPhase = name
+    onPhase?.(name)
+  }
+
+  for await (const frame of parseNdjsonStream(response.body, signal)) {
+    const message = frame.message || {}
+
+    if (message.thinking) {
+      phase("thinking")
+      onThinkingDelta?.(message.thinking)
+    }
+    if (message.content) {
+      phase("responding")
+      content += message.content
+      onTextDelta?.(message.content)
+    }
+    for (const tc of message.tool_calls || []) {
+      const call = {
+        id: tc.id || `ollama-${toolCalls.length}`,
+        name: tc.function?.name,
+        arguments: tc.function?.arguments ?? {}
+      }
+      toolCalls.push(call)
+      onToolCall?.(call)
+    }
+    if (frame.done) finishReason = frame.done_reason || "stop"
+  }
+
+  return { content, toolCalls, finishReason }
+}
+
+// Ollama's own catalogue, for the model picker when there is no hub to ask.
+export async function fetchOllamaModels({ baseUrl, signal }) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/tags`, { signal })
+    if (!response.ok) return []
+    const data = await response.json()
+    return (data.models || []).map((m) => m.name).filter(Boolean)
+  } catch (e) {
+    // A picker that cannot be populated is not a reason to break the widget.
+    return []
+  }
+}

data/app/helpers/llm_meta_widget/widget_helper.rb

@@ -16,7 +16,18 @@ module LlmMetaWidget
   # (page-embedded aiActions / host-wide well-known / hub-registered).
   module WidgetHelper
     DEFAULTS = {
-      api_key_uuid:            "ollama-local",
+      api_key_uuid:            "ollama-local",   # llm_meta_server provider only
+      # Answering the chat and registering tools are separate jobs. Name each
+      # endpoint for the job it does; neither implies the other.
+      #
+      #   llm_url:       who answers the chat (required)
+      #   llm_provider:  what it speaks — :llm_meta_server (default) or :ollama
+      #   tool_hub_url:  an llm_meta_server whose registered MCP tools to
+      #                  offer. Absent means none — which does NOT mean "no
+      #                  tools": page actions and the host's own
+      #                  .well-known/mcp.json are unaffected.
+      llm_provider:            "llm_meta_server",
+      tool_hub_url:            nil,
       orchestrator_path:       "/llm_meta_widget_assets/orchestrator.js",
       actions_schema_id:       "ai-actions",
       state_global:            "aiState",
@@ -42,9 +53,20 @@ module LlmMetaWidget
       greeting:                nil
     }.freeze
 
-    def llm_meta_widget(base_url:, model:, **overrides)
-      locals = DEFAULTS.merge(base_url: base_url, model: model, **overrides)
-      render partial: "llm_meta_widget/chat_panel", locals: locals
+    def llm_meta_widget(llm_url:, model:, **overrides)
+      locals = DEFAULTS.merge(llm_url: llm_url, model: model, **overrides)
+      provider = locals[:llm_provider].to_s
+      unless %w[llm_meta_server ollama].include?(provider)
+        raise ArgumentError,
+              "llm_meta_widget: llm_provider must be :llm_meta_server or :ollama, got #{provider.inspect}"
+      end
+      raise ArgumentError, "llm_meta_widget: llm_url is required" if llm_url.to_s.strip.empty?
+
+      hub = locals[:tool_hub_url]
+      hub = nil if hub.to_s.strip.empty?
+
+      render partial: "llm_meta_widget/chat_panel",
+             locals: locals.merge(llm_provider: provider, tool_hub_url: hub)
     end
   end
 end

data/app/views/llm_meta_widget/_chat_panel.html.erb

@@ -452,7 +452,7 @@
 	import { runChatLoop, fetchMcpManifest, listMcpPrompts, getMcpPrompt,
 	         listMcpResources, readMcpResource, promptMessagesToText,
 	         loadHostResource, resourceLinesForTurn, resolvePromptArguments,
-	         promptButtonProps, promptArgumentSummary } from "<%= orchestrator_path %>";
+	         promptButtonProps, promptArgumentSummary, fetchOllamaModels } from "<%= orchestrator_path %>";
 	import { marked } from "/llm_meta_widget_assets/marked.esm.js";
 
 	// Standard prose settings — GFM (tables, autolinks, strikethrough),
@@ -460,7 +460,12 @@
 	// bare newlines still reads naturally.
 	marked.setOptions({ gfm: true, breaks: true });
 
-	var META_BASE              = <%= base_url.to_json.html_safe %>;
+	// Two endpoints, two jobs: one answers the chat, the other registers the
+	// MCP tools on offer. They are usually the same llm_meta_server, but need
+	// not be — an adopter can run their own Ollama and still borrow a hub's
+	// tools, or use no hub at all.
+	var LLM_BASE               = <%= llm_url.to_json.html_safe %>;
+	var TOOL_HUB_BASE          = <%= tool_hub_url.to_json.html_safe %>;
 	var API_KEY_UUID           = <%= api_key_uuid.to_json.html_safe %>;
 	var MODEL                  = <%= model.to_json.html_safe %>;
 	var ACTIONS_SCHEMA_ID      = <%= actions_schema_id.to_json.html_safe %>;
@@ -470,8 +475,12 @@
 	var REMOTE_TOOLS_SCHEMA_ID = <%= remote_tools_schema_id.to_json.html_safe %>;
 	var MAX_ROUNDS             = <%= max_rounds.to_json.html_safe %>;
 	var WELL_KNOWN_URLS        = <%= raw(well_known_urls.nil? ? "null" : well_known_urls.to_json) %>;
+	var LLM_PROVIDER           = <%= llm_provider.to_json.html_safe %>;
 	var ENABLE_MODEL_PICKER    = <%= enable_model_picker.to_json.html_safe %>;
-	var ENABLE_TOOL_PICKER     = <%= enable_tool_picker.to_json.html_safe %>;
+	// 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.
+	var ENABLE_TOOL_PICKER     = <%= enable_tool_picker.to_json.html_safe %> && <%= tool_hub_url.to_json.html_safe %> !== null;
 	var MODEL_ALLOWLIST        = <%= raw(models.nil?    ? "null" : models.to_json) %>;
 	var HUB_TOOLS_ALLOWLIST    = <%= raw(hub_tools.nil? ? "null" : hub_tools.to_json) %>;
 
@@ -633,8 +642,27 @@
 		// still works with the initial `model:` + no hub tools).
 		var tasks = [];
 
-		if (ENABLE_MODEL_PICKER && modelPicker) {
-			tasks.push(fetch(META_BASE + "/api/llms", { headers: { "Accept": "application/json" } })
+		if (ENABLE_MODEL_PICKER && modelPicker && LLM_PROVIDER === "ollama") {
+			// No hub to ask: Ollama lists its own models.
+			tasks.push(fetchOllamaModels({ baseUrl: LLM_BASE }).then(function(names) {
+				var flat = names
+					.filter(function(n) { return anyAllowedByAllowlist(n, MODEL_ALLOWLIST); })
+					.map(function(n) { return { value: n, label: n }; });
+				if (!flat.some(function(m) { return m.value === MODEL; })) {
+					flat.unshift({ value: MODEL, label: MODEL });
+				}
+				modelPicker.innerHTML = "";
+				flat.forEach(function(m) {
+					var opt = document.createElement("option");
+					opt.value = m.value;
+					opt.textContent = m.label;
+					if (m.value === MODEL) opt.selected = true;
+					modelPicker.appendChild(opt);
+				});
+				if (flat.length > 1) modelPicker.style.display = "";
+			}));
+		} else if (ENABLE_MODEL_PICKER && modelPicker) {
+			tasks.push(fetch(LLM_BASE + "/api/llms", { headers: { "Accept": "application/json" } })
 				.then(function(r) { return r.ok ? r.json() : { llms: [] }; })
 				.then(function(payload) {
 					// /api/llms is heterogeneous per family:
@@ -671,7 +699,7 @@
 		}
 
 		if (ENABLE_TOOL_PICKER && toolsListEl) {
-			tasks.push(fetch(META_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" } })
+			tasks.push(fetch(TOOL_HUB_BASE + "/api/mcp_servers", { headers: { "Accept": "application/json" } })
 				.then(function(r) { return r.ok ? r.json() : { mcp_servers: [] }; })
 				.then(function(payload) {
 					hubMcpServers = (payload.mcp_servers || []).filter(function(s) {
@@ -1256,7 +1284,8 @@
 				.concat([{ role: "user", content: userText }]);
 
 			var result = await runChatLoop({
-				baseUrl:       META_BASE,
+				baseUrl:       LLM_BASE,
+				toolHubUrl:    TOOL_HUB_BASE,
 				apiKeyUuid:    API_KEY_UUID,
 				modelName:     MODEL,
 				messages:      messages,
@@ -1265,6 +1294,7 @@
 				hostWideTools: hostWideTools,
 				aiActions:     window[ACTIONS_GLOBAL] || {},
 				maxRounds:     MAX_ROUNDS,
+				provider:      LLM_PROVIDER === "ollama" ? "ollama" : "hub",
 				signal:        currentAbort.signal,
 				onToolCall: function(toolCall) { announceToolCall(toolCall); },
 				onToolDispatched: function(outcome) { resolveToolCall(outcome); },

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

metadata

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