llm_meta_widget 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20aa5babd648e80015577ece5c815b37f6fe5e06d6136c91647f49831016833b
-  data.tar.gz: 8dfc055787110255fbf32368bc3f29cf11b3be178477dac9dadf08243a48d096
+  metadata.gz: 17cad71af08d5e4c49a3e7418055bd9c034880d9ab6cae2cbb3fb6cf3a0f0804
+  data.tar.gz: 24e7aa0c38400bccee9ddc832a6da10cf2788f42e343b67901d0cfc9a7748e24
 SHA512:
-  metadata.gz: 2545397e740fefb805c8b8b3f9c90ca78814d71b2138f91a35afd38e1499f9bace74428faaf9160cbda4d9a5b51421a81f16f51df82c7ce88389d07acb97293d
-  data.tar.gz: a05e51a8b8e94a0153d5c7612901cba9ff2f31beb3142e656852cfa43c87b65ecc513d42c2a6a7a9b2a7ef6b0be3f240ec067bd468afd4b320684089cddfff3b
+  metadata.gz: 2e55a245ad87d21f2d235fe9c211751520172df72f7197ad70b558a546c0b80e62ce63e9f00718ac0f91145d2a14bf920db808f70a550c7822d603c20a565833
+  data.tar.gz: bdad3eda95fd643db1dc11fc10c4e2c48d0d3442d3e2a1a79012f1e8bb2af769dc98217d897b6fd7b173a17f06e7ba55ab3209d50a3cd7186349dbce5920030b

data/README.md

@@ -6,28 +6,71 @@ Client-orchestrated: the widget fetches host-side action schemas + host-publishe
 
 **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.
 
-## Installation (local, path-based)
+## What you need first
 
-Add to the host app's Gemfile:
+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.
+
+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.
+
+| Requirement | Version |
+|---|---|
+| Ruby | >= 3.2 |
+| Rails | >= 8.0 (8.1 not required) |
+| A reachable llm_meta_server | any |
+
+## Installation
 
 ```ruby
-gem "llm_meta_widget", path: "../llm_meta/llm_meta_widget"
+# Gemfile
+gem "llm_meta_widget", "~> 0.4"
+```
+
+```
+bundle install
 ```
 
-Then `bundle install`. The engine auto-includes the widget helper into ActionView, so nothing else to wire up.
+That is the whole install. There is **no `mount` to add** — the engine
+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.
 
-## Usage
+## Minimal working example
 
-On any view where you want the widget:
+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",
-                    model:    "qwen3-6-35b-fast") %>
+                    model:    "qwen3-6-35b-fast",
+                    greeting: "Hi — ask me anything about this page.") %>
 ```
 
-That's the minimum. The widget renders a floating chat panel; visitors get a message-list, an input box, and (by default) a model dropdown + tool picker below the input.
+Start the app, open that page, and click the round toggle at the bottom right.
+**Success looks like:** a panel opens showing your greeting, you type "hello",
+the role label turns into a spinning gear reading "Working…", and the reply
+streams in.
+
+If the panel opens but nothing comes back, it is almost always CORS. The hub
+must list your app's origin in its `config/initializers/cors.rb` for the
+`/api/*` resource, because the widget calls the hub **from the visitor's
+browser**, not from your server. Open the browser console: a blocked request
+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.
+- The model name is the hub's name for it (`GET /api/llms` lists them), not
+  the provider's.
 
-To make the LLM able to do more than converse, declare tools using any of the **three tool classes** below.
+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.
 
 ## Three tool classes
 
@@ -72,7 +115,17 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 
 **What the LLM sees.** The `ai-actions` JSON is passed to the meta-server as `local_tools` for every turn. Alongside it, every reader in `window.aiState` is invoked (each turn) and the results are JSON-serialized into a `Current page state:` block appended to the system prompt — the LLM can answer from state directly instead of tool-calling for lookups.
 
-**When the tool_call fires.** Fire-and-forget, dispatched **AFTER** the LLM's response text finishes streaming. The action's return value is NOT fed back to the LLM this turn — the model already produced its user-facing answer and moved on. This is a deliberate design choice (see `project_page_embedded_actions` memory): writes are separated from the conversation loop so the LLM can commit to an action without waiting for a round-trip. Use Class 1/2 instead when you need the LLM to actually see the tool's result.
+**When the tool_call fires.** During the turn, as soon as the LLM emits the
+call. Since 0.4.0 the action's outcome — `{ok: true, applied: "<name>"}`, or
+the error message if it raised — is fed back to the LLM as a tool result, and
+the turn continues. Before 0.4.0 these were fire-and-forget, which meant a
+turn whose only calls were page actions ended there: any task shaped *change
+the page, then do something with it* was cut off after the write. The change
+also means the LLM can see that an action failed and correct itself, instead
+of the failure being visible only to the visitor.
+
+Budget for it: every page action now costs a round, so a flow that writes twice
+and then calls a tool needs roughly five or six. See `max_rounds:` below.
 
 **Args**: parsed JS object matching the `input_schema`. Return value ignored. Async allowed (widget doesn't await, but browser will still execute the promise). Exceptions logged and surfaced as an `❌ <name>` chip in the message footer.
 
@@ -115,7 +168,7 @@ Declared out-of-band on the meta-server (via the hub's admin UI or `/user/:id/mc
 
 **What the LLM sees.** Only tools from servers the visitor has **enabled via the tool picker** (see "Level-1 pickers" below). Nothing is auto-selected — the visitor opts in per session.
 
-**When the tool_call fires.** Synchronously during the turn — widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/chat_streams` endpoint with `tool_ids: [...]`; the hub proxies to each MCP server and streams results back through SSE.
+**When the tool_call fires.** Synchronously during the turn — widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/single_llm_calls` endpoint with `tool_ids: [...]`; the hub proxies to each MCP server and streams results back through SSE.
 
 **Error path.** Hub-side errors (rate limit, timeout, MCP server unavailable, upstream failure) arrive as SSE `event: error` frames with typed codes (`mcp_unavailable`, `timeout`, `rate_limit`, …); the widget surfaces them in the message bubble with a per-code prefix.
 
@@ -162,12 +215,69 @@ To lock the widget to the fixed `model:` prop and disable Class-1 tools entirely
 | `actions_global:` | `"aiActions"` | Global window object holding Class-3 implementations |
 | `remote_tools_schema_id:` | `"remote-mcp-tools"` | Optional DOM id for pre-configured Class-1 tools (bypasses picker) |
 | `well_known_urls:` | `nil` | `nil` = auto-discover same-origin; explicit array = fetch those; `[]` = disable |
-| `max_rounds:` | `3` | Cap on tool-call rounds per LLM turn |
+| `greeting:` | `nil` | First thing a visitor sees when the panel opens, above the offered prompt templates. `nil` = a generic line |
+| `max_rounds:` | `3` | Cap on tool-call rounds per LLM turn. Page actions cost a round each since 0.4.0 — raise it for multi-step flows |
 | `enable_model_picker:` | `true` | Show model dropdown (Level-1) |
 | `enable_tool_picker:` | `true` | Show tool picker (Level-1) |
 | `models:` | `nil` | Model-name allowlist; `nil` = all anon-available |
 | `hub_tools:` | `nil` | MCP-server-name allowlist; `nil` = all anon-public |
 
+## Declaring resources and prompts (static-primitives extension)
+
+If you operate the MCP endpoint behind your `.well-known/mcp.json`, you can
+also offer **prompts** (one-click starting points, shown as buttons above the
+input) and **resources** (reference data the widget can put in the model's
+context). The widget reads two optional fields the
+`io.modelcontextprotocol/static-primitives` extension defines on a
+`resources/list` entry:
+
+```json
+{
+  "uri": "yourhost://catalog",
+  "name": "Catalog",
+  "mimeType": "application/json",
+  "_meta": {
+    "io.modelcontextprotocol/static-primitives": {
+      "sizeBytes": 1298,
+      "volatility": "stable",
+      "autoAttach": true
+    }
+  }
+}
+```
+
+- **`sizeBytes`** — the byte length of the payload `resources/read` returns.
+  The widget decides whether it can afford the resource *before* fetching it;
+  over its budget (8 KB), the bytes never cross the wire and the LLM is left
+  to ask for what it needs through your tools instead.
+- **`volatility`** — `"stable"` (read once, re-used) or `"volatile"` (re-read
+  on every turn that uses it).
+- **`autoAttach`** — may the widget put this in the model's context without
+  the visitor asking?
+
+All three are optional. A server that declares none behaves exactly as one
+that predates the extension: the resource is fetched, trimmed to budget and
+carried in the model's context.
+
+A prompt is offered as a button labelled by its `title`. Declare its arguments
+as **optional** and fill them from page state where you can: an argument the
+visitor must supply by hand makes the button useless to the visitor who needed
+it most, since they must already know your form to press it.
+
+## Further reading
+
+- **The static-primitives extension** — `io.modelcontextprotocol/static-primitives`,
+  a follow-on to [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol)
+  (Server Cards). The fields above are a reference implementation of its
+  current draft shape.
+- **MCP itself** — <https://modelcontextprotocol.io>
+- **A worked adopter** — PubDictionaries' annotation page
+  (<https://pubdictionaries.org/text_annotation>) runs this widget with all
+  three tool classes plus prompts and resources. Its
+  `app/views/annotation/text_annotation.html.erb` and `app/controllers/mcp_controller.rb`
+  are the fullest example available.
+- **Issues and questions** — <https://github.com/jdkim/llm_meta_widget/issues>
+
 ## License
 
 Apache-2.0.

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

@@ -1072,6 +1072,10 @@
 
 	var currentThinkingBlock = null;
 	var currentThinkingBody  = null;
+	// The assistant bubble of the turn in flight. Reasoning belongs ABOVE that
+	// bubble's content, the way llm_meta_chat places it — appending it to the
+	// transcript instead left it below the answer it was reasoning towards.
+	var activeAssistantBody  = null;
 
 	function ensureThinkingBlock() {
 		if (currentThinkingBody) return currentThinkingBody;
@@ -1095,7 +1099,11 @@
 		body.className = "message-thinking-content";
 		details.appendChild(summary);
 		details.appendChild(body);
-		historyEl.appendChild(details);
+		if (activeAssistantBody && activeAssistantBody.parentNode) {
+			activeAssistantBody.parentNode.insertBefore(details, activeAssistantBody);
+		} else {
+			historyEl.appendChild(details);
+		}
 		historyEl.scrollTop = historyEl.scrollHeight;
 		currentThinkingBlock = details;
 		currentThinkingBody  = body;
@@ -1187,6 +1195,7 @@
 		currentAbort = new AbortController();
 
 		var assistantBody = appendTurn("assistant", "");
+		activeAssistantBody = assistantBody;
 		markWorking(assistantBody.roleLabel);
 		var assistantMarkdown = "";  // accumulate raw markdown, re-render on each delta
 
@@ -1296,6 +1305,7 @@
 			// no spinner: it says "still working" about a turn that ended.
 			markDone(assistantBody.roleLabel);
 			collapseThinkingBlock();
+			activeAssistantBody = null;
 			currentAbort = null;
 		}
 	});

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

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