labimotion 2.4.0.rc8 → 2.4.0.rc10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb80f2785578e7024da49b80d642b5d79360b576be7cd3035588d158e433ce9a
-  data.tar.gz: d34d16a3ea0499082e3573e8486acfc0039729ede44defaf191079ca8bcb53ff
+  metadata.gz: 6355c96e00c582cf1b874e6e4300bbb26a150f276e3afcde63e364e50a7b4f31
+  data.tar.gz: 69b3c2d5fa16f295ee2dbdf4b240b0948e1e1f05a3a3edb8c4c4881fecda1137
 SHA512:
-  metadata.gz: fbd4bc4b60468e2ffabfd9da96d9425e3aa718a305747c794f35bd63d27ae3e0d630ee90d68b37a5ad353e307b692c41364ff905947b9b623f9d75a5d9dcedc9
-  data.tar.gz: 5062fc57240fb3319a7a2a272fccd20eee6d379910c7b14c7ff9a0ca975d1920f0dc019a812873fa173796d8ad3e26bced01610f48d296b7e6d3d2d8787dff8a
+  metadata.gz: a916242cee0543be6fa0fa04333eaa9dfede1d486f311e0229b97f13120e18b80e58bdbfac234b0429a09e2ba915bafe461be229a52cc64bde1ecd8fd403a597
+  data.tar.gz: f79f17d2d887a637566ba9bd81123cb1474c75dcb6519813b2dcb770888e1c49c7b55342899f2455423e2a46da3d6056d27229048b431b2fa9c78595c9acfd41

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 * Features and enhancements:
+  * The AI whitelist reading moves into the gem as `Labimotion::MatriceLabimotion`, a concern the host mixes into whichever model holds its UI feature configs (`Matrice` in the Chemotion ELN). Who is allowed stays the host's decision and the host's data — an admin edits `ai_uids` / `fill_uids` on the UI Features page — but what the answer means is LabIMotion's: which generic types have an AI integration (`AI_FEATURES`), that auto-fill is a sub-gate on `ai_uids` rather than a list of its own, and that every step is closed by default, so a missing feature row, a missing key, an empty list or a malformed value all resolve to nobody. Supplies `.ai_uids`, `.fill_uids`, `.ai_enabled_for?`, `.ai_features_for` and `.ai_enabled_for_any?`; the uid reader behind them stays private to the including model. A host needs two things for it to work: the including model answers `find_by(name:)` with a record exposing a `configs` hash, and its user answers `matrix_check_by_name(name)` with whether that feature is visible to them at all. This also settles where `Labimotion::LabimotionAiAPI`'s own `Matrice.ai_enabled_for_any?` gate comes from — the method is now defined by this gem rather than borrowed from whatever the host happened to implement. It also absorbs the auto-fill gate the host used to own as a `LabimotionAiAccess` service: `.fill_enabled_for?(user)` is `ai_uids` AND `fill_uids` on `FILL_FEATURE` (genericElement, the only feature carrying such a list — the designer's "New (AI)" buttons on the other two types are admin-only and need no second gate), so the gem's `ai_fill_data` route and the host's own `aiFill` flag answer through one method and cannot disagree about who may auto-fill. That drops the gem from two host constants to one: it no longer reaches for a `LabimotionAiAccess` a host had to implement, only for the model carrying this concern. Host ELN change is the `include`, the deletion of the moved methods and of that service; **the host will not boot without a gem carrying this concern**, since the model that includes it is loaded app-wide.
+  * Per-user settings now live in a gem-owned `user_settings` table instead of the host's profile jsonb, starting with the AI settings that were the only occupant. One row per `(user_id, key)`, each with its own `settings` jsonb and a unique index on the pair — `Labimotion::UserSetting`, keys enumerated in `Constants::UserSettingKey` (`ai` today, `my_layers` next). Split by row rather than one blob per user on purpose: the keys have nothing to do with each other and differ wildly in size, so a shared row would mean every save rewrites the lot and two features saving at once would clobber each other. `Labimotion::ProfileAiSettings` — the concern the host mixed into `Profile` — is **removed** and replaced by `Labimotion::UserAiSettings`, a wrapper over the `ai` row with the same field semantics it always had (nil leaves a field unchanged, a blank string clears it, the api_key is stored encrypted and only ever reported as set-or-not) and an injectable store so the shape can be exercised without a database. Encryption stays the host's `Encryptor`, unchanged, so stored ciphertext keeps decrypting. `Constants::UserSetting` is renamed `Constants::UserKlassSetting` — its members are the sub-keys of the per-klass table and the old name would now read as the new one's. Requires host ELN twin migrations `create_user_settings` and `move_labimotion_ai_settings_to_user_settings`; the latter copies each profile's `labimotion_ai` object verbatim (ciphertext included — re-encrypting would be the only way to get it wrong) and then deletes the profile key, unlike the `ui_preference` consolidation which left an inert value behind: this one would otherwise leave a second copy of a credential in a column several endpoints serialize. It is reversible, so rolling the gem back does not strand a key in a table nothing reads. Deploy order is migrate → **restart**.
+  * New template-sharing role `Maintainer` ([chem-generic-ui#1082](https://github.com/cllde8/chem-generic-ui/issues/1082)): everything an editor may do plus releasing **minor** versions — major releases, activation, deletion and share management stay owner-only. `KlassShare::LEVELS` gains `maintainer: 25` (additive, strictly between editor and owner, nobody renumbered — the one-owner partial index on level 30 is untouched, so no migration); `ShareResolver::REQUIRED_LEVEL` gains `release_minor: 25` while `release` keeps meaning the major at 30; `update_template` now asks `:write` for a draft, `:release_minor` for a minor and `:release` for a major — an unrecognised release value fails toward the stricter gate. List payloads gain `can_release_minor` under the same `share_context` guard as the other capability booleans, the grant and level-change routes accept level 25, and the `release_minor` refusal names maintainer access instead of claiming owner-only. Ships with the matching chem-generic-ui change (Minor button gated on the new capability; an absent field on an older gem falls back to `can_release`).
   * `Link Element` is now available as a column type inside `Table` fields of generic elements and segments ([chem-generic-ui#1055](https://github.com/LabIMotion/chem-generic-ui/issues/1055), labimotion#261). A `drag_element` cell stores the same payload the layer-level field stores (`el_id`, `el_klass`, `el_label`, `el_name`, `el_tip`, `icon_name`) and deliberately carries no `is_new`/`cr_opt`: a drop links a record that already exists and must never create one on save, unlike the sample column it sits next to. The stored label, name, tooltip and icon are refreshed on every read by the new `Labimotion::Serializer.set_table_element`, called from `PropertiesEntity` and `ElnElementEntity` as well, so all three property loaders agree rather than drifting into three copies. `SampleAssociation.build_table_element` writes the `Labimotion::ElementsElement` join rows and feeds the same `els` list that the stale-link cleanup compares against — feeding it is load-bearing, since the cleanup would otherwise `destroy_all` the rows it had just created. Both paths skip a cell whose `el_klass` is a `Labimotion::LinkedElement::MODELS` key: such a column accepts reactions, wellplates, screens and the rest as readily as generic elements, and for those `el_id` is not a `Labimotion::Element` id, so resolving it would relabel or link a wholly unrelated element — the same guard the layer-level field already applies. Carried through every export path: XLSX (`exporter_helpers`, expandable like the sample and molecule columns, short label as the cell text and `Name` as an optional sub-column), DOCX (`export_element`), and the ZIP round-trip (`export_utils` remaps element ids to uuids, `import_utils` re-links them through the new `proc_table_element`). A linked element has no structure image, so the cell shows the klass icon instead of an SVG.
   * Element cover images, write path ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): the element create and update saves now validate the `cover_images` key of the optional `metadata` param — an array of at most 3 `{ source: attachment|analysis, id: <integer> }` references, mirroring the chem-generic-ui picker's cap and vocabulary, normalized to exactly those two entry keys — and refuse a malformed selection with a plain 422 before any container/sample-association write runs. All cover-image helpers live in the dedicated `Labimotion::CoverImageHelpers` module, with the contract cap and source vocabulary as `Constants::CoverImage::MAX`/`SOURCES`. The rest of the metadata document keeps its existing contract: a present param replaces the stored hash wholesale, because its other writers (layer groups/restrictions from the details page, host regComps through the registry seam) remove a key by omitting it, while an absent param leaves stored metadata untouched — an old client that does not send `metadata` can never wipe a saved cover selection. References only, no FK: a deleted attachment/analysis leaves a dangling reference the UI skips at render time. No migration (`elements.metadata` and `elements_revisions.metadata` already exist), no entity change (`metadata` was already exposed), no klass change (the per-klass `cover_image` toggle rides the existing `update_settings` shallow merge); revision snapshots already carry `metadata` alongside `properties`, and restoring a revision round-trips the cover selection through this validated save.
   * Element cover images, original serving ([chem-generic-ui#1050](https://github.com/LabIMotion/chem-generic-ui/issues/1050), labimotion#259): new `GET /generic_elements/cover_image?element_id=&source=&id=` answers the original file behind a cover-image reference, so the element page's display area can show originals while thumbnails stay in the picker. Gated by the `genericElement` matrix check plus `ElementPolicy` `read?` **and** `read_dataset?` (analysis previews are dataset attachments, and the ELN's own attachment reads demand both); the reference resolves through the element's own associations only, so a foreign attachment or container id answers 404, never a file. An `analysis` reference resolves the container preview server-side for the first time, mirroring the client's `getContainerImageData`: the container's `preferred_thumbnail` while it still exists, else the newest "combined" image, else the newest thumbnail-bearing dataset attachment. The body is the original bytes under the file's own content type — or the PNG thumbnail when a browser could not render the original (TIFF, raw-data files behind an analysis preview). An optional `variant=thumbnail` always answers the PNG thumbnail through the same gate and resolution, which is what the picker's rows show — for an svg the stored thumbnail (black: ImageMagick reads `transparent` as black) is replaced by a fresh white-background rasterization of the original, through the same shared converter as the docx export — with it, the whole cover-image feature runs on gem-owned API surface and the host wires no fetcher at all. The picker's Save persists directly through the new `POST /generic_elements/cover_images` (`element_id`, `cover_images`; gated by `ElementPolicy` `update?` + the matrix check): the same validation as the element-save path, then a **targeted merge** of exactly the `cover_images` key into the stored metadata — deliberately narrower than the element save's wholesale-replace contract, so this writer can neither wipe nor resurrect `groups`/host keys. Live like klass settings: the write is immediate and unversioned until the next element save snapshots metadata into the revisions. The docx export (`ExportElement`) now renders the cover selection too: the stored references resolve through the same helpers as the `cover_image` endpoint, each image is embedded above the layers (originals for the rasters Word renders reliably — png/jpeg/gif/bmp; other renderable originals such as svg are rasterized onto white via MiniMagick, with the CSS keyword `transparent` normalized to `none` first because ImageMagick’s own SVG renderer reads it as black — the PNG thumbnail only as last resort), captioned "ref: …" and scaled to the page via MiniMagick-read dimensions (best effort — without them the template placeholder geometry is kept), Requires the matching `Labimotion_lines.docx` template change in the host ELN (a `has_cover`-guarded `cover_images:each` block before the layers loop); an old template simply ignores the new context keys.

data/lib/labimotion/apis/generic_dataset_api.rb

@@ -107,6 +107,43 @@ module Labimotion
         end
       end
 
+      namespace :plan_ai_klass do
+        # The cheap half of fine-tuning: an instruction plus an INDEX of the open
+        # template in, a short list of structural operations out, which the
+        # designer applies with the handlers it already has. Type-agnostic like
+        # :refine_ai_klass beside it — the path reads as dataset only because
+        # that is where this family of routes was first added.
+        #
+        # Gated on the same whitelist as the AI settings API
+        # (Labimotion::MatriceLabimotion, via the host's model): this endpoint
+        # spends the user's AI budget, so reaching it needs more than being
+        # logged in. NameError, not defined?, for the reason spelled out at
+        # generic_element_api's :ai_fill_data — under Zeitwerk `defined?` is nil
+        # until the constant is first referenced, and a host that ships no such
+        # model is a refusal too.
+        before do
+          allowed = begin
+            Matrice.ai_enabled_for_any?(current_user)
+          rescue NameError
+            false
+          end
+          unless allowed
+            error!({ status: 'error', message: 'AI template editing is not enabled for this account.' }, 403)
+          end
+        end
+
+        desc 'plan structural changes to a template with AI (returns operations for the designer to apply)'
+        params do
+          use :plan_ai_dataset_klass_params
+        end
+        post do
+          plan_ai_dataset_klass(params, current_user)
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { status: 'error', message: e.message }
+        end
+      end
+
       namespace :find_template do
         desc 'Find best matching template for given OLS term ID'
         params do

data/lib/labimotion/apis/generic_element_api.rb

@@ -233,19 +233,20 @@ module Labimotion
       # instance route and Element.find(nil) is raised.
       namespace :ai_fill_data do
         # Auto-fill is the one AI action ordinary users reach — the designer's
-        # create/refine routes are admin-only — so it carries its own whitelist,
-        # supplied by the host: the genericElement AI list narrowed by
-        # :fill_uids. Reached through the host the same way this API already
-        # reaches ElementPolicy, and CLOSED when the host provides no such
-        # policy, matching how every other gate in this feature defaults.
+        # create/refine routes are admin-only — so it carries its own whitelist:
+        # the genericElement AI list narrowed by :fill_uids. The rule is ours
+        # (Labimotion::MatriceLabimotion); the lists are the host's, on the
+        # model it mixes that concern into. Reached the same way this API already
+        # reaches ElementPolicy, and CLOSED when the host mounts no such model,
+        # matching how every other gate in this feature defaults.
         # NameError, not defined?: under Zeitwerk `defined?` is nil until the
         # constant has actually been referenced, so testing it would refuse the
         # first request after every boot. Referencing it triggers the autoload;
-        # a host that genuinely ships no such policy raises, and that is a
+        # a host that genuinely ships no such model raises, and that is a
         # refusal too.
         before do
           allowed = begin
-            LabimotionAiAccess.fill_enabled_for?(current_user)
+            Matrice.fill_enabled_for?(current_user)
           rescue NameError
             false
           end

data/lib/labimotion/apis/klass_share_api.rb

@@ -7,7 +7,7 @@ module Labimotion
   # Share management for generic templates (template-sharing.md §7). Its own API class, not
   # more namespaces in GenericKlassAPI, so the spec harness can load and mount it alone.
   #
-  # Grant and level-change accept viewer/editor only: the owner level never moves through
+  # Grant and level-change accept viewer/editor/maintainer only: the owner level never moves through
   # these routes. It moves through transfer_ownership, an update of the single owner row, so
   # the one-owner-per-klass invariant holds at every instant and the handover is auditable.
   #
@@ -292,7 +292,7 @@ module Labimotion
           { mc: 'se00', msg: e.message }
         end
 
-        desc 'grant viewer/editor access to users (upsert)'
+        desc 'grant viewer/editor/maintainer access to users (upsert)'
         params do
           requires :klass, type: String, desc: 'Klass', values: Labimotion::Constants::Klass::ALL
           requires :id, type: Integer, desc: 'Klass ID'
@@ -300,10 +300,11 @@ module Labimotion
           # rubocop:disable Style/RedundantArrayConstructor
           requires :user_ids, type: Array[Integer], desc: 'users to share with (Persons only)'
           # rubocop:enable Style/RedundantArrayConstructor
-          # Literal 10/20 (viewer/editor), not KlassShare::LEVELS: params blocks run while
-          # the routes are built, and referencing the ActiveRecord model there would force it
-          # to load in any process that only mounts the API. Owner (30) is absent on purpose.
-          requires :permission_level, type: Integer, desc: 'viewer or editor', values: [10, 20]
+          # Literal 10/20/25 (viewer/editor/maintainer), not KlassShare::LEVELS: params blocks
+          # run while the routes are built, and referencing the ActiveRecord model there would
+          # force it to load in any process that only mounts the API. Owner (30) is absent on
+          # purpose.
+          requires :permission_level, type: Integer, desc: 'viewer, editor or maintainer', values: [10, 20, 25]
         end
         post do
           klz = fetch_klass(params[:klass], params[:id])
@@ -331,7 +332,7 @@ module Labimotion
           # grant into an se00 (labimotion#255 — moved in from the host).
           Labimotion::ShareNotifier.grant(
             klass: klz, actor: current_user, user_ids: params[:user_ids].uniq,
-            level: params[:permission_level] == 20 ? 'editor' : 'viewer'
+            level: { 10 => 'viewer', 20 => 'editor', 25 => 'maintainer' }.fetch(params[:permission_level])
           )
           { mc: 'ss00' }.merge(represent_shares(klz))
         rescue StandardError => e
@@ -339,13 +340,14 @@ module Labimotion
           { mc: 'se00', msg: e.message }
         end
 
-        desc 'change the level of one share (viewer/editor only)'
+        desc 'change the level of one share (viewer/editor/maintainer only)'
         params do
           requires :share_id, type: Integer, desc: 'Share ID'
-          # Literal 10/20 (viewer/editor), not KlassShare::LEVELS: params blocks run while
-          # the routes are built, and referencing the ActiveRecord model there would force it
-          # to load in any process that only mounts the API. Owner (30) is absent on purpose.
-          requires :permission_level, type: Integer, desc: 'viewer or editor', values: [10, 20]
+          # Literal 10/20/25 (viewer/editor/maintainer), not KlassShare::LEVELS: params blocks
+          # run while the routes are built, and referencing the ActiveRecord model there would
+          # force it to load in any process that only mounts the API. Owner (30) is absent on
+          # purpose.
+          requires :permission_level, type: Integer, desc: 'viewer, editor or maintainer', values: [10, 20, 25]
         end
         put ':share_id' do
           row = find_share!(params[:share_id])

data/lib/labimotion/apis/labimotion_ai_api.rb

@@ -6,10 +6,9 @@ module Labimotion
   # Per-user LabIMotion AI settings: the model, an optional personal API key and
   # an optional provider endpoint of one's own.
   #
-  # These live on the HOST's user profile rather than in a gem table, because the
-  # credential belongs to the person, not to LabIMotion — so the routes stay
-  # under /profiles and reach the host's Profile through current_user, the same
-  # way the rest of this gem reaches ElementPolicy and Matrice.
+  # They live in our own user_settings table under the 'ai' key
+  # (Labimotion::UserAiSettings). The routes stay under /profiles, where clients
+  # already reach them, but nothing is stored on the host's profile any more.
   #
   # The API key is stored encrypted and never returned; a read only reports
   # whether one is set.
@@ -18,6 +17,7 @@ module Labimotion
     # :models) lists none. A representative subset of the chat-capable KI-Toolbox
     # models (ki-toolbox.scc.kit.edu); the full list lives in the yml.
     DEFAULT_MODELS = %w[
+      kit.mistral-small-4-119b-a8b
       azure.gpt-4.1-mini
       azure.gpt-4.1
       azure.gpt-5
@@ -81,10 +81,16 @@ module Labimotion
           # with the user's saved model so their current selection is always valid.
           def labimotion_ai_models
             models = labimotion_ai_server_models
-            append_ai_model(models, current_user.profile.labimotion_ai_model.to_s)
+            append_ai_model(models, ai_settings.model.to_s)
             models
           end
 
+          # This user's stored AI settings. Memoized per request: several of the
+          # routes below read it more than once.
+          def ai_settings
+            @ai_settings ||= Labimotion::UserAiSettings.for(current_user)
+          end
+
           # Model ids the SHARED server key permits — the server models plus the
           # ENV default. Unlike available_models this excludes the user's own saved
           # model, so it is safe to enforce a keyless user's selection against.
@@ -122,13 +128,13 @@ module Labimotion
 
         desc 'get the current user LabIMotion AI settings (never returns the key)'
         get do
-          profile = current_user.profile
+          settings = ai_settings
           configured = Rails.configuration.respond_to?(:labimotion_ai) ? Rails.configuration.labimotion_ai : nil
           {
-            model: profile.labimotion_ai_model,
-            api_key_set: profile.labimotion_ai_api_key?,
-            base_url: profile.labimotion_ai_base_url,
-            api_path: profile.labimotion_ai_api_path,
+            model: settings.model,
+            api_key_set: settings.api_key?,
+            base_url: settings.base_url,
+            api_path: settings.api_path,
             available_models: labimotion_ai_models,
             default_model: (configured && configured[:model]).presence,
             default_base_url: (configured && configured[:base_url]).presence,
@@ -146,7 +152,7 @@ module Labimotion
           optional :clear_endpoint, type: Boolean, default: false, desc: 'Remove the stored provider endpoint'
         end
         put do
-          profile = current_user.profile
+          settings = ai_settings
           api_key_arg =
             if params[:clear_api_key]
               '' # blank -> clear
@@ -162,7 +168,7 @@ module Labimotion
             elsif params[:api_key].present?
               true
             else
-              profile.labimotion_ai_api_key?
+              settings.api_key?
             end
           # A keyless user's AI calls run on the shared server key, so the chosen
           # model must be one the admin approved. A user on their own key may pick
@@ -184,7 +190,7 @@ module Labimotion
           api_path_arg = params[:clear_endpoint] ? '' : params[:api_path]
           validate_ai_endpoint!(base_url_arg, will_have_key)
 
-          summary = profile.update_labimotion_ai(
+          summary = settings.update(
             model: params[:model].presence, api_key: api_key_arg,
             base_url: base_url_arg, api_path: api_path_arg
           )
@@ -201,14 +207,14 @@ module Labimotion
 
         desc 'fetch the live model list from the AI provider with the user personal key'
         post 'models' do
-          profile = current_user.profile
+          settings = ai_settings
           # Deliberately the PERSONAL key only: the shared server key must not be
           # sent to a user-supplied provider URL, and a keyless user's model choice
           # is restricted to labimotion_ai_admin_model_ids anyway.
           result = Labimotion::AiModels.new(
-            api_key: profile.labimotion_ai_api_key,
-            base_url: profile.labimotion_ai_base_url,
-            api_path: profile.labimotion_ai_api_path
+            api_key: settings.api_key,
+            base_url: settings.base_url,
+            api_path: settings.api_path
           ).call
           { status: true, models: result[:models], endpoint: result[:endpoint] }
         rescue StandardError => e
@@ -217,15 +223,15 @@ module Labimotion
 
         desc 'test the current user LabIMotion AI connection (nothing is saved)'
         post 'test' do
-          profile = current_user.profile
+          settings = ai_settings
           # Same values the runtime override path reads, so the test exercises the
           # real config: base_url/api_path are honored by the gem only alongside a
           # personal key, and a custom endpoint is SSRF-validated there.
           result = Labimotion::AiTemplate.ping(
-            model: profile.labimotion_ai_model,
-            api_key: profile.labimotion_ai_api_key,
-            base_url: profile.labimotion_ai_base_url,
-            api_path: profile.labimotion_ai_api_path
+            model: settings.model,
+            api_key: settings.api_key,
+            base_url: settings.base_url,
+            api_path: settings.api_path
           )
           { status: true, ok: true, model: result['model'],
             endpoint: result['endpoint'], ms: result['ms'] }

data/lib/labimotion/apis/user_klass_settings_api.rb

@@ -20,12 +20,12 @@ module Labimotion
       # as "leave alone"; an empty linked_el_attrs array reads as "clear".
       def submitted_settings(settings)
         settings = (settings || {}).transform_keys(&:to_s)
-        toolbar = settings[Labimotion::Constants::UserSetting::TOOLBAR]
-        attrs = settings[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS]
+        toolbar = settings[Labimotion::Constants::UserKlassSetting::TOOLBAR]
+        attrs = settings[Labimotion::Constants::UserKlassSetting::LINKED_EL_ATTRS]
         {}.tap do |result|
-          result[Labimotion::Constants::UserSetting::TOOLBAR] = toolbar if toolbar.is_a?(Hash)
+          result[Labimotion::Constants::UserKlassSetting::TOOLBAR] = toolbar if toolbar.is_a?(Hash)
           if attrs.is_a?(Array)
-            result[Labimotion::Constants::UserSetting::LINKED_EL_ATTRS] = normalize_linked_el_attrs(attrs)
+            result[Labimotion::Constants::UserKlassSetting::LINKED_EL_ATTRS] = normalize_linked_el_attrs(attrs)
           end
         end
       end

data/lib/labimotion/constants.rb

@@ -46,11 +46,28 @@ module Labimotion
 
     # The independent sub-settings held side by side in
     # user_klass_settings.settings. A save writes only the ones it carries.
-    module UserSetting
+    #
+    # Named for the table: these are the sub-keys of a per-user, per-KLASS row.
+    # The per-user, klass-independent settings are a different table with its own
+    # key list — see UserSettingKey below.
+    module UserKlassSetting
       TOOLBAR = 'toolbar'
       LINKED_EL_ATTRS = 'linked_el_attrs'
     end
 
+    # The `key` column of user_settings: one row per user per key, each owning an
+    # independent `settings` jsonb. A feature claims a key here and nothing else
+    # in the table can disturb it, which is the point of splitting by row rather
+    # than sharing one blob — a large layer library and a stored credential have
+    # no reason to be rewritten by each other's saves.
+    module UserSettingKey
+      # Per-user AI settings: model, personal API key (encrypted), provider
+      # endpoint. Read and written through Labimotion::UserAiSettings.
+      AI = 'ai'
+      # A user's own layers — visible to them alone, not published to a template.
+      MY_LAYERS = 'my_layers'
+    end
+
     # The independent sub-settings held side by side in a KLASS's own `settings`
     # jsonb (element_klasses / segment_klasses / dataset_klasses). A save
     # shallow-merges, so writing one never disturbs the others.

data/lib/labimotion/entities/generic_klass_entity.rb

@@ -26,7 +26,7 @@ module Labimotion
     # in the class body would chain-autoload KlassShare (an ActiveRecord model) just to load
     # this entity, which the gem's Rails-less spec harness cannot do. The blocks only run when
     # a share context was preloaded, so inside them the constants are safe.
-    %i[write release deactivate destroy manage].each do |action|
+    %i[write release release_minor deactivate destroy manage].each do |action|
       expose "can_#{action}", if: :share_context do |object, options|
         context = options[:share_context]
         key = Labimotion::KlassShare.key_of(object)

data/lib/labimotion/helpers/dataset_helpers.rb

@@ -144,18 +144,67 @@ module Labimotion
         cols: params[:cols],
         **overrides
       )
-      {
-        status: 'success',
-        label: ai['label'].presence || params[:label],
-        layers: ai['layers'],
-        select_options: ai['select_options'],
-        summary: ai['summary']
-      }
+      refine_outcome(ai, params[:label])
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
       { status: 'error', message: e.message }
     end
 
+    # Turn an instruction into a list of STRUCTURAL operations the designer applies
+    # itself, from an INDEX of the open template rather than the template. A layout
+    # change then costs what the sentence costs, not what the template costs.
+    #
+    # Four outcomes, three of them normal:
+    #   'success'   — operations to apply
+    #   'design'    — not expressible as operations; the client re-asks on refine
+    #   'unrelated' — not a template change at all; the turn STOPS here
+    #   'error'     — the request failed
+    # 'design' is deliberately not an error: it is the routing answer for every
+    # instruction that needs new fields, wording, units or ontology terms.
+    # 'unrelated' exists so an off-topic message does not fall through to refine,
+    # where the whole template would be re-emitted to report that nothing changed.
+    def plan_ai_dataset_klass(params, current_user)
+      instruction = params[:instruction].to_s.strip
+      raise 'An instruction is required' if instruction.blank?
+
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.plan(
+        index: params[:index] || {},
+        instruction: instruction,
+        ols_term_id: ai_term_with_label(params[:ols_term_id]),
+        history: params[:history],
+        **overrides
+      )
+      plan_outcome(ai)
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      { status: 'error', message: e.message }
+    end
+
+    def refine_outcome(refined, fallback_label)
+      {
+        status: 'success',
+        label: refined['label'].presence || fallback_label,
+        layers: refined['layers'],
+        select_options: refined['select_options'],
+        summary: refined['summary'],
+        usage: refined['usage'],
+        model: refined['model']
+      }
+    end
+
+    # Which of the three normal outcomes this plan is. `model` rides on all of
+    # them: it is what actually answered, which is not always what the user
+    # picked — a keyless user's choice is clamped to the server allowlist.
+    def plan_outcome(plan)
+      base = { reason: plan['reason'], usage: plan['usage'], model: plan['model'] }
+      return base.merge(status: 'unrelated') if plan['unrelated']
+      return base.merge(status: 'design') if plan['needs_design']
+
+      { status: 'success', operations: plan['operations'], summary: plan['summary'],
+        usage: plan['usage'], model: plan['model'] }
+    end
+
     def find_best_match_template(ols_term_id)
       result = Labimotion::TemplateMatcher.find_best_match(ols_term_id)
       if result[:template]

data/lib/labimotion/helpers/element_helpers.rb

@@ -141,7 +141,7 @@ module Labimotion
         instructions: ai_fill_instructions(element),
         **overrides
       )
-      { status: 'success', values: ai['values'], summary: ai['summary'] }
+      { status: 'success', values: ai['values'], summary: ai['summary'], usage: ai['usage'], model: ai['model'] }
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
       { status: 'error', message: e.message }

data/lib/labimotion/helpers/generic_helpers.rb

@@ -31,8 +31,11 @@ module Labimotion
     # the helpers. ShareResolver stays the enforcement authority.
     ACTION_PHRASE = {
       read: 'view', write: 'edit', release: 'release',
+      release_minor: 'release a minor version of',
       deactivate: 'activate or deactivate', destroy: 'delete', manage: 'manage sharing for'
     }.freeze
+    # `release_minor` is deliberately NOT here: a maintainer holds it too, so its refusal
+    # must not claim "only the owner can" — it gets its own maintainer wording below.
     OWNER_ONLY_ACTIONS = %i[release deactivate destroy manage].freeze
 
     # What makes a klass unique among the *active* rows. These are model validations only —
@@ -92,6 +95,8 @@ module Labimotion
     def authorization_refusal_msg(name, action)
       requirement = if OWNER_ONLY_ACTIONS.include?(action)
                       "Only the owner can #{ACTION_PHRASE[action]} this template."
+                    elsif action == :release_minor
+                      "You need maintainer access to #{ACTION_PHRASE[action]} this template."
                     elsif action == :read
                       "You need shared access to #{ACTION_PHRASE[action]} this template."
                     else
@@ -109,20 +114,18 @@ module Labimotion
       raise e
     end
 
-    # Per-user AI overrides (model + API key) resolved from the host app's user
-    # profile. Returns {} when the host doesn't expose them, so AiTemplate falls
-    # back to the server-wide yml/ENV configuration. Guarded with respond_to? to
-    # keep the gem decoupled from the host's Profile implementation. Shared by the
-    # dataset / element / segment AI helpers.
+    # Per-user AI overrides (model + API key) from the user's own settings row.
+    # Returns {} when nothing is stored, so AiTemplate falls back to the
+    # server-wide yml/ENV configuration. Shared by the dataset / element /
+    # segment AI helpers.
     def ai_user_overrides(current_user)
-      profile = current_user.respond_to?(:profile) ? current_user.profile : nil
-      return {} if profile.nil?
+      return {} if current_user.nil?
 
-      model   = (profile.labimotion_ai_model if profile.respond_to?(:labimotion_ai_model))
-      api_key = (profile.labimotion_ai_api_key if profile.respond_to?(:labimotion_ai_api_key))
-      model   = ai_shared_key_model(model) if api_key.blank?
+      settings = Labimotion::UserAiSettings.for(current_user)
+      api_key = settings.api_key
+      model   = api_key.blank? ? ai_shared_key_model(settings.model) : settings.model
 
-      { model: model, api_key: api_key }.merge(ai_provider_overrides(profile, api_key)).compact
+      { model: model, api_key: api_key }.merge(ai_provider_overrides(settings, api_key)).compact
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
       {}
@@ -131,13 +134,10 @@ module Labimotion
     # Personal provider endpoint (base_url/api_path) — honored only ALONGSIDE a
     # personal key, so the shared server key is never sent to a user-supplied URL.
     # The base_url itself is SSRF-validated later, in AiTemplate.
-    def ai_provider_overrides(profile, api_key)
+    def ai_provider_overrides(settings, api_key)
       return {} if api_key.blank?
 
-      {
-        base_url: (profile.labimotion_ai_base_url if profile.respond_to?(:labimotion_ai_base_url)),
-        api_path: (profile.labimotion_ai_api_path if profile.respond_to?(:labimotion_ai_api_path))
-      }
+      { base_url: settings.base_url, api_path: settings.api_path }
     end
 
     # On the SHARED server key (user has no personal key), keep the user's model
@@ -205,10 +205,18 @@ module Labimotion
 
     def update_template(params, current_user)
       klz = fetch_klass(params[:klass], params[:id])
-      # The split that makes `editor` mean "drafting only": a draft save needs :write, while
-      # anything else bumps the version and cuts a revision — publishing, which is :release.
+      # The split that makes `editor` mean "drafting only" and `maintainer` mean "drafting
+      # plus minor releases": a draft save needs :write; a minor release bumps the version
+      # and cuts a revision, which a maintainer may do (:release_minor); a major release —
+      # and any release value nobody recognises — stays owner-only (:release), so an unknown
+      # value fails toward the stricter gate.
       # Authorization before the stale check: who may act comes before whether the copy is fresh.
-      authorize_klass!(klz, params[:release] == 'draft' ? :write : :release)
+      release_action = case params[:release]
+                       when 'draft' then :write
+                       when 'minor' then :release_minor
+                       else :release
+                       end
+      authorize_klass!(klz, release_action)
       guard_stale_template!(klz, params[:properties_template])
       uuid = SecureRandom.uuid
       properties = params[:properties_template]

data/lib/labimotion/helpers/param_helpers.rb

@@ -104,6 +104,19 @@ module Labimotion
       end
     end
 
+    params :plan_ai_dataset_klass_params do
+      requires :instruction, type: String, desc: 'Natural-language change to apply to the template'
+      optional :ols_term_id, type: String, desc: 'CHMO ontology term (context only)'
+      # The INDEX, not the template: layer/field keys, labels and types only. Left
+      # as an opaque Hash because the gem only relays it — the client builds it and
+      # the client consumes the plan that comes back.
+      optional :index, type: Hash, desc: 'Compact index of the open template (keys, labels, types, groups)'
+      optional :history, type: Array, desc: 'Prior chat turns for continuity' do
+        optional :role, type: String, desc: 'user | assistant'
+        optional :content, type: String, desc: 'Message content'
+      end
+    end
+
     params :update_element_klass_params do
       requires :id, type: Integer, desc: 'Element Klass ID'
       optional :label, type: String, desc: 'Element Klass Label'