imago 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ab8cd4f924113a9ba92f0f6918b137c0132ebda6fe9d8d2006a62e158d1f987
-  data.tar.gz: 78f6726394dac041f2d82d1e068012767c94a616267801ac4cf597540e070884
+  metadata.gz: d295fddaf05348d473874c6f08e10b93937f27f3e4b228b68ad33e96073fde17
+  data.tar.gz: 88d463fefbb56a175ffce52504374615ddbdb61b15877a05a01ee0e7f75432c8
 SHA512:
-  metadata.gz: d9b288487b3d77b17b70fe5289a9b63744e454f2bf01358304b846e0eb6cef28326287ac319887a1e539ea7f15a16ad22fc19f6579da47118d0fa6685b8d51e0
-  data.tar.gz: 2f3d13bd6d3bce751755c6a41e333139413cc28a1f31e6fde0c09c7671a592a9d87d731336200733112ad15d4886376708c48f25decf1008126866615d6f8bfa
+  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

@@ -5,8 +5,8 @@ require_relative 'lib/imago/version'
 Gem::Specification.new do |spec|
   spec.name = 'imago'
   spec.version = Imago::VERSION
-  spec.authors = ['Your Name']
-  spec.email = ['your.email@example.com']
+  spec.authors = ['NEETzsche']
+  spec.email = ['thestranjer@protonmail.com']
 
   spec.summary = 'A unified Ruby interface for multiple image generation AI providers'
   spec.description = 'Imago provides a simple, unified API to generate images using various AI providers ' \
@@ -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.1'
+  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,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: imago
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
-- Your Name
+- NEETzsche
 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
@@ -40,7 +54,7 @@ dependencies:
 description: Imago provides a simple, unified API to generate images using various
   AI providers including OpenAI (DALL-E), Google Gemini, and xAI (Grok).
 email:
-- your.email@example.com
+- thestranjer@protonmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -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: []