runway-ruby 0.1.0

data/lib/runway_ml/validator_builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RunwayML
+  # Builds validators from OpenAPI schema definitions
+  module ValidatorBuilder
+    class << self
+      def build_enum_validator(enum_values)
+        ->(value, errors, field_name) {
+          unless enum_values.include?(value)
+            errors[field_name] = "must be one of: #{enum_values.join(', ')}, got #{value.inspect}"
+          end
+        }
+      end
+
+      def build_string_length_validator(min_length: nil, max_length: nil)
+        ->(value, errors, field_name) {
+          return if value.nil?
+
+          # Handle UTF-16 length for prompt text
+          if field_name.to_s.include?("prompt_text") || field_name.to_s.include?("promptText")
+            utf16_length = value.encode("UTF-16LE").bytesize / 2
+            length = utf16_length
+          else
+            length = value.to_s.length
+          end
+
+          if min_length && length < min_length
+            errors[field_name] = "must be at least #{min_length} characters, got #{length}"
+          end
+
+          if max_length && length > max_length
+            errors[field_name] = "must be at most #{max_length} characters, got #{length}"
+          end
+        }
+      end
+
+      def build_numeric_range_validator(minimum: nil, maximum: nil)
+        ->(value, errors, field_name) {
+          return if value.nil?
+
+          if minimum && value < minimum
+            errors[field_name] = "must be at least #{minimum}, got #{value}"
+          end
+
+          if maximum && value > maximum
+            errors[field_name] = "must be at most #{maximum}, got #{value}"
+          end
+        }
+      end
+
+      def extract_constraints_from_schema(schema)
+        constraints = {}
+
+        if schema["type"] == "string"
+          constraints[:string_length] = {
+            min_length: schema["minLength"],
+            max_length: schema["maxLength"]
+          }.compact
+        end
+
+        if schema["type"] == "number" || schema["type"] == "integer"
+          constraints[:numeric_range] = {
+            minimum: schema["minimum"],
+            maximum: schema["maximum"]
+          }.compact
+        end
+
+        if schema["enum"]
+          constraints[:enum] = schema["enum"]
+        end
+
+        constraints
+      end
+
+      def build_from_openapi_property(property_schema, field_name)
+        constraints = extract_constraints_from_schema(property_schema)
+        validators = []
+
+        if constraints[:enum]
+          validators << build_enum_validator(constraints[:enum])
+        end
+
+        if constraints[:string_length].any?
+          validators << build_string_length_validator(**constraints[:string_length])
+        end
+
+        if constraints[:numeric_range].any?
+          validators << build_numeric_range_validator(**constraints[:numeric_range])
+        end
+
+        validators
+      end
+    end
+  end
+end

data/lib/runway_ml/validators/base_validators.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module RunwayML
+  module Validators
+    class RatioValidator
+      def initialize(valid_ratios:)
+        @valid_ratios = valid_ratios
+      end
+
+      def validate(ratio, errors)
+        unless valid_ratios.include?(ratio)
+          errors[:ratio] = "must be one of: #{valid_ratios.join(', ')}"
+        end
+      end
+
+      private
+
+      attr_reader :valid_ratios
+    end
+
+    class PromptTextValidator
+      def initialize(max_length:, required: true)
+        @max_length = max_length
+        @required = required
+      end
+
+      def validate(prompt_text, errors)
+        if prompt_text.nil? || prompt_text.empty?
+          errors[:prompt_text] = "cannot be empty" if required
+          return
+        end
+
+        utf16_length = prompt_text.encode("UTF-16LE").bytesize / 2
+        if utf16_length > max_length
+          errors[:prompt_text] = "must be at most #{max_length} characters (UTF-16 code units), got #{utf16_length}"
+        end
+      end
+
+      private
+
+      attr_reader :max_length, :required
+    end
+
+    class DurationValidator
+      def initialize(valid_values: nil, range: nil, exact: nil)
+        @valid_values = valid_values
+        @range = range
+        @exact = exact
+      end
+
+      def validate(duration, errors)
+        return unless duration
+
+        if exact
+          unless duration == exact
+            errors[:duration] = "must be exactly #{exact}"
+          end
+        elsif valid_values
+          unless valid_values.include?(duration)
+            errors[:duration] = "must be one of: #{valid_values.join(', ')}"
+          end
+        elsif range
+          unless range.include?(duration)
+            errors[:duration] = "must be between #{range.min} and #{range.max} seconds"
+          end
+        end
+      end
+
+      private
+
+      attr_reader :valid_values, :range, :exact
+    end
+
+    class SeedValidator
+      def initialize(range:)
+        @range = range
+      end
+
+      def validate(seed, errors)
+        return unless seed
+
+        unless range.include?(seed)
+          errors[:seed] = "must be between #{range.min} and #{range.max}"
+        end
+      end
+
+      private
+
+      attr_reader :range
+    end
+
+    class PublicFigureThresholdValidator
+      def initialize(valid_thresholds:)
+        @valid_thresholds = valid_thresholds
+      end
+
+      def validate(public_figure_threshold, errors)
+        return unless public_figure_threshold
+
+        unless valid_thresholds.include?(public_figure_threshold)
+          errors[:public_figure_threshold] = "must be one of: #{valid_thresholds.join(', ')}"
+        end
+      end
+
+      private
+
+      attr_reader :valid_thresholds
+    end
+
+    class AudioValidator
+      def validate(audio, errors)
+        return if audio.nil?
+
+        unless [ true, false ].include?(audio)
+          errors[:audio] = "must be true or false"
+        end
+      end
+    end
+
+    class ImageUriValidator
+      VALID_CONTENT_TYPES = [ "image/jpeg", "image/jpg", "image/png", "image/webp" ].freeze
+
+      def validate(uri, errors, field: :prompt_image)
+        return unless uri.is_a?(String)
+
+        if uri.length < 13
+          errors[field] = "URI must be at least 13 characters"
+          return
+        end
+
+        if uri.start_with?("https://")
+          validate_https_url(uri, errors, field)
+        elsif uri.start_with?("runway://")
+          validate_runway_uri(uri, errors, field)
+        elsif uri.start_with?("data:image/")
+          validate_data_uri(uri, errors, field)
+        else
+          errors[field] = "must be a valid HTTPS URL, Runway URI (runway://), or data URI (data:image/)"
+        end
+      end
+
+      private
+
+      def validate_https_url(uri, errors, field)
+        if uri.length > 2048
+          errors[field] = "HTTPS URL must be at most 2048 characters"
+        end
+      end
+
+      def validate_runway_uri(uri, errors, field)
+        if uri.length > 5000
+          errors[field] = "Runway URI must be at most 5000 characters"
+        end
+      end
+
+      def validate_data_uri(uri, errors, field)
+        if uri.length > 5242880
+          errors[field] = "Data URI must be at most 5242880 characters"
+          return
+        end
+
+        content_type_match = uri.match(/^data:(image\/[^;,]+)/)
+        return unless content_type_match
+
+        content_type = content_type_match[1]
+        return if VALID_CONTENT_TYPES.include?(content_type)
+
+        if content_type == "image/gif"
+          errors[field] = "GIF images are not supported. Use JPEG, PNG, or WebP"
+        else
+          errors[field] = "unsupported image type '#{content_type}'. Must be JPEG (image/jpeg or image/jpg), PNG (image/png), or WebP (image/webp)"
+        end
+      end
+    end
+
+    class VideoUriValidator
+      VALID_CONTENT_TYPES = [ "video/mp4", "video/quicktime", "video/x-matroska", "video/webm", "video/3gpp", "video/ogg", "video/x-msvideo", "video/x-flv", "video/mpeg" ].freeze
+
+      def validate(uri, errors, field: :video, max_data_uri_size: 16777216)
+        return unless uri.is_a?(String)
+
+        if uri.length < 13
+          errors[field] = "URI must be at least 13 characters"
+          return
+        end
+
+        if uri.start_with?("https://")
+          validate_https_url(uri, errors, field)
+        elsif uri.start_with?("runway://")
+          validate_runway_uri(uri, errors, field)
+        elsif uri.start_with?("data:video/")
+          validate_data_uri(uri, errors, field, max_data_uri_size)
+        else
+          errors[field] = "must be a valid HTTPS URL, Runway URI (runway://), or data URI (data:video/)"
+        end
+      end
+
+      private
+
+      def validate_https_url(uri, errors, field)
+        if uri.length > 2048
+          errors[field] = "HTTPS URL must be at most 2048 characters"
+        end
+      end
+
+      def validate_runway_uri(uri, errors, field)
+        if uri.length > 5000
+          errors[field] = "Runway URI must be at most 5000 characters"
+        end
+      end
+
+      def validate_data_uri(uri, errors, field, max_size)
+        if uri.length > max_size
+          errors[field] = "Data URI must be at most #{max_size} characters"
+          return
+        end
+
+        content_type_match = uri.match(/^data:(video\/[^;,]+)/)
+        return unless content_type_match
+
+        content_type = content_type_match[1]
+        errors[field] = "unsupported video type '#{content_type}'" unless VALID_CONTENT_TYPES.include?(content_type)
+      end
+    end
+
+    class BodyControlValidator
+      def validate(body_control, errors)
+        return if body_control.nil?
+
+        unless [ true, false ].include?(body_control)
+          errors[:body_control] = "must be true or false"
+        end
+      end
+    end
+
+    class ExpressionIntensityValidator
+      def initialize(range: 1..5)
+        @range = range
+      end
+
+      def validate(expression_intensity, errors)
+        return if expression_intensity.nil?
+
+        unless range.include?(expression_intensity)
+          errors[:expression_intensity] = "must be between #{range.min} and #{range.max}"
+        end
+      end
+
+      private
+
+      attr_reader :range
+    end
+
+    class CharacterValidator
+      def initialize
+        @video_uri_validator = VideoUriValidator.new
+      end
+
+      def validate(character, errors)
+        return if character.nil?
+
+        unless character.is_a?(Hash)
+          errors[:character] = "must be a Hash with 'type' and 'uri'"
+          return
+        end
+
+        type = character[:type]
+        uri = character[:uri]
+
+        unless [ "image", "video" ].include?(type)
+          errors[:character] = "type must be 'image' or 'video'"
+          return
+        end
+
+        if type == "image"
+          # Reuse ImageUriValidator for image validation
+          ImageUriValidator.new.validate(uri, errors, field: :character)
+        elsif type == "video"
+          @video_uri_validator.validate(uri, errors, field: :character)
+        end
+      end
+
+      private
+
+      attr_reader :video_uri_validator
+    end
+
+    class ReferenceVideoValidator
+      def initialize
+        @video_uri_validator = VideoUriValidator.new
+      end
+
+      def validate(reference, errors)
+        return if reference.nil?
+
+        unless reference.is_a?(Hash)
+          errors[:reference] = "must be a Hash with 'type' and 'uri'"
+          return
+        end
+
+        type = reference[:type]
+        uri = reference[:uri]
+
+        unless type == "video"
+          errors[:reference] = "type must be 'video'"
+          return
+        end
+
+        @video_uri_validator.validate(uri, errors, field: :reference)
+      end
+
+      private
+
+      attr_reader :video_uri_validator
+    end
+
+    class UUIDValidator
+      # RFC 4122 UUID v4 pattern from OpenAPI spec
+      UUID_PATTERN = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$/
+
+      def validate(uuid, errors, field: :id)
+        if uuid.nil?
+          errors[field] = "cannot be nil"
+          return
+        end
+
+        unless uuid.is_a?(String)
+          errors[field] = "must be a string"
+          return
+        end
+
+        unless uuid.match?(UUID_PATTERN)
+          errors[field] = "must be a valid UUID (RFC 4122 v4)"
+        end
+      end
+    end
+  end
+end

data/lib/runway_ml/validators/character_performance_validator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base_validators"
+
+module RunwayML
+  module Validators
+    class CharacterPerformanceValidator
+      def initialize
+        @ratio_validator = RatioValidator.new(
+          valid_ratios: [ "1280:720", "720:1280", "960:960", "1104:832", "832:1104", "1584:672" ]
+        )
+        @seed_validator = SeedValidator.new(range: 0..4294967295)
+        @body_control_validator = BodyControlValidator.new
+        @expression_intensity_validator = ExpressionIntensityValidator.new(range: 1..5)
+        @character_validator = CharacterValidator.new
+        @reference_video_validator = ReferenceVideoValidator.new
+        @public_figure_threshold_validator = PublicFigureThresholdValidator.new(
+          valid_thresholds: [ "auto", "low" ]
+        )
+      end
+
+      def validate(character:, reference:, ratio:, seed: nil, body_control: nil, expression_intensity: nil, public_figure_threshold: nil)
+        errors = {}
+
+        character_validator.validate(character, errors)
+        reference_video_validator.validate(reference, errors)
+        ratio_validator.validate(ratio, errors)
+        seed_validator.validate(seed, errors)
+        body_control_validator.validate(body_control, errors)
+        expression_intensity_validator.validate(expression_intensity, errors)
+        public_figure_threshold_validator.validate(public_figure_threshold, errors)
+
+        { errors: errors }
+      end
+
+      private
+
+      attr_reader :ratio_validator, :seed_validator, :body_control_validator, :expression_intensity_validator, :character_validator, :reference_video_validator, :public_figure_threshold_validator
+    end
+  end
+end

data/lib/runway_ml/validators/gen3a_turbo_validator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "base_validators"
+require_relative "prompt_image_validator"
+
+module RunwayML
+  module Validators
+    class Gen3aTurboValidator
+      def initialize(image_processor:)
+        @image_processor = image_processor
+        @ratio_validator = RatioValidator.new(valid_ratios: [ "768:1280", "1280:768" ])
+        @prompt_text_validator = PromptTextValidator.new(max_length: 1000, required: true)
+        @duration_validator = DurationValidator.new(valid_values: [ 5, 10 ])
+        @seed_validator = SeedValidator.new(range: 0..4294967295)
+        @public_figure_threshold_validator = PublicFigureThresholdValidator.new(
+          valid_thresholds: [ "auto", "low" ]
+        )
+        @prompt_image_validator = PromptImageValidator.new(
+          image_processor: image_processor,
+          array_size: 1..2,
+          valid_positions: [ "first", "last" ]
+        )
+      end
+
+      def validate(prompt_image:, prompt_text:, ratio:, duration:, seed:, public_figure_threshold:)
+        errors = {}
+
+        ratio_validator.validate(ratio, errors)
+        prompt_text_validator.validate(prompt_text, errors)
+        duration_validator.validate(duration, errors)
+        seed_validator.validate(seed, errors)
+        public_figure_threshold_validator.validate(public_figure_threshold, errors)
+
+        # Process and validate prompt_image
+        processed_prompt_image = image_processor.process(prompt_image, errors)
+        prompt_image_validator.validate(processed_prompt_image, errors)
+
+        { errors: errors, processed_prompt_image: processed_prompt_image }
+      end
+
+      private
+
+      attr_reader :image_processor, :ratio_validator, :prompt_text_validator,
+                  :duration_validator, :seed_validator, :public_figure_threshold_validator,
+                  :prompt_image_validator
+    end
+  end
+end

data/lib/runway_ml/validators/gen4_turbo_validator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "base_validators"
+require_relative "prompt_image_validator"
+
+module RunwayML
+  module Validators
+    class Gen4TurboValidator
+      def initialize(image_processor:)
+        @image_processor = image_processor
+        @ratio_validator = RatioValidator.new(
+          valid_ratios: [ "1280:720", "720:1280", "1104:832", "832:1104", "960:960", "1584:672" ]
+        )
+        @prompt_text_validator = PromptTextValidator.new(max_length: 1000, required: true)
+        @duration_validator = DurationValidator.new(range: 2..10)
+        @seed_validator = SeedValidator.new(range: 0..4294967295)
+        @public_figure_threshold_validator = PublicFigureThresholdValidator.new(
+          valid_thresholds: [ "auto", "low" ]
+        )
+        @prompt_image_validator = PromptImageValidator.new(
+          image_processor: image_processor,
+          array_size: 1,
+          valid_positions: [ "first" ]
+        )
+      end
+
+      def validate(prompt_image:, prompt_text:, ratio:, duration:, seed:, public_figure_threshold:)
+        errors = {}
+
+        ratio_validator.validate(ratio, errors)
+        prompt_text_validator.validate(prompt_text, errors)
+        duration_validator.validate(duration, errors)
+        seed_validator.validate(seed, errors)
+        public_figure_threshold_validator.validate(public_figure_threshold, errors)
+
+        # Process and validate prompt_image
+        processed_prompt_image = image_processor.process(prompt_image, errors)
+        prompt_image_validator.validate(processed_prompt_image, errors)
+
+        { errors: errors, processed_prompt_image: processed_prompt_image }
+      end
+
+      private
+
+      attr_reader :image_processor, :ratio_validator, :prompt_text_validator,
+                  :duration_validator, :seed_validator, :public_figure_threshold_validator,
+                  :prompt_image_validator
+    end
+  end
+end

data/lib/runway_ml/validators/prompt_image_validator.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "base_validators"
+
+module RunwayML
+  module Validators
+    class PromptImageValidator
+      def initialize(image_processor:, array_size:, valid_positions:, only_first_frame: false)
+        @image_processor = image_processor
+        @array_size = array_size
+        @valid_positions = valid_positions
+        @only_first_frame = only_first_frame
+        @image_uri_validator = ImageUriValidator.new
+      end
+
+      def validate(prompt_image, errors)
+        if prompt_image.nil?
+          errors[:prompt_image] = "is required"
+          return
+        end
+
+        if prompt_image.is_a?(String)
+          image_uri_validator.validate(prompt_image, errors)
+        elsif prompt_image.is_a?(Array)
+          validate_array_format(prompt_image, errors)
+        else
+          errors[:prompt_image] = "must be a string or an array"
+        end
+      end
+
+      private
+
+      attr_reader :image_processor, :array_size, :valid_positions, :only_first_frame, :image_uri_validator
+
+      def validate_array_format(prompt_image, errors)
+        if array_size.is_a?(Range)
+          unless array_size.include?(prompt_image.length)
+            errors[:prompt_image] = "array must contain #{array_size.min} to #{array_size.max} items"
+            return
+          end
+        elsif prompt_image.length != array_size
+          errors[:prompt_image] = "array must contain exactly #{array_size} item#{'s' if array_size > 1}"
+          return
+        end
+
+        validate_array_items(prompt_image, errors)
+        validate_array_rules(prompt_image, errors)
+      end
+
+      def validate_array_items(prompt_image, errors)
+        prompt_image.each_with_index do |item, index|
+          unless item.is_a?(Hash)
+            errors[:prompt_image] = "array items must be objects with 'uri' and 'position' fields"
+            return
+          end
+
+          unless item.key?(:uri) || item.key?("uri")
+            errors[:prompt_image] = "array item #{index + 1} must have 'uri' field"
+          end
+
+          unless item.key?(:position) || item.key?("position")
+            errors[:prompt_image] = "array item #{index + 1} must have 'position' field"
+          end
+
+          position = item[:position] || item["position"]
+          if position && !valid_positions.include?(position)
+            errors[:prompt_image] = "position must be one of: #{valid_positions.join(', ')}"
+          end
+
+          uri = item[:uri] || item["uri"]
+          image_uri_validator.validate(uri, errors) if uri
+        end
+      end
+
+      def validate_array_rules(prompt_image, errors)
+        return if errors[:prompt_image] # Skip if there are already errors
+
+        # Rule: cannot generate with only a last frame (veo3.1 specific)
+        if only_first_frame && prompt_image.length == 1
+          item = prompt_image.first
+          position = item[:position] || item["position"]
+          if position == "last"
+            errors[:prompt_image] = "cannot generate with only a last frame. Must include a first frame."
+          end
+        end
+
+        # Rule: with 2 items, ensure one is "first" and one is "last"
+        if prompt_image.length == 2 && valid_positions.sort == [ "first", "last" ]
+          positions = prompt_image.map { |item| item[:position] || item["position"] }.compact
+          unless positions.sort == [ "first", "last" ]
+            errors[:prompt_image] = "array with 2 items must have one 'first' and one 'last' position"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/runway_ml/validators/sound_effect_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base_validators"
+
+module RunwayML
+  module Validators
+    class SoundEffectValidator
+      def initialize
+        @prompt_text_validator = PromptTextValidator.new(max_length: 3000, required: true)
+        @duration_validator = DurationValidator.new(range: 0.5..30)
+      end
+
+      def validate(prompt_text:, duration:, loop:)
+        errors = {}
+
+        prompt_text_validator.validate(prompt_text, errors)
+        duration_validator.validate(duration, errors) unless duration.nil?
+
+        { errors: errors }
+      end
+
+      private
+
+      attr_reader :prompt_text_validator, :duration_validator
+    end
+  end
+end