imago 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32b2597d5abd824bba56fe349f70df96231527c712c587666c07882cd046388d
-  data.tar.gz: e7a2f4a5c7845b6bd548f03adc2586236a056192c80c707c49d6109509982a58
+  metadata.gz: 417e5a3f6b7a3d41cee0ce17ec1cc225862fcc72c2448fc1c9b1da989509afd3
+  data.tar.gz: feca98a16c48e79f386b88626d7fa5934be4637910ae250a91bf036f79a2865b
 SHA512:
-  metadata.gz: 165ae60b51d64db276bf3ec15979ba0e06fc352074635b8386468ccf72fc0dcca9de35102e592ae9fce9eddd6dab2f59ff1855e51f44feecf053ef9f93ae5e55
-  data.tar.gz: 9af79343ed2ea4e4ade8079b95bd8fce0fe6cadd17796064c6677d7613b1311012c38ac18e9507def8bf9c19db05a2d4a8660f5c776ea26f26777482bb1fac01
+  metadata.gz: bb62ccf9dcb695a401f08674d68ba37e7b3f2e8cdb7ae5820735d987aa41839f95a2fd5152533016fd8a6b704fd43df26ebf9e18d8b4f64181ed4bfbea3a4a1e
+  data.tar.gz: da94d8fbd02b78cce3ab04c567fa90881752670973925254c77ed724a645c9974dbb635b810e70ebe7182e5f5b658ae83f29590adaa867844760c5501cb70027

data/.rubocop.yml

@@ -44,5 +44,22 @@ RSpec/NestedGroups:
 Layout/LineLength:
   Max: 120
 
+Metrics/ClassLength:
+  Max: 100
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 10
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
 RSpec/MessageSpies:
   EnforcedStyle: receive

data/README.md

@@ -124,6 +124,45 @@ result[:images].each do |image|
 end
 ```
 
+### Image Input (Image-to-Image)
+
+Imago supports image inputs for image editing and image-to-image generation. You can provide images as URLs or base64-encoded data.
+
+```ruby
+# URL string (auto-detect mime type from extension)
+client = Imago.new(provider: :openai)
+result = client.generate("Make this colorful", images: ["https://example.com/photo.jpg"])
+
+# Base64 with explicit mime type
+result = client.generate("Add a hat", images: [
+  { base64: "iVBORw0KGgo...", mime_type: "image/png" }
+])
+
+# URL with explicit mime type (useful when URL has no extension)
+result = client.generate("Edit this", images: [
+  { url: "https://example.com/photo", mime_type: "image/jpeg" }
+])
+
+# Mixed inputs
+result = client.generate("Combine these", images: [
+  "https://example.com/photo1.jpg",
+  { base64: "iVBORw0KGgo...", mime_type: "image/jpeg" }
+])
+```
+
+#### Image Input Provider Support
+
+| Provider | Support | Limits |
+|----------|---------|--------|
+| OpenAI | Yes (gpt-image-*, dall-e-2) | 16 images max |
+| Gemini | Yes | 10 images max |
+| xAI | No | N/A |
+
+**Notes:**
+- DALL-E 3 does not support image inputs
+- Mime types are auto-detected from URL extensions (png, jpg, jpeg, webp, gif)
+- Base64 images require an explicit `mime_type`
+
 ### Listing Available Models
 
 ```ruby
@@ -167,6 +206,9 @@ rescue Imago::ConfigurationError => e
   puts "Configuration error: #{e.message}"
 rescue Imago::ProviderNotFoundError => e
   puts "Unknown provider: #{e.message}"
+rescue Imago::UnsupportedFeatureError => e
+  puts "Feature not supported: #{e.message}"
+  puts "Provider: #{e.provider}, Feature: #{e.feature}"
 end
 ```
 

data/imago.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'base64', '~> 0.2'
   spec.add_dependency 'faraday', '~> 2.0'
   spec.add_dependency 'faraday-multipart', '~> 1.0'
 end

data/lib/imago/errors.rb

@@ -22,4 +22,14 @@ module Imago
   class InvalidRequestError < ApiError; end
 
   class ProviderNotFoundError < Error; end
+
+  class UnsupportedFeatureError < Error
+    attr_reader :provider, :feature
+
+    def initialize(message, provider: nil, feature: nil)
+      @provider = provider
+      @feature = feature
+      super(message)
+    end
+  end
 end

data/lib/imago/gemini_response_parser.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Imago
+  class GeminiResponseParser
+    def parse(body)
+      candidates = body['candidates'] || []
+      images = candidates.flat_map { |candidate| extract_images(candidate) }
+      { images: images }
+    end
+
+    private
+
+    def extract_images(candidate)
+      parts = candidate.dig('content', 'parts') || []
+      parts.filter_map { |part| parse_image_part(part) }
+    end
+
+    def parse_image_part(part)
+      return unless part['inlineData']
+
+      { base64: part['inlineData']['data'], mime_type: part['inlineData']['mimeType'] }.compact
+    end
+  end
+end

data/lib/imago/image_input.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Imago
+  class ImageInput
+    MIME_TYPES = {
+      'png' => 'image/png',
+      'jpg' => 'image/jpeg',
+      'jpeg' => 'image/jpeg',
+      'webp' => 'image/webp',
+      'gif' => 'image/gif'
+    }.freeze
+
+    attr_reader :url, :base64, :mime_type
+
+    def self.from(input)
+      case input
+      when String
+        from_url_string(input)
+      when Hash
+        from_hash(input)
+      else
+        raise ArgumentError, "Invalid image input: expected String or Hash, got #{input.class}"
+      end
+    end
+
+    def self.from_url_string(url)
+      mime_type = detect_mime_type(url)
+      new(url: url, mime_type: mime_type)
+    end
+
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+
+      return from_base64_hash(hash) if hash[:base64]
+      return from_url_hash(hash) if hash[:url]
+
+      raise ArgumentError, 'Image hash must contain either :url or :base64 key'
+    end
+
+    def self.from_base64_hash(hash)
+      raise ArgumentError, 'mime_type is required for base64 images' unless hash[:mime_type]
+
+      new(base64: hash[:base64], mime_type: hash[:mime_type])
+    end
+
+    def self.from_url_hash(hash)
+      mime_type = hash[:mime_type] || detect_mime_type(hash[:url])
+      new(url: hash[:url], mime_type: mime_type)
+    end
+
+    def self.detect_mime_type(url)
+      extension = File.extname(URI.parse(url).path).delete('.').downcase
+      MIME_TYPES[extension]
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    private_class_method :from_url_string, :from_hash, :from_base64_hash, :from_url_hash, :detect_mime_type
+
+    def initialize(url: nil, base64: nil, mime_type: nil)
+      @url = url
+      @base64 = base64
+      @mime_type = mime_type
+    end
+
+    def url?
+      !@url.nil?
+    end
+
+    def base64?
+      !@base64.nil?
+    end
+  end
+end

data/lib/imago/multipart_builder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Imago
+  class MultipartBuilder
+    def initialize(model)
+      @model = model
+    end
+
+    def build_body(prompt, images, opts)
+      body = base_body(prompt)
+      add_images(body, images)
+      body.merge(opts.except(:images))
+    end
+
+    def build_image_part(image)
+      image.url? ? image.url : build_file_part(image)
+    end
+
+    private
+
+    def base_body(prompt)
+      { model: @model, prompt: prompt }
+    end
+
+    def add_images(body, images)
+      images.each_with_index do |image, index|
+        body["image[#{index}]"] = build_image_part(image)
+      end
+    end
+
+    def build_file_part(image)
+      io = StringIO.new(Base64.decode64(image.base64))
+      extension = extract_extension(image.mime_type)
+      Faraday::Multipart::FilePart.new(io, image.mime_type, "image.#{extension}")
+    end
+
+    def extract_extension(mime_type)
+      mime_type&.split('/')&.last || 'png'
+    end
+  end
+end

data/lib/imago/providers/base.rb

@@ -77,6 +77,21 @@ module Imago
         else "API error: #{response.body}"
         end
       end
+
+      def normalize_images(images)
+        return [] if images.nil? || images.empty?
+
+        images.map { |img| ImageInput.from(img) }
+      end
+
+      def validate_image_count!(images, max:)
+        return if images.nil? || images.length <= max
+
+        raise InvalidRequestError.new(
+          "Too many images: #{images.length} provided, maximum is #{max}",
+          status_code: 400
+        )
+      end
     end
   end
 end

data/lib/imago/providers/gemini.rb

@@ -4,6 +4,7 @@ module Imago
   module Providers
     class Gemini < Base
       BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'
+      MAX_IMAGES = 10
 
       KNOWN_IMAGE_MODELS = %w[
         imagen-3.0-generate-002
@@ -14,15 +15,9 @@ module Imago
       ].freeze
 
       def generate(prompt, opts = {})
-        conn = connection(BASE_URL)
-        endpoint = "models/#{model}:generateContent"
-
-        response = conn.post(endpoint) do |req|
-          req.params['key'] = api_key
-          req.body = build_request_body(prompt, opts)
-        end
-
-        parse_generate_response(handle_response(response))
+        validate_image_count!(opts[:images], max: MAX_IMAGES)
+        response = execute_generate_request(prompt, opts)
+        response_parser.parse(handle_response(response))
       end
 
       def models
@@ -41,64 +36,84 @@ module Imago
 
       private
 
+      def response_parser
+        @response_parser ||= Imago::GeminiResponseParser.new
+      end
+
+      def execute_generate_request(prompt, opts)
+        conn = connection(BASE_URL)
+        body = build_request_body(prompt, opts)
+        conn.post(generate_endpoint) { |req| configure_request(req, body) }
+      end
+
+      def generate_endpoint
+        "models/#{model}:generateContent"
+      end
+
+      def configure_request(req, body)
+        req.params['key'] = api_key
+        req.body = body
+      end
+
       def build_request_body(prompt, opts)
-        body = { contents: [{ parts: [{ text: build_prompt(prompt, opts) }] }] }
+        body = { contents: [{ parts: build_parts(prompt, opts) }] }
         body[:generationConfig] = build_generation_config(opts) if generation_config_present?(opts)
         body
       end
 
-      def build_prompt(prompt, opts)
-        return prompt unless opts[:negative_prompt]
+      def build_parts(prompt, opts)
+        parts = [{ text: build_prompt(prompt, opts) }]
+        normalize_images(opts[:images]).each { |img| parts << build_image_part(img) }
+        parts
+      end
 
-        "#{prompt}. Avoid: #{opts[:negative_prompt]}"
+      def build_image_part(image)
+        image.url? ? build_file_data(image) : build_inline_data(image)
       end
 
-      def generation_config_present?(opts)
-        opts[:n] || opts[:sample_count] || opts[:aspect_ratio] || opts[:seed]
+      def build_file_data(image)
+        { fileData: { fileUri: image.url, mimeType: image.mime_type }.compact }
       end
 
-      def build_generation_config(opts)
-        config = {}
-        config[:candidateCount] = opts[:sample_count] || opts[:n] if opts[:n] || opts[:sample_count]
-        config[:seed] = opts[:seed] if opts[:seed]
-        config[:aspectRatio] = opts[:aspect_ratio] if opts[:aspect_ratio]
-        config
+      def build_inline_data(image)
+        { inlineData: { data: image.base64, mimeType: image.mime_type } }
       end
 
-      def parse_generate_response(body)
-        candidates = body['candidates'] || []
-        images = candidates.flat_map { |candidate| extract_images_from_candidate(candidate) }
-        { images: images }
+      def build_prompt(prompt, opts)
+        opts[:negative_prompt] ? "#{prompt}. Avoid: #{opts[:negative_prompt]}" : prompt
       end
 
-      def extract_images_from_candidate(candidate)
-        parts = candidate.dig('content', 'parts') || []
-        parts.filter_map do |part|
-          next unless part['inlineData']
+      def generation_config_present?(opts)
+        opts[:n] || opts[:sample_count] || opts[:aspect_ratio] || opts[:seed]
+      end
 
-          { base64: part['inlineData']['data'], mime_type: part['inlineData']['mimeType'] }.compact
-        end
+      def build_generation_config(opts)
+        { candidateCount: opts[:sample_count] || opts[:n], seed: opts[:seed], aspectRatio: opts[:aspect_ratio] }.compact
       end
 
       def fetch_models
-        conn = connection(BASE_URL)
-        response = conn.get('models') do |req|
-          req.params['key'] = api_key
-        end
-
-        body = handle_response(response)
-        filter_image_models(body['models'] || [])
+        response = connection(BASE_URL).get('models') { |req| req.params['key'] = api_key }
+        filter_image_models(handle_response(response)['models'] || [])
       rescue ApiError
         KNOWN_IMAGE_MODELS
       end
 
       def filter_image_models(models)
-        image_model_names = models
-                            .select { |m| m['supportedGenerationMethods']&.include?('generateContent') }
-                            .map { |m| m['name'].sub('models/', '') }
-                            .select { |name| name.include?('imagen') || name.include?('image') }
+        names = extract_image_model_names(models)
+        names.empty? ? KNOWN_IMAGE_MODELS : names
+      end
+
+      def extract_image_model_names(models)
+        content_models = models.select { |m| supports_generate_content?(m) }
+        content_models.map { |m| m['name'].sub('models/', '') }.select { |n| image_model?(n) }
+      end
+
+      def supports_generate_content?(model)
+        model['supportedGenerationMethods']&.include?('generateContent')
+      end
 
-        image_model_names.empty? ? KNOWN_IMAGE_MODELS : image_model_names
+      def image_model?(name)
+        name.include?('imagen') || name.include?('image')
       end
     end
   end

data/lib/imago/providers/openai.rb

@@ -1,26 +1,19 @@
 # frozen_string_literal: true
 
+require 'faraday/multipart'
+
 module Imago
   module Providers
     class OpenAI < Base
       BASE_URL = 'https://api.openai.com/v1'
+      MAX_IMAGES = 16
 
-      KNOWN_IMAGE_MODELS = %w[
-        dall-e-3
-        dall-e-2
-        gpt-image-1
-        gpt-image-1.5
-        gpt-image-1-mini
-      ].freeze
+      KNOWN_IMAGE_MODELS = %w[dall-e-3 dall-e-2 gpt-image-1 gpt-image-1.5 gpt-image-1-mini].freeze
+      MODELS_SUPPORTING_IMAGE_INPUT = %w[dall-e-2 gpt-image-1 gpt-image-1.5 gpt-image-1-mini].freeze
 
       def generate(prompt, opts = {})
-        conn = connection(BASE_URL)
-        response = conn.post('images/generations') do |req|
-          req.headers['Authorization'] = "Bearer #{api_key}"
-          req.body = build_request_body(prompt, opts)
-        end
-
-        parse_generate_response(handle_response(response))
+        has_images = opts[:images] && !opts[:images].empty?
+        has_images ? generate_with_images(prompt, opts) : generate_text_only(prompt, opts)
       end
 
       def models
@@ -39,40 +32,89 @@ module Imago
 
       private
 
-      def build_request_body(prompt, opts)
-        {
-          model: model,
-          prompt: prompt
-        }.merge(opts)
+      def generate_text_only(prompt, opts)
+        response = post_with_auth('images/generations', build_request_body(prompt, opts))
+        parse_response(response)
+      end
+
+      def generate_with_images(prompt, opts)
+        validate_model_supports_images!
+        validate_image_count!(opts[:images], max: MAX_IMAGES)
+        response = post_multipart_edit(prompt, opts)
+        parse_response(response)
+      end
+
+      def post_with_auth(endpoint, body)
+        connection(BASE_URL).post(endpoint) do |req|
+          req.headers['Authorization'] = auth_header
+          req.body = body
+        end
       end
 
-      def parse_generate_response(body)
+      def post_multipart_edit(prompt, opts)
+        body = build_multipart_body(prompt, opts)
+        multipart_connection.post('images/edits') { |req| configure_auth_request(req, body) }
+      end
+
+      def build_multipart_body(prompt, opts)
+        images = normalize_images(opts[:images])
+        multipart_builder.build_body(prompt, images, opts)
+      end
+
+      def configure_auth_request(req, body)
+        req.headers['Authorization'] = auth_header
+        req.body = body
+      end
+
+      def parse_response(response)
+        body = handle_response(response)
         images = body['data']&.map { |img| parse_image(img) }
         { images: images || [], created: body['created'] }
       end
 
+      def auth_header
+        "Bearer #{api_key}"
+      end
+
+      def multipart_builder
+        @multipart_builder ||= Imago::MultipartBuilder.new(model)
+      end
+
+      def multipart_connection
+        @multipart_connection ||= Faraday.new(url: BASE_URL) do |conn|
+          conn.request :multipart
+          conn.response :json
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def validate_model_supports_images!
+        return if MODELS_SUPPORTING_IMAGE_INPUT.include?(model)
+
+        raise InvalidRequestError.new(
+          "Model '#{model}' does not support image inputs. Supported: #{MODELS_SUPPORTING_IMAGE_INPUT.join(', ')}",
+          status_code: 400
+        )
+      end
+
+      def build_request_body(prompt, opts)
+        { model: model, prompt: prompt }.merge(opts)
+      end
+
       def parse_image(img)
         { url: img['url'], base64: img['b64_json'], revised_prompt: img['revised_prompt'] }.compact
       end
 
       def fetch_models
-        conn = connection(BASE_URL)
-        response = conn.get('models') do |req|
-          req.headers['Authorization'] = "Bearer #{api_key}"
-        end
-
-        body = handle_response(response)
-        filter_image_models(body['data'] || [])
+        response = connection(BASE_URL).get('models') { |req| req.headers['Authorization'] = auth_header }
+        filter_image_models(handle_response(response)['data'] || [])
       rescue ApiError
         KNOWN_IMAGE_MODELS
       end
 
       def filter_image_models(models)
-        image_model_ids = models
-                          .map { |m| m['id'] }
-                          .select { |id| id.include?('dall-e') || id.include?('image') }
-
-        image_model_ids.empty? ? KNOWN_IMAGE_MODELS : image_model_ids
+        ids = models.map { |m| m['id'] }.select { |id| id.include?('dall-e') || id.include?('image') }
+        ids.empty? ? KNOWN_IMAGE_MODELS : ids
       end
     end
   end

data/lib/imago/providers/xai.rb

@@ -11,12 +11,8 @@ module Imago
       ].freeze
 
       def generate(prompt, opts = {})
-        conn = connection(BASE_URL)
-        response = conn.post('images/generations') do |req|
-          req.headers['Authorization'] = "Bearer #{api_key}"
-          req.body = build_request_body(prompt, opts)
-        end
-
+        raise_if_images_provided(opts)
+        response = execute_generate_request(prompt, opts)
         parse_generate_response(handle_response(response))
       end
 
@@ -36,6 +32,21 @@ module Imago
 
       private
 
+      def execute_generate_request(prompt, opts)
+        conn = connection(BASE_URL)
+        body = build_request_body(prompt, opts)
+        conn.post('images/generations') { |req| configure_request(req, body) }
+      end
+
+      def configure_request(req, body)
+        req.headers['Authorization'] = auth_header
+        req.body = body
+      end
+
+      def auth_header
+        "Bearer #{api_key}"
+      end
+
       def build_request_body(prompt, opts)
         {
           model: model,
@@ -46,17 +57,19 @@ module Imago
       end
 
       def parse_generate_response(body)
-        images = body['data']&.map do |img|
-          {
-            url: img['url'],
-            base64: img['b64_json']
-          }.compact
-        end
+        images = body['data']&.map { |img| { url: img['url'], base64: img['b64_json'] }.compact }
+        { images: images || [], created: body['created'] }
+      end
 
-        {
-          images: images || [],
-          created: body['created']
-        }
+      def raise_if_images_provided(opts)
+        return unless opts[:images] && !opts[:images].empty?
+
+        raise UnsupportedFeatureError.new(
+          'xAI does not currently support image inputs. ' \
+          'Image-to-image generation may be available in future API versions.',
+          provider: :xai,
+          feature: :image_input
+        )
       end
     end
   end

data/lib/imago/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imago
-  VERSION = '0.1.2'
+  VERSION = '0.2.1'
 end

data/lib/imago.rb

@@ -5,6 +5,9 @@ require 'json'
 
 require_relative 'imago/version'
 require_relative 'imago/errors'
+require_relative 'imago/image_input'
+require_relative 'imago/multipart_builder'
+require_relative 'imago/gemini_response_parser'
 require_relative 'imago/providers/base'
 require_relative 'imago/providers/openai'
 require_relative 'imago/providers/gemini'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imago
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - NEETzsche
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -53,6 +67,9 @@ files:
 - lib/imago.rb
 - lib/imago/client.rb
 - lib/imago/errors.rb
+- lib/imago/gemini_response_parser.rb
+- lib/imago/image_input.rb
+- lib/imago/multipart_builder.rb
 - lib/imago/providers/base.rb
 - lib/imago/providers/gemini.rb
 - lib/imago/providers/openai.rb
@@ -80,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: A unified Ruby interface for multiple image generation AI providers
 test_files: []