ruby_llm-pollinations 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8739629c1d55bee37679e2c7a25cc6fe11d77451e6e986504ac04a6d82d9d7d4
+  data.tar.gz: 000d89d0c0bfcb2c398d2cac9917b46ab04d285d54910b74415d2c068dbaf691
+SHA512:
+  metadata.gz: 60b83e16c6cd2c13f8a19a69978f31c5ae04c2d4125ef9625883d01088ce3c950373624f999341af762bdf4a0ecb7d6dd74a9e071d63a86586d60a92b3d7ed1c
+  data.tar.gz: b284bef0524943e972940c11f773a8791d4b4cb4fb4343d07a9ddc8dd6c330868add9ea028721ed524ee5ac72b2228b4e5426d86d16fe5904c62194b99e6cee8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Compasify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,199 @@
+# ruby_llm-pollinations
+
+[Pollinations AI](https://pollinations.ai) provider plugin for [RubyLLM](https://github.com/crmne/ruby_llm).
+
+Adds chat, image/video generation, text-to-speech, music generation, and transcription — without modifying RubyLLM core.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'ruby_llm'
+gem 'ruby_llm-pollinations', github: 'compasify/ruby_llm-pollinations'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+```ruby
+RubyLLM.configure do |c|
+  c.pollinations_api_key = ENV['POLLINATIONS_API_KEY']
+
+  # Optional
+  c.pollinations_api_base = 'https://gen.pollinations.ai' # default
+  c.default_audio_model = 'tts-1'                         # default
+end
+```
+
+## Usage
+
+### Chat
+
+```ruby
+chat = RubyLLM.chat(model: 'openai', provider: :pollinations)
+response = chat.ask("What is Pollinations AI?")
+puts response.content
+```
+
+Streaming:
+
+```ruby
+chat = RubyLLM.chat(model: 'openai', provider: :pollinations)
+chat.ask("Tell me a story") { |chunk| print chunk.content }
+```
+
+### Image Generation
+
+```ruby
+image = RubyLLM.paint(
+  "a cyberpunk cat in neon lights",
+  model: 'flux',
+  provider: :pollinations,
+  size: '1024x1024',
+  seed: 42,
+  enhance: true,
+  negative_prompt: 'blurry, low quality'
+)
+
+image.save('cat.jpg')
+```
+
+### Video Generation
+
+```ruby
+video = RubyLLM.paint(
+  "a cat walking on the moon",
+  model: 'veo',
+  provider: :pollinations,
+  size: '1024x576',
+  duration: 6,
+  aspect_ratio: '16:9',
+  audio: true
+)
+
+video.save('moon_cat.mp4')
+```
+
+Supported video models: `veo`, `seedance`, `seedance-pro`, `grok-video`, `ltx-2`
+
+### Text-to-Speech
+
+```ruby
+audio = RubyLLM.speak(
+  "Hello from Pollinations!",
+  model: 'tts-1',
+  voice: 'alloy',
+  provider: :pollinations
+)
+
+audio.save('hello.mp3')
+```
+
+Available voices: `alloy`, `echo`, `fable`, `onyx`, `shimmer`, `coral`, `verse`, `ballad`, `ash`, `sage`, `amuch`, `dan`, `rachel`, `bella`
+
+### Music Generation
+
+```ruby
+music = RubyLLM.speak(
+  "Upbeat electronic track with synth leads",
+  model: 'elevenmusic',
+  provider: :pollinations,
+  duration: 120,
+  instrumental: true
+)
+
+music.save('track.mp3')
+```
+
+### Transcription
+
+```ruby
+transcription = RubyLLM.transcribe(
+  'audio.mp3',
+  model: 'whisper-large-v3',
+  provider: :pollinations,
+  language: 'en'
+)
+
+puts transcription.text
+```
+
+### Tool Calling
+
+```ruby
+class WeatherTool < RubyLLM::Tool
+  description "Get current weather"
+  param :city, type: :string, desc: "City name"
+
+  def execute(city:)
+    "25°C, sunny in #{city}"
+  end
+end
+
+chat = RubyLLM.chat(model: 'openai', provider: :pollinations)
+chat.with_tool(WeatherTool)
+chat.ask("What's the weather in Tokyo?")
+```
+
+### Account & Billing
+
+```ruby
+config = RubyLLM::Configuration.new.tap { |c| c.pollinations_api_key = ENV['POLLINATIONS_API_KEY'] }
+provider = RubyLLM::Pollinations::Provider::Pollinations.new(config)
+
+provider.balance        # => { balance: 1234.56 }
+provider.profile        # => { name: "...", tier: "seed", ... }
+provider.usage          # => { usage: [...], count: 42 }
+provider.usage_daily    # => { usage: [...], count: 7 }
+provider.key_info       # => { valid: true, type: "secret", pollen_budget: 10000, ... }
+```
+
+### List Available Models
+
+```ruby
+RubyLLM.models.refresh!
+pollinations_models = RubyLLM.models.all.select { |m| m.provider == 'pollinations' }
+pollinations_models.each { |m| puts "#{m.id} (#{m.family})" }
+```
+
+## How It Works
+
+This gem registers itself as a RubyLLM provider via `Provider.register` and applies three defensive monkey-patches that automatically skip themselves if RubyLLM adds native support:
+
+| Patch | Purpose |
+|---|---|
+| `Provider#paint(**options)` | Passes extra options (seed, enhance, negative_prompt) through the paint call chain |
+| `Image.paint(**options)` | Forwards options from the public API to the provider |
+| `RubyLLM.speak` | Adds text-to-speech support (not yet in RubyLLM core) |
+
+## Supported Models
+
+| Type | Models |
+|---|---|
+| Chat | `openai`, `gemini`, `claude`, and others via Pollinations |
+| Image | `flux`, `zimage`, `gptimage`, `seedream`, `nanobanana`, `kontext`, `imagen`, `klein`, `wan` |
+| Video | `veo`, `seedance`, `seedance-pro`, `grok-video`, `ltx-2` |
+| Audio/TTS | `tts-1` |
+| Music | `elevenmusic`, `music` |
+| Transcription | `whisper-large-v3`, `whisper-1` |
+
+Run `RubyLLM.models.refresh!` to get the latest list from the API.
+
+## Development
+
+```bash
+git clone https://github.com/compasify/ruby_llm-pollinations.git
+cd ruby_llm-pollinations
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

data/lib/ruby_llm/pollinations/audio_output.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    class AudioOutput
+      attr_reader :data, :mime_type, :model_id, :duration
+
+      def initialize(data: nil, mime_type: nil, model_id: nil, duration: nil)
+        @data = data
+        @mime_type = mime_type
+        @model_id = model_id
+        @duration = duration
+      end
+
+      def base64?
+        !@data.nil?
+      end
+
+      def to_blob
+        return unless base64?
+
+        Base64.decode64(@data)
+      end
+
+      def save(path)
+        File.binwrite(File.expand_path(path), to_blob)
+        path
+      end
+
+      def self.speak(input, model: nil, voice: nil, provider: nil, assume_model_exists: false, context: nil, **options) # rubocop:disable Metrics/ParameterLists
+        config = context&.config || RubyLLM.config
+        model ||= config.default_audio_model
+        model, provider_instance = RubyLLM::Models.resolve(model, provider: provider,
+                                                                   assume_exists: assume_model_exists, config: config)
+        model_id = model.id
+
+        provider_instance.speak(input, model: model_id, voice: voice, **options)
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/patches/image_paint.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Image
+    class << self
+      unless method_defined?(:_pollinations_patched_paint)
+        alias _original_paint paint
+
+        def paint(prompt, model: nil, provider: nil, assume_model_exists: false, size: '1024x1024', context: nil, **options) # rubocop:disable Metrics/ParameterLists
+          config = context&.config || RubyLLM.config
+          model ||= config.default_image_model
+          model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                           config: config)
+          model_id = model.id
+
+          provider_instance.paint(prompt, model: model_id, size: size, **options)
+        end
+
+        def _pollinations_patched_paint = true
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/patches/provider_paint.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Provider
+    unless instance_method(:paint).parameters.any? { |type, _| type == :keyrest }
+      def paint(prompt, model:, size:, **options)
+        payload = render_image_payload(prompt, model: model, size: size, **options)
+        response = @connection.post images_url, payload
+        parse_image_response(response, model: model)
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/patches/speak.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module SpeakMethod
+    def speak(...)
+      Pollinations::AudioOutput.speak(...)
+    end
+  end
+
+  extend SpeakMethod unless respond_to?(:speak)
+
+  unless Configuration.options.include?(:default_audio_model)
+    Configuration.send(:option, :default_audio_model, 'tts-1')
+  end
+end

data/lib/ruby_llm/pollinations/provider/account.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Account
+        def profile
+          response = @connection.get('account/profile')
+          normalize_profile(response.body)
+        end
+
+        def balance
+          response = @connection.get('account/balance')
+          { balance: response.body['balance'] }
+        end
+
+        def usage(format: :json, limit: 100, before: nil)
+          response = @connection.get('account/usage') do |req|
+            req.params[:format] = format.to_s
+            req.params[:limit] = limit
+            req.params[:before] = before if before
+          end
+          normalize_usage(response.body, format)
+        end
+
+        def usage_daily(format: :json)
+          response = @connection.get('account/usage/daily') do |req|
+            req.params[:format] = format.to_s
+          end
+          normalize_usage(response.body, format)
+        end
+
+        def key_info
+          response = @connection.get('account/key')
+          normalize_key_info(response.body)
+        end
+
+        private
+
+        def normalize_profile(data)
+          {
+            name: data['name'],
+            email: data['email'],
+            github_username: data['githubUsername'],
+            image: data['image'],
+            tier: data['tier'],
+            created_at: parse_timestamp(data['createdAt']),
+            next_reset_at: parse_timestamp(data['nextResetAt'])
+          }
+        end
+
+        def normalize_usage(data, format)
+          return data if format.to_sym == :csv
+
+          {
+            usage: data['usage'] || [],
+            count: data['count']
+          }
+        end
+
+        def normalize_key_info(data)
+          {
+            valid: data['valid'],
+            type: data['type'],
+            name: data['name'],
+            expires_at: parse_timestamp(data['expiresAt']),
+            expires_in: data['expiresIn'],
+            permissions: normalize_permissions(data['permissions']),
+            pollen_budget: data['pollenBudget'],
+            rate_limit_enabled: data['rateLimitEnabled']
+          }
+        end
+
+        def normalize_permissions(permissions)
+          return nil unless permissions
+
+          {
+            models: permissions['models'],
+            account: permissions['account']
+          }
+        end
+
+        def parse_timestamp(value)
+          return nil unless value
+
+          Time.parse(value)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/audio.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Audio
+        module_function
+
+        MUSIC_MODELS = %w[elevenmusic music].freeze
+        DEFAULT_VOICE = 'alloy'
+        DEFAULT_FORMAT = 'mp3'
+        DEFAULT_SPEED = 1.0
+        MAX_INPUT_LENGTH = 4096
+
+        VOICE_ENUM = %w[
+          alloy echo fable onyx shimmer coral verse ballad ash sage amuch dan
+          rachel bella
+        ].freeze
+
+        FORMAT_ENUM = %w[mp3 opus aac flac wav pcm].freeze
+
+        def speech_url
+          'v1/audio/speech'
+        end
+
+        def render_speech_payload(input, model:, voice:, **options)
+          validate_speech_input!(input)
+          build_speech_payload(input, model, voice, options)
+        end
+
+        def validate_speech_input!(input)
+          raise ArgumentError, 'Input text is required' if input.nil? || input.to_s.empty?
+          return unless input.length > MAX_INPUT_LENGTH
+
+          raise ArgumentError, "Input exceeds maximum length of #{MAX_INPUT_LENGTH} characters"
+        end
+
+        def build_speech_payload(input, model, voice, options)
+          payload = {
+            input: input,
+            model: model,
+            voice: voice || DEFAULT_VOICE,
+            response_format: options[:response_format] || DEFAULT_FORMAT,
+            speed: options[:speed] || DEFAULT_SPEED
+          }
+          add_music_options(payload, model, options)
+          payload.compact
+        end
+
+        def add_music_options(payload, model, options)
+          return unless music_model?(model)
+
+          payload[:duration] = options[:duration] if options[:duration]
+          payload[:instrumental] = options[:instrumental] if options.key?(:instrumental)
+        end
+
+        def parse_speech_response(response, model:)
+          content_type = response.headers['content-type'] || ''
+          mime_type = content_type.empty? ? 'audio/mpeg' : content_type.split(';').first.strip
+          data = Base64.strict_encode64(response.body)
+
+          RubyLLM::Pollinations::AudioOutput.new(
+            data: data,
+            mime_type: mime_type,
+            model_id: model
+          )
+        end
+
+        def music_model?(model)
+          return false unless model
+
+          MUSIC_MODELS.include?(model.to_s.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/capabilities.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Capabilities
+        module_function
+
+        DEFAULT_CONTEXT_WINDOW = 128_000
+        DEFAULT_MAX_TOKENS = 16_384
+        CHAT_MODEL_FAMILIES = %w[gemini claude openai].freeze
+
+        def model_family(model_id)
+          case model_id
+          when /^openai/ then 'openai'
+          when /^gemini/ then 'gemini'
+          when /^claude/ then 'claude'
+          when /^flux|^zimage|^gptimage|^seedream|^nanobanana|^kontext|^imagen|^klein|^wan/ then 'image'
+          when /^veo|^seedance|^grok-video|^ltx/ then 'video'
+          when /^whisper/ then 'transcription'
+          when /^tts|^elevenmusic|^music/ then 'audio'
+          else 'other'
+          end
+        end
+
+        def model_type(model_id)
+          case model_family(model_id)
+          when 'image', 'video' then 'image'
+          when 'transcription', 'audio' then 'audio'
+          else 'chat'
+          end
+        end
+
+        def context_window_for(model_id)
+          case model_family(model_id)
+          when 'gemini' then 1_000_000
+          when 'claude' then 200_000
+          else DEFAULT_CONTEXT_WINDOW
+          end
+        end
+
+        def max_tokens_for(model_id)
+          case model_family(model_id)
+          when 'gemini', 'claude' then 8_192
+          else DEFAULT_MAX_TOKENS
+          end
+        end
+
+        def supports_vision?(model_id)
+          CHAT_MODEL_FAMILIES.include?(model_family(model_id))
+        end
+
+        def supports_functions?(model_id)
+          CHAT_MODEL_FAMILIES.include?(model_family(model_id))
+        end
+
+        def supports_structured_output?(model_id)
+          CHAT_MODEL_FAMILIES.include?(model_family(model_id))
+        end
+
+        def supports_json_mode?(model_id)
+          supports_structured_output?(model_id)
+        end
+
+        def input_price_for(_model_id)
+          0.0
+        end
+
+        def output_price_for(_model_id)
+          0.0
+        end
+
+        def format_display_name(model_id)
+          model_id.tr('-', ' ').split.map(&:capitalize).join(' ')
+        end
+
+        def modalities_for(model_id)
+          case model_type(model_id)
+          when 'image'
+            { input: ['text'], output: ['image'] }
+          when 'audio'
+            { input: %w[text audio], output: ['audio'] }
+          else
+            modalities = { input: ['text'], output: ['text'] }
+            modalities[:input] << 'image' if supports_vision?(model_id)
+            modalities
+          end
+        end
+
+        def capabilities_for(model_id)
+          capabilities = []
+          capabilities << 'streaming' if model_type(model_id) == 'chat'
+          capabilities << 'function_calling' if supports_functions?(model_id)
+          capabilities << 'structured_output' if supports_structured_output?(model_id)
+          capabilities
+        end
+
+        def pricing_for(model_id)
+          {
+            text_tokens: {
+              standard: {
+                input_per_million: input_price_for(model_id),
+                output_per_million: output_price_for(model_id)
+              }
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/chat.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Chat
+        def completion_url
+          'v1/chat/completions'
+        end
+
+        module_function
+
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists
+          payload = {
+            model: model.id,
+            messages: format_messages(messages),
+            stream: stream
+          }
+
+          payload[:temperature] = temperature unless temperature.nil?
+          payload[:tools] = tools.map { |_, tool| Tools.tool_for(tool) } if tools.any?
+
+          if schema
+            strict = schema[:strict] != false
+            payload[:response_format] = {
+              type: 'json_schema',
+              json_schema: {
+                name: 'response',
+                schema: schema,
+                strict: strict
+              }
+            }
+          end
+
+          effort = resolve_effort(thinking)
+          payload[:reasoning_effort] = effort if effort
+
+          payload[:stream_options] = { include_usage: true } if stream
+          payload
+        end
+
+        def parse_completion_response(response)
+          data = response.body
+          return if data.nil? || data.empty?
+
+          raise RubyLLM::Error.new(response, data.dig('error', 'message')) if data.dig('error', 'message')
+
+          message_data = data.dig('choices', 0, 'message')
+          return unless message_data
+
+          usage = data['usage'] || {}
+          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
+          thinking_tokens = usage.dig('completion_tokens_details', 'reasoning_tokens')
+          content, thinking_from_blocks = extract_content_and_thinking(message_data['content'])
+          thinking_text = thinking_from_blocks || extract_thinking_text(message_data)
+
+          RubyLLM::Message.new(
+            role: :assistant,
+            content: content,
+            thinking: RubyLLM::Thinking.build(text: thinking_text),
+            tool_calls: Tools.parse_tool_calls(message_data['tool_calls']),
+            input_tokens: usage['prompt_tokens'],
+            output_tokens: usage['completion_tokens'],
+            cached_tokens: cached_tokens,
+            cache_creation_tokens: 0,
+            thinking_tokens: thinking_tokens,
+            model_id: data['model'],
+            raw: response
+          )
+        end
+
+        def format_messages(messages)
+          messages.map do |msg|
+            {
+              role: msg.role.to_s,
+              content: Media.format_content(msg.content),
+              tool_calls: Tools.format_tool_calls(msg.tool_calls),
+              tool_call_id: msg.tool_call_id
+            }.compact
+          end
+        end
+
+        def resolve_effort(thinking)
+          return nil unless thinking
+
+          thinking.respond_to?(:effort) ? thinking.effort : thinking
+        end
+
+        def extract_thinking_text(message_data)
+          candidate = message_data['reasoning_content'] || message_data['reasoning'] || message_data['thinking']
+          candidate.is_a?(String) ? candidate : nil
+        end
+
+        def extract_content_and_thinking(content)
+          return extract_think_tag_content(content) if content.is_a?(String)
+          return [content, nil] unless content.is_a?(Array)
+
+          text = extract_text_from_blocks(content)
+          thinking = extract_thinking_from_blocks(content)
+
+          [text.empty? ? nil : text, thinking.empty? ? nil : thinking]
+        end
+
+        def extract_text_from_blocks(blocks)
+          blocks.filter_map do |block|
+            block['text'] if block['type'] == 'text' && block['text'].is_a?(String)
+          end.join
+        end
+
+        def extract_thinking_from_blocks(blocks)
+          blocks.filter_map do |block|
+            block['thinking'] if block['type'] == 'thinking' && block['thinking'].is_a?(String)
+          end.join
+        end
+
+        def extract_think_tag_content(text)
+          return [text, nil] unless text.include?('<think>')
+
+          thinking = text.scan(%r{<think>(.*?)</think>}m).join
+          content = text.gsub(%r{<think>.*?</think>}m, '').strip
+
+          [content.empty? ? nil : content, thinking.empty? ? nil : thinking]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/images.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Images
+        module_function
+
+        VIDEO_MODELS = %w[veo seedance seedance-pro grok-video ltx-2].freeze
+        DEFAULT_IMAGE_MODEL = 'flux'
+
+        def images_url(prompt, **options)
+          encoded_prompt = ERB::Util.url_encode(prompt)
+          params = build_image_params(options)
+          query_string = params.empty? ? '' : "?#{URI.encode_www_form(params)}"
+          "image/#{encoded_prompt}#{query_string}"
+        end
+
+        def render_image_payload(prompt, model:, size:, **options)
+          width, height = parse_size(size)
+          {
+            prompt: prompt,
+            model: model || DEFAULT_IMAGE_MODEL,
+            width: width,
+            height: height
+          }.merge(options.slice(:image, :seed, :quality, :safe, :enhance, :negative_prompt,
+                                :duration, :aspect_ratio, :audio))
+        end
+
+        def parse_image_response(response, model:)
+          content_type = response.headers['content-type'] || ''
+          is_video = video_response?(content_type, model)
+          mime_type = extract_mime_type(content_type, is_video)
+          data = Base64.strict_encode64(response.body)
+
+          RubyLLM::Image.new(
+            data: data,
+            mime_type: mime_type,
+            model_id: model
+          )
+        end
+
+        def video_model?(model)
+          VIDEO_MODELS.include?(model.to_s.downcase)
+        end
+
+        def video_response?(content_type, model)
+          content_type.include?('video/') || video_model?(model)
+        end
+
+        BASIC_PARAMS = %i[model width height seed quality].freeze
+        BOOLEAN_PARAMS = %i[safe enhance].freeze
+
+        def build_image_params(options)
+          params = extract_basic_params(options)
+          extract_boolean_params(params, options)
+          params[:negative_prompt] = options[:negative_prompt] if options[:negative_prompt]
+          params[:image] = options[:image] if options[:image]
+          params[:nologo] = true
+          params[:private] = true
+          add_video_params(params, options) if options[:model] && video_model?(options[:model])
+          params
+        end
+
+        def extract_basic_params(options)
+          BASIC_PARAMS.each_with_object({}) do |key, params|
+            params[key] = options[key] if options[key]
+          end
+        end
+
+        def extract_boolean_params(params, options)
+          BOOLEAN_PARAMS.each do |key|
+            params[key] = options[key] if options.key?(key)
+          end
+        end
+
+        def add_video_params(params, options)
+          params[:duration] = options[:duration] if options[:duration]
+          params[:aspectRatio] = options[:aspect_ratio] if options[:aspect_ratio]
+          params[:audio] = options[:audio] if options.key?(:audio)
+        end
+
+        def parse_size(size)
+          return [1024, 1024] unless size
+
+          parts = size.to_s.split('x')
+          return [1024, 1024] unless parts.length == 2
+
+          [parts[0].to_i, parts[1].to_i]
+        end
+
+        def extract_mime_type(content_type, is_video)
+          return 'video/mp4' if is_video && !content_type.include?('video/')
+          return content_type.split(';').first.strip unless content_type.empty?
+
+          is_video ? 'video/mp4' : 'image/jpeg'
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/media.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Media
+        module_function
+
+        def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
+          return content.value if content.is_a?(RubyLLM::Content::Raw)
+          return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
+          return content unless content.is_a?(RubyLLM::Content)
+
+          parts = []
+          parts << format_text(content.text) if content.text
+
+          content.attachments.each do |attachment|
+            case attachment.type
+            when :image
+              parts << format_image(attachment)
+            when :pdf
+              parts << format_pdf(attachment)
+            when :audio
+              parts << format_audio(attachment)
+            when :text
+              parts << format_text_file(attachment)
+            else
+              raise RubyLLM::UnsupportedAttachmentError, attachment.type
+            end
+          end
+
+          parts
+        end
+
+        def format_image(image)
+          {
+            type: 'image_url',
+            image_url: {
+              url: image.url? ? image.source.to_s : image.for_llm
+            }
+          }
+        end
+
+        def format_pdf(pdf)
+          {
+            type: 'file',
+            file: {
+              filename: pdf.filename,
+              file_data: pdf.for_llm
+            }
+          }
+        end
+
+        def format_text_file(text_file)
+          {
+            type: 'text',
+            text: text_file.for_llm
+          }
+        end
+
+        def format_audio(audio)
+          {
+            type: 'input_audio',
+            input_audio: {
+              data: audio.encoded,
+              format: audio.format
+            }
+          }
+        end
+
+        def format_text(text)
+          {
+            type: 'text',
+            text: text
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/models.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Models
+        module_function
+
+        def models_url
+          'v1/models'
+        end
+
+        def parse_list_models_response(response, slug, capabilities)
+          Array(response.body['data']).map do |model_data|
+            build_model_info(model_data, slug, capabilities)
+          end
+        end
+
+        def build_model_info(model_data, slug, capabilities)
+          model_id = model_data['id']
+
+          RubyLLM::Model::Info.new(
+            id: model_id,
+            name: capabilities.format_display_name(model_id),
+            provider: slug,
+            family: capabilities.model_family(model_id),
+            created_at: parse_created_at(model_data['created']),
+            context_window: capabilities.context_window_for(model_id),
+            max_output_tokens: capabilities.max_tokens_for(model_id),
+            modalities: capabilities.modalities_for(model_id),
+            capabilities: capabilities.capabilities_for(model_id),
+            pricing: capabilities.pricing_for(model_id),
+            metadata: build_metadata(model_data)
+          )
+        end
+
+        def parse_created_at(created)
+          return nil unless created
+
+          Time.at(created)
+        end
+
+        def build_metadata(model_data)
+          {
+            object: model_data['object'],
+            owned_by: model_data['owned_by']
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/pollinations.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      class Pollinations < RubyLLM::Provider
+        include Chat
+        include Media
+        include Streaming
+        include Tools
+        include Images
+        include Audio
+        include Transcription
+        include Models
+        include Account
+
+        IMAGE_API_BASE = 'https://gen.pollinations.ai'
+
+        def api_base
+          @config.pollinations_api_base || 'https://gen.pollinations.ai'
+        end
+
+        def headers
+          {
+            'Authorization' => "Bearer #{@config.pollinations_api_key}",
+            'Content-Type' => 'application/json'
+          }.compact
+        end
+
+        def paint(prompt, model:, size:, **options)
+          payload = render_image_payload(prompt, model: model, size: size, **options)
+          url = images_url(prompt, **payload)
+          response = image_connection.get(url)
+          parse_image_response(response, model: model)
+        end
+
+        def speak(input, model:, voice: nil, **options)
+          payload = render_speech_payload(input, model: model, voice: voice, **options)
+          response = @connection.post(speech_url, payload)
+          parse_speech_response(response, model: model)
+        end
+
+        class << self
+          def capabilities
+            Capabilities
+          end
+
+          def configuration_options
+            %i[pollinations_api_key pollinations_api_base]
+          end
+
+          def configuration_requirements
+            %i[pollinations_api_key]
+          end
+        end
+
+        private
+
+        def image_connection
+          @image_connection ||= Faraday.new(IMAGE_API_BASE) do |faraday|
+            faraday.options.timeout = @config.request_timeout || 600
+            faraday.response :logger, RubyLLM.logger, bodies: false, log_level: :debug
+            faraday.request :retry, max: @config.max_retries || 3, retry_statuses: [429, 500, 502, 503, 504]
+            faraday.adapter :net_http
+            faraday.use :llm_errors, provider: self
+            faraday.headers['Authorization'] = "Bearer #{@config.pollinations_api_key}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/streaming.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Streaming
+        module_function
+
+        def stream_url
+          completion_url
+        end
+
+        def build_chunk(data)
+          usage = data['usage'] || {}
+          cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
+          delta = data.dig('choices', 0, 'delta') || {}
+          content_source = delta['content'] || data.dig('choices', 0, 'message', 'content')
+          content, thinking_from_blocks = Chat.extract_content_and_thinking(content_source)
+
+          RubyLLM::Chunk.new(
+            role: :assistant,
+            model_id: data['model'],
+            content: content,
+            thinking: RubyLLM::Thinking.build(
+              text: thinking_from_blocks || delta['reasoning_content'] || delta['reasoning']
+            ),
+            tool_calls: Tools.parse_tool_calls(delta['tool_calls'], parse_arguments: false),
+            input_tokens: usage['prompt_tokens'],
+            output_tokens: usage['completion_tokens'],
+            cached_tokens: cached_tokens,
+            cache_creation_tokens: 0,
+            thinking_tokens: usage.dig('completion_tokens_details', 'reasoning_tokens')
+          )
+        end
+
+        def parse_streaming_error(data)
+          error_data = JSON.parse(data)
+          return unless error_data['error']
+
+          error = error_data['error']
+          code = error['code'] || error['type']
+
+          case code
+          when 'RATE_LIMIT', 'rate_limit_exceeded', 'insufficient_quota'
+            [429, error['message']]
+          when 'INTERNAL_ERROR', 'server_error'
+            [500, error['message']]
+          when 'UNAUTHORIZED'
+            [401, error['message']]
+          when 'PAYMENT_REQUIRED'
+            [402, error['message']]
+          else
+            [400, error['message']]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/tools.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Tools
+        module_function
+
+        EMPTY_PARAMETERS_SCHEMA = {
+          'type' => 'object',
+          'properties' => {},
+          'required' => [],
+          'additionalProperties' => false,
+          'strict' => true
+        }.freeze
+
+        def parameters_schema_for(tool)
+          tool.params_schema || schema_from_parameters(tool.parameters)
+        end
+
+        def schema_from_parameters(parameters)
+          schema_definition = RubyLLM::Tool::SchemaDefinition.from_parameters(parameters)
+          schema_definition&.json_schema || EMPTY_PARAMETERS_SCHEMA
+        end
+
+        def tool_for(tool)
+          parameters_schema = parameters_schema_for(tool)
+
+          definition = {
+            type: 'function',
+            function: {
+              name: tool.name,
+              description: tool.description,
+              parameters: parameters_schema
+            }
+          }
+
+          return definition if tool.provider_params.empty?
+
+          RubyLLM::Utils.deep_merge(definition, tool.provider_params)
+        end
+
+        def format_tool_calls(tool_calls)
+          return nil unless tool_calls&.any?
+
+          tool_calls.map do |_, tc|
+            {
+              id: tc.id,
+              type: 'function',
+              function: {
+                name: tc.name,
+                arguments: JSON.generate(tc.arguments)
+              }
+            }
+          end
+        end
+
+        def parse_tool_call_arguments(tool_call)
+          arguments = tool_call.dig('function', 'arguments')
+
+          if arguments.nil? || arguments.empty?
+            {}
+          else
+            JSON.parse(arguments)
+          end
+        end
+
+        def parse_tool_calls(tool_calls, parse_arguments: true)
+          return nil unless tool_calls&.any?
+
+          tool_calls.to_h do |tc|
+            [
+              tc['id'],
+              RubyLLM::ToolCall.new(
+                id: tc['id'],
+                name: tc.dig('function', 'name'),
+                arguments: parse_arguments ? parse_tool_call_arguments(tc) : tc.dig('function', 'arguments')
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/provider/transcription.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    module Provider
+      module Transcription
+        module_function
+
+        SUPPORTED_MODELS = %w[whisper-large-v3 whisper-1].freeze
+        DEFAULT_MODEL = 'whisper-large-v3'
+        RESPONSE_FORMATS = %w[json text srt verbose_json vtt].freeze
+
+        def transcription_url
+          'v1/audio/transcriptions'
+        end
+
+        def render_transcription_payload(file_part, model:, language:, **options)
+          {
+            file: file_part,
+            model: model || DEFAULT_MODEL,
+            language: language,
+            prompt: options[:prompt],
+            response_format: options[:response_format] || 'json',
+            temperature: options[:temperature]
+          }.compact
+        end
+
+        def parse_transcription_response(response, model:)
+          data = response.body
+          return RubyLLM::Transcription.new(text: data, model: model) if data.is_a?(String)
+
+          RubyLLM::Transcription.new(
+            text: data['text'],
+            model: model,
+            language: data['language'],
+            duration: data['duration'],
+            segments: data['segments']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/pollinations/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Pollinations
+    VERSION = '0.1.0'
+  end
+end

data/lib/ruby_llm-pollinations.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+require_relative 'ruby_llm/pollinations/version'
+require_relative 'ruby_llm/pollinations/audio_output'
+require_relative 'ruby_llm/pollinations/patches/provider_paint'
+require_relative 'ruby_llm/pollinations/patches/image_paint'
+require_relative 'ruby_llm/pollinations/patches/speak'
+require_relative 'ruby_llm/pollinations/provider/capabilities'
+require_relative 'ruby_llm/pollinations/provider/chat'
+require_relative 'ruby_llm/pollinations/provider/streaming'
+require_relative 'ruby_llm/pollinations/provider/tools'
+require_relative 'ruby_llm/pollinations/provider/media'
+require_relative 'ruby_llm/pollinations/provider/images'
+require_relative 'ruby_llm/pollinations/provider/audio'
+require_relative 'ruby_llm/pollinations/provider/transcription'
+require_relative 'ruby_llm/pollinations/provider/models'
+require_relative 'ruby_llm/pollinations/provider/account'
+require_relative 'ruby_llm/pollinations/provider/pollinations'
+
+RubyLLM::Provider.register :pollinations, RubyLLM::Pollinations::Provider::Pollinations

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-pollinations
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Compasify
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.14.0
+description: Adds Pollinations AI support to RubyLLM — chat, image/video generation,
+  TTS/music, and transcription via the Pollinations API. Installs as a standalone
+  gem without modifying RubyLLM core.
+email:
+- timdapan.com@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_llm-pollinations.rb
+- lib/ruby_llm/pollinations/audio_output.rb
+- lib/ruby_llm/pollinations/patches/image_paint.rb
+- lib/ruby_llm/pollinations/patches/provider_paint.rb
+- lib/ruby_llm/pollinations/patches/speak.rb
+- lib/ruby_llm/pollinations/provider/account.rb
+- lib/ruby_llm/pollinations/provider/audio.rb
+- lib/ruby_llm/pollinations/provider/capabilities.rb
+- lib/ruby_llm/pollinations/provider/chat.rb
+- lib/ruby_llm/pollinations/provider/images.rb
+- lib/ruby_llm/pollinations/provider/media.rb
+- lib/ruby_llm/pollinations/provider/models.rb
+- lib/ruby_llm/pollinations/provider/pollinations.rb
+- lib/ruby_llm/pollinations/provider/streaming.rb
+- lib/ruby_llm/pollinations/provider/tools.rb
+- lib/ruby_llm/pollinations/provider/transcription.rb
+- lib/ruby_llm/pollinations/version.rb
+homepage: https://github.com/compasify/ruby_llm-pollinations
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/compasify/ruby_llm-pollinations
+  source_code_uri: https://github.com/compasify/ruby_llm-pollinations
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Pollinations AI provider for RubyLLM
+test_files: []