nitro_intelligence 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c43b6d21a0be3ea130217218e82e017b7f01d5be0a8dcafeb55578741f6097fd
-  data.tar.gz: c872f0b16af367955b74116a54f62de096688f461e365f04ee2184351c7ca020
+  metadata.gz: 0e7cc3cbb0388e9001c106d00fddb60d6e1d7f2c3b9b54aa50d842e9ed719b8f
+  data.tar.gz: c1fce6397a2b3bba37ac56531c27608f9e8503e11603c0d9d2634a77dc17937f
 SHA512:
-  metadata.gz: 472a5f7d3b53b76f2967cdc38456b0ee5926f29900036bd1ff44ac0d03615e53226d8a47191a75d07727c70f8566a7855b5e3dbf3721dae3554814d8a13d93a4
-  data.tar.gz: 4a2c14cc4556cb88a658ae4994af79d2c8a001921accdfb9b731afeb210ea706e4307f9ea45a104abb061254263fa55d23f114007cdef9d35ffb70114c9116c0
+  metadata.gz: 5c40c5f964e4e9c5441460f7c5113ea4e55d83e73ed9be8cc82c8021a0b8d69772ea8f29a3de6b9a3706557fb8260377bebac2231542cfcbd940ef3973156a6c
+  data.tar.gz: ee972990ddda7041e3a756384022e46c68bc3e8af6e5188c545ad559e1c46618b7a1c0a5733940dd093c7a3d73aeb71a2012266de082776a3ec945b32c925067

data/docs/CHANGELOG.md

@@ -5,7 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [4.1.1](https://github.com/powerhome/nitro-intelligence.rb/compare/v4.1.0...v4.1.1) (2026-11-05)
+
+
+### Fixed
+
+* reject a model of the wrong type before sending a request ([#181](https://github.com/powerhome/nitro-intelligence.rb/issues/181)) ([c84955d](https://github.com/powerhome/nitro-intelligence.rb/commit/c84955d9b3751f1c456ff1e03df48fa962204b7e))
 
 ## [4.1.0] - 2026-11-04
 
@@ -223,7 +228,6 @@ Each warns through `NitroIntelligence.deprecator`, and is removed in 5.0. See [U
 - Require Ruby 3.3 or later (#10)
 - Upgrade langfuse-rb to 0.7.0. (#12)
 
-[Unreleased]: https://github.com/powerhome/nitro-intelligence.rb/compare/v4.1.0-nitro_intelligence...HEAD
 [4.1.0]: https://github.com/powerhome/nitro-intelligence.rb/compare/v4.0.0-nitro_intelligence...v4.1.0-nitro_intelligence
 [4.0.0]: https://github.com/powerhome/nitro-intelligence.rb/compare/v3.1.0-nitro_intelligence...v4.0.0-nitro_intelligence
 [3.1.0]: https://github.com/powerhome/nitro-intelligence.rb/compare/v3.0.2-nitro_intelligence...v3.1.0-nitro_intelligence

data/lib/nitro_intelligence/client/client.rb

@@ -26,8 +26,8 @@ module NitroIntelligence
     end
 
     # @api private
-    def self.validate_model(model)
-      raise ArgumentError, "Unsupported model: '#{model}'" unless NitroIntelligence.model_catalog.exists?(model)
+    def self.validate_model(model, type: Model)
+      NitroIntelligence.model_catalog.fetch(model, type:)
     end
   end
 end

data/lib/nitro_intelligence/client/handlers/audio_transcription_handler.rb

@@ -14,9 +14,7 @@ module NitroIntelligence
         end
 
         def perform_request(audio_file:, message: "", parameters: {}, correlation_trace_id: nil, mask_content: false)
-          add_request_headers(parameters, MODALITY_HEADER => "audio", REQUESTED_MODEL_HEADER => parameters[:model])
-          add_correlation_headers(parameters, trace_id: correlation_trace_id)
-          add_message_redaction_header(parameters, mask_content:)
+          add_gateway_headers(parameters, correlation_trace_id:, mask_content:, modality: "audio")
           @client.audio.transcriptions.create(
             prompt: message,
             file: audio_file,
@@ -31,7 +29,7 @@ module NitroIntelligence
           }
 
           parameters.replace(default_parameters.merge(parameters))
-          Client.validate_model(parameters[:model])
+          Client.validate_model(parameters[:model], type: TextModel)
         end
       end
     end

data/lib/nitro_intelligence/client/handlers/base_handler.rb

@@ -119,6 +119,15 @@ module NitroIntelligence
           )
         end
 
+        # Every request to the gateway names the model asked for, and the modality where the
+        # route alone does not, carries the correlation headers and, for a project that masks
+        # content, asks the gateway to redact it from its logs.
+        def add_gateway_headers(parameters, correlation_trace_id:, mask_content:, modality: nil)
+          add_request_headers(parameters, MODALITY_HEADER => modality, REQUESTED_MODEL_HEADER => parameters[:model])
+          add_correlation_headers(parameters, trace_id: correlation_trace_id)
+          add_message_redaction_header(parameters, mask_content:)
+        end
+
         # A project that masks content in Cerebro keeps it out of the gateway's logs
         # too, so one setting decides where a request's content is recorded.
         def add_message_redaction_header(parameters, mask_content:)

data/lib/nitro_intelligence/client/handlers/chat_handler.rb

@@ -14,9 +14,7 @@ module NitroIntelligence
         end
 
         def perform_request(parameters: {}, correlation_trace_id: nil, mask_content: false)
-          add_request_headers(parameters, REQUESTED_MODEL_HEADER => parameters[:model])
-          add_correlation_headers(parameters, trace_id: correlation_trace_id)
-          add_message_redaction_header(parameters, mask_content:)
+          add_gateway_headers(parameters, correlation_trace_id:, mask_content:)
           @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
         end
 
@@ -33,7 +31,7 @@ module NitroIntelligence
           }
 
           parameters.replace(default_parameters.merge(parameters))
-          Client.validate_model(parameters[:model])
+          Client.validate_model(parameters[:model], type: TextModel)
         end
       end
     end

data/lib/nitro_intelligence/client/handlers/decision_handler.rb

@@ -34,9 +34,7 @@ module NitroIntelligence
         end
 
         def perform_request(state:, questions:, parameters: {}, correlation_trace_id: nil, mask_content: false)
-          add_request_headers(parameters, REQUESTED_MODEL_HEADER => parameters[:model])
-          add_correlation_headers(parameters, trace_id: correlation_trace_id)
-          add_message_redaction_header(parameters, mask_content:)
+          add_gateway_headers(parameters, correlation_trace_id:, mask_content:)
           response = @client.request(
             method: :post,
             path:,
@@ -54,12 +52,7 @@ module NitroIntelligence
           }
 
           parameters.replace(default_parameters.merge(parameters))
-          Client.validate_model(parameters[:model])
-          return if NitroIntelligence.model_catalog.lookup_by_name(parameters[:model]).is_a?(DecisionModel)
-
-          # A decision request has nothing in common with a chat one, so a model of another type
-          # would fail at the gateway with an error that does not say why.
-          raise ArgumentError, "Model '#{parameters[:model]}' is not a decision model"
+          Client.validate_model(parameters[:model], type: DecisionModel)
         end
 
       private

data/lib/nitro_intelligence/client/handlers/image_handler.rb

@@ -21,12 +21,12 @@ module NitroIntelligence
         end
 
         def perform_request(parameters: {}, correlation_trace_id: nil, mask_content: false)
-          add_request_headers(parameters, MODALITY_HEADER => "image", REQUESTED_MODEL_HEADER => parameters[:model])
-          add_correlation_headers(parameters, trace_id: correlation_trace_id)
-          add_message_redaction_header(parameters, mask_content:)
+          add_gateway_headers(parameters, correlation_trace_id:, mask_content:, modality: "image")
           @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
         end
 
+        # The model is not checked here: building the ImageGeneration already checked it, along
+        # with the aspect ratio and resolution it supports.
         def validate_and_resolve!(parameters, image_generation)
           default_parameters = {
             image_generation:,
@@ -45,7 +45,6 @@ module NitroIntelligence
           # Deep, so that request options a caller passes (headers, max_retries,
           # timeout) sit alongside the image config rather than replacing it.
           parameters.replace(default_parameters.deep_merge(parameters))
-          Client.validate_model(parameters[:model])
         end
 
       private

data/lib/nitro_intelligence/client/handlers/observed/audio_transcription_handler.rb

@@ -1,3 +1,4 @@
+require "nitro_intelligence/client/handlers/observed/base_handler"
 require "base64"
 require "nitro_intelligence/media/audio"
 require "nitro_intelligence/observability/prompt_resolver"
@@ -7,18 +8,13 @@ module NitroIntelligence
     module Handlers
       module Observed
         # @api private
-        class AudioTranscriptionHandler
+        class AudioTranscriptionHandler < BaseHandler
           # Raised by {Client::Base#transcribe_audio} on an observed client when the prompt it names
           # is not a text prompt.
           #
           # @api public
           class ObservedAudioTranscriptionPromptError < StandardError; end
 
-          def initialize(base_handler:, observer:)
-            @base_handler = base_handler
-            @observer = observer
-          end
-
           def create(audio_file:, message: +"", parameters: {})
             @base_handler.validate_and_resolve!(parameters)
 
@@ -39,10 +35,6 @@ module NitroIntelligence
 
         private
 
-          def project
-            @observer.project_client.project
-          end
-
           def handle_prompt(message:, parameters:)
             prompt = NitroIntelligence::Observability::PromptResolver.for(
               store: project.prompt_store,

data/lib/nitro_intelligence/client/handlers/observed/base_handler.rb

@@ -0,0 +1,23 @@
+module NitroIntelligence
+  module Client
+    module Handlers
+      module Observed
+        # Wraps a handler's request in an observation recorded to the observer's Cerebro project.
+        #
+        # @api private
+        class BaseHandler
+          def initialize(base_handler:, observer:)
+            @base_handler = base_handler
+            @observer = observer
+          end
+
+        private
+
+          def project
+            @observer.project_client.project
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/handlers/observed/chat_handler.rb

@@ -1,3 +1,4 @@
+require "nitro_intelligence/client/handlers/observed/base_handler"
 require "nitro_intelligence/observability/prompt_resolver"
 
 module NitroIntelligence
@@ -6,7 +7,7 @@ module NitroIntelligence
       # @api private
       module Observed
         # @api private
-        class ChatHandler
+        class ChatHandler < BaseHandler
           # Raised by {Client::Base#chat} on an observed client when the request carries no user
           # message for the model to answer: the prompt supplies only a system message, and the
           # caller passed no `message`.
@@ -14,11 +15,6 @@ module NitroIntelligence
           # @api public
           class ObservedChatPromptError < StandardError; end
 
-          def initialize(base_handler:, observer:)
-            @base_handler = base_handler
-            @observer = observer
-          end
-
           def create(message: "", parameters: {})
             @base_handler.validate_and_resolve!(parameters, message)
 
@@ -41,10 +37,6 @@ module NitroIntelligence
 
         private
 
-          def project
-            @observer.project_client.project
-          end
-
           # A chat completion needs a turn for the model to answer, and it is the model's own
           # chat template that insists on one: Qwen's raises "No user query found in
           # messages." Left to the gateway that costs a round trip and comes back as a 400

data/lib/nitro_intelligence/client/handlers/observed/decision_handler.rb

@@ -1,3 +1,5 @@
+require "nitro_intelligence/client/handlers/observed/base_handler"
+
 module NitroIntelligence
   module Client
     module Handlers
@@ -7,12 +9,7 @@ module NitroIntelligence
         # powerhome/cerebro#128.
         #
         # @api private
-        class DecisionHandler
-          def initialize(base_handler:, observer:)
-            @base_handler = base_handler
-            @observer = observer
-          end
-
+        class DecisionHandler < BaseHandler
           def create(state:, questions:, parameters: {})
             @base_handler.validate_and_resolve!(parameters)
 
@@ -33,10 +30,6 @@ module NitroIntelligence
 
         private
 
-          def project
-            @observer.project_client.project
-          end
-
           def workflow(generation:, state:, questions:, parameters:)
             decision = @base_handler.perform_request(
               state:, questions:, parameters:, correlation_trace_id: generation.trace_id,

data/lib/nitro_intelligence/client/handlers/observed/image_handler.rb

@@ -1,3 +1,4 @@
+require "nitro_intelligence/client/handlers/observed/base_handler"
 require "nitro_intelligence/media/image_generation"
 require "nitro_intelligence/observability/prompt_resolver"
 
@@ -6,12 +7,7 @@ module NitroIntelligence
     module Handlers
       module Observed
         # @api private
-        class ImageHandler
-          def initialize(base_handler:, observer:)
-            @base_handler = base_handler
-            @observer = observer
-          end
-
+        class ImageHandler < BaseHandler
           def create(message: "", target_image: nil, reference_images: [], parameters: {})
             image_generation = build_image_generation(message:, target_image:, reference_images:, parameters:)
 
@@ -36,10 +32,6 @@ module NitroIntelligence
 
         private
 
-          def project
-            @observer.project_client.project
-          end
-
           def build_image_generation(message:, target_image:, reference_images:, parameters:)
             NitroIntelligence::ImageGeneration.new(message:, target_image:, reference_images:) do |config|
               config.aspect_ratio = parameters[:aspect_ratio] if parameters.key?(:aspect_ratio)

data/lib/nitro_intelligence/client/handlers/observed/text_to_speech_handler.rb

@@ -1,3 +1,4 @@
+require "nitro_intelligence/client/handlers/observed/base_handler"
 require "nitro_intelligence/media/audio"
 require "nitro_intelligence/observability/prompt_resolver"
 
@@ -6,18 +7,13 @@ module NitroIntelligence
     module Handlers
       module Observed
         # @api private
-        class TextToSpeechHandler
+        class TextToSpeechHandler < BaseHandler
           # Raised by {Client::Base#text_to_speech} on an observed client when the prompt it names
           # is not a text prompt.
           #
           # @api public
           class ObservedTextToSpeechPromptError < StandardError; end
 
-          def initialize(base_handler:, observer:)
-            @base_handler = base_handler
-            @observer = observer
-          end
-
           def create(message: "", parameters: {})
             prompt = handle_prompt(parameters:)
 
@@ -39,10 +35,6 @@ module NitroIntelligence
 
         private
 
-          def project
-            @observer.project_client.project
-          end
-
           def handle_prompt(parameters:)
             prompt = NitroIntelligence::Observability::PromptResolver.for(
               store: project.prompt_store,

data/lib/nitro_intelligence/client/handlers/text_to_speech_handler.rb

@@ -14,9 +14,7 @@ module NitroIntelligence
         end
 
         def perform_request(message: "", parameters: {}, correlation_trace_id: nil, mask_content: false)
-          add_request_headers(parameters, MODALITY_HEADER => "audio", REQUESTED_MODEL_HEADER => parameters[:model])
-          add_correlation_headers(parameters, trace_id: correlation_trace_id)
-          add_message_redaction_header(parameters, mask_content:)
+          add_gateway_headers(parameters, correlation_trace_id:, mask_content:, modality: "audio")
           @client.audio.speech.create(
             input: message,
             **parameters.slice(*ALLOWED_EXTRA_PARAMETERS)
@@ -25,8 +23,7 @@ module NitroIntelligence
 
         def validate_and_resolve!(parameters)
           model_name = parameters[:model] || NitroIntelligence.model_catalog.default_text_to_speech_model&.name
-          model = NitroIntelligence.model_catalog.lookup_by_name(model_name)
-          raise ArgumentError, "Unsupported model: '#{model_name}'" unless model
+          model = Client.validate_model(model_name, type: TextToSpeechModel)
 
           default_parameters = {
             metadata: {},

data/lib/nitro_intelligence/media/image_generation.rb

@@ -123,8 +123,7 @@ module NitroIntelligence
 
     def validate_config!
       # Check model supported
-      @model = NitroIntelligence.model_catalog.lookup_by_name(@config.model)
-      raise ArgumentError, "Unsupported model: '#{@config.model}'" unless @model
+      @model = NitroIntelligence.model_catalog.fetch(@config.model, type: ImageModel)
 
       # Check aspect_ratio supported
       unless @model.aspect_ratios.include?(@config.aspect_ratio)

data/lib/nitro_intelligence/models/model.rb

@@ -1,6 +1,11 @@
 module NitroIntelligence
   # @api private
   class Model
+    # What the model is for, as an error names it: "image" for ImageModel, "text-to-speech" for
+    # TextToSpeechModel. Taken from the class name, so a new kind of model has one without
+    # declaring it.
+    def self.kind = name.demodulize.delete_suffix("Model").underscore.dasherize
+
     attr_reader :name, :omit_output_fields
 
     def initialize(name:, omit_output_fields: [], **)

data/lib/nitro_intelligence/models/model_catalog.rb

@@ -24,6 +24,21 @@ module NitroIntelligence
       @models.find { |model| model.name == name }
     end
 
+    # The named model, checked to be of the type a request needs. A model of another type
+    # would fail at the gateway, or deep in a handler's own validation, with an error that
+    # does not say why.
+    def fetch(name, type: Model)
+      model = lookup_by_name(name)
+      raise ArgumentError, "Unsupported model: '#{name}'" unless model
+
+      return model if model.is_a?(type)
+
+      article = type.kind.start_with?(/[aeiou]/) ? "an" : "a"
+      raise ArgumentError, "Model '#{name}' is not #{article} #{type.kind} model"
+    end
+
+    # Unused within the gem, which validates through #fetch, but kept for applications that check
+    # whether a model is configured before offering it.
     def exists?(name)
       lookup_by_name(name).present?
     end

data/lib/nitro_intelligence/version.rb

@@ -1,4 +1,4 @@
 module NitroIntelligence
   # The gem's version.
-  VERSION = "4.1.0".freeze
+  VERSION = "4.1.1".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1
 platform: ruby
 authors:
 - Igor Artemenko
@@ -90,6 +90,7 @@ files:
 - lib/nitro_intelligence/client/handlers/decision_handler.rb
 - lib/nitro_intelligence/client/handlers/image_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/audio_transcription_handler.rb
+- lib/nitro_intelligence/client/handlers/observed/base_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/chat_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/decision_handler.rb
 - lib/nitro_intelligence/client/handlers/observed/image_handler.rb