imago 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32b2597d5abd824bba56fe349f70df96231527c712c587666c07882cd046388d
-  data.tar.gz: e7a2f4a5c7845b6bd548f03adc2586236a056192c80c707c49d6109509982a58
+  metadata.gz: d295fddaf05348d473874c6f08e10b93937f27f3e4b228b68ad33e96073fde17
+  data.tar.gz: 88d463fefbb56a175ffce52504374615ddbdb61b15877a05a01ee0e7f75432c8
 SHA512:
-  metadata.gz: 165ae60b51d64db276bf3ec15979ba0e06fc352074635b8386468ccf72fc0dcca9de35102e592ae9fce9eddd6dab2f59ff1855e51f44feecf053ef9f93ae5e55
-  data.tar.gz: 9af79343ed2ea4e4ade8079b95bd8fce0fe6cadd17796064c6677d7613b1311012c38ac18e9507def8bf9c19db05a2d4a8660f5c776ea26f26777482bb1fac01
+  metadata.gz: 77e736f2487e31b1fc933fb4a174b8b67a0406116be1335a270890560a09a983418f2c7c368aa10d7489f51e745e9c5c27a9b9c238e82fe6314e0bd1b3d5713b
+  data.tar.gz: bb9c1ecf14c3f911f0869c8247f80297b575a57febd299cfd3b01063dd790cae866fcc8ec18d3dbe37c4e35320ea72138a210191e7057f240416d49e8748ae81

data/.rubocop.yml

@@ -44,5 +44,9 @@ RSpec/NestedGroups:
 Layout/LineLength:
   Max: 120
 
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/imago/providers/openai.rb'
+
 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/image_input.rb

@@ -0,0 +1,69 @@
+# 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)
+
+      if hash[:base64]
+        raise ArgumentError, 'mime_type is required for base64 images' unless hash[:mime_type]
+
+        new(base64: hash[:base64], mime_type: hash[:mime_type])
+      elsif hash[:url]
+        mime_type = hash[:mime_type] || detect_mime_type(hash[:url])
+        new(url: hash[:url], mime_type: mime_type)
+      else
+        raise ArgumentError, 'Image hash must contain either :url or :base64 key'
+      end
+    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, :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/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,6 +15,7 @@ module Imago
       ].freeze
 
       def generate(prompt, opts = {})
+        validate_image_count!(opts[:images], max: MAX_IMAGES)
         conn = connection(BASE_URL)
         endpoint = "models/#{model}:generateContent"
 
@@ -42,11 +44,26 @@ module Imago
       private
 
       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_parts(prompt, opts)
+        parts = [{ text: build_prompt(prompt, opts) }]
+        images = normalize_images(opts[:images])
+        images.each { |img| parts << build_image_part(img) }
+        parts
+      end
+
+      def build_image_part(image)
+        if image.url?
+          { fileData: { fileUri: image.url, mimeType: image.mime_type }.compact }
+        else
+          { inlineData: { data: image.base64, mimeType: image.mime_type } }
+        end
+      end
+
       def build_prompt(prompt, opts)
         return prompt unless opts[:negative_prompt]
 

data/lib/imago/providers/openai.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require 'faraday/multipart'
+require 'base64'
+
 module Imago
   module Providers
     class OpenAI < Base
       BASE_URL = 'https://api.openai.com/v1'
+      MAX_IMAGES = 16
 
       KNOWN_IMAGE_MODELS = %w[
         dall-e-3
@@ -13,14 +17,20 @@ module Imago
         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)
+        images = opts[:images]
+        if images && !images.empty?
+          generate_with_images(prompt, opts)
+        else
+          generate_text_only(prompt, opts)
         end
-
-        parse_generate_response(handle_response(response))
       end
 
       def models
@@ -39,6 +49,73 @@ module Imago
 
       private
 
+      def generate_text_only(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))
+      end
+
+      def generate_with_images(prompt, opts)
+        validate_model_supports_images!
+        validate_image_count!(opts[:images], max: MAX_IMAGES)
+
+        images = normalize_images(opts[:images])
+        conn = multipart_connection(BASE_URL)
+
+        response = conn.post('images/edits') do |req|
+          req.headers['Authorization'] = "Bearer #{api_key}"
+          req.body = build_multipart_body(prompt, images, opts)
+        end
+
+        parse_generate_response(handle_response(response))
+      end
+
+      def validate_model_supports_images!
+        return if MODELS_SUPPORTING_IMAGE_INPUT.include?(model)
+
+        supported = MODELS_SUPPORTING_IMAGE_INPUT.join(', ')
+        raise InvalidRequestError.new(
+          "Model '#{model}' does not support image inputs. Supported models: #{supported}",
+          status_code: 400
+        )
+      end
+
+      def multipart_connection(base_url)
+        Faraday.new(url: base_url) do |conn|
+          conn.request :multipart
+          conn.response :json
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def build_multipart_body(prompt, images, opts)
+        body = {
+          model: model,
+          prompt: prompt
+        }
+
+        images.each_with_index do |image, index|
+          body["image[#{index}]"] = build_image_part(image)
+        end
+
+        clean_opts = opts.except(:images)
+        body.merge(clean_opts)
+      end
+
+      def build_image_part(image)
+        if image.url?
+          image.url
+        else
+          io = StringIO.new(Base64.decode64(image.base64))
+          extension = image.mime_type&.split('/')&.last || 'png'
+          Faraday::Multipart::FilePart.new(io, image.mime_type, "image.#{extension}")
+        end
+      end
+
       def build_request_body(prompt, opts)
         {
           model: model,

data/lib/imago/providers/xai.rb

@@ -11,6 +11,8 @@ module Imago
       ].freeze
 
       def generate(prompt, opts = {})
+        raise_if_images_provided(opts)
+
         conn = connection(BASE_URL)
         response = conn.post('images/generations') do |req|
           req.headers['Authorization'] = "Bearer #{api_key}"
@@ -58,6 +60,17 @@ module Imago
           created: body['created']
         }
       end
+
+      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
 end

data/lib/imago/version.rb

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

data/lib/imago.rb

@@ -5,6 +5,7 @@ require 'json'
 
 require_relative 'imago/version'
 require_relative 'imago/errors'
+require_relative 'imago/image_input'
 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.0
 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,7 @@ files:
 - lib/imago.rb
 - lib/imago/client.rb
 - lib/imago/errors.rb
+- lib/imago/image_input.rb
 - lib/imago/providers/base.rb
 - lib/imago/providers/gemini.rb
 - lib/imago/providers/openai.rb
@@ -80,7 +95,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: []