labimotion 2.4.0.rc9 → 2.4.0.rc11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6b27ce7b185d248cf78a19fbeb00cf5c60edeed1e090d1fa73c2de8d4465579
-  data.tar.gz: dd64b3fd5e1fbb717135444ed666df30e2ae542e6e65fb2a3616b210ab9d5832
+  metadata.gz: cc8a97c07b6329e1a6be6097c923d710101dfe03494e98463ab2795cea02a590
+  data.tar.gz: 7d5535979919fe5709feed7a00860ba6ac24c6c69999e3b1e9f0c03819b3268e
 SHA512:
-  metadata.gz: 3cbf525c1197064ab1b25a11d77fd94249e064d6f705c1ae5e9306bc497e7080c5c2c3266fd8bec52c2ee502862e8b82f6324d3e3aca20d2a6565dbcaa67f811
-  data.tar.gz: 5c96c935475319618a2c9eb66d5cd102a0971b6f7628a7bd97bcaa5f5cd8686933c6c3cef110d24be30250f01493569ae966f3eb07ecde06ed3e04e710668b64
+  metadata.gz: 79b2acc5223830bb6c4444342173b80af2ad4611f095e07cfcc89861473cf5f2e2854b0ed67e098b8c9bd94fe9285178f06fb20c7ae84729d5938d567a490531
+  data.tar.gz: b657890bf6c80d13283ba1936678c2c364308e80ba0cf01b51f36d129012873c47b2a9393724d2154307ba1ee267708a00992a49038428c3abe8160ef607eeb2

data/lib/labimotion/apis/generic_dataset_api.rb

@@ -85,6 +85,21 @@ module Labimotion
           use :create_ai_dataset_klass_params
         end
         post do
+          # Settle the cheap objections BEFORE spending a provider call on this:
+          # a taken name is knowable now, and finding out after generation means
+          # 15-90s and a token spend for an answer a lookup could have given.
+          validation = Labimotion::AiKlassValidator.error_for(kind: 'dataset', params: params)
+          next { status: 'error', message: validation } if validation
+
+          # Generation is a long provider call, so it is handed to the host's worker
+          # and the request answers at once; the result arrives as a notification
+          # linking back into the designer. A host with no such worker gets the
+          # old inline behaviour rather than an error.
+          if Labimotion::AiKlassQueue.queue(kind: 'dataset', params: params, user: current_user)
+            next { status: 'queued',
+                   message: 'Generating the template in the background. You will be notified when it is ready.' }
+          end
+
           msg = create_ai_dataset_klass(params, current_user)
           klass = Labimotion::DatasetKlassEntity.represent(Labimotion::DatasetKlass.all)
           { status: msg[:status], message: msg[:message], klass: klass }
@@ -107,6 +122,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

@@ -219,6 +219,21 @@ module Labimotion
         end
         post do
           authenticate_admin!('elements')
+          # Settle the cheap objections BEFORE spending a provider call on this:
+          # a taken name is knowable now, and finding out after generation means
+          # 15-90s and a token spend for an answer a lookup could have given.
+          validation = Labimotion::AiKlassValidator.error_for(kind: 'element', params: params)
+          next { status: 'error', message: validation } if validation
+
+          # Generation is a long provider call, so it is handed to the host's worker
+          # and the request answers at once; the result arrives as a notification
+          # linking back into the designer. A host with no such worker gets the
+          # old inline behaviour rather than an error.
+          if Labimotion::AiKlassQueue.queue(kind: 'element', params: params, user: current_user)
+            next { status: 'queued',
+                   message: 'Generating the template in the background. You will be notified when it is ready.' }
+          end
+
           msg = create_ai_element_klass(params, current_user)
           { status: msg[:status], message: msg[:message],
             klass: Labimotion::ElementKlassEntity.represent(Labimotion::ElementKlass.where(is_active: true)) }

data/lib/labimotion/apis/labimotion_ai_api.rb

@@ -17,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[
+      models/DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf
       kit.mistral-small-4-119b-a8b
       azure.gpt-4.1-mini
       azure.gpt-4.1
@@ -99,18 +100,23 @@ module Labimotion
             (ids << ENV['KI_TOOLBOX_MODEL'].to_s).compact_blank.uniq
           end
 
-          # A well-formed https URL with a host. The deep SSRF check (host resolves
-          # to a public address) runs server-side in the gem at request time; this
-          # is only a fast format check for immediate UI feedback.
-          def https_endpoint?(url)
+          # A well-formed URL with a host, https only. In non-production envs
+          # (dev/test against local providers) http is also accepted. The deep
+          # SSRF check (host resolves to a public address) runs server-side in
+          # the gem at request time; this is only a fast format check for
+          # immediate UI feedback.
+          def valid_ai_endpoint?(url)
             uri = URI.parse(url.to_s.strip)
-            uri.is_a?(URI::HTTPS) && uri.host.present?
+            return false unless uri.host.present?
+
+            Rails.env.production? ? uri.is_a?(URI::HTTPS) : uri.is_a?(URI::HTTP)
           rescue URI::InvalidURIError
             false
           end
 
           # A personal provider endpoint is only usable with a personal key, and
-          # must be a valid https URL. Raises a 422 otherwise; no-op when unset.
+          # must be a valid https URL (http allowed outside production). Raises
+          # a 422 otherwise; no-op when unset.
           def validate_ai_endpoint!(base_url_arg, will_have_key)
             return if base_url_arg.blank?
 
@@ -120,9 +126,10 @@ module Labimotion
                 422
               )
             end
-            return if https_endpoint?(base_url_arg)
+            return if valid_ai_endpoint?(base_url_arg)
 
-            error!({ status: false, error: 'The AI provider endpoint must be a valid https:// URL.' }, 422)
+            scheme_msg = Rails.env.production? ? 'https://' : 'http:// or https://'
+            error!({ status: false, error: "The AI provider endpoint must be a valid #{scheme_msg} URL." }, 422)
           end
         end
 
@@ -136,7 +143,7 @@ module Labimotion
             base_url: settings.base_url,
             api_path: settings.api_path,
             available_models: labimotion_ai_models,
-            default_model: (configured && configured[:model]).presence,
+            default_model: (configured && configured[:model]).presence || DEFAULT_MODELS.first,
             default_base_url: (configured && configured[:base_url]).presence,
             server_api_key_set: (configured && configured[:api_key]).present?
           }

data/lib/labimotion/apis/segment_api.rb

@@ -69,6 +69,22 @@ module Labimotion
           @klass = fetch_klass('ElementKlass', params[:element_klass])
         end
         post do
+          # Settle the cheap objections BEFORE spending a provider call on this:
+          # a taken name is knowable now, and finding out after generation means
+          # 15-90s and a token spend for an answer a lookup could have given.
+          validation = Labimotion::AiKlassValidator.error_for(kind: 'segment', params: params, element_klass: @klass)
+          next { status: 'error', message: validation } if validation
+
+          # Generation is a long provider call, so it is handed to the host's worker
+          # and the request answers at once; the result arrives as a notification
+          # linking back into the designer. A host with no such worker gets the
+          # old inline behaviour rather than an error.
+          if Labimotion::AiKlassQueue.queue(kind: 'segment', params: params, user: current_user,
+                                            element_klass_id: @klass&.id)
+            next { status: 'queued',
+                   message: 'Generating the template in the background. You will be notified when it is ready.' }
+          end
+
           msg = create_ai_segment_klass(current_user, params)
           { status: msg[:status], message: msg[:message],
             klass: Labimotion::SegmentKlassEntity.represent(Labimotion::SegmentKlass.all) }

data/lib/labimotion/helpers/dataset_helpers.rb

@@ -113,9 +113,24 @@ module Labimotion
         'created_by' => current_user.id
       }
 
-      ds = Labimotion::DatasetKlass.create!(attributes)
+      # Same as the non-AI create beside it: the owner row shares the create's
+      # transaction, because a klass committed without one is owner-less and
+      # falls OPEN to the legacy designer-wide gate — every designer of the
+      # family could then edit, release and delete it, while its creator holds
+      # no special standing at all. seed_owner! rescues only RecordNotUnique and
+      # RecordInvalid, so any other failure has to take the klass down with it;
+      # this helper turns every StandardError into { status: 'error' }, and
+      # without the transaction the caller would be told the create failed while
+      # an unowned template silently persisted.
+      ds = Labimotion::DatasetKlass.transaction do
+        Labimotion::DatasetKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
       ds.create_klasses_revision(current_user)
-      { status: 'success',
+      # `record` is the row itself. The background job that calls this needs the
+      # template, not a sentence about it, to link the notification back to it.
+      { status: 'success', record: ds,
         message: "The AI dataset template [#{label}] has been created as inactive. Review and activate it in the designer." }
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
@@ -144,18 +159,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

@@ -106,13 +106,28 @@ module Labimotion
         'created_by' => current_user.id
       }
 
-      new_klass = Labimotion::ElementKlass.create!(attributes)
+      # Same as the non-AI create beside it: the owner row shares the create's
+      # transaction, because a klass committed without one is owner-less and
+      # falls OPEN to the legacy designer-wide gate — every designer of the
+      # family could then edit, release and delete it, while its creator holds
+      # no special standing at all. seed_owner! rescues only RecordNotUnique and
+      # RecordInvalid, so any other failure has to take the klass down with it;
+      # this helper turns every StandardError into { status: 'error' }, and
+      # without the transaction the caller would be told the create failed while
+      # an unowned template silently persisted.
+      new_klass = Labimotion::ElementKlass.transaction do
+        Labimotion::ElementKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
       new_klass.reload
       new_klass.create_klasses_revision(current_user)
       klass_names_file = Labimotion::KLASSES_JSON # Rails.root.join('app/packs/klasses.json')
       klasses = Labimotion::ElementKlass.where(is_active: true)&.pluck(:name) || []
       File.write(klass_names_file, klasses)
-      { status: 'success',
+      # `record` is the row itself. The background job that calls this needs the
+      # template, not a sentence about it, to link the notification back to it.
+      { status: 'success', record: new_klass,
         message: "The AI element template [#{label}] has been created as inactive. Review and activate it in the designer." }
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)
@@ -141,7 +156,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/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'

data/lib/labimotion/helpers/segment_helpers.rb

@@ -106,10 +106,25 @@ module Labimotion
       # params[:metadata] via declared. Absent -> leave the column default.
       attributes['metadata'] = params[:metadata] if params[:metadata].present?
 
-      klass = Labimotion::SegmentKlass.create!(attributes)
+      # Same as the non-AI create beside it: the owner row shares the create's
+      # transaction, because a klass committed without one is owner-less and
+      # falls OPEN to the legacy designer-wide gate — every designer of the
+      # family could then edit, release and delete it, while its creator holds
+      # no special standing at all. seed_owner! rescues only RecordNotUnique and
+      # RecordInvalid, so any other failure has to take the klass down with it;
+      # this helper turns every StandardError into { status: 'error' }, and
+      # without the transaction the caller would be told the create failed while
+      # an unowned template silently persisted.
+      klass = Labimotion::SegmentKlass.transaction do
+        Labimotion::SegmentKlass.create!(attributes).tap do |klz|
+          Labimotion::KlassShare.seed_owner!(klz, current_user.id)
+        end
+      end
       klass.reload
       klass.create_klasses_revision(current_user)
-      { status: 'success',
+      # `record` is the row itself. The background job that calls this needs the
+      # template, not a sentence about it, to link the notification back to it.
+      { status: 'success', record: klass,
         message: "The AI segment template [#{params[:label]}] has been created as inactive. Review and activate it in the designer." }
     rescue StandardError => e
       Labimotion.log_exception(e, current_user)

data/lib/labimotion/libs/ai_egress_guard.rb

@@ -26,10 +26,13 @@ module Labimotion
       '255.255.255.255/32', '::/128', '::1/128', 'fc00::/7', 'fe80::/10', 'ff00::/8'
     ].map { |cidr| IPAddr.new(cidr) }.freeze
 
-    # Raise BlockedError unless url is a public https endpoint. Returns url.
+    # Raise BlockedError unless url is a public https endpoint (http is also
+    # accepted outside production, e.g. against a local dev provider). Returns url.
     def self.validate!(url)
       uri = parse(url)
-      raise BlockedError, 'AI provider URL must use https' unless uri.scheme == 'https'
+      allowed_schemes = Rails.env.production? ? %w[https] : %w[https http]
+      raise BlockedError, "AI provider URL must use #{allowed_schemes.join(' or ')}" unless
+        allowed_schemes.include?(uri.scheme)
 
       host = uri.host.to_s
       raise BlockedError, 'AI provider URL has no host' if host.empty?
@@ -37,7 +40,7 @@ module Labimotion
       addresses = resolve(host)
       raise BlockedError, "AI provider host could not be resolved: #{host}" if addresses.empty?
 
-      blocked = addresses.find { |ip| !public_ip?(ip) }
+      blocked = addresses.find { |ip| !allowed_ip?(ip) }
       raise BlockedError, "AI provider host resolves to a non-public address (#{blocked})" if blocked
 
       url
@@ -80,5 +83,17 @@ module Labimotion
     rescue StandardError
       false
     end
+
+    # Outside production, a private-network address (e.g. a self-hosted model
+    # on another machine on the LAN) is allowed; loopback/link-local/other
+    # EXTRA_BLOCKED ranges (cloud metadata etc.) stay blocked regardless of env.
+    def self.allowed_ip?(ip)
+      return public_ip?(ip) if Rails.env.production?
+      return false if ip.loopback? || ip.link_local?
+
+      EXTRA_BLOCKED.none? { |net| net.include?(ip) }
+    rescue StandardError
+      false
+    end
   end
 end

data/lib/labimotion/libs/ai_klass_queue.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Labimotion
+  # Hands AI template generation to the host's background worker.
+  #
+  # Generating a template is one long provider call — 18s for a small segment,
+  # past 90s for a large one — and running it inside the request held the dialog
+  # open for all of it, losing the work if the tab was closed or reloaded. The
+  # endpoints enqueue instead and answer at once; the result comes back as a
+  # notification carrying a link into the designer.
+  #
+  # The job itself belongs to the host: ActiveJob, the queue and the Message
+  # machinery are all its, and a gem that shipped its own would be defining
+  # infrastructure it does not own. So the host class is reached by its bare
+  # name and only if it exists — the same NameError-guarded pattern used for
+  # Matrice and Message elsewhere in this gem. A host without it gets the old
+  # inline behaviour rather than an error, which is what `queue` returning false
+  # tells the caller.
+  module AiKlassQueue
+    JOB = 'AiTemplateJob'
+
+    # @return [Boolean] true when the work was handed off
+    def self.queue(kind:, params:, user:, element_klass_id: nil)
+      job = job_class
+      return false if job.nil?
+
+      # Grape params are a Hashie::Mash; the queue serialises what it is given,
+      # and a Mash carries method_missing behaviour a worker process should not
+      # be asked to rebuild. A plain hash is the whole contract.
+      args = [kind.to_s, plain(params), user.id, element_klass_id]
+      inline? ? run_now(job, args, user) : job.perform_later(*args)
+      true
+    rescue StandardError => e
+      # An enqueue that fails must not fail the request: the caller falls back
+      # to generating inline, which is slower but still correct.
+      Labimotion.log_exception(e, user)
+      false
+    end
+
+    # Queued in every environment, development included: one code path, and the
+    # request returns straight away wherever it runs. Development therefore
+    # needs a worker like anywhere else — without one the job sits in the table
+    # and the notification never arrives.
+    #
+    # LABIMOTION_AI_INLINE=true runs it in the request instead, for a machine
+    # with no worker to spare. Off unless asked for, because a create that
+    # blocks for the length of a provider call is not the behaviour anyone
+    # should get by accident.
+    def self.inline?
+      ENV['LABIMOTION_AI_INLINE'] == 'true'
+    rescue StandardError
+      false
+    end
+
+    # Deliberately swallows: the job reports its own failure as a notification,
+    # exactly as it would on a worker, and letting it raise here would send the
+    # caller down the inline-generation fallback — spending a second provider
+    # call on work that has already been done and paid for.
+    def self.run_now(job, args, user)
+      job.perform_now(*args)
+    rescue StandardError => e
+      Labimotion.log_exception(e, user)
+      nil
+    end
+
+    def self.job_class
+      Object.const_get(JOB)
+    rescue NameError
+      nil
+    end
+
+    # Only what the helpers read, and stringified: file payloads included, since
+    # the reference files are part of the request the worker has to replay.
+    #
+    # A JSON round trip rather than as_json, because that is precisely what the
+    # queue will do to these arguments anyway — so anything that would not
+    # survive being written to the jobs table fails here, in the request, rather
+    # than in a worker nobody is watching.
+    def self.plain(params)
+      return {} if params.nil?
+
+      source = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params
+      JSON.parse(JSON.generate(source))
+    end
+  end
+end

data/lib/labimotion/libs/ai_klass_validator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Labimotion
+  # The checks that must happen BEFORE a template is generated.
+  #
+  # Generation moved to a background job, and the cheap objections — this name
+  # is taken, this ontology term already has a template — used to live inside
+  # the create helpers, which now run inside that job. So the user spent a
+  # provider call and 15-90s of waiting only to be told the label was already in
+  # use, which was knowable before a single token was spent. Worse, the answer
+  # arrived as a notification long after the dialog that could have fixed it had
+  # closed.
+  #
+  # These are only the objections that can be settled by a lookup. Anything the
+  # model decides at create! stays there: this is a courtesy gate, not a second
+  # source of truth, and the create still validates for real.
+  module AiKlassValidator
+    # @return [String, nil] the objection, or nil when there is none
+    def self.error_for(kind:, params:, element_klass: nil)
+      files = file_error(params)
+      return files if files
+
+      case kind.to_s
+      when 'element' then element_error(params)
+      when 'segment' then segment_error(params, element_klass)
+      when 'dataset' then dataset_error(params)
+      end
+    end
+
+    def self.file_error(params)
+      count = Array(params[:files]).size
+      return nil if count <= Labimotion::AiTemplate::MAX_FILES
+
+      "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})."
+    end
+
+    # Mirrors ElementKlass's `validates :name, uniqueness:` — scoped to rows that
+    # are not soft-deleted, so a deleted template does not block the name it no
+    # longer holds.
+    def self.element_error(params)
+      name = params[:name].to_s.strip
+      return 'A name is required.' if name.blank?
+      return 'A label is required.' if params[:label].to_s.strip.blank?
+
+      return unless Labimotion::ElementKlass.where(deleted_at: nil).exists?(name: name)
+
+      "An element named [#{name}] already exists."
+    end
+
+    # Mirrors SegmentKlass's `validates :label, uniqueness: { scope: :element_klass_id }`.
+    # The label only has to be unique WITHIN its parent element, which is why the
+    # parent has to be known before this can be answered at all.
+    def self.segment_error(params, element_klass)
+      label = params[:label].to_s.strip
+      return 'A label is required.' if label.blank?
+      return 'A parent element is required.' if element_klass.nil?
+
+      taken = Labimotion::SegmentKlass.where(deleted_at: nil)
+                                      .exists?(label: label, element_klass_id: element_klass.id)
+      return unless taken
+
+      "A segment template labelled [#{label}] already exists for this element."
+    end
+
+    def self.dataset_error(params)
+      term = params[:ols_term_id].to_s.split('|').first.to_s.strip
+      return 'An ontology term (CHMO) is required.' if term.blank?
+
+      return unless Labimotion::DatasetKlass.where(deleted_at: nil).exists?(ols_term_id: term)
+
+      "A dataset template already exists for #{term}. Edit it in the designer instead."
+    end
+  end
+end

data/lib/labimotion/libs/ai_template.rb

@@ -72,6 +72,45 @@ module Labimotion
     # while still bounding a template that puts an essay on every field.
     MAX_FIELD_DESC_CHARS = 1000
 
+    # A structural plan is a handful of operations, never a template. Capping the
+    # reply this hard is the whole point of the path: it bounds the cheap route to
+    # a rounding error, and a model that starts echoing a template instead of
+    # planning hits the ceiling and is escalated rather than billed for 16k tokens.
+    PLAN_MAX_TOKENS = 1200
+
+    # The closed vocabulary of STRUCTURAL operations the designer already applies
+    # itself (chem-generic-ui: action-handler / group-handler / sorting-handler),
+    # each mapped to the builder that validates it. Anything outside this table is
+    # design work and goes back through refine. A table rather than a case: the
+    # vocabulary is data, and the client dispatches on exactly these strings.
+    PLAN_BUILDERS = {
+      'delete_layer' => :delete_layer_op,
+      'ungroup_layer' => :ungroup_layer_op,
+      'update_layer' => :update_layer_op,
+      'delete_field' => :delete_field_op,
+      'set_field' => :field_update_op,
+      'reorder_layers' => :reorder_layers_op,
+      'group_layers' => :group_layers_op
+    }.freeze
+
+    # Layer attributes update_layer may change.
+    PLAN_LAYER_ATTRS = %w[label cols color].freeze
+
+    # Field attributes set_field may change. Deliberately EXCLUDES "type": a type
+    # change cascades into units, numeric config, restrictions and display-name
+    # references, and the designer's own handler owns that logic — routing it
+    # through here would reimplement it worse.
+    PLAN_FIELD_ATTRS = %w[label description placeholder required readonly cols hasOwnRow].freeze
+
+    # Field attributes above that are flags, not text.
+    PLAN_FIELD_FLAGS = %w[required readonly hasOwnRow].freeze
+
+    # A plan longer than this is not a structural edit any more.
+    MAX_PLAN_OPERATIONS = 25
+
+    # How much of a provider's error message is shown to the user.
+    MAX_PROVIDER_ERROR_CHARS = 300
+
     # Generate a metadata template for a generic dataset, element or segment.
     #
     # The JSON template schema (layers / fields / select_options) is IDENTICAL
@@ -115,6 +154,33 @@ module Labimotion
         .refine(current: current, instruction: instruction)
     end
 
+    # Turn a natural-language instruction into a list of STRUCTURAL operations,
+    # without sending the template or asking the model to re-emit it.
+    #
+    # Refine's cost is set by the template, not the request: the model is told to
+    # reproduce every layer and field verbatim, so "delete the processing layer"
+    # bills the same thousands of output tokens as a redesign — and on a long
+    # template the model stops mid-copy, which surfaces as an unparseable
+    # response. Neither is inherent to the request. Deleting a layer, grouping
+    # two, reordering, flipping `required` are all things chem-generic-ui already
+    # does deterministically, cascades and workflow guard included; the model is
+    # only needed to read the sentence and name the layer.
+    #
+    # So this path sends an INDEX (keys, labels, types) and takes back a short op
+    # list the designer applies itself. When the instruction needs judgement the
+    # ops cannot express — new fields, wording, units, ontology terms — the model
+    # says so and the caller falls back to refine.
+    #
+    # @param index [Hash] compact template index (see chem-generic-ui buildTemplateIndex)
+    # @param instruction [String] the change to apply
+    # @param history [Array<Hash>] prior turns [{ 'role' => .., 'content' => .. }]
+    # @return [Hash] { 'operations' => Array, 'summary' => String,
+    #   'needs_design' => Boolean, 'reason' => String, 'usage' => Hash }
+    def self.plan(index:, instruction:, ols_term_id: nil, history: [], model: nil, api_key: nil, base_url: nil, api_path: nil)
+      new(ols_term_id: ols_term_id, history: history, model: model, api_key: api_key, base_url: base_url, api_path: api_path)
+        .plan(index: index, instruction: instruction)
+    end
+
     # Extract DATA VALUES for an existing generic element/segment/dataset instance
     # from a document's text, to pre-fill the working copy for human review. This
     # does NOT design or modify a template — it only reads values for the fields the
@@ -229,7 +295,7 @@ module Labimotion
       end
 
       response = post_messages
-      raise "AI request failed (HTTP #{response.code})" unless response.code == 200
+      request_failed!('generate', response) unless response.code == 200
 
       body = JSON.parse(response.body)
       guard_finish_reason!(body)
@@ -237,7 +303,7 @@ module Labimotion
       text = extract_text(body)
       raise 'AI returned an empty response' if text.blank?
 
-      normalize(parse_json(text))
+      normalize(parse_json(text)).merge('usage' => usage_from(body))
     rescue JSON::ParserError => e
       log_ai_response('generate could not parse response', response&.body)
       Labimotion.log_exception(e)
@@ -249,7 +315,7 @@ module Labimotion
       raise 'An instruction is required' if instruction.to_s.strip.blank?
 
       response = post_chat(refine_messages(current, instruction))
-      raise "AI request failed (HTTP #{response.code})" unless response.code == 200
+      request_failed!('refine', response) unless response.code == 200
 
       body = JSON.parse(response.body)
       guard_finish_reason!(body)
@@ -268,6 +334,8 @@ module Labimotion
       end
 
       result['summary'] = (data.is_a?(Hash) ? data['summary'].to_s.strip : '')
+      result['usage'] = usage_from(body)
+      result['model'] = model
       result
     rescue JSON::ParserError => e
       log_ai_response('refine could not parse response', response&.body)
@@ -275,6 +343,25 @@ module Labimotion
       raise 'AI returned a response that could not be parsed as a template'
     end
 
+    def plan(index:, instruction:)
+      raise 'AI API key is not configured (set config/labimotion_ai.yml :api_key or KI_TOOLBOX_API_KEY)' if api_key.blank?
+      raise 'An instruction is required' if instruction.to_s.strip.blank?
+
+      response = post_chat(plan_messages(index, instruction), PLAN_MAX_TOKENS)
+      request_failed!('plan', response) unless response.code == 200
+
+      body = JSON.parse(response.body)
+      raise 'AI request was declined by the content filter' if finish_reason(body) == 'content_filter'
+
+      plan_from(body)
+    rescue JSON::ParserError => e
+      log_ai_response('plan could not parse response', response&.body)
+      Labimotion.log_exception(e)
+      # An unparseable PLAN is not a failed request — it is a signal to take the
+      # slower path, which is exactly what escalation asks the caller to do.
+      escalate('The model did not return a usable plan.')
+    end
+
     def fill(properties:, context_text:, instructions: nil)
       raise 'AI API key is not configured (set config/labimotion_ai.yml :api_key or KI_TOOLBOX_API_KEY)' if api_key.blank?
       raise 'No readable text could be extracted from the selected source' if context_text.to_s.strip.blank?
@@ -288,7 +375,7 @@ module Labimotion
       raise 'This element template has no fields to fill' if schema.empty?
 
       response = post_chat(fill_messages(schema, context_text))
-      raise "AI request failed (HTTP #{response.code})" unless response.code == 200
+      request_failed!('fill', response) unless response.code == 200
 
       body = JSON.parse(response.body)
       guard_finish_reason!(body)
@@ -300,7 +387,9 @@ module Labimotion
       raw_values = data.is_a?(Hash) ? data['values'] : nil
       {
         'values' => normalize_fill_values(props, raw_values),
-        'summary' => (data.is_a?(Hash) ? data['summary'].to_s.strip : '')
+        'summary' => (data.is_a?(Hash) ? data['summary'].to_s.strip : ''),
+        'usage' => usage_from(body),
+        'model' => model
       }
     rescue JSON::ParserError => e
       log_ai_response('fill could not parse response', response&.body)
@@ -325,7 +414,7 @@ module Labimotion
     # content-filter block, or a response truncated at the token limit — the latter
     # would otherwise surface as a confusing parse/empty-template error.
     def guard_finish_reason!(body)
-      case Array(body['choices']).first&.dig('finish_reason')
+      case finish_reason(body)
       when 'content_filter'
         raise 'AI request was declined by the content filter'
       when 'length'
@@ -334,16 +423,59 @@ module Labimotion
       end
     end
 
+    def finish_reason(body)
+      Array(body['choices']).first&.dig('finish_reason').to_s
+    end
+
+    # A non-200 carries the provider's own reason, and that reason is the only
+    # thing separating a 400 for "no such model" from a 400 for "context length
+    # exceeded" or "max_tokens above this model's limit". Raising the bare status
+    # code — as this used to — leaves whoever hit it on another instance with
+    # nothing to go on but the number.
+    # The whole body still reaches log/labimotion.log; only what the user is
+    # shown is capped, because a misconfigured endpoint can answer with an entire
+    # HTML error page.
+    def request_failed!(context, response)
+      log_ai_response("#{context} failed (HTTP #{response.code})", response.body)
+      detail = provider_error(response).to_s.strip[0, MAX_PROVIDER_ERROR_CHARS]
+      message = "AI request failed (HTTP #{response.code})"
+      message += " — #{detail}" if detail.present?
+      raise message
+    end
+
+    # OpenAI-compatible gateways answer {"error": {"message": ..}}; this one
+    # (Open WebUI in front of vLLM) answers {"detail": ..}. Take either, and the
+    # raw body when it is neither.
+    def provider_error(response)
+      body = JSON.parse(response.body.to_s)
+      return '' unless body.is_a?(Hash)
+
+      err = body['error']
+      message = err.is_a?(Hash) ? err['message'] : err
+      message.presence || body['detail'].presence || body['message'].presence || ''
+    rescue JSON::ParserError
+      response.body.to_s.strip
+    end
+
     # Best-effort: record the raw model output (truncated) to log/labimotion.log so a
     # response that can't be turned into a template can be diagnosed. Never raises.
     def log_ai_response(context, raw)
       return if raw.to_s.strip.empty?
 
-      Labimotion.logger.warn("AiTemplate #{context}; raw (truncated): #{raw.to_s[0, 2000]}")
+      Labimotion.logger.warn("AiTemplate #{context}; raw (truncated): #{loggable(raw)}")
     rescue StandardError
       nil
     end
 
+    # An HTTParty body arrives as ASCII-8BIT, and a template full of °C and µm
+    # carries the high bytes to prove it. Interpolating that into a UTF-8 log
+    # line makes the write fail — silently, and precisely on the responses this
+    # exists to diagnose. Scrubbed to the encoding the log is actually in, and
+    # cut afterwards so the slice cannot split a character in half.
+    def loggable(raw)
+      raw.to_s.dup.force_encoding('UTF-8').scrub('')[0, 2000]
+    end
+
     # Map a non-200 status from the ping into a message that points at the setting
     # most likely at fault. Network/SSRF failures raise before this (from post_chat).
     def ping_error(code)
@@ -452,6 +584,24 @@ module Labimotion
             'model in your AI settings, or raise :timeout in config/labimotion_ai.yml.'
     end
 
+    # What the call cost, as the provider counted it. OpenAI-compatible responses
+    # carry it in `usage`; KI-Toolbox does, and it is the only per-request figure
+    # available — the gateway exposes no account-level usage API.
+    #
+    # nil when the provider reports nothing, rather than zeros: "not reported" and
+    # "cost nothing" are different answers and a caller should be able to tell
+    # them apart before showing a number to a user.
+    def usage_from(body)
+      usage = body['usage']
+      return nil unless usage.is_a?(Hash)
+
+      {
+        'prompt' => usage['prompt_tokens'],
+        'completion' => usage['completion_tokens'],
+        'total' => usage['total_tokens']
+      }.compact.presence
+    end
+
     # OpenAI-compatible chat completions return the text at
     # choices[0].message.content.
     def extract_text(body)
@@ -726,13 +876,7 @@ module Labimotion
     def refine_messages(current, instruction)
       messages = [{ role: 'system', content: refine_system_content(current) }]
       messages << { role: 'user', content: current_template_context(current) }
-      @history.each do |turn|
-        role = (turn['role'] || turn[:role]).to_s
-        content = (turn['content'] || turn[:content]).to_s
-        next if content.strip.blank?
-
-        messages << { role: (role == 'assistant' ? 'assistant' : 'user'), content: content }
-      end
+      messages.concat(history_messages)
       messages << { role: 'user', content: refine_instruction_prompt(instruction) }
       messages
     end
@@ -923,6 +1067,257 @@ module Labimotion
       PROMPT
     end
 
+    # --- structural plan ----------------------------------------------------
+
+    def plan_messages(index, instruction)
+      messages = [{ role: 'system', content: plan_system_content }]
+      messages << { role: 'user', content: plan_index_context(index) }
+      messages.concat(history_messages)
+      messages << { role: 'user', content: plan_instruction_prompt(instruction) }
+      messages
+    end
+
+    def plan_system_content
+      cfg[:plan_system_prompt].presence || default_plan_system_prompt
+    end
+
+    # Written against the operations chem-generic-ui can already apply. Every rule
+    # here is about NAMING an existing thing, never about describing one — which
+    # is why this prompt is a fraction of refine's and why its reply is bounded:
+    # there is nothing in the vocabulary whose length grows with the template.
+    def default_plan_system_prompt
+      <<~PROMPT
+        You turn a change request for a LabIMotion metadata template into a
+        STRUCTURAL PLAN: a short list of operations the designer applies itself.
+        You never write templates, layers or fields.
+
+        You are given an INDEX of the open template — its layers (key, label,
+        columns, group) and, per layer, its fields (key, label, type). It omits
+        descriptions, options, units and restrictions.
+
+        Reply with a SINGLE JSON object — no prose, no markdown, no code fences —
+        in one of exactly three shapes:
+
+        A  { "operations": [ ... ], "summary": "one sentence describing the change" }
+           The operations below can carry the request out.
+
+        B  { "needs_design": true, "reason": "<short reason>" }
+           It is about this template, but the operations cannot express it
+           (adding a field or layer, wording, types, units, options, ontology
+           terms, moving a field between layers, merging layers, renaming a
+           key), or you cannot tell which layer or field it means, or it is only
+           partly structural — a partial plan would silently drop the rest.
+
+        C  { "unrelated": true, "reason": "<one sentence, what this dialog is for>" }
+           The message asks for NO change to anything — a greeting, a question
+           about the world, arithmetic, chit-chat. Do not answer the message.
+
+        C is decided by what the message ASKS FOR, never by what you can do with
+        it. Any request to change the template — however vague, however badly it
+        names things, "tidy this up" included — is A or B, never C.
+
+            "delete the results layer"               -> A
+            "make the operator field required"       -> A
+            "put setup and acquisition in one group" -> A
+            "add a field for the serial number"      -> B
+            "tidy this up"                           -> B
+            "remove the physical description bit"    -> A if a layer matches, else B
+            "1+1=?"                                  -> C
+            "hello"                                  -> C
+            "what is the boiling point of water?"    -> C
+
+        Operations, and nothing else:
+        - {"op":"delete_layer","layer":"<layer_key>"}
+        - {"op":"update_layer","layer":"<layer_key>","label":"..","cols":1-6,"color":"default"}
+        - {"op":"delete_field","layer":"<layer_key>","field":"<field_key>"}
+        - {"op":"set_field","layer":"<layer_key>","field":"<field_key>","required":true,
+           "readonly":false,"label":"..","description":"..","placeholder":"..","cols":1-6,"hasOwnRow":true}
+        - {"op":"reorder_layers","order":["<layer_key>", ...]}
+        - {"op":"group_layers","label":"<group label>","layers":["<layer_key>", ...]}
+        - {"op":"ungroup_layer","layer":"<layer_key>"}
+
+        - Match what a request names against the index by label, ignoring case,
+          plurals and small wording differences; take the closest match. A name
+          that matches nothing is B, never C.
+        - Use the index's exact layer_key and field_key strings; never invent one.
+        - Send only the attributes the request asks you to change; never pad.
+        - set_field CHANGES a field already in the index and can never add one.
+          A request to ADD a field or layer is B, even when something similar
+          is already there.
+        - group_layers needs only its "label": free text you choose, no id.
+          Grouping existing layers is always A, never B.
+        - reorder_layers takes EVERY layer key, in the new order.
+      PROMPT
+    end
+
+    def plan_index_context(index)
+      index = {} unless index.is_a?(Hash)
+      "Template index (JSON):\n#{JSON.generate(index)}"
+    end
+
+    def plan_instruction_prompt(instruction)
+      <<~PROMPT.strip
+        Change request: #{instruction}
+
+        Answer with the structural plan for this request, with needs_design if it
+        cannot be expressed by the operations above, or with unrelated if it is
+        not a request to change this template.
+      PROMPT
+    end
+
+    # Prior turns, shared by refine and plan. Both need the same continuity and
+    # the same coercion of an untrusted role to one of the two the API accepts.
+    def history_messages
+      @history.filter_map do |turn|
+        content = (turn['content'] || turn[:content]).to_s
+        next if content.strip.blank?
+
+        role = (turn['role'] || turn[:role]).to_s
+        { role: (role == 'assistant' ? 'assistant' : 'user'), content: content }
+      end
+    end
+
+    def plan_from(body)
+      usage = usage_from(body)
+      # A plan that hits the ceiling is a model writing a template instead of
+      # planning. Escalate rather than raise — refine can still serve this one.
+      return escalate('The model returned a template instead of a plan.', usage) if finish_reason(body) == 'length'
+
+      text = extract_text(body)
+      return escalate('AI returned an empty response.', usage) if text.blank?
+
+      data = parse_json(text)
+      data = {} unless data.is_a?(Hash)
+      return unrelated(data['reason'].to_s.strip, usage) if truthy?(data['unrelated'])
+      return escalate(data['reason'].to_s.strip, usage) if truthy?(data['needs_design'])
+
+      operations = normalize_operations(data['operations'])
+      return escalate('The request did not map to any structural operation.', usage) if operations.empty?
+
+      plan_result(usage).merge('operations' => operations, 'summary' => data['summary'].to_s.strip)
+    end
+
+    # "Not structural" is a routing answer, not a failure: the caller re-asks on
+    # the refine path. usage still rides along — the attempt was billed.
+    def escalate(reason, usage = nil)
+      plan_result(usage).merge(
+        'needs_design' => true,
+        'reason' => reason.presence || 'This request needs template design.'
+      )
+    end
+
+    # Neither structural nor design: the message was not a change to this
+    # template at all. Escalating it would send the whole template to be re-emitted
+    # verbatim so the model can reply that there was nothing to do — thousands of
+    # output tokens for an answer the plan call already has. So this outcome stops
+    # the turn instead of falling through to refine.
+    def unrelated(reason, usage = nil)
+      plan_result(usage).merge(
+        'unrelated' => true,
+        'reason' => reason.presence || 'That is not a change to this template.'
+      )
+    end
+
+    # `model` is what actually served the request, not what the user picked: a
+    # keyless user's choice is clamped to the server allowlist, so the two can
+    # differ and only this one is the answer to "which model ran?".
+    def plan_result(usage)
+      {
+        'operations' => [], 'summary' => '', 'needs_design' => false,
+        'unrelated' => false, 'usage' => usage, 'model' => model
+      }
+    end
+
+    # Drop anything outside the vocabulary rather than passing it on: the client
+    # dispatches on `op`, so an unknown verb would be a silent no-op there, and a
+    # malformed one a silent half-edit. Both are worse than a short plan.
+    def normalize_operations(raw)
+      Array(raw).filter_map { |op| normalize_operation(op) }.first(MAX_PLAN_OPERATIONS)
+    end
+
+    def normalize_operation(raw)
+      return nil unless raw.is_a?(Hash)
+
+      builder = PLAN_BUILDERS[raw['op'].to_s.strip]
+      builder && send(builder, raw)
+    end
+
+    def delete_layer_op(raw)
+      layer_only_op('delete_layer', raw)
+    end
+
+    def ungroup_layer_op(raw)
+      layer_only_op('ungroup_layer', raw)
+    end
+
+    def layer_only_op(name, raw)
+      key = layer_key(raw)
+      key.blank? ? nil : { 'op' => name, 'layer' => key }
+    end
+
+    def update_layer_op(raw)
+      key = layer_key(raw)
+      return nil if key.blank?
+
+      attrs = slice_present(raw, PLAN_LAYER_ATTRS)
+      return nil if attrs.empty?
+
+      attrs['cols'] = attrs['cols'].to_i.clamp(1, 6) if attrs.key?('cols')
+      { 'op' => 'update_layer', 'layer' => key }.merge(attrs)
+    end
+
+    def delete_field_op(raw)
+      key = layer_key(raw)
+      field = raw['field'].to_s.strip
+      return nil if key.blank? || field.blank?
+
+      { 'op' => 'delete_field', 'layer' => key, 'field' => field }
+    end
+
+    def field_update_op(raw)
+      key = layer_key(raw)
+      field = raw['field'].to_s.strip
+      return nil if key.blank? || field.blank?
+
+      attrs = slice_present(raw, PLAN_FIELD_ATTRS)
+      return nil if attrs.empty?
+
+      PLAN_FIELD_FLAGS.each { |flag| attrs[flag] = truthy?(attrs[flag]) if attrs.key?(flag) }
+      attrs['cols'] = attrs['cols'].to_i.clamp(1, 6) if attrs.key?('cols')
+      { 'op' => 'set_field', 'layer' => key, 'field' => field }.merge(attrs)
+    end
+
+    def reorder_layers_op(raw)
+      order = string_list(raw['order'])
+      order.size < 2 ? nil : { 'op' => 'reorder_layers', 'order' => order }
+    end
+
+    def group_layers_op(raw)
+      label = raw['label'].to_s.strip
+      layers = string_list(raw['layers'])
+      return nil if label.blank? || layers.empty?
+
+      { 'op' => 'group_layers', 'label' => label, 'layers' => layers }
+    end
+
+    def layer_key(raw)
+      (raw['layer'] || raw['key']).to_s.strip
+    end
+
+    def string_list(raw)
+      Array(raw).map { |v| v.to_s.strip }.compact_blank.uniq
+    end
+
+    # Keep only the keys the model actually sent, so "absent" (leave alone) stays
+    # distinguishable from "sent as false/blank" (change it).
+    def slice_present(raw, keys)
+      keys.each_with_object({}) { |k, out| out[k] = raw[k] if raw.key?(k) && !raw[k].nil? }
+    end
+
+    def truthy?(value)
+      [true, 'true', 'True', 1, '1'].include?(value)
+    end
+
     # Tolerate models that wrap JSON in ```json fences despite instructions.
     def parse_json(text)
       cleaned = text.strip

data/lib/labimotion/version.rb

@@ -2,5 +2,5 @@
 
 ## Labimotion Version
 module Labimotion
-  VERSION = '2.4.0.rc9'
+  VERSION = '2.4.0.rc11'
 end

data/lib/labimotion.rb

@@ -88,6 +88,8 @@ module Labimotion
 
   ######## Libs
   autoload :AiTemplate, 'labimotion/libs/ai_template'
+  autoload :AiKlassQueue, 'labimotion/libs/ai_klass_queue'
+  autoload :AiKlassValidator, 'labimotion/libs/ai_klass_validator'
   autoload :AiEgressGuard, 'labimotion/libs/ai_egress_guard'
   autoload :AiModels, 'labimotion/libs/ai_models'
   autoload :UserAiSettings, 'labimotion/libs/user_ai_settings'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: labimotion
 version: !ruby/object:Gem::Version
-  version: 2.4.0.rc9
+  version: 2.4.0.rc11
 platform: ruby
 authors:
 - Chia-Lin Lin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: caxlsx
@@ -145,6 +145,8 @@ files:
 - lib/labimotion/helpers/segment_helpers.rb
 - lib/labimotion/helpers/vocabulary_helpers.rb
 - lib/labimotion/libs/ai_egress_guard.rb
+- lib/labimotion/libs/ai_klass_queue.rb
+- lib/labimotion/libs/ai_klass_validator.rb
 - lib/labimotion/libs/ai_models.rb
 - lib/labimotion/libs/ai_template.rb
 - lib/labimotion/libs/attachment_handler.rb