labimotion 2.4.0.rc2 → 2.4.0.rc4

data/lib/labimotion/apis/labimotion_doi_api.rb

@@ -7,6 +7,10 @@ module Labimotion
     # rubocop:disable Metrics/BlockLength
     # Grape route and helper DSL blocks are necessarily large.
     KLASS_TYPES = Labimotion::TemplateDoiHelpers::KLASS_BY_TYPE.keys.freeze
+    # Publication fields exposed on the public (anonymous) DOI endpoints.
+    # `contributor` (singular) is kept for DOIs released before contributors
+    # became a list — their snapshot still carries it.
+    PUBLIC_PUBLICATION_KEYS = %w[title description authors contributors contributor references license].freeze
 
     helpers do
       def resolve_klass!(type, id)
@@ -41,25 +45,36 @@ module Labimotion
         )
       end
 
-      # Public, read-only view of one released DOI version.
-      def released_doi_version(doi)
+      # Public, read-only view of one released DOI version, carrying the
+      # publication metadata that version was released with.
+      def released_doi_version(record, doi)
         full = doi.full_doi
         {
           doi: full,
           doi_url: "https://dx.doi.org/#{full}",
           version: ::Doi.labimotion_doi_version(doi),
-          minted_at: doi.minted_at
+          minted_at: doi.minted_at,
+          publication: released_publication(record, doi)
         }
       end
 
+      # The snapshot taken when this version was released. DOIs released before
+      # snapshots were kept have none, and fall back to the template's current
+      # publication — the best available answer for them.
+      def released_publication(record, doi)
+        publication = ::Doi.labimotion_doi_publication(doi).presence ||
+                      (record.properties_template || {})['publication']
+        publication.is_a?(Hash) ? publication.slice(*PUBLIC_PUBLICATION_KEYS) : {}
+      end
+
       # Public payload for a template that has at least one released DOI: the
       # latest released DOI promoted to the top level, plus its publication
-      # metadata, hub deep-link and every released version. `record_id` matches
-      # the hub grid's row id (identifier || uuid) so the frontend can merge it.
+      # metadata, hub deep-link and every released version. Each version brings
+      # its own publication, so the top-level one is the latest release's rather
+      # than the template's work-in-progress. `record_id` matches the hub grid's
+      # row id (identifier || uuid) so the frontend can merge it.
       def released_template_doi(record, dois)
-        versions = dois.sort_by(&:id).map { |doi| released_doi_version(doi) }
-        publication = (record.properties_template || {})['publication']
-        publication = publication.is_a?(Hash) ? publication.slice('title', 'description', 'authors', 'license') : {}
+        versions = dois.sort_by(&:id).map { |doi| released_doi_version(record, doi) }
         versions.last.merge(
           record_id: record.try(:identifier).presence || record.try(:uuid).presence || record.id,
           identifier: record.try(:identifier),
@@ -68,7 +83,6 @@ module Labimotion
           template_version: record.try(:version),
           next_doi_version: ::Doi.labimotion_version_segment(record),
           template_url: Labimotion::TemplateDoiHelpers.template_url(record),
-          publication: publication,
           versions: versions
         )
       end
@@ -125,7 +139,7 @@ module Labimotion
                 version: ::Doi.labimotion_doi_version(doi),
                 full_doi: doi.full_doi,
                 minted: doi.minted == true,
-                xml: Labimotion::BuildTemplateDoiXml.new(record, doi, current_user).call
+                xml: Labimotion::BuildTemplateDoiXml.new(record, doi).call
               }
             end
             { versions: versions }

data/lib/labimotion/apis/labimotion_template_browse_api.rb

@@ -9,6 +9,10 @@ module Labimotion
   class LabimotionTemplateBrowseAPI < Grape::API
     KLASS_BY_TYPE = Labimotion::TemplateDoiHelpers::KLASS_BY_TYPE
     KLASS_TYPES = KLASS_BY_TYPE.keys.freeze
+    # Publication fields exposed alongside a template / its released DOIs.
+    # `contributor` (singular) is kept for DOIs released before contributors
+    # became a list — their snapshot still carries it.
+    PUBLICATION_KEYS = %w[title description authors contributors contributor references license].freeze
     # type => [revision model, foreign key to the klass]
     REVISION_BY_TYPE = {
       'element' => [::Labimotion::ElementKlassesRevision, :element_klass_id],
@@ -76,7 +80,14 @@ module Labimotion
       # The template's DOI publication metadata (shown alongside the DOI).
       def template_publication(record)
         pub = (record.properties_template || {})['publication']
-        pub.is_a?(Hash) ? pub.slice('title', 'description', 'authors', 'license') : {}
+        pub.is_a?(Hash) ? pub.slice(*PUBLICATION_KEYS) : {}
+      end
+
+      # The publication a released DOI was published with. Falls back to the
+      # template's current metadata for DOIs released before snapshots were kept.
+      def released_publication(record, doi)
+        pub = ::Doi.labimotion_doi_publication(doi)
+        pub.is_a?(Hash) && pub.any? ? pub.slice(*PUBLICATION_KEYS) : template_publication(record)
       end
 
       # Released (minted) DOIs of the template, each tagged with its DOI version
@@ -88,6 +99,7 @@ module Labimotion
           full = doi.full_doi
           { version: ::Doi.labimotion_doi_version(doi), doi: full,
             doi_url: "https://dx.doi.org/#{full}", minted_at: doi.minted_at,
+            publication: released_publication(record, doi),
             xml: Labimotion::BuildTemplateDoiXml.new(record, doi).call }
         end
       end

data/lib/labimotion/apis/segment_api.rb

@@ -25,8 +25,21 @@ module Labimotion
           optional :displayed_in_list, type: Boolean, desc: 'Display in list format', default: false
         end
         get do
-          list = klass_list(nil, params[:is_active], false)
-          present list, with: Labimotion::SegmentKlassEntity, root: 'klass', displayed_in_list: false
+          # SegmentKlassEntity nests ElementKlassEntity, and Grape hands serialization options
+          # down into nested entities — so the element klasses resolve an owner too. Their
+          # authors have to go into the same map, or every row falls back to its own user
+          # query and the preload this option exists for buys nothing. `klass_list` only
+          # preloads the association when filtering by element, which this call does not, so
+          # ask for it here or `map(&:element_klass)` is itself one query per row.
+          list = klass_list(nil, params[:is_active], false).preload(:element_klass)
+          owners = Labimotion::OwnerResolver.map_for(list.to_a + list.map(&:element_klass))
+          # The nested element klasses go into the same share context for the same reason
+          # they share the owners map; ShareResolver folds a segment's parent in by itself.
+          share_context = Labimotion::ShareResolver.context_for(
+            list.to_a + list.map(&:element_klass), current_user
+          )
+          present list, with: Labimotion::SegmentKlassEntity, root: 'klass', displayed_in_list: false,
+                        with_ownership: true, owners: owners, share_context: share_context
         end
       end
 
@@ -36,7 +49,7 @@ module Labimotion
           use :create_segment_klass_params
         end
         after_validation do
-          authenticate_admin!('segments')
+          authenticate_admin!(Labimotion::Constants::Family::SEGMENT)
           @klass = fetch_klass('ElementKlass', params[:element_klass])
         end
         post do
@@ -46,14 +59,31 @@ module Labimotion
         end
       end
 
-      namespace :update_segment_klass do
-        desc 'update Generic Segment Klass'
+      namespace :create_ai_klass do
+        desc 'create a Generic Segment Klass from an AI-generated template'
         params do
-          use :update_segment_klass_params
+          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
+          use :update_segment_klass_params
         end
+        # authorize_klass!(:write) runs inside the helper, on the loaded record.
         post do
           update_segment_klass(current_user, params)
         rescue StandardError => e
@@ -67,7 +97,10 @@ module Labimotion
         params do
           requires :identifier, type: String, desc: 'identifier'
         end
-        post do
+        post do # rubocop:disable Metrics/BlockLength
+          # Pulling from the repository creates or overwrites a local template — the same
+          # create/upgrade pair the import endpoints gate, so it takes the same two gates.
+          authenticate_admin!(Labimotion::Constants::Family::SEGMENT)
           sk_obj = fetch_repo_generic_template('Segment', params[:identifier])
           sk_obj = sk_obj.deep_symbolize_keys[:generic_template]
           return { error: 'No template data found' } unless sk_obj.present?
@@ -75,9 +108,17 @@ module Labimotion
           ek_obj = Labimotion::ElementKlass.find_by(name: sk_obj.dig(:element_klass, :klass_name))
           return { error: 'No related element data found' } unless ek_obj.present?
 
-          segment_klass = Labimotion::SegmentKlass.find_or_create_by(
-            identifier: sk_obj.dig(:identifier),
-          )
+          segment_klass = Labimotion::SegmentKlass.find_by(identifier: sk_obj.dig(:identifier))
+          # Syncing over an existing template replaces its released properties — :release,
+          # owner-only, exactly like the upgrade branch of validate_klass.
+          authorize_klass!(segment_klass, :release) if segment_klass
+          newly_created = segment_klass.nil?
+          # created_by belongs in this INSERT, not only in the update below: the column is
+          # NOT NULL since tighten_klass_created_columns, so a bare create is one relaxed
+          # label validation away from an ActiveRecord::NotNullViolation that would break
+          # every Hub pull of a new segment template.
+          segment_klass ||= Labimotion::SegmentKlass.create(identifier: sk_obj.dig(:identifier),
+                                                            created_by: current_user.id)
           segment_klass.update(sk_obj.slice(
             :label,
             :desc,
@@ -92,6 +133,10 @@ module Labimotion
             released_at: DateTime.now,
             sync_time: DateTime.now,
           ))
+          # Owner bookkeeping only for a template this pull just created. An existing
+          # owner-less row stays owner-less: assigning it a first owner is the
+          # administrator's transfer_ownership call, not a side effect of syncing.
+          Labimotion::KlassShare.seed_owner!(segment_klass, current_user.id) if newly_created
 
           present segment_klass, with: Labimotion::SegmentKlassEntity, root: 'klass'
         rescue StandardError => e
@@ -126,6 +171,9 @@ module Labimotion
           requires :identifier, type: String, desc: 'Identifier'
         end
         post do
+          # Importing needs the global create right; upgrading an existing template is gated
+          # owner-only inside validate_klass, where the create/update branch is decided.
+          authenticate_admin!(Labimotion::Constants::Family::SEGMENT)
           msg = create_repo_klass(params, current_user, request.headers['Origin'])
           klass = Labimotion::SegmentKlassEntity.represent(Labimotion::SegmentKlass.all)
           { status: msg[:status], message: msg[:message], klass: klass }
@@ -142,6 +190,9 @@ module Labimotion
           use :upload_segment_klass_params
         end
         post do
+          # Same split as create_repo_klass: create right here, owner-only upgrade inside
+          # validate_klass. This route previously had no gate at all.
+          authenticate_admin!(Labimotion::Constants::Family::SEGMENT)
           declared_params = declared(params, include_missing: false)
           attributes = declared_params.merge(
               created_by: current_user.id,

data/lib/labimotion/constants.rb

@@ -28,5 +28,19 @@ module Labimotion
       DATASET = 'DatasetKlass'
       ALL = [ELEMENT, SEGMENT, DATASET].freeze
     end
+
+    # The designer-right families as keyed in `users.generic_admin` (host-owned jsonb) and
+    # read by authenticate_admin!. FAMILY_OF answers which family gates a klass type.
+    module Family
+      ELEMENT = 'elements'
+      SEGMENT = 'segments'
+      DATASET = 'datasets'
+      ALL = [ELEMENT, SEGMENT, DATASET].freeze
+      FAMILY_OF = {
+        Klass::ELEMENT => ELEMENT,
+        Klass::SEGMENT => SEGMENT,
+        Klass::DATASET => DATASET
+      }.freeze
+    end
   end
 end

data/lib/labimotion/entities/application_entity.rb

@@ -8,8 +8,20 @@ module Labimotion
     # Common condition for fields that should not be displayed in list views
     DISPLAYED_IN_LIST_CONDITION = { unless: :displayed_in_list }.freeze
 
+    # Ownership is opt-in per call site and deliberately does NOT reuse `displayed_in_list`.
+    # That option is passed as `true` on the payloads submitted to the central Template Hub
+    # (labimotion_hub_api.rb:76, :103), so keying ownership on it would ship local user
+    # identity off-instance; and it is hardcoded `false` on all three Designer list endpoints,
+    # which are the only places ownership is wanted. Off by default, so `download_klass`
+    # exports and Hub submissions stay clean without having to opt out.
+    WITH_OWNERSHIP_CONDITION = { if: :with_ownership }.freeze
+
+    # ISO 8601. A zone *name* (strftime '%Z', e.g. "UTC") is not a valid ISO zone designator, so
+    # clients parsing it with moment.js fall back to `new Date()` — engine-specific behaviour.
+    ELN_TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S%z'
+
     format_with(:eln_timestamp) do |datetime|
-      datetime.present? ? datetime.strftime('%Y-%m-%d %H:%M:%S %Z') : nil
+      datetime.present? ? datetime.strftime(ELN_TIMESTAMP_FORMAT) : nil
     end
   end
 end

data/lib/labimotion/entities/generic_klass_entity.rb

@@ -11,5 +11,130 @@ module Labimotion
     expose :metadata, **DISPLAYED_IN_LIST_CONDITION, anonymize_with: {}
     expose :settings, **DISPLAYED_IN_LIST_CONDITION, anonymize_with: {}
     expose_timestamps(timestamp_fields: %i[released_at created_at updated_at sync_time])
+
+    expose :created_by, **WITH_OWNERSHIP_CONDITION
+    expose :owner, **WITH_OWNERSHIP_CONDITION
+
+    # The capability block the grid and toolbars key off — never the raw level, so a policy
+    # change is one edit to ShareResolver::REQUIRED_LEVEL and every button follows. Exposed
+    # only when the list endpoint preloaded a share context: absent on exports and Hub
+    # submissions by construction (same reasoning as WITH_OWNERSHIP_CONDITION), and absent on
+    # hosts that have not run the klass_shares migration, whose payloads stay byte-identical
+    # to Phase 0.
+    expose :current_user_permission, if: :share_context
+    # Plain symbols rather than ShareResolver::REQUIRED_LEVEL.keys: referencing that constant
+    # in the class body would chain-autoload KlassShare (an ActiveRecord model) just to load
+    # this entity, which the gem's Rails-less spec harness cannot do. The blocks only run when
+    # a share context was preloaded, so inside them the constants are safe.
+    %i[write release deactivate destroy manage].each do |action|
+      expose "can_#{action}", if: :share_context do |object, options|
+        context = options[:share_context]
+        key = Labimotion::KlassShare.key_of(object)
+        level = context[:levels][key]
+        if context[:admin]
+          # Administrator = implicit owner everywhere.
+          true
+        elsif !context[:has_owner].include?(key)
+          # Owner-less templates keep the legacy designer-wide rights (permanent fallback) —
+          # which the ungated lists' non-designer readers never held, so the grid must not
+          # offer them buttons the server will 401.
+          (context[:legacy] || {})[key.split(':').first] == true
+        else
+          !level.nil? && level >= Labimotion::ShareResolver::REQUIRED_LEVEL[action]
+        end
+      end
+    end
+
+    # How many people are waiting for access to this template, for the owner only — everyone
+    # else reads 0, because ShareResolver scopes the count to the requesting user's own owner
+    # rows and nobody else can act on it. It rides the payload the grid already fetches, so
+    # the Share button stays coloured across a reload without a call of its own. A block for
+    # the same reason as the capabilities above: naming KlassShare in the class body would
+    # chain-autoload an ActiveRecord model into the Rails-less spec harness. Absent without a
+    # share context, exactly like its neighbours.
+    expose :pending_request_count, if: :share_context do |object, options|
+      (options[:share_context][:pending_requests] || {})[Labimotion::KlassShare.key_of(object)] || 0
+    end
+
+    # `state` is what the grid badges on: a template whose owner left the institute has nobody
+    # to ask, which is the case ownership transfer exists to resolve.
+    #
+    # With a share context the owner is the permission_level=30 share row — the transferable
+    # right — and `created_by` stays exposed above as immutable provenance; the two diverge
+    # permanently after the first transfer. Without a context (host not migrated, or an
+    # endpoint that predates shares) the Phase 0 behaviour stands: `created_by` is the owner.
+    def owner
+      return owner_from_share if share_context
+
+      owner_from_created_by
+    end
+
+    # The level label, or nil when the user has no row at all. Note the fourth answer:
+    # `'requested'` — a level-0 row is a standing access request, not access, so a client
+    # must compare the level rather than test this string for truthiness.
+    def current_user_permission
+      level = share_context[:levels][Labimotion::KlassShare.key_of(object)]
+      level && Labimotion::KlassShare::LEVELS.key(level)&.to_s
+    end
+
+    private
+
+    def share_context
+      options[:share_context]
+    end
+
+    def owner_from_share
+      ref = share_context[:owners][Labimotion::KlassShare.key_of(object)]
+      return nil if ref.nil? && !share_context[:has_owner].include?(Labimotion::KlassShare.key_of(object))
+      # The ref keeps the share row's user id even when the user record cannot be resolved,
+      # so the transfer flow still knows who the row points at.
+      return { id: ref&.id, name: nil, name_abbreviation: nil, state: 'unknown' } if ref.nil? || ref.user.nil?
+
+      user_hash(ref.id, ref.user)
+    end
+
+    def owner_from_created_by
+      user_id = object.created_by
+      return nil if user_id.blank?
+
+      user = owners_map[user_id] || Labimotion::OwnerResolver.find(user_id)
+      return { id: user_id, name: nil, name_abbreviation: nil, state: 'unknown' } if user.nil?
+
+      user_hash(user_id, user)
+    end
+
+    def user_hash(user_id, user)
+      {
+        id: user_id,
+        name: user.name,
+        name_abbreviation: user.name_abbreviation,
+        state: owner_state(user)
+      }
+    end
+
+    def owners_map
+      options[:owners] || {}
+    end
+
+    # All three columns are host-owned and none is guaranteed: `deleted_at` only exists if the
+    # host's User is acts_as_paranoid (the same assumption OwnerResolver guards),
+    # `account_active` postdates some deployments, and `type` is there only on an STI User.
+    # A missing column means "nothing says otherwise", not a 500 on the whole Designer grid.
+    def owner_state(user)
+      return 'deleted' if user.respond_to?(:deleted_at) && user.deleted_at.present?
+      # `account_active` is nil on accounts predating the column and on non-Person types;
+      # only an explicit false means deactivated.
+      return 'deactivated' if user.respond_to?(:account_active) && user.account_active == false
+      # An admin-owned template has an owner who is neither gone nor disabled, so it read
+      # `active` and appeared in no banner list — yet a designer refused on it is told by
+      # `sc11` to ask that owner, and the request comes back 422: ELN's channel_type-8 fan-out
+      # inserts notifications for `type = 'Person'` only. Nothing told anyone that a transfer
+      # is what this template needs. Ordered last of the three: a deleted or deactivated admin
+      # is deleted or deactivated first. A blank `type` counts as unnotifiable too, because
+      # that same `type = 'Person'` filter skips it just as surely.
+      return 'unnotifiable' if user.respond_to?(:type) && user.type != 'Person'
+
+      'active'
+    end
   end
 end

data/lib/labimotion/entities/klass_share_entity.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'labimotion/entities/application_entity'
+module Labimotion
+  # One collaborator row in the Share modal. Exposes both the integer level and its label so
+  # the frontend neither hardcodes the numeric mapping nor loses the ordering the integers
+  # carry. The user block mirrors the owner block on GenericKlassEntity, `state` included —
+  # a share held by a departed user renders greyed out, it is never deleted (the account can
+  # be undeleted, and its shares should come back with it).
+  class KlassShareEntity < Labimotion::ApplicationEntity
+    expose :id, :klass_type, :klass_id, :created_by
+    expose :permission
+    expose :permission_level_value, as: :permission_level
+    expose :user
+    expose_timestamps(timestamp_fields: %i[created_at])
+
+    def permission
+      value = object.permission_level
+      value.is_a?(Integer) ? Labimotion::KlassShare::LEVELS.key(value)&.to_s : value.to_s
+    end
+
+    def permission_level_value
+      object.level
+    end
+
+    def user
+      resolved = options[:users]&.[](object.shared_with_id) ||
+                 Labimotion::OwnerResolver.find(object.shared_with_id)
+      return { id: object.shared_with_id, name: nil, name_abbreviation: nil, state: 'unknown' } if resolved.nil?
+
+      {
+        id: object.shared_with_id,
+        name: resolved.name,
+        name_abbreviation: resolved.name_abbreviation,
+        state: user_state(resolved)
+      }
+    end
+
+    private
+
+    def user_state(user)
+      return 'deleted' if user.respond_to?(:deleted_at) && user.deleted_at.present?
+      return 'deactivated' if user.respond_to?(:account_active) && user.account_active == false
+
+      'active'
+    end
+  end
+end

data/lib/labimotion/helpers/dataset_helpers.rb

@@ -31,6 +31,9 @@ module Labimotion
           { status: 'success', message: "This dataset: #{attributes['label']} has the latest version!" }
         else
           ds = Labimotion::DatasetKlass.find_by(ols_term_id: attributes['ols_term_id'])
+          # Upgrading bumps the version and cuts a revision — :release, owner-only; the gate
+          # lives on the update branch because only the ols_term_id lookup decides it.
+          authorize_klass!(ds, :release)
           ds.update!(attributes)
           ds.create_klasses_revision(current_user)
           { status: 'success',
@@ -38,7 +41,13 @@ module Labimotion
         end
       else
         attributes['created_by'] = current_user.id
-        ds = Labimotion::DatasetKlass.create!(attributes)
+        # The owner row shares the create's transaction: a klass committed without it is
+        # owner-less, which falls open to the legacy designer-wide gate.
+        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',
           message: "The dataset: #{attributes['label']} has been created using version: #{attributes['version']}!" }
@@ -49,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]
@@ -60,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: '',