labimotion 2.3.0 → 2.4.0.rc11

data/lib/labimotion/helpers/cover_image_helpers.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'grape'
+require 'labimotion/constants'
+
+module Labimotion
+  ## Element cover images (chem-generic-ui#1050, labimotion#259).
+  ## `cover_images` is the one element-metadata key whose shape the gem owns:
+  ## validation and normalization of the stored references, their direct
+  ## save, the resolution of a reference to the attachment holding its
+  ## picture, and the bytes served for the display area (originals), the
+  ## picker rows (thumbnails) and the docx export.
+  module CoverImageHelpers
+    extend Grape::API::Helpers
+
+    # Element metadata is a client-round-tripped document with several writers —
+    # layer groups/restrictions from the element details page, host regComps
+    # through the registry seam — and those writers remove a key by omitting it.
+    # So a present :metadata param replaces the stored hash wholesale; only an
+    # absent param leaves the stored metadata untouched (an old client that does
+    # not send :metadata must never wipe a saved cover selection). `cover_images`
+    # is the one key the gem owns: its entries are validated against the picker's
+    # cap and source vocabulary and normalized to exactly source/id, so nothing
+    # else reaches the jsonb column through that key.
+    def prepare_element_metadata(stored, incoming)
+      return stored || {} if incoming.nil?
+
+      # to_h returns self for a plain Hash — dup so the caller's copy stays intact.
+      metadata = incoming.to_h.dup
+      return metadata unless metadata.key?('cover_images') || metadata.key?(:cover_images)
+
+      entries = metadata.key?('cover_images') ? metadata['cover_images'] : metadata[:cover_images]
+      metadata.delete(:cover_images)
+      metadata['cover_images'] = validate_cover_images!(entries)
+      metadata
+    end
+
+    def validate_cover_images!(entries)
+      cover_images_error!('must be an array') unless entries.is_a?(Array)
+      max = Constants::CoverImage::MAX
+      cover_images_error!("holds at most #{max} entries") if entries.size > max
+
+      entries.map { |entry| normalized_cover_image!(entry) }
+    end
+
+    def normalized_cover_image!(entry)
+      cover_image_entry_error! unless entry.is_a?(Hash)
+      source = entry['source'] || entry[:source]
+      id = entry['id'] || entry[:id]
+      cover_image_entry_error! unless Constants::CoverImage::SOURCES.include?(source) && id.is_a?(Integer)
+      { 'source' => source, 'id' => id }
+    end
+
+    def cover_image_entry_error!
+      cover_images_error!("entries must be { source: #{Constants::CoverImage::SOURCES.join(' | ')}, id: integer }")
+    end
+
+    def cover_images_error!(reason)
+      error!("metadata.cover_images #{reason}", 422)
+    end
+
+    # Direct write of the one gem-owned metadata key (the cover picker's
+    # Save): a targeted merge, deliberately narrower than the element save's
+    # wholesale-replace contract — this writer owns exactly cover_images and
+    # can neither wipe nor resurrect any other key. Live like klass settings:
+    # not versioned until the next element save snapshots metadata.
+    def save_cover_images(element, entries)
+      validated = validate_cover_images!(entries)
+      element.update!(metadata: (element.metadata || {}).merge('cover_images' => validated))
+      validated
+    end
+
+    # Resolves a stored cover-image reference to the Attachment holding its
+    # picture, or nil. Ownership is part of the resolution: an attachment is
+    # looked up through the element's own association, an analysis must be one
+    # of the element's analyses — a foreign id answers nil, never a file.
+    def cover_image_attachment(element, source, sid)
+      case source
+      when 'attachment'
+        element.attachments.find_by(id: sid)
+      when 'analysis'
+        container = element.analyses.find_by(id: sid)
+        container && analysis_preview_attachment(container)
+      end
+    end
+
+    # Server twin of the ELN client's getContainerImageData: among the
+    # thumbnail-bearing attachments of the analysis' dataset children, the
+    # container's preferred_thumbnail wins while it still exists, then the
+    # newest "combined" image, then the newest overall.
+    def analysis_preview_attachment(container)
+      dataset_ids = container.children.where(container_type: 'dataset').pluck(:id)
+      return nil if dataset_ids.empty?
+
+      candidates = Attachment.where(attachable_type: 'Container', attachable_id: dataset_ids, thumb: true).to_a
+      pick_preview_attachment(container, candidates)
+    end
+
+    def pick_preview_attachment(container, candidates)
+      return nil if candidates.empty?
+
+      preferred = preferred_candidate(container, candidates)
+      return preferred if preferred
+
+      combined = candidates.select { |att| att.filename.to_s.downcase.include?('combined') }
+      (combined.empty? ? candidates : combined).max_by(&:updated_at)
+    end
+
+    # hstore values are strings — the stored preferred_thumbnail id arrives as '1'.
+    def preferred_candidate(container, candidates)
+      preferred_id = (container.extended_metadata || {})['preferred_thumbnail'].to_i
+      candidates.find { |att| att.id == preferred_id }
+    end
+
+    # The picker's rows ask for variant=thumbnail — the small uniform PNG;
+    # everything else means the original (display area). An svg's STORED
+    # thumbnail is black (see cover_rasterize), so it is re-rasterized from
+    # the original instead, falling back to the stored one.
+    def cover_image_body(att, variant)
+      return cover_image_payload(att) unless variant == 'thumbnail'
+
+      thumb = svg_cover_thumbnail(att) || att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    end
+
+    COVER_THUMB_RESIZE = '256x256>'
+
+    def svg_cover_thumbnail(att)
+      mime = att.content_type.to_s.downcase
+      return nil unless mime.include?('svg')
+
+      data = att.read_file
+      data && cover_rasterize(data, mime, resize: COVER_THUMB_RESIZE)
+    end
+
+    ## ImageMagick's own SVG renderer reads the CSS keyword `transparent` as
+    ## black — the defect behind the ELN thumbnails' black background — so
+    ## paint properties are normalized to `none` first and the result is a
+    ## PNG flattened onto white. Nil when conversion is unavailable or
+    ## fails; callers fall back.
+    SVG_TRANSPARENT_RE =
+      /((?:fill|stroke|stop-color|flood-color|background(?:-color)?)\s*[:=]\s*["']?)transparent\b/i
+
+    def cover_rasterize(data, mime, resize: nil)
+      # Deferred on purpose: mini_magick is a host-bundle gem, not a
+      # dependency of this gem — at the top of the file it would break gem
+      # load (and the spec suite) on a host without it, while here a miss is
+      # rescued below into the nil fallback.
+      require 'mini_magick'
+      data = data.gsub(SVG_TRANSPARENT_RE, '\1none') if mime.include?('svg')
+      image = MiniMagick::Image.read(data, cover_read_ext(mime))
+      image.format('png') do |convert|
+        convert.background('white')
+        convert.flatten
+        convert.resize(resize) if resize
+      end
+      image.to_blob
+    rescue LoadError, StandardError => e
+      Labimotion.log_exception(e)
+      nil
+    end
+
+    def cover_read_ext(mime)
+      subtype = mime.split('/').last.to_s.sub('+xml', '')
+      subtype.empty? ? '.img' : ".#{subtype}"
+    end
+
+    # The bytes + content type to serve for a cover attachment: the original
+    # file whenever a browser can render it, otherwise the PNG thumbnail
+    # (TIFF originals, raw-data files behind an analysis preview). Nil when
+    # neither is readable.
+    def cover_image_payload(att)
+      if att.type_image? && !att.type_image_tiff?
+        data = att.read_file
+        return [data, att.content_type] if data
+      end
+      thumb = att.read_thumbnail
+      [thumb, 'image/png'] if thumb
+    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,168 @@ 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
+      }
+
+      # 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)
+      # `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)
+      { 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
+      )
+      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]
@@ -60,6 +231,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: '',