labimotion 2.4.0.rc9 → 2.4.0.rc10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6b27ce7b185d248cf78a19fbeb00cf5c60edeed1e090d1fa73c2de8d4465579
-  data.tar.gz: dd64b3fd5e1fbb717135444ed666df30e2ae542e6e65fb2a3616b210ab9d5832
+  metadata.gz: 6355c96e00c582cf1b874e6e4300bbb26a150f276e3afcde63e364e50a7b4f31
+  data.tar.gz: 69b3c2d5fa16f295ee2dbdf4b240b0948e1e1f05a3a3edb8c4c4881fecda1137
 SHA512:
-  metadata.gz: 3cbf525c1197064ab1b25a11d77fd94249e064d6f705c1ae5e9306bc497e7080c5c2c3266fd8bec52c2ee502862e8b82f6324d3e3aca20d2a6565dbcaa67f811
-  data.tar.gz: 5c96c935475319618a2c9eb66d5cd102a0971b6f7628a7bd97bcaa5f5cd8686933c6c3cef110d24be30250f01493569ae966f3eb07ecde06ed3e04e710668b64
+  metadata.gz: a916242cee0543be6fa0fa04333eaa9dfede1d486f311e0229b97f13120e18b80e58bdbfac234b0429a09e2ba915bafe461be229a52cc64bde1ecd8fd403a597
+  data.tar.gz: f79f17d2d887a637566ba9bd81123cb1474c75dcb6519813b2dcb770888e1c49c7b55342899f2455423e2a46da3d6056d27229048b431b2fa9c78595c9acfd41

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/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/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/libs/ai_template.rb

@@ -72,6 +72,42 @@ 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
+
     # Generate a metadata template for a generic dataset, element or segment.
     #
     # The JSON template schema (layers / fields / select_options) is IDENTICAL
@@ -115,6 +151,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
@@ -237,7 +300,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)
@@ -268,6 +331,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 +340,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)
+      raise "AI request failed (HTTP #{response.code})" 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?
@@ -300,7 +384,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 +411,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,6 +420,10 @@ module Labimotion
       end
     end
 
+    def finish_reason(body)
+      Array(body['choices']).first&.dig('finish_reason').to_s
+    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)
@@ -452,6 +542,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 +834,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 +1025,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.rc10'
 end

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.rc10
 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-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: caxlsx