labimotion 2.4.0.rc6 → 2.4.0.rc7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa32d7e24804c4f270efdbce75bccf847ae3d30ae1f6b265c17b9c196e9c12a6
-  data.tar.gz: b6901471f70ac6874bf68a517ea9d994a3e4054d089a2bc66e042de38e97f4fd
+  metadata.gz: baacaf6374ee395ea0178ebb5d0ecf6d3fef5a0f37bb17852e4742ac6442ccee
+  data.tar.gz: 01ab63f69e28a3d990480c9dd6eb747f26bc7cc727c57ddcb94034a8e987937e
 SHA512:
-  metadata.gz: b6612883678081acfa046ea9956424f06b512f5ea941cac2dd219e60809f0ed308026d9e0e8c9a112e067b8718f4a2b55939211b0843100d6329a9502341ddee
-  data.tar.gz: c52a79f87e8dffb30d340be92e107e6518c96e3c28d46a6857e6355ff3e30ec399a989cce94553188b4baff83ac548d34d80083b185a523be8c31823bdc7e97c
+  metadata.gz: 5463d7bffb59f2ef5ef5e664a8ac97fb28557965942a0b182ca2834ec33cc0d81a1ef275799f9b0b7cadb93c1851eff0dbf429c115c863d336c92e91d68395fb
+  data.tar.gz: b83156927689da21c02e5a632d526fd1eafb9cd93695ef407fc88cf6b7d65a49593519cb36b2ed9c93afffcb935bbfe3ad274950e549839f6ca40a605a4ec82f

data/lib/labimotion/apis/generic_element_api.rb

@@ -232,6 +232,26 @@ module Labimotion
       # 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
+        # Auto-fill is the one AI action ordinary users reach — the designer's
+        # create/refine routes are admin-only — so it carries its own whitelist,
+        # supplied by the host: the genericElement AI list narrowed by
+        # :fill_uids. Reached through the host the same way this API already
+        # reaches ElementPolicy, and CLOSED when the host provides no such
+        # policy, matching how every other gate in this feature defaults.
+        # NameError, not defined?: under Zeitwerk `defined?` is nil until the
+        # constant has actually been referenced, so testing it would refuse the
+        # first request after every boot. Referencing it triggers the autoload;
+        # a host that genuinely ships no such policy raises, and that is a
+        # refusal too.
+        before do
+          allowed = begin
+            LabimotionAiAccess.fill_enabled_for?(current_user)
+          rescue NameError
+            false
+          end
+          error!({ status: 'error', message: 'AI auto-fill is not enabled for this account.' }, 403) unless allowed
+        end
+
         desc "Auto-fill a generic element's data values from a document using AI"
         params do
           use :ai_fill_element_data_params

data/lib/labimotion/apis/labimotion_ai_api.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require 'labimotion/version'
+
+module Labimotion
+  # Per-user LabIMotion AI settings: the model, an optional personal API key and
+  # an optional provider endpoint of one's own.
+  #
+  # These live on the HOST's user profile rather than in a gem table, because the
+  # credential belongs to the person, not to LabIMotion — so the routes stay
+  # under /profiles and reach the host's Profile through current_user, the same
+  # way the rest of this gem reaches ElementPolicy and Matrice.
+  #
+  # The API key is stored encrypted and never returned; a read only reports
+  # whether one is set.
+  class LabimotionAiAPI < Grape::API
+    # Fallback model choices when the server config (config/labimotion_ai.yml
+    # :models) lists none. A representative subset of the chat-capable KI-Toolbox
+    # models (ki-toolbox.scc.kit.edu); the full list lives in the yml.
+    DEFAULT_MODELS = %w[
+      azure.gpt-4.1-mini
+      azure.gpt-4.1
+      azure.gpt-5
+      azure.gpt-5-mini
+      google.claude-sonnet-4.6
+      google.claude-haiku-4.5
+      google.gemini-2.5-pro
+      kit.gpt-oss-120b
+    ].freeze
+
+    # rubocop:disable Metrics/BlockLength
+    resource :profiles do
+      namespace :labimotion_ai do
+        # Per-user LabIMotion AI settings (model + personal API key) for the
+        # AI dataset-template feature. The API key is stored encrypted and is
+        # never returned — only whether one is set.
+
+        # These settings only exist to serve the AI integration, so they follow
+        # the same whitelist (matrices.configs :ai_uids). Users off the list get
+        # a 403 rather than a settings page they cannot act on.
+        before do
+          error!({ status: false, error: 'AI integration is not enabled for this account.' }, 403) unless
+            Matrice.ai_enabled_for_any?(current_user)
+        end
+
+        helpers do
+          # Normalize a configured model entry (an id String, or a Hash with
+          # :id/:label) into { id:, label: }. Label falls back to the id.
+          def normalize_ai_model(entry)
+            if entry.respond_to?(:[]) && !entry.is_a?(String)
+              id = (entry[:id] || entry['id']).to_s
+              label = (entry[:label] || entry['label']).to_s
+            else
+              id = entry.to_s
+              label = ''
+            end
+            return nil if id.blank?
+
+            { id: id, label: label.presence || id }
+          end
+
+          # Add id (with a label) to models unless already present. Mutates models.
+          def append_ai_model(models, id)
+            return if id.blank? || models.any? { |m| m[:id] == id }
+
+            models << { id: id, label: id }
+          end
+
+          # The admin-approved models [{ id:, label: }] for the SHARED server key:
+          # the configured :models pick-list (or the built-in default) plus the
+          # server default (:model). No per-user selection — safe to enforce.
+          def labimotion_ai_server_models
+            configured = Rails.configuration.respond_to?(:labimotion_ai) ? Rails.configuration.labimotion_ai : nil
+            models = Array(configured && configured[:models]).filter_map { |e| normalize_ai_model(e) }
+            models = Labimotion::LabimotionAiAPI::DEFAULT_MODELS.map { |id| { id: id, label: id } } if models.empty?
+            append_ai_model(models, (configured && configured[:model]).to_s)
+            models
+          end
+
+          # The selectable models as [{ id:, label: }]. Extends the server models
+          # with the user's saved model so their current selection is always valid.
+          def labimotion_ai_models
+            models = labimotion_ai_server_models
+            append_ai_model(models, current_user.profile.labimotion_ai_model.to_s)
+            models
+          end
+
+          # Model ids the SHARED server key permits — the server models plus the
+          # ENV default. Unlike available_models this excludes the user's own saved
+          # model, so it is safe to enforce a keyless user's selection against.
+          def labimotion_ai_admin_model_ids
+            ids = labimotion_ai_server_models.pluck(:id)
+            (ids << ENV['KI_TOOLBOX_MODEL'].to_s).compact_blank.uniq
+          end
+
+          # A well-formed https URL with a host. The deep SSRF check (host resolves
+          # to a public address) runs server-side in the gem at request time; this
+          # is only a fast format check for immediate UI feedback.
+          def https_endpoint?(url)
+            uri = URI.parse(url.to_s.strip)
+            uri.is_a?(URI::HTTPS) && uri.host.present?
+          rescue URI::InvalidURIError
+            false
+          end
+
+          # A personal provider endpoint is only usable with a personal key, and
+          # must be a valid https URL. Raises a 422 otherwise; no-op when unset.
+          def validate_ai_endpoint!(base_url_arg, will_have_key)
+            return if base_url_arg.blank?
+
+            unless will_have_key
+              error!(
+                { status: false, error: 'Add your personal API key to use your own AI provider endpoint.' },
+                422
+              )
+            end
+            return if https_endpoint?(base_url_arg)
+
+            error!({ status: false, error: 'The AI provider endpoint must be a valid https:// URL.' }, 422)
+          end
+        end
+
+        desc 'get the current user LabIMotion AI settings (never returns the key)'
+        get do
+          profile = current_user.profile
+          configured = Rails.configuration.respond_to?(:labimotion_ai) ? Rails.configuration.labimotion_ai : nil
+          {
+            model: profile.labimotion_ai_model,
+            api_key_set: profile.labimotion_ai_api_key?,
+            base_url: profile.labimotion_ai_base_url,
+            api_path: profile.labimotion_ai_api_path,
+            available_models: labimotion_ai_models,
+            default_model: (configured && configured[:model]).presence,
+            default_base_url: (configured && configured[:base_url]).presence,
+            server_api_key_set: (configured && configured[:api_key]).present?
+          }
+        end
+
+        desc 'update the current user LabIMotion AI settings'
+        params do
+          optional :model, type: String, desc: 'Selected model id'
+          optional :api_key, type: String, desc: 'Personal API key (stored encrypted)'
+          optional :clear_api_key, type: Boolean, default: false, desc: 'Remove the stored API key'
+          optional :base_url, type: String, desc: 'Personal AI provider base URL (https; needs a personal key)'
+          optional :api_path, type: String, desc: 'Personal AI provider chat-completions path'
+          optional :clear_endpoint, type: Boolean, default: false, desc: 'Remove the stored provider endpoint'
+        end
+        put do
+          profile = current_user.profile
+          api_key_arg =
+            if params[:clear_api_key]
+              '' # blank -> clear
+            elsif params[:api_key].present?
+              params[:api_key]
+            end
+          # nil -> keep the stored key
+
+          # Whether the user will hold a personal key after this save.
+          will_have_key =
+            if params[:clear_api_key]
+              false
+            elsif params[:api_key].present?
+              true
+            else
+              profile.labimotion_ai_api_key?
+            end
+          # A keyless user's AI calls run on the shared server key, so the chosen
+          # model must be one the admin approved. A user on their own key may pick
+          # any model. Enforce only when an allowlist is actually configured.
+          if params[:model].present? && !will_have_key
+            allowed = labimotion_ai_admin_model_ids
+            if allowed.any? && allowed.exclude?(params[:model])
+              error!(
+                { status: false,
+                  error: 'That model is not available on the shared server key. Pick a listed ' \
+                         'model, or add your personal API key in My LabIMotion to use it.' },
+                422
+              )
+            end
+          end
+
+          # base_url/api_path: '' clears (via clear_endpoint), a value sets, nil keeps.
+          base_url_arg = params[:clear_endpoint] ? '' : params[:base_url]
+          api_path_arg = params[:clear_endpoint] ? '' : params[:api_path]
+          validate_ai_endpoint!(base_url_arg, will_have_key)
+
+          summary = profile.update_labimotion_ai(
+            model: params[:model].presence, api_key: api_key_arg,
+            base_url: base_url_arg, api_path: api_path_arg
+          )
+          {
+            model: summary[:model],
+            api_key_set: summary[:api_key_set],
+            base_url: summary[:base_url],
+            api_path: summary[:api_path],
+            available_models: labimotion_ai_models
+          }
+        rescue StandardError => e
+          error!({ status: false, error: e.message }, 422)
+        end
+
+        desc 'fetch the live model list from the AI provider with the user personal key'
+        post 'models' do
+          profile = current_user.profile
+          # Deliberately the PERSONAL key only: the shared server key must not be
+          # sent to a user-supplied provider URL, and a keyless user's model choice
+          # is restricted to labimotion_ai_admin_model_ids anyway.
+          result = Labimotion::AiModels.new(
+            api_key: profile.labimotion_ai_api_key,
+            base_url: profile.labimotion_ai_base_url,
+            api_path: profile.labimotion_ai_api_path
+          ).call
+          { status: true, models: result[:models], endpoint: result[:endpoint] }
+        rescue StandardError => e
+          error!({ status: false, error: e.message }, 422)
+        end
+
+        desc 'test the current user LabIMotion AI connection (nothing is saved)'
+        post 'test' do
+          profile = current_user.profile
+          # Same values the runtime override path reads, so the test exercises the
+          # real config: base_url/api_path are honored by the gem only alongside a
+          # personal key, and a custom endpoint is SSRF-validated there.
+          result = Labimotion::AiTemplate.ping(
+            model: profile.labimotion_ai_model,
+            api_key: profile.labimotion_ai_api_key,
+            base_url: profile.labimotion_ai_base_url,
+            api_path: profile.labimotion_ai_api_path
+          )
+          { status: true, ok: true, model: result['model'],
+            endpoint: result['endpoint'], ms: result['ms'] }
+        rescue StandardError => e
+          error!({ status: false, ok: false, error: e.message }, 422)
+        end
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end

data/lib/labimotion/apis/labimotion_api.rb

@@ -12,7 +12,9 @@ module Labimotion
     mount Labimotion::LabimotionHubAPI
     mount Labimotion::StandardLayerAPI
     mount Labimotion::VocabularyAPI
+    mount Labimotion::OntologyRootAPI
     mount Labimotion::UserAPI
+    mount Labimotion::LabimotionAiAPI
     mount Labimotion::UserKlassSettingsAPI
     mount Labimotion::KlassShareAPI
     mount Labimotion::MttAPI

data/lib/labimotion/apis/ontology_root_api.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'labimotion/version'
+
+module Labimotion
+  # Serves the stored subtree behind one "ontology-select" root, and lets a user
+  # refresh it.
+  #
+  # The client sends the `ontology_term` string its field already holds and the
+  # server derives the file path from it. Nothing about the naming scheme is
+  # public, so it can change later without touching the frontend or migrating
+  # anything — worst case the files are fetched again.
+  #
+  # One root per request. A field may pin several, and the picker already walks
+  # them one at a time.
+  class OntologyRootAPI < Grape::API
+    helpers Labimotion::GenericHelpers
+
+    resource :ontology_roots do
+      helpers do
+        # The one root a request is about, or a 400 naming what was unusable.
+        def ontology_root!(term)
+          root = Labimotion::OntologyTerms.parse(term).first
+          error!({ status: 'error', message: 'not a usable ontology term' }, 400) if root.nil?
+
+          root
+        end
+
+        def refresher
+          current_user.respond_to?(:name_abbreviation) ? current_user.name_abbreviation : nil
+        rescue StandardError
+          nil
+        end
+      end
+
+      desc "One root's subtree, as the picker and the auto-fill both read it"
+      params do
+        requires :term, type: String, desc: "The field's ontology_term value"
+      end
+      get do
+        root = ontology_root!(params[:term])
+        doc = Labimotion::OntologyStore.document(root, synced_by: refresher)
+        if doc.nil?
+          # The store could not be filled and the service could not be reached.
+          # The picker falls back to what it can, rather than showing an empty
+          # vocabulary as though the ontology genuinely had no terms.
+          { status: 'error', message: 'this ontology could not be reached' }
+        else
+          { status: 'success', root: doc }
+        end
+      rescue StandardError => e
+        Labimotion.log_exception(e, current_user)
+        { status: 'error', message: e.message }
+      end
+
+      desc 'Re-fetch this root from the ontology service and store what comes back'
+      params do
+        requires :term, type: String, desc: "The field's ontology_term value"
+      end
+      post :refresh do
+        root = ontology_root!(params[:term])
+        { status: 'success', root: Labimotion::OntologyStore.refresh!(root, synced_by: refresher) }
+      rescue Labimotion::OntologyStore::Error => e
+        # Expected refusals — already refreshed a moment ago, someone else is
+        # refreshing, the result came back empty or collapsed. The person who
+        # pressed the button gets the reason; what is stored is untouched.
+        { status: 'error', message: e.message }
+      rescue StandardError => e
+        Labimotion.log_exception(e, current_user)
+        { status: 'error', message: e.message }
+      end
+    end
+  end
+end

data/lib/labimotion/conf.rb

@@ -3,4 +3,9 @@
 ## Labimotion Configuration
 module Labimotion
   KLASSES_JSON = Rails.root.join('public', 'klasses.json').to_s.freeze # Rails.root.join('app/packs/klasses.json').to_s.freeze
+
+  # One JSON file per ontology root, holding the subtree an "ontology-select"
+  # field may offer. Sits under the host's public/ontologies, which the ELN
+  # already gitignores and already lets this gem write to (see KLASSES_JSON).
+  ONTOLOGY_ROOTS_DIR = Rails.public_path.join('ontologies', 'roots').to_s.freeze
 end

data/lib/labimotion/constants.rb

@@ -51,6 +51,17 @@ module Labimotion
       LINKED_EL_ATTRS = 'linked_el_attrs'
     end
 
+    # The independent sub-settings held side by side in a KLASS's own `settings`
+    # jsonb (element_klasses / segment_klasses / dataset_klasses). A save
+    # shallow-merges, so writing one never disturbs the others.
+    module KlassSetting
+      LAYER_FUNCTIONS = 'layer_functions'
+      COVER_IMAGE = 'cover_image'
+      # Template-specific guidance for the AI data auto-fill, written by the
+      # designer and read by Labimotion::AiTemplate.fill.
+      AI_FILL_PROMPT = 'ai_fill_prompt'
+    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

data/lib/labimotion/helpers/element_helpers.rb

@@ -136,8 +136,9 @@ module Labimotion
       text = ai_fill_source_text(element, params)
       overrides = ai_user_overrides(current_user)
       ai = Labimotion::AiTemplate.fill(
-        properties: element.properties,
+        properties: ai_fill_properties(element),
         context_text: text,
+        instructions: ai_fill_instructions(element),
         **overrides
       )
       { status: 'success', values: ai['values'], summary: ai['summary'] }
@@ -146,6 +147,43 @@ module Labimotion
       { status: 'error', message: e.message }
     end
 
+    # The element's properties, with the select_options its own fields point at.
+    #
+    # An element instance never stores select_options: create and update both
+    # delete the key (see create_element/update_element below), because the
+    # options belong to the template, not to the instance. The fill prompt lists
+    # a select's allowed options so the model can pick one, and reads them out
+    # of the properties it is handed — so passing element.properties straight
+    # through offered the model an EMPTY list for every select and select-multi
+    # field. Nothing to choose from, so those fields came back unfilled, which
+    # reads as the AI having ignored them.
+    #
+    # properties_release, not the klass's current properties_template: it is the
+    # release this element was actually built against, so its option keys are the
+    # ones the element's fields reference and the ones the form will accept back.
+    # Same source the UI and the exporter read for this element.
+    def ai_fill_properties(element)
+      props = element.properties
+      return props unless props.is_a?(Hash)
+      return props if props['select_options'].present?
+
+      release = element.properties_release
+      options = release.is_a?(Hash) ? release['select_options'] : nil
+      return props if options.blank?
+
+      props.merge('select_options' => options)
+    end
+
+    # The template's own auto-fill guidance, from Template settings in the designer.
+    # Read from the KLASS rather than the element's copied properties, so editing it
+    # takes effect on elements that already exist instead of only on new ones.
+    def ai_fill_instructions(element)
+      settings = element.element_klass&.settings
+      return nil unless settings.is_a?(Hash)
+
+      settings[Labimotion::Constants::KlassSetting::AI_FILL_PROMPT].presence
+    end
+
     # Resolve the requested source into plain text, enforcing ownership first.
     def ai_fill_source_text(element, params)
       case params[:source]
@@ -155,6 +193,8 @@ module Labimotion
         ai_fill_analysis_text(element, params[:container_id])
       when 'upload'
         ai_fill_upload_text(params[:files])
+      when 'text'
+        ai_fill_pasted_text(params[:text])
       else
         error!('400 Bad Request', 400)
       end
@@ -205,6 +245,16 @@ module Labimotion
       parts.join("\n\n")
     end
 
+    # Text pasted straight into the dialog. Capped like an extracted file so a
+    # very long paste cannot blow the model's context or the request budget —
+    # the same MAX_FILE_CHARS the file path is held to.
+    def ai_fill_pasted_text(text)
+      body = text.to_s.strip
+      error!('400 Bad Request', 400) if body.empty?
+
+      body[0, Labimotion::AiTemplate::MAX_FILE_CHARS].to_s
+    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)

data/lib/labimotion/helpers/param_helpers.rb

@@ -66,9 +66,10 @@ module Labimotion
     # `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'
+      requires :source, type: String, values: %w[attachment analysis upload text], 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 :text, type: String, desc: 'Pasted plain text (source == text)'
       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)'