@mercury-fw/kit 0.71.0 → 0.73.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @mercury-fw/kit
 
+## 0.73.0
+
+### Minor Changes
+
+- a8e2fe9: - the work nobody waits on (titles, memory captures, corrections, the archive's index, the nightly review) waits for the model: it runs only in the requests the turns leave free of the model's `capacity`, one model call at a time, titles, corrections and the archive's index first
+  - `ollamaModel(name, { backgroundSlots })`: how many of the model's requests that work may take at once; 1 when left out, below `capacity` when it's above 1
+  - a turn's corrections, its threshold capture and its message's indexing no longer hold the conversation's next turn
+  - a model of a plugin's own (`ctx.modelFor`) goes through the same queue
+  - `background.job` in the traces: each piece of that work that called a model, its models, model calls, time waited, time taken, and whether it was done, failed or dropped at stop
+  - `mfw create`: `backgroundSlots` read from `OLLAMA_BACKGROUND_SLOTS`, in the env example
+  - **Migration:** to set it from the environment, add `backgroundSlots: envNumber("OLLAMA_BACKGROUND_SLOTS"),` to the turn model's `ollamaModel(...)` in `mercury.config.ts`
+- 40fde6b: - `ollamaModel(name, settings?)` and `ollamaEmbedding(name, { capacity }?)` declare a model; `capacity`, how many requests its server answers at once, 1 when left out
+  - `models` in `mercury.config.ts`: `turn` (required), `background` (titles, memory captures, corrections, nightly review; the turn's when left out), `embedding`
+  - a `vectorIndex` without `models.embedding` stops the start
+  - `ctx.modelFor(handle)` in a plugin's `build()`: the model of a handle the plugin was given in its configuration
+  - `system.start` carries `models` (each role's name and capacity) instead of `model` and `modelSettings`
+  - the startup log names each role's model
+  - `mfw create`: the config declares `main` from `OLLAMA_MODEL` and its settings, and `models` with `turn` and `embedding`; `OLLAMA_CAPACITY` in the env example
+  - **Breaking:** `model` is gone from `mercury.config.ts`, and the core no longer reads `OLLAMA_MODEL` or `OLLAMA_EMBEDDING_MODEL`: declare the models in `models`
+  - **Migration:** in `mercury.config.ts`, import `ollamaEmbedding` and `ollamaModel` from `@mercury-fw/core`, add above the config `const main = ollamaModel(process.env.OLLAMA_MODEL, { think: envBoolean("OLLAMA_THINK", true), temperature: envNumber("OLLAMA_TEMPERATURE"), topP: envNumber("OLLAMA_TOP_P"), topK: envNumber("OLLAMA_TOP_K"), capacity: envNumber("OLLAMA_CAPACITY") });`, and replace the `model: { ... }` section with `models: { turn: main, embedding: ollamaEmbedding(process.env.OLLAMA_EMBEDDING_MODEL ?? "nomic-embed-text") },`; `OLLAMA_CAPACITY` is optional
+
+### Patch Changes
+
+- fb1f30a: - conversation-store contract: `ConversationStorePlugin`, `ConversationStore`, `StoredMessage`, `StoredTitle`, `CONVERSATION_STORE_API_VERSION`
+  - `conversationStore` in `mercury.config.ts`: where every conversation's messages and title are kept
+  - **Breaking:** without `conversationStore` nothing is archived: no reopened or listed conversations, no titles, no `recall_verbatim`
+  - `qdrantConversations()` in `@mercury-fw/store-qdrant`: messages in `conversation_messages` (`QDRANT_MESSAGES_COLLECTION`), titles in `conversation_titles` (`QDRANT_TITLES_COLLECTION`); on start, copies the messages of `verbatim_archive` into `conversation_messages` once, marking the copy done only when all are in
+  - `@mercury-fw/core` no longer depends on `@qdrant/js-client-rest` and no longer reads `QDRANT_URL`
+  - **Breaking:** `GET /health` (HTTP): `conversationStoreReachable` and `vectorIndexReachable` (`null` when not declared) instead of `qdrantReachable`
+  - **Breaking:** channel contract 7: `ChannelHostReads.conversation`, `conversations` and `memoryScroll` optional, given only with a conversation store / a vector index; channels written for contract 6 are refused
+  - `channel-http`, `channel-google-chat`: channel contract 7, framework 0.73 or later
+  - `channel-http`: `/conversation`, `/conversations` (`GET`, `PATCH`) only with a conversation store, `/memory/scroll` only with a vector index; `404` otherwise
+  - `system.start` trace event: `conversationStore` (`declared`, `active`)
+  - `mfw create`: new apps declare `conversationStore: qdrantConversations()`
+  - **Migration:** in `mercury.config.ts`, import `qdrantConversations` from `@mercury-fw/store-qdrant` and add `conversationStore: qdrantConversations(),`; upgrade `@mercury-fw/channel-http` and `@mercury-fw/channel-google-chat` with the framework; a UI reading `qdrantReachable` from `/health` reads the two new fields
+- Updated dependencies [a8e2fe9]
+- Updated dependencies [fb1f30a]
+- Updated dependencies [4a00b0c]
+- Updated dependencies [40fde6b]
+- Updated dependencies [b634bd1]
+  - @mercury-fw/plugin-types@0.73.0
+  - @mercury-fw/channel-types@0.73.0
+
+## 0.72.0
+
+### Patch Changes
+
+- Updated dependencies [468cb12]
+  - @mercury-fw/channel-types@0.72.0
+  - @mercury-fw/plugin-types@0.72.0
+
 ## 0.71.0
 
 ### Patch Changes

package/README.md

@@ -29,9 +29,11 @@ Every plugin says what it lets the agent do in its `description`: one sentence,
 
 The assistant has the name the app gives it (`persona.name`), so a plugin never writes one into what the model reads. Its fragment, its skills and its tools' descriptions say `{{assistant}}`, which the core replaces with that name. A text the plugin builds while running gets the name as `assistantName` in its `build()` context (a channel gets it in its runtime context too). Where the one acting is the system around the model (a list it appends, an account it picks), the text says "the system" and no name at all.
 
+A plugin that calls a model of its own doesn't pick or build it: it takes a `MercuryModelHandle` in its own configuration, which the app declares with `ollamaModel(name, settings)` from `@mercury-fw/core` (`myPlugin({ model: ollamaModel("<its-model>") })`), and in `build()` turns it into the model with `ctx.modelFor(handle)`, the same model for the same handle, queued like the app's own (a call during a turn never waits, and counts against the background work on that model). `ctx.model` is the app's turn model, for a check on an answer. `modelFor` is absent with a core older than 0.73.
+
 What a plugin shows the person in its own words (a status line while its tool runs, a choice's label, a heading it adds) is written once, in English, in the plugin's `messages`, every key under its name (`web-search.choice.once`); the core refuses a plugin with a key outside it, and `core` and `app` can't be plugin names (their keys are the core's and the app's). While a turn runs the plugin gets `t`, the texts of the person the turn is for, and asks for each text by its key: in `SessionToolContext.t`, as the second argument of a status describer, the third of a post-processor, and in a post-turn guard (`statusLabel(t)`, `run(text, steps, t)`). The app translates the keys in its language files. The core's own keys (`core.…`) are always there, `core.status.command` for a CLI command's default status line among them. This came with version 5 of the plugin contract; version 6 makes the `description` required. A plugin written for an older version isn't loaded, and the log says why.
 
-A channel's texts work the same way (channel contract version 6): its English in `messages`, under its name; `ctx.i18n.forRequest(principal, hint)` gives the texts for a request, in the person's language, else the `hint` (an `Accept-Language` value the channel passes on, also as `InboundTurn.languageHint`), else the app's default. `ctx.confirm` and `ctx.resolveConfirmation` hand back what to tell the person (`{ text, resume? }`), so a channel never words a confirmation itself, and `finalize(text, { pendingNote })` says when the text begins with the core's stand-in for an answer the model didn't write, which a channel showing its own confirmation UI drops.
+A channel's texts work the same way (channel contract version 7): its English in `messages`, under its name; `ctx.i18n.forRequest(principal, hint)` gives the texts for a request, in the person's language, else the `hint` (an `Accept-Language` value the channel passes on, also as `InboundTurn.languageHint`), else the app's default. `ctx.confirm` and `ctx.resolveConfirmation` hand back what to tell the person (`{ text, resume? }`), so a channel never words a confirmation itself, and `finalize(text, { pendingNote })` says when the text begins with the core's stand-in for an answer the model didn't write, which a channel showing its own confirmation UI drops.
 
 A proper workflow for writing plugins, with an SDK on top of these contracts, is planned ([#27](https://github.com/lucabro81/mercury-fw/issues/27)).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/kit",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -27,8 +27,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.71.0",
-    "@mercury-fw/plugin-types": "0.71.0"
+    "@mercury-fw/channel-types": "0.73.0",
+    "@mercury-fw/plugin-types": "0.73.0"
   },
   "devDependencies": {
     "@mercury-fw/typescript-config": "*",