labimotion 2.4.0.rc5 → 2.4.0.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e6b4cffa98971ea0ef93e54a537710c7fdc587f2433f038a54f42be1ac63f21
-  data.tar.gz: b57ba99244c3b9ec975fef1acb2c1b588b8d9bee5a5d6c356d336bc247c08738
+  metadata.gz: fa32d7e24804c4f270efdbce75bccf847ae3d30ae1f6b265c17b9c196e9c12a6
+  data.tar.gz: b6901471f70ac6874bf68a517ea9d994a3e4054d089a2bc66e042de38e97f4fd
 SHA512:
-  metadata.gz: c727c0b2409e463b0e6130986ebdcc528cf6473696b2124889061557f365ec163cc1393d08662b258801ddadafd16f7134e82786d759121b915e47b499814b55
-  data.tar.gz: 84ac6b69a8326012b61eae9aefef2f248c85ac22fa45cf266cf03114378a0cde2d1839f0798d3d460d35223000283db2a7ee4dcb3bdcfa4e4faac414ad01460b
+  metadata.gz: b6612883678081acfa046ea9956424f06b512f5ea941cac2dd219e60809f0ed308026d9e0e8c9a112e067b8718f4a2b55939211b0843100d6329a9502341ddee
+  data.tar.gz: c52a79f87e8dffb30d340be92e107e6518c96e3c28d46a6857e6355ff3e30ec399a989cce94553188b4baff83ac548d34d80083b185a523be8c31823bdc7e97c

data/lib/labimotion/apis/generic_dataset_api.rb

@@ -7,6 +7,7 @@ module Labimotion
 
     helpers Labimotion::GenericHelpers
     helpers Labimotion::DatasetHelpers
+    helpers Labimotion::ParamHelpers
 
     resource :generic_dataset do
       namespace :klasses do
@@ -78,6 +79,34 @@ module Labimotion
         end
       end
 
+      namespace :create_ai_klass do
+        desc 'create a Generic Dataset Klass from an AI-generated template'
+        params do
+          use :create_ai_dataset_klass_params
+        end
+        post do
+          msg = create_ai_dataset_klass(params, current_user)
+          klass = Labimotion::DatasetKlassEntity.represent(Labimotion::DatasetKlass.all)
+          { status: msg[:status], message: msg[:message], klass: klass }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { error: e.message }
+        end
+      end
+
+      namespace :refine_ai_klass do
+        desc 'refine a Generic Dataset Klass template with AI (returns the revised template; not persisted)'
+        params do
+          use :refine_ai_dataset_klass_params
+        end
+        post do
+          refine_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

@@ -212,6 +212,43 @@ module Labimotion
         end
       end
 
+      namespace :create_ai_klass do
+        desc 'create a Generic Element Klass from an AI-generated template'
+        params do
+          use :create_ai_element_klass_params
+        end
+        post do
+          authenticate_admin!('elements')
+          msg = create_ai_element_klass(params, current_user)
+          { status: msg[:status], message: msg[:message],
+            klass: Labimotion::ElementKlassEntity.represent(Labimotion::ElementKlass.where(is_active: true)) }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { error: e.message }
+        end
+      end
+
+      # Sibling namespace of :create_ai_klass — MUST stay above the route_param :id
+      # blocks below, otherwise POST /ai_fill_data falls through to the element
+      # instance route and Element.find(nil) is raised.
+      namespace :ai_fill_data do
+        desc "Auto-fill a generic element's data values from a document using AI"
+        params do
+          use :ai_fill_element_data_params
+        end
+        post do
+          msg = ai_fill_element_data(params, current_user)
+          if msg[:status] == 'success'
+            { status: 'success', values: msg[:values], summary: msg[:summary] }
+          else
+            { status: 'error', message: msg[:message] }
+          end
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { status: 'error', message: e.message }
+        end
+      end
+
       namespace :update_element_klass do
         desc 'update Generic Element Klass'
         params do

data/lib/labimotion/apis/segment_api.rb

@@ -59,6 +59,25 @@ module Labimotion
         end
       end
 
+      namespace :create_ai_klass do
+        desc 'create a Generic Segment Klass from an AI-generated template'
+        params do
+          use :create_ai_segment_klass_params
+        end
+        after_validation do
+          authenticate_admin!('segments')
+          @klass = fetch_klass('ElementKlass', params[:element_klass])
+        end
+        post do
+          msg = create_ai_segment_klass(current_user, params)
+          { status: msg[:status], message: msg[:message],
+            klass: Labimotion::SegmentKlassEntity.represent(Labimotion::SegmentKlass.all) }
+        rescue StandardError => e
+          Labimotion.log_exception(e, current_user)
+          { error: e.message }
+        end
+      end
+
       namespace :update_segment_klass do
         desc 'update Generic Segment Klass'
         params do

data/lib/labimotion/helpers/dataset_helpers.rb

@@ -58,6 +58,104 @@ module Labimotion
       raise e
     end
 
+    # Create a new (inactive) dataset klass whose properties template is
+    # generated by an LLM from a CHMO ontology term plus optional description,
+    # reference links and uploaded files. The admin reviews/edits the generated
+    # template in the designer and activates it (human-in-the-loop).
+    def create_ai_dataset_klass(params, current_user)
+      ols_term_id = params[:ols_term_id].to_s.split('|').first.to_s.strip
+      raise 'An ontology term (CHMO) is required' if ols_term_id.blank?
+
+      if Labimotion::DatasetKlass.find_by(ols_term_id: ols_term_id).present?
+        return { status: 'error',
+                 message: "A dataset template already exists for #{ols_term_id}. Edit it in the designer instead." }
+      end
+
+      if Array(params[:files]).size > Labimotion::AiTemplate::MAX_FILES
+        return { status: 'error', message: "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})." }
+      end
+
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.generate(
+        ols_term_id: params[:ols_term_id],
+        desc: params[:desc],
+        cols: params[:cols],
+        references: params[:references],
+        files: params[:files],
+        **overrides
+      )
+
+      uuid = SecureRandom.uuid
+      label = ai['label'].presence ||
+              params[:ols_term_id].to_s.split('|').last.to_s.strip.presence ||
+              'AI dataset template'
+      # property-base schema requires pkg, uuid, klass, layers, version, identifier.
+      properties_template = {
+        'uuid' => uuid,
+        'klass' => 'DatasetKlass',
+        'pkg' => Labimotion::Utils.pkg(nil),
+        'version' => '1.0.0',
+        'identifier' => uuid,
+        'layers' => ai['layers'],
+        'select_options' => ai['select_options'],
+        'metadata' => ai['metadata']
+      }
+      attributes = {
+        'uuid' => uuid,
+        'label' => label,
+        'desc' => params[:desc].presence || ai['label'].presence,
+        'ols_term_id' => ols_term_id,
+        'place' => ((Labimotion::DatasetKlass.all.length * 10) || 0) + 10,
+        'is_active' => false,
+        'released_at' => DateTime.now,
+        'properties_template' => properties_template,
+        'properties_release' => properties_template,
+        'created_by' => current_user.id
+      }
+
+      ds = Labimotion::DatasetKlass.create!(attributes)
+      ds.create_klasses_revision(current_user)
+      { status: 'success',
+        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)
+      { status: 'error', message: e.message }
+    end
+
+    # Refine an existing dataset template with AI and return the revised template
+    # (label, layers, select_options) plus a one-line summary of the change.
+    # Nothing is persisted — the admin applies the result into the designer's
+    # working copy and saves it there (human-in-the-loop, mirrors the create flow).
+    def refine_ai_dataset_klass(params, current_user)
+      instruction = params[:instruction].to_s.strip
+      raise 'An instruction is required' if instruction.blank?
+
+      current = {
+        'label' => params[:label],
+        'layers' => params[:layers] || {},
+        'select_options' => params[:select_options] || {}
+      }
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.refine(
+        current: current,
+        instruction: instruction,
+        ols_term_id: ai_term_with_label(params[:ols_term_id]),
+        history: params[:history],
+        cols: params[:cols],
+        **overrides
+      )
+      {
+        status: 'success',
+        label: ai['label'].presence || params[:label],
+        layers: ai['layers'],
+        select_options: ai['select_options'],
+        summary: ai['summary']
+      }
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      { status: 'error', message: e.message }
+    end
+
     def find_best_match_template(ols_term_id)
       result = Labimotion::TemplateMatcher.find_best_match(ols_term_id)
       if result[:template]
@@ -69,6 +167,21 @@ module Labimotion
 
     private
 
+    # Pair the CHMO id with its human label ("CHMO:0000470 | mass spectrometry")
+    # by resolving the label from ols_terms, so the AI refine scope guard can name
+    # the method rather than show a bare id. Falls back to the raw value when the
+    # term is missing/unknown; never raises (a failed lookup must not block refine).
+    def ai_term_with_label(raw)
+      id = raw.to_s.split('|').first.to_s.strip
+      return raw.to_s if id.blank? || !defined?(OlsTerm)
+
+      label = OlsTerm.find_by(term_id: id)&.label
+      label.present? ? "#{id} | #{label}" : raw.to_s
+    rescue StandardError => e
+      Labimotion.log_exception(e)
+      raw.to_s
+    end
+
     def build_template_response(template, match_type, info_messages)
       response = {
         error: '',

data/lib/labimotion/helpers/element_helpers.rb

@@ -54,6 +54,184 @@ module Labimotion
       raise e
     end
 
+    # Create a new (inactive) element klass whose properties template is
+    # generated by an LLM from a user-provided name/label plus optional
+    # description, reference links and uploaded files. The admin reviews/edits
+    # the generated template in the designer and activates it (human-in-the-loop).
+    def create_ai_element_klass(params, current_user)
+      name = params[:name]
+      label = params[:label]
+      if Labimotion::ElementKlass.find_by(name: name).present?
+        return { status: 'error', message: "An element named [#{name}] already exists." }
+      end
+
+      if Array(params[:files]).size > Labimotion::AiTemplate::MAX_FILES
+        return { status: 'error', message: "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})." }
+      end
+
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.generate(
+        kind: 'element',
+        subject: "#{params[:label]} (#{params[:name]})",
+        desc: params[:desc],
+        cols: params[:cols],
+        references: params[:references],
+        files: params[:files],
+        **overrides
+      )
+
+      uuid = SecureRandom.uuid
+      # property-base schema requires pkg, uuid, klass, layers, version, identifier.
+      properties_template = {
+        'uuid' => uuid,
+        'klass' => 'ElementKlass',
+        'pkg' => Labimotion::Utils.pkg(nil),
+        'version' => '1.0.0',
+        'identifier' => uuid,
+        'layers' => ai['layers'],
+        'select_options' => ai['select_options'],
+        'metadata' => ai['metadata']
+      }
+      attributes = {
+        'name' => name,
+        'label' => label,
+        'klass_prefix' => params[:klass_prefix],
+        'icon_name' => params[:icon_name],
+        'desc' => params[:desc].presence || ai['label'].presence,
+        'is_active' => false,
+        'uuid' => uuid,
+        'released_at' => DateTime.now,
+        'properties_template' => properties_template,
+        'properties_release' => properties_template,
+        'created_by' => current_user.id
+      }
+
+      new_klass = Labimotion::ElementKlass.create!(attributes)
+      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',
+        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)
+      { status: 'error', message: e.message }
+    end
+
+    # AI auto-fill of a generic element instance's DATA VALUES from a document
+    # (an existing attachment, an analysis, or freshly uploaded files). Reads the
+    # source text, asks the LLM to extract values for the element's OWN template
+    # fields, validates them, and returns them for the client to merge into the
+    # working copy for human review. Nothing is persisted here.
+    #
+    # Authorization: the caller must be able to READ the element, and the source
+    # must BELONG to that element (see the ownership checks below) — this endpoint
+    # reads files by id, so it must never read an Attachment/Container the user
+    # does not already have access to through this element.
+    def ai_fill_element_data(params, current_user)
+      element = Labimotion::Element.find(params[:element_id])
+      error!('401 Unauthorized', 401) unless ElementPolicy.new(current_user, element).read?
+
+      text = ai_fill_source_text(element, params)
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.fill(
+        properties: element.properties,
+        context_text: text,
+        **overrides
+      )
+      { status: 'success', values: ai['values'], summary: ai['summary'] }
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      { status: 'error', message: e.message }
+    end
+
+    # Resolve the requested source into plain text, enforcing ownership first.
+    def ai_fill_source_text(element, params)
+      case params[:source]
+      when 'attachment'
+        ai_fill_attachment_text(element, params[:attachment_id])
+      when 'analysis'
+        ai_fill_analysis_text(element, params[:container_id])
+      when 'upload'
+        ai_fill_upload_text(params[:files])
+      else
+        error!('400 Bad Request', 400)
+      end
+    end
+
+    # The attachment must be one of the element's own attachments OR an attachment
+    # of one of the element's analysis DATASET containers. Only then is it read.
+    def ai_fill_attachment_text(element, attachment_id)
+      error!('404 Not Found', 404) if attachment_id.nil?
+      error!('404 Not Found', 404) unless ai_fill_element_attachment_ids(element).include?(attachment_id.to_i)
+
+      att = Attachment.find(attachment_id)
+      Labimotion::FileExtractor.extract_bytes(att.filename, att.read_file)
+    end
+
+    # The container id must be one of the element's own analysis containers. Then
+    # concatenate the extracted text of every attachment on that analysis's dataset
+    # children, each prefixed "### <filename>", with the analysis name/description
+    # prepended as context. Cap at AiTemplate::MAX_FILES; skip unreadable files.
+    def ai_fill_analysis_text(element, container_id)
+      error!('404 Not Found', 404) if container_id.nil?
+      analysis = element.analyses.detect { |c| c.id == container_id.to_i }
+      error!('404 Not Found', 404) if analysis.nil?
+
+      parts = []
+      context = [analysis.name.presence, analysis.description.presence].compact.join(' — ')
+      parts << "Analysis: #{context}" if context.present?
+
+      ai_fill_analysis_attachments(analysis).first(Labimotion::AiTemplate::MAX_FILES).each do |att|
+        content = ai_fill_extract_attachment(att)
+        next if content.to_s.strip.empty?
+
+        parts << "### #{att.filename}\n#{content}"
+      end
+      parts.join("\n\n")
+    end
+
+    def ai_fill_upload_text(files)
+      parts = Array(files).first(Labimotion::AiTemplate::MAX_FILES).map do |file|
+        name = file[:filename] || file['filename']
+        next if name.blank?
+
+        content = Labimotion::FileExtractor.extract(name, file[:content_base64] || file['content_base64'])
+        next if content.to_s.strip.empty?
+
+        "### #{name}\n#{content}"
+      end.compact
+      parts.join("\n\n")
+    end
+
+    # Ids of attachments this element may expose to the AI fill: its own
+    # attachments plus the attachments of its analysis dataset containers.
+    def ai_fill_element_attachment_ids(element)
+      own = element.attachments.pluck(:id)
+      dataset_ids = ai_fill_dataset_containers(element).map(&:id)
+      dataset_att = dataset_ids.empty? ? [] : Attachment.where(attachable_type: 'Container', attachable_id: dataset_ids).pluck(:id)
+      (own + dataset_att).uniq
+    end
+
+    # Dataset containers under all of the element's analysis containers.
+    def ai_fill_dataset_containers(element)
+      element.analyses.flat_map { |analysis| analysis.children.where(container_type: 'dataset').to_a }
+    end
+
+    def ai_fill_analysis_attachments(analysis)
+      analysis.children.where(container_type: 'dataset').flat_map do |dataset|
+        Attachment.where(attachable_type: 'Container', attachable_id: dataset.id).to_a
+      end
+    end
+
+    def ai_fill_extract_attachment(att)
+      Labimotion::FileExtractor.extract_bytes(att.filename, att.read_file)
+    rescue StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
     def update_element_klass(current_user, params)
       place = params[:place] || 100
       begin

data/lib/labimotion/helpers/generic_helpers.rb

@@ -109,6 +109,68 @@ 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.
+    def ai_user_overrides(current_user)
+      profile = current_user.respond_to?(:profile) ? current_user.profile : nil
+      return {} if profile.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?
+
+      { model: model, api_key: api_key }.merge(ai_provider_overrides(profile, api_key)).compact
+    rescue StandardError => e
+      Labimotion.log_exception(e, current_user)
+      {}
+    end
+
+    # 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)
+      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))
+      }
+    end
+
+    # On the SHARED server key (user has no personal key), keep the user's model
+    # only if the admin allowed it; otherwise return nil so AiTemplate falls back
+    # to the server default. Returns the model unchanged when no allowlist is
+    # configured (fail open). Guards an off-list model being billed to the shared key.
+    def ai_shared_key_model(model)
+      return model if model.blank?
+
+      allow = ai_server_model_allowlist
+      allow.any? && !allow.include?(model.to_s) ? nil : model
+    end
+
+    # Model ids the server permits on the SHARED key: the admin pick-list
+    # (:models) plus the server default (:model / KI_TOOLBOX_MODEL), read from the
+    # host config the same way Labimotion::AiTemplate does. Empty when the admin
+    # configured neither — the caller then skips the clamp (fail open), matching
+    # the gem's decoupled, non-blocking handling of overrides.
+    def ai_server_model_allowlist
+      cfg = Rails.configuration.labimotion_ai || {}
+      list = cfg[:models].is_a?(Array) ? cfg[:models] : []
+      ids = list.map { |entry| ai_model_entry_id(entry) }
+      (ids << cfg[:model].to_s << ENV['KI_TOOLBOX_MODEL'].to_s).reject(&:blank?).uniq
+    rescue StandardError
+      []
+    end
+
+    def ai_model_entry_id(entry)
+      return entry.to_s unless entry.is_a?(Hash)
+
+      (entry[:id] || entry['id']).to_s
+    end
+
     def deactivate_klass(params)
       klz = fetch_klass(params[:klass], params[:id])
       authorize_klass!(klz, :deactivate)

data/lib/labimotion/helpers/param_helpers.rb

@@ -35,6 +35,74 @@ module Labimotion
       optional :properties_template, type: Hash, desc: 'Element Klass properties template'
     end
 
+    params :create_ai_dataset_klass_params do
+      requires :ols_term_id, type: String, desc: 'CHMO ontology term (e.g. "CHMO:0000470 | mass spectrometry (MS)")'
+      optional :desc, type: String, desc: 'Description / intent of the new dataset template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :create_ai_element_klass_params do
+      requires :name, type: String, desc: 'Element Klass Name'
+      requires :label, type: String, desc: 'Element Klass Label'
+      requires :klass_prefix, type: String, desc: 'Element Klass Short Label Prefix'
+      optional :icon_name, type: String, desc: 'Element Klass Icon Name'
+      optional :desc, type: String, desc: 'Description / intent of the new element template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    # AI auto-fill of a generic element instance's DATA VALUES from a document.
+    # `files` mirrors the create_ai_*_klass_params file block (source == 'upload').
+    params :ai_fill_element_data_params do
+      requires :element_id, type: Integer, desc: 'Generic element id whose data values to fill'
+      requires :source, type: String, values: %w[attachment analysis upload], desc: 'Value source'
+      optional :attachment_id, type: Integer, desc: 'Attachment id (required when source == attachment)'
+      optional :container_id, type: Integer, desc: 'Analysis container id (required when source == analysis)'
+      optional :files, type: Array, desc: 'Uploaded files (source == upload)' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :create_ai_segment_klass_params do
+      requires :label, type: String, desc: 'Segment Klass Label'
+      requires :element_klass, type: Integer, desc: 'Parent Element Klass Id'
+      optional :metadata, type: Hash, desc: 'Klass metadata (segment render kind, e.g. { is_properties })'
+      optional :desc, type: String, desc: 'Description / intent of the new segment template'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Default columns per row for generated layers'
+      optional :references, type: Array[String], desc: 'Reference links (publications / standards)'
+      optional :files, type: Array, desc: 'Reference files for context' do
+        optional :filename, type: String, desc: 'File name'
+        optional :content, type: String, desc: 'Client-read plaintext (legacy, truncated)'
+        optional :content_base64, type: String, desc: 'Base64-encoded raw file bytes (PDF/Excel/text — preferred)'
+      end
+    end
+
+    params :refine_ai_dataset_klass_params do
+      requires :instruction, type: String, desc: 'Natural-language change to apply to the template'
+      optional :label, type: String, desc: 'Current template label'
+      optional :ols_term_id, type: String, desc: 'CHMO ontology term (context only)'
+      optional :cols, type: Integer, values: 1..6, default: 1, desc: 'Fallback columns per row when a layer omits its own'
+      optional :layers, type: Hash, desc: 'Current template layers'
+      optional :select_options, type: Hash, desc: 'Current template select options'
+      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

@@ -54,6 +54,68 @@ module Labimotion
       raise e
     end
 
+    # Create a new (inactive) segment klass whose properties template is
+    # generated by an LLM from a user-provided label plus optional description,
+    # reference links and uploaded files. The parent ElementKlass must be set on
+    # @klass by the API (after_validation), mirroring create_segment_klass. The
+    # admin reviews/edits the generated template in the designer and activates it.
+    def create_ai_segment_klass(current_user, params)
+      return { status: 'error', message: 'A parent element class is required.' } if @klass.nil?
+
+      if Array(params[:files]).size > Labimotion::AiTemplate::MAX_FILES
+        return { status: 'error', message: "Too many files (max #{Labimotion::AiTemplate::MAX_FILES})." }
+      end
+
+      overrides = ai_user_overrides(current_user)
+      ai = Labimotion::AiTemplate.generate(
+        kind: 'segment',
+        subject: params[:label],
+        desc: params[:desc],
+        cols: params[:cols],
+        references: params[:references],
+        files: params[:files],
+        **overrides
+      )
+
+      uuid = SecureRandom.uuid
+      # property-base schema requires pkg, uuid, klass, layers, version, identifier.
+      properties_template = {
+        'uuid' => uuid,
+        'klass' => 'SegmentKlass',
+        'pkg' => Labimotion::Utils.pkg(nil),
+        'version' => '1.0.0',
+        'identifier' => uuid,
+        'layers' => ai['layers'],
+        'select_options' => ai['select_options'],
+        'metadata' => ai['metadata']
+      }
+      attributes = {
+        'label' => params[:label],
+        'desc' => params[:desc].presence || ai['label'].presence,
+        'element_klass' => @klass,
+        'place' => 100,
+        'is_active' => false,
+        'uuid' => uuid,
+        'released_at' => DateTime.now,
+        'properties_template' => properties_template,
+        'properties_release' => properties_template,
+        'created_by' => current_user.id
+      }
+      # Klass-level segment metadata (render kind: own tab vs the host element's
+      # Properties tab), mirroring the non-AI create_segment_klass which persists
+      # params[:metadata] via declared. Absent -> leave the column default.
+      attributes['metadata'] = params[:metadata] if params[:metadata].present?
+
+      klass = Labimotion::SegmentKlass.create!(attributes)
+      klass.reload
+      klass.create_klasses_revision(current_user)
+      { status: 'success',
+        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)
+      { status: 'error', message: e.message }
+    end
+
     def update_segment_klass(current_user, params)
       segment = fetch_klass('SegmentKlass', params[:id])
       authorize_klass!(segment, :write)