labimotion 2.4.0.rc5 → 2.4.0.rc7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e6b4cffa98971ea0ef93e54a537710c7fdc587f2433f038a54f42be1ac63f21
-  data.tar.gz: b57ba99244c3b9ec975fef1acb2c1b588b8d9bee5a5d6c356d336bc247c08738
+  metadata.gz: baacaf6374ee395ea0178ebb5d0ecf6d3fef5a0f37bb17852e4742ac6442ccee
+  data.tar.gz: 01ab63f69e28a3d990480c9dd6eb747f26bc7cc727c57ddcb94034a8e987937e
 SHA512:
-  metadata.gz: c727c0b2409e463b0e6130986ebdcc528cf6473696b2124889061557f365ec163cc1393d08662b258801ddadafd16f7134e82786d759121b915e47b499814b55
-  data.tar.gz: 84ac6b69a8326012b61eae9aefef2f248c85ac22fa45cf266cf03114378a0cde2d1839f0798d3d460d35223000283db2a7ee4dcb3bdcfa4e4faac414ad01460b
+  metadata.gz: 5463d7bffb59f2ef5ef5e664a8ac97fb28557965942a0b182ca2834ec33cc0d81a1ef275799f9b0b7cadb93c1851eff0dbf429c115c863d336c92e91d68395fb
+  data.tar.gz: b83156927689da21c02e5a632d526fd1eafb9cd93695ef407fc88cf6b7d65a49593519cb36b2ed9c93afffcb935bbfe3ad274950e549839f6ca40a605a4ec82f

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,63 @@ 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
+        # 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
+        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/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/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/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/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: '',