flow_chat 0.6.1 → 0.7.0

data/lib/flow_chat/instrumentation/log_subscriber.rb

@@ -0,0 +1,176 @@
+module FlowChat
+  module Instrumentation
+    class LogSubscriber
+      # Flow execution events
+      def flow_execution_start(event)
+        payload = event.payload
+        FlowChat.logger.info { "Flow Execution Started: #{payload[:flow_name]}##{payload[:action]} [Session: #{payload[:session_id]}]" }
+      end
+
+      def flow_execution_end(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.info { "Flow Execution Completed: #{payload[:flow_name]}##{payload[:action]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+      end
+
+      def flow_execution_error(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.error { "Flow Execution Failed: #{payload[:flow_name]}##{payload[:action]} (#{duration}ms) - #{payload[:error_class]}: #{payload[:error_message]} [Session: #{payload[:session_id]}]" }
+      end
+
+      # Session events
+      def session_created(event)
+        payload = event.payload
+        FlowChat.logger.info { "Session Created: #{payload[:session_id]} [Store: #{payload[:store_type]}, Gateway: #{payload[:gateway]}]" }
+      end
+
+      def session_destroyed(event)
+        payload = event.payload
+        FlowChat.logger.info { "Session Destroyed: #{payload[:session_id]} [Gateway: #{payload[:gateway]}]" }
+      end
+
+      def session_cache_hit(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Cache Hit: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_cache_miss(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Cache Miss: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_data_set(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Data Set: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_data_get(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Data Get: #{payload[:session_id]} - Key: #{payload[:key]} = #{payload[:value].inspect}" }
+      end
+
+      # Middleware events
+      def middleware_before(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Middleware Before: #{payload[:middleware_name]} [Session: #{payload[:session_id]}]" }
+      end
+
+      def middleware_after(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.debug { "Middleware After: #{payload[:middleware_name]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+      end
+
+      # Platform-agnostic events (new scalable approach)
+      def message_received(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+
+        case platform.to_sym
+        when :whatsapp
+          contact_info = payload[:contact_name] ? " (#{payload[:contact_name]})" : ""
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]}#{contact_info} - Type: #{payload[:message_type]} [ID: #{payload[:message_id]}]" }
+        when :ussd
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]} - Input: '#{payload[:message]}' [Session: #{payload[:session_id]}]" }
+        else
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]} - Message: '#{payload[:message]}' [Session: #{payload[:session_id]}]" }
+        end
+      end
+
+      def message_sent(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        case platform.to_sym
+        when :whatsapp
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms) [Length: #{payload[:content_length]} chars]" }
+        when :ussd
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+        else
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms)" }
+        end
+      end
+
+      def webhook_verified(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.info { "#{platform_name} Webhook Verified Successfully [Challenge: #{payload[:challenge]}]" }
+      end
+
+      def webhook_failed(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.warn { "#{platform_name} Webhook Verification Failed: #{payload[:reason]}" }
+      end
+
+      def media_upload(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        if payload[:success] != false  # Check for explicit false, not just falsy
+          FlowChat.logger.info { "#{platform_name} Media Upload: #{payload[:filename]} (#{format_bytes(payload[:size])}, #{duration}ms) - Success" }
+        else
+          FlowChat.logger.error { "#{platform_name} Media Upload Failed: #{payload[:filename]} (#{duration}ms) - #{payload[:error]}" }
+        end
+      end
+
+      def pagination_triggered(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.info { "#{platform_name} Pagination Triggered: Page #{payload[:current_page]}/#{payload[:total_pages]} (#{payload[:content_length]} chars) [Session: #{payload[:session_id]}]" }
+      end
+
+      def api_request(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        if payload[:success]
+          FlowChat.logger.debug { "#{platform_name} API Request: #{payload[:method]} #{payload[:endpoint]} (#{duration}ms) - Success" }
+        else
+          FlowChat.logger.error { "#{platform_name} API Request: #{payload[:method]} #{payload[:endpoint]} (#{duration}ms) - Failed: #{payload[:status]} #{payload[:error]}" }
+        end
+      end
+
+      # Context events
+      def context_created(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Context Created [Gateway: #{payload[:gateway] || "unknown"}]" }
+      end
+
+      private
+
+      # Format platform name for display
+      def format_platform_name(platform)
+        case platform.to_sym
+        when :whatsapp then "WhatsApp"
+        when :ussd then "USSD"
+        else platform.to_s.capitalize
+        end
+      end
+
+      # Format bytes in a human-readable way
+      def format_bytes(bytes)
+        return "unknown size" unless bytes
+
+        if bytes < 1024
+          "#{bytes} bytes"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(1)} KB"
+        else
+          "#{(bytes / (1024.0 * 1024.0)).round(1)} MB"
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation/metrics_collector.rb

@@ -0,0 +1,197 @@
+module FlowChat
+  module Instrumentation
+    class MetricsCollector
+      attr_reader :metrics
+
+      def initialize
+        @metrics = {}
+        @mutex = Mutex.new
+        subscribe_to_events
+      end
+
+      # Get current metrics snapshot
+      def snapshot
+        @mutex.synchronize { @metrics.dup }
+      end
+
+      # Reset all metrics
+      def reset!
+        @mutex.synchronize { @metrics.clear }
+      end
+
+      # Get metrics for a specific category
+      def get_category(category)
+        @mutex.synchronize do
+          @metrics.select { |key, _| key.to_s.start_with?("#{category}.") }
+        end
+      end
+
+      private
+
+      def subscribe_to_events
+        # Flow execution metrics
+        ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
+          increment_counter("flows.executed")
+          track_timing("flows.execution_time", event.duration)
+          increment_counter("flows.by_name.#{event.payload[:flow_name]}")
+        end
+
+        ActiveSupport::Notifications.subscribe("flow.execution.error.flow_chat") do |event|
+          increment_counter("flows.errors")
+          increment_counter("flows.errors.by_class.#{event.payload[:error_class]}")
+          increment_counter("flows.errors.by_flow.#{event.payload[:flow_name]}")
+        end
+
+        # Session metrics
+        ActiveSupport::Notifications.subscribe("session.created.flow_chat") do |event|
+          increment_counter("sessions.created")
+          increment_counter("sessions.created.by_gateway.#{event.payload[:gateway]}")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.destroyed.flow_chat") do |event|
+          increment_counter("sessions.destroyed")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.cache.hit.flow_chat") do |event|
+          increment_counter("sessions.cache.hits")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.cache.miss.flow_chat") do |event|
+          increment_counter("sessions.cache.misses")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.data.get.flow_chat") do |event|
+          increment_counter("sessions.data.get")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.data.set.flow_chat") do |event|
+          increment_counter("sessions.data.set")
+        end
+
+        ActiveSupport::Notifications.subscribe("message.received.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.messages.received")
+          if event.payload[:message_type]
+            increment_counter("#{platform}.messages.received.by_type.#{event.payload[:message_type]}")
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("message.sent.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.messages.sent")
+          if event.payload[:message_type]
+            increment_counter("#{platform}.messages.sent.by_type.#{event.payload[:message_type]}")
+          end
+          track_timing("#{platform}.api.response_time", event.duration)
+        end
+
+        ActiveSupport::Notifications.subscribe("webhook.verified.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.webhook.verified")
+        end
+
+        ActiveSupport::Notifications.subscribe("webhook.failed.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.webhook.failures")
+          if event.payload[:reason]
+            increment_counter("#{platform}.webhook.failures.by_reason.#{event.payload[:reason]}")
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("media.upload.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          if event.payload[:success] != false
+            increment_counter("#{platform}.media.uploads.success")
+            if event.payload[:size]
+              track_histogram("#{platform}.media.upload_size", event.payload[:size])
+            end
+          else
+            increment_counter("#{platform}.media.uploads.failure")
+          end
+          track_timing("#{platform}.media.upload_time", event.duration)
+        end
+
+        ActiveSupport::Notifications.subscribe("pagination.triggered.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.pagination.triggered")
+          if event.payload[:content_length]
+            track_histogram("#{platform}.pagination.content_length", event.payload[:content_length])
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("api.request.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          if event.payload[:success]
+            increment_counter("#{platform}.api.requests.success")
+          else
+            increment_counter("#{platform}.api.requests.failure")
+            if event.payload[:status]
+              increment_counter("#{platform}.api.requests.failure.by_status.#{event.payload[:status]}")
+            end
+          end
+          track_timing("#{platform}.api.request_time", event.duration)
+        end
+      end
+
+      def increment_counter(key, value = 1)
+        @mutex.synchronize do
+          @metrics[key] ||= 0
+          @metrics[key] += value
+        end
+      end
+
+      def track_timing(key, duration_ms)
+        timing_key = "#{key}.timings"
+        @mutex.synchronize do
+          @metrics[timing_key] ||= []
+          @metrics[timing_key] << duration_ms
+
+          # Keep only last 1000 measurements for memory efficiency
+          @metrics[timing_key] = @metrics[timing_key].last(1000) if @metrics[timing_key].size > 1000
+
+          # Calculate and store aggregates
+          timings = @metrics[timing_key]
+          @metrics["#{key}.avg"] = timings.sum / timings.size
+          @metrics["#{key}.min"] = timings.min
+          @metrics["#{key}.max"] = timings.max
+          @metrics["#{key}.p50"] = percentile(timings, 50)
+          @metrics["#{key}.p95"] = percentile(timings, 95)
+          @metrics["#{key}.p99"] = percentile(timings, 99)
+        end
+      end
+
+      def track_histogram(key, value)
+        histogram_key = "#{key}.histogram"
+        @mutex.synchronize do
+          @metrics[histogram_key] ||= []
+          @metrics[histogram_key] << value
+
+          # Keep only last 1000 measurements
+          @metrics[histogram_key] = @metrics[histogram_key].last(1000) if @metrics[histogram_key].size > 1000
+
+          # Calculate aggregates
+          values = @metrics[histogram_key]
+          @metrics["#{key}.total"] = values.sum
+          @metrics["#{key}.avg"] = values.sum / values.size
+          @metrics["#{key}.min"] = values.min
+          @metrics["#{key}.max"] = values.max
+        end
+      end
+
+      def percentile(array, percentile)
+        return nil if array.empty?
+
+        sorted = array.sort
+        k = (percentile / 100.0) * (sorted.length - 1)
+        f = k.floor
+        c = k.ceil
+
+        return sorted[k] if f == c
+
+        d0 = sorted[f] * (c - k)
+        d1 = sorted[c] * (k - f)
+        d0 + d1
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation/setup.rb

@@ -0,0 +1,155 @@
+module FlowChat
+  module Instrumentation
+    module Setup
+      class << self
+        attr_accessor :log_subscriber, :metrics_collector
+
+        # Initialize instrumentation with default subscribers
+        def initialize!
+          setup_log_subscriber if FlowChat::Config.logger
+          setup_metrics_collector
+
+          FlowChat.logger&.info { "FlowChat::Instrumentation: Initialized with logging and metrics collection" }
+        end
+
+        # Set up both logging and metrics collection
+        def setup_instrumentation!(options = {})
+          setup_logging!(options)
+          setup_metrics!(options)
+        end
+
+        # Set up logging (LogSubscriber)
+        def setup_logging!(options = {})
+          return if @log_subscriber_setup
+
+          require_relative "log_subscriber"
+          setup_log_subscriber(options)
+          @log_subscriber_setup = true
+        end
+
+        # Set up metrics collection (MetricsCollector)
+        def setup_metrics!(options = {})
+          return if @metrics_collector_setup
+
+          require_relative "metrics_collector"
+          setup_metrics_collector(options)
+          @metrics_collector_setup = true
+        end
+
+        # Cleanup all subscribers
+        def cleanup!
+          @log_subscriber = nil
+          @metrics_collector = nil
+
+          # Note: ActiveSupport::Notifications doesn't provide an easy way to
+          # unsubscribe all subscribers, so this is mainly for reference cleanup
+          FlowChat.logger&.info { "FlowChat::Instrumentation: Cleaned up instrumentation" }
+        end
+
+        # Get current metrics (thread-safe)
+        def metrics
+          @metrics_collector&.snapshot || {}
+        end
+
+        # Reset metrics
+        def reset_metrics!
+          @metrics_collector&.reset!
+        end
+
+        # Subscribe to custom events
+        def subscribe(event_pattern, &block)
+          ActiveSupport::Notifications.subscribe(event_pattern, &block)
+        end
+
+        # Instrument a one-off event
+        def instrument(event_name, payload = {}, &block)
+          full_event_name = "#{event_name}.flow_chat"
+
+          enriched_payload = {
+            timestamp: Time.current
+          }.merge(payload).compact
+
+          ActiveSupport::Notifications.instrument(full_event_name, enriched_payload, &block)
+        end
+
+        # Access the metrics collector instance
+        def metrics_collector
+          @metrics_collector ||= FlowChat::Instrumentation::MetricsCollector.new
+        end
+
+        # Reset instrumentation (useful for testing)
+        def reset!
+          @log_subscriber_setup = false
+          @metrics_collector_setup = false
+          @log_subscriber = nil
+          @metrics_collector = nil
+        end
+
+        private
+
+        def setup_log_subscriber(options = {})
+          # Check if Rails is available and use its initialization callback
+          if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+            Rails.application.config.after_initialize do
+              initialize_log_subscriber
+            end
+          else
+            # Initialize immediately for non-Rails environments
+            initialize_log_subscriber
+          end
+        end
+
+        def initialize_log_subscriber
+          return if @log_subscriber
+
+          @log_subscriber = FlowChat::Instrumentation::LogSubscriber.new
+
+          # Manually subscribe to all FlowChat events
+          subscribe_to_events
+        end
+
+        def subscribe_to_events
+          # Core framework events
+          subscribe_event("flow.execution.start.flow_chat", :flow_execution_start)
+          subscribe_event("flow.execution.end.flow_chat", :flow_execution_end)
+          subscribe_event("flow.execution.error.flow_chat", :flow_execution_error)
+
+          # Session events
+          subscribe_event("session.created.flow_chat", :session_created)
+          subscribe_event("session.destroyed.flow_chat", :session_destroyed)
+          subscribe_event("session.data.get.flow_chat", :session_data_get)
+          subscribe_event("session.data.set.flow_chat", :session_data_set)
+          subscribe_event("session.cache.hit.flow_chat", :session_cache_hit)
+          subscribe_event("session.cache.miss.flow_chat", :session_cache_miss)
+
+          # Platform-agnostic events (new scalable approach)
+          subscribe_event("message.received.flow_chat", :message_received)
+          subscribe_event("message.sent.flow_chat", :message_sent)
+          subscribe_event("webhook.verified.flow_chat", :webhook_verified)
+          subscribe_event("webhook.failed.flow_chat", :webhook_failed)
+          subscribe_event("api.request.flow_chat", :api_request)
+          subscribe_event("media.upload.flow_chat", :media_upload)
+          subscribe_event("pagination.triggered.flow_chat", :pagination_triggered)
+
+          # Middleware events
+          subscribe_event("middleware.before.flow_chat", :middleware_before)
+          subscribe_event("middleware.after.flow_chat", :middleware_after)
+
+          # Context events
+          subscribe_event("context.created.flow_chat", :context_created)
+        end
+
+        def subscribe_event(event_name, method_name)
+          ActiveSupport::Notifications.subscribe(event_name) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            @log_subscriber.send(method_name, event) if @log_subscriber.respond_to?(method_name)
+          end
+        end
+
+        def setup_metrics_collector(options = {})
+          @metrics_collector = FlowChat::Instrumentation::MetricsCollector.new
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation.rb

@@ -0,0 +1,70 @@
+require "active_support/notifications"
+
+module FlowChat
+  module Instrumentation
+    extend ActiveSupport::Concern
+
+    # Instrument a block of code with the given event name and payload
+    def instrument(event_name, payload = {}, &block)
+      enriched_payload = payload&.dup || {}
+      if respond_to?(:context) && context
+        enriched_payload[:session_id] = context["session.id"] if context["session.id"]
+        enriched_payload[:flow_name] = context["flow.name"] if context["flow.name"]
+        enriched_payload[:gateway] = context["request.gateway"] if context["request.gateway"]
+      end
+
+      self.class.instrument(event_name, enriched_payload, &block)
+    end
+
+    class_methods do
+      def instrument(event_name, payload = {}, &block)
+        FlowChat::Instrumentation.instrument(event_name, payload, &block)
+      end
+    end
+
+    # Module-level method for direct calls like FlowChat::Instrumentation.instrument
+    def self.instrument(event_name, payload = {}, &block)
+      full_event_name = "#{event_name}.flow_chat"
+
+      enriched_payload = {
+        timestamp: Time.current
+      }.merge(payload || {}).compact
+
+      ActiveSupport::Notifications.instrument(full_event_name, enriched_payload, &block)
+    end
+
+    # Predefined event names for consistency
+    module Events
+      # Core framework events
+      FLOW_EXECUTION_START = "flow.execution.start"
+      FLOW_EXECUTION_END = "flow.execution.end"
+      FLOW_EXECUTION_ERROR = "flow.execution.error"
+
+      # Context events
+      CONTEXT_CREATED = "context.created"
+
+      # Session events
+      SESSION_CREATED = "session.created"
+      SESSION_DESTROYED = "session.destroyed"
+      SESSION_DATA_GET = "session.data.get"
+      SESSION_DATA_SET = "session.data.set"
+      SESSION_CACHE_HIT = "session.cache.hit"
+      SESSION_CACHE_MISS = "session.cache.miss"
+
+      # Platform-agnostic messaging events
+      # Gateway/platform information is included in the payload
+      MESSAGE_RECEIVED = "message.received"
+      MESSAGE_SENT = "message.sent"
+      WEBHOOK_VERIFIED = "webhook.verified"
+      WEBHOOK_FAILED = "webhook.failed"
+      API_REQUEST = "api.request"
+      MEDIA_UPLOAD = "media.upload"
+
+      PAGINATION_TRIGGERED = "pagination.triggered"
+
+      # Middleware events
+      MIDDLEWARE_BEFORE = "middleware.before"
+      MIDDLEWARE_AFTER = "middleware.after"
+    end
+  end
+end

data/lib/flow_chat/prompt.rb

@@ -6,13 +6,9 @@ module FlowChat
       @user_input = input
     end
 
-    def ask(msg, choices: nil, convert: nil, validate: nil, transform: nil, media: nil)
-      # Validate media and choices compatibility
-      validate_media_choices_compatibility(media, choices)
-
+    def ask(msg, choices: nil, transform: nil, validate: nil, media: nil)
       if user_input.present?
         input = user_input
-        input = convert.call(input) if convert.present?
         validation_error = validate.call(input) if validate.present?
 
         if validation_error.present?
@@ -38,17 +34,18 @@ module FlowChat
       terminate! message, media: media
     end
 
-    def select(msg, choices, media: nil)
-      # Validate media and choices compatibility
-      validate_media_choices_compatibility(media, choices)
+    def select(msg, choices, media: nil, error_message: "Invalid selection:")
+      raise ArgumentError, "choices must be an array or hash" unless choices.is_a?(Array) || choices.is_a?(Hash)
 
-      choices, choices_prompt = build_select_choices choices
+      normalized_choices = normalize_choices(choices)
       ask(
         msg,
-        choices: choices_prompt,
-        convert: lambda { |choice| choice.to_i },
-        validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).cover?(choice) },
-        transform: lambda { |choice| choices[choice - 1] },
+        choices: choices,
+        validate: lambda { |choice| error_message unless normalized_choices.key?(choice.to_s) },
+        transform: lambda do |choice|
+          choices = choices.keys if choices.is_a?(Hash)
+          choices.index_by { |choice| choice.to_s }[choice.to_s]
+        end,
         media: media
       )
     end
@@ -67,20 +64,23 @@ module FlowChat
       end
     end
 
-    def build_select_choices(choices)
+    def normalize_choices(choices)
       case choices
-      when Array
-        choices_prompt = choices.map.with_index { |c, i| [i + 1, c] }.to_h
+      when nil
+        nil
       when Hash
-        choices_prompt = choices.values.map.with_index { |c, i| [i + 1, c] }.to_h
-        choices = choices.keys
+        choices.map { |k, v| [k.to_s, v] }.to_h
+      when Array
+        choices.map { |c| [c.to_s, c] }.to_h
       else
         raise ArgumentError, "choices must be an array or hash"
       end
-      [choices, choices_prompt]
     end
 
     def prompt!(msg, choices: nil, media: nil)
+      validate_media_choices_compatibility(media, choices)
+
+      choices = normalize_choices(choices)
       raise FlowChat::Interrupt::Prompt.new(msg, choices: choices, media: media)
     end
 
@@ -88,4 +88,4 @@ module FlowChat
       raise FlowChat::Interrupt::Terminate.new(msg, media: media)
     end
   end
-end 
+end