turnkit 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5694bc97b2f735e5076574e2863ee5addc41926bd85edf02e1835263ffb3516
-  data.tar.gz: 65286330a1d0b4bbd0e3e6c11ba73abd836fb22a44ae4b3ab48a58ecf9d19425
+  metadata.gz: 67553a737fbce38e2402167aeb2cc799c55390c5c7c9740a8d73d056b0679a06
+  data.tar.gz: fc395c09f05e8ba640ec9dda4907419f0a76a47e8a45607435c5dde0630c3562
 SHA512:
-  metadata.gz: 2b3674abf0cae37286a04431f0ceb02a30e282c715e4d6d96e51c0a08d600c94a9fee6c82bf178c0b97ff080ee221b00a18b5409e72003d92c7a5430b34d5733
-  data.tar.gz: 7141f5cc00df42bfaf0e9b035d75f54e0b7c9b14ff71a8c95805242b32835fb410358f7f42ff2161f89896425b62fd840c05dcc2504f555430450517dc61bf9b
+  metadata.gz: 45864840f7bc24d3626e0e3bb849f2ea3d71c1fdb8a2faa7ff19725ab0b6932d205962208c2ea75be7014d8f0befa7c6ebd754e0f5dfedd7db6875fff90254a9
+  data.tar.gz: 7dc83b0922078e52fb220438097514c0efba0d10740a9cec40e810f316d42c6e50fdc67f92db2cb9e9564fdcab376a1e01286d8821effa4a9246e51f8baf6c1c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.1 - 2026-06-19
+
+- Add first-class media analysis with `Turn#view_media`, `TurnKit.view_media`, and `TurnKit::ViewMediaTool`.
+- Normalize media inputs for paths, URLs, IO/bytes, and Rails Active Storage-compatible attachments.
+- Persist media analysis messages with model, provider, usage, cost, structured output, events, and output policy support.
+- Add a Gemini 3 Flash media-analysis smoke example.
+
+## 0.4.0 - 2026-06-19
+
+- Add first-class image generation with `Turn#paint`, `TurnKit.paint`, and `TurnKit::ImageTool`.
+- Persist generated images as durable image messages with normalized metadata, usage, cost, and event callbacks.
+- Add image output policy support and a `generate-image` CLI smoke example for Gemini 16:9 image generation.
+
 ## 0.3.0 - 2026-06-10
 
 - Make the task-runtime API skills-first and intentionally breaking: `max_spend` is the only spend-limit name and output validation is exposed as `output_policy` / `policy_audit`.

data/README.md

@@ -459,6 +459,121 @@ puts turn.output_text
 
 Rely on TurnKit to validate tools and model-provided arguments.
 
+### Images
+
+Generate images inside a durable turn with `turn.paint`. The image call uses the
+configured client adapter, records usage and cost on the turn, persists an image
+message, and emits `image.requested` / `image.completed` events.
+
+```ruby
+image = turn.paint(
+  "Create a 16:9 editorial header image for the article.",
+  model: "gemini-3-pro-image-preview",
+  provider: :gemini,
+  size: "1024x576",
+  metadata: { article_id: article.id }
+)
+
+image.url       # provider-hosted URL when returned
+image.to_blob   # generated bytes for base64 responses, or fetched URL bytes
+image.mime_type # "image/png"
+```
+
+For reusable workflow steps, subclass `TurnKit::ImageTool`:
+
+```ruby
+class GenerateHeaderImage < TurnKit::ImageTool
+  description "Generate an article header image."
+  parameter :title, :string, required: true
+
+  model "gemini-3-pro-image-preview"
+  provider :gemini
+  size "1024x576"
+
+  def prompt(title:)
+    "Create a 16:9 editorial header image for #{title}."
+  end
+end
+```
+
+Rails apps can attach generated images from the event stream without TurnKit
+taking a dependency on Active Storage:
+
+```ruby
+TurnKit.on_event = ->(event) do
+  next unless event.type == "image.completed"
+
+  image = TurnKit::ImageResult.from_h(event.payload.fetch(:image))
+  Article.find(event.payload.dig(:metadata, :article_id)).header_image.attach(
+    io: StringIO.new(image.to_blob),
+    filename: "header.png",
+    content_type: image.mime_type
+  )
+end
+```
+
+Require an image before completion with `TurnKit::OutputPolicy.require_image`.
+
+### Media analysis
+
+Analyze existing images, PDFs, audio, or video inside a durable turn with
+`turn.view_media`. Media inputs can be local paths, URLs, IO-like objects,
+`TurnKit::MediaInput.bytes(...)`, or Rails Active Storage blobs/attachments.
+TurnKit records usage and cost on the turn, persists a media analysis message,
+and emits `media.requested` / `media.completed` / `media.failed` events.
+
+```ruby
+analysis = turn.view_media(
+  article.header_image,
+  objective: "Verify this generated header matches the article art direction.",
+  model: "gemini-2.5-pro",
+  provider: :gemini,
+  metadata: { article_id: article.id }
+)
+
+analysis.text          # text analysis
+analysis.data          # structured output when requested
+analysis.media         # normalized media metadata
+```
+
+For bytes, provide a MIME type so adapters can pass the media correctly:
+
+```ruby
+media = TurnKit::MediaInput.bytes(
+  File.binread("header.png"),
+  mime_type: "image/png",
+  filename: "header.png"
+)
+```
+
+For reusable workflow steps, subclass `TurnKit::ViewMediaTool`:
+
+```ruby
+class ReviewHeaderImage < TurnKit::ViewMediaTool
+  description "Review a generated article header image."
+  parameter :article_id, :integer, required: true
+
+  model "gemini-2.5-pro"
+  provider :gemini
+
+  def media(article_id:)
+    Article.find(article_id).header_image
+  end
+
+  def objective(article_id:)
+    "Review this generated image against the article art direction."
+  end
+
+  def metadata(article_id:)
+    { article_id: article_id }
+  end
+end
+```
+
+Require a media review before completion with
+`TurnKit::OutputPolicy.require_media_analysis`. TurnKit persists media metadata
+and analysis text, not raw media bytes.
+
 ### Structured Output
 
 Define a schema:

data/lib/turnkit/adapters/ruby_llm.rb

@@ -41,6 +41,40 @@ module TurnKit
         normalize_response(response, model: model)
       end
 
+      def paint(prompt:, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: nil, on_event: nil)
+        require "ruby_llm"
+
+        configure_from_environment
+        kwargs = paint_kwargs(
+          model: model,
+          provider: provider,
+          assume_model_exists: assume_model_exists || false,
+          size: size || "1024x1024",
+          with: input_images,
+          mask: mask,
+          params: params || {}
+        )
+        image = ::RubyLLM.paint(prompt, **kwargs)
+        normalize_image_response(image, model: model, provider: provider, params: { "size" => size || "1024x1024" }.merge(params || {}), metadata: metadata)
+      end
+
+      def view_media(media:, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: nil, on_event: nil)
+        require "ruby_llm"
+
+        configure_from_environment
+        media_input = MediaInput.wrap(media)
+        content = ::RubyLLM::Content.new(objective.to_s)
+        content.add_attachment(media_input.attachment_source, filename: media_input.filename)
+
+        chat = ::RubyLLM.chat(model: model)
+        chat.with_schema(normalize_schema(output_schema)) if output_schema
+        chat.with_params(**params) if params && !params.empty?
+        chat.add_message(role: :user, content: content)
+
+        response = complete_without_tool_execution(chat)
+        normalize_media_analysis_response(response, media: media_input, model: model, provider: provider, params: params || {}, metadata: metadata)
+      end
+
       private
         def configure_from_environment
           config = ::RubyLLM.config
@@ -246,6 +280,70 @@ module TurnKit
 
           response.cost&.total
         end
+
+        def paint_kwargs(kwargs)
+          parameters = ::RubyLLM::Image.method(:paint).parameters
+          return kwargs if parameters.any? { |kind, _| kind == :keyrest }
+
+          accepted = parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }
+          unsupported = kwargs.keys.select { |key| !accepted.include?(key) && !blank?(kwargs[key]) }
+          raise ArgumentError, "RubyLLM image generation does not support: #{unsupported.join(", ")}" if unsupported.any?
+
+          kwargs.slice(*accepted)
+        end
+
+        def blank?(value)
+          value.nil? || value == false || (value.respond_to?(:empty?) && value.empty?)
+        end
+
+        def normalize_image_response(image, model:, provider:, params:, metadata:)
+          usage = Usage.new(
+            input_tokens: image_usage_value(image, "input_tokens"),
+            output_tokens: image_usage_value(image, "output_tokens"),
+            cost: response_cost(image)
+          )
+          part = ImageResult.new(
+            url: image.respond_to?(:url) ? image.url : nil,
+            data: image.respond_to?(:data) ? image.data : nil,
+            mime_type: image.respond_to?(:mime_type) ? image.mime_type : nil,
+            revised_prompt: image.respond_to?(:revised_prompt) ? image.revised_prompt : nil,
+            model: image.respond_to?(:model_id) ? image.model_id : model,
+            provider: provider&.to_s,
+            usage: usage,
+            params: params,
+            metadata: metadata || {}
+          ).to_h.merge("type" => "image")
+
+          Result.new(parts: [ part ], usage: usage, model: part["model"], output_data: { "type" => "image", "images" => [ part ] })
+        end
+
+        def normalize_media_analysis_response(response, media:, model:, provider:, params:, metadata:)
+          usage = Usage.new(
+            input_tokens: token_value(response, :input_tokens),
+            output_tokens: token_value(response, :output_tokens),
+            cached_tokens: token_value(response, :cached_tokens),
+            cache_write_tokens: token_value(response, :cache_creation_tokens),
+            thinking_tokens: thinking_token_value(response),
+            cost: response_cost(response)
+          )
+          part = MediaAnalysisResult.new(
+            text: response_text(response),
+            data: response_data(response),
+            model: response.respond_to?(:model_id) ? response.model_id : model,
+            provider: provider&.to_s,
+            usage: usage,
+            params: params,
+            media: media.to_h,
+            metadata: metadata || {}
+          ).to_h.merge("type" => "media_analysis")
+
+          Result.new(parts: [ part ], usage: usage, model: part["model"], output_data: { "type" => "media_analysis", "media_analyses" => [ part ] })
+        end
+
+        def image_usage_value(image, key)
+          usage = image.respond_to?(:usage) ? image.usage || {} : {}
+          (usage[key] || usage[key.to_sym]).to_i
+        end
     end
   end
 end

data/lib/turnkit/client.rb

@@ -9,5 +9,13 @@ module TurnKit
     def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
       raise NotImplementedError
     end
+
+    def paint(prompt:, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: nil, on_event: nil)
+      raise NotImplementedError
+    end
+
+    def view_media(media:, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: nil, on_event: nil)
+      raise NotImplementedError
+    end
   end
 end

data/lib/turnkit/image_result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "base64"
+require "open-uri"
+
+module TurnKit
+  class ImageResult
+    attr_reader :url, :data, :mime_type, :revised_prompt, :model, :provider, :usage, :params, :metadata
+
+    def self.from_h(value)
+      new(**value.transform_keys(&:to_sym))
+    end
+
+    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model: nil, provider: nil, usage: Usage.new, params: {}, metadata: {}, **)
+      @url = url
+      @data = data
+      @mime_type = mime_type
+      @revised_prompt = revised_prompt
+      @model = model
+      @provider = provider
+      @usage = usage.is_a?(Usage) ? usage : Usage.from_h(usage || {})
+      @params = params || {}
+      @metadata = metadata || {}
+    end
+
+    def to_blob
+      raise Error, "image has no url or data" if url.to_s.empty? && data.to_s.empty?
+
+      data ? Base64.decode64(data) : URI.open(url, &:read)
+    end
+
+    def cost
+      Cost.from_usage(usage, model: model)
+    end
+
+    def to_h
+      {
+        "url" => url,
+        "data" => data,
+        "mime_type" => mime_type,
+        "revised_prompt" => revised_prompt,
+        "model" => model,
+        "provider" => provider,
+        "usage" => usage.to_h,
+        "cost" => cost.to_h,
+        "params" => params,
+        "metadata" => metadata
+      }.compact
+    end
+  end
+end

data/lib/turnkit/image_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ImageTool < Tool
+    class << self
+      %i[model provider size assume_model_exists params].each do |name|
+        define_method(name) do |value = nil|
+          instance_variable_set("@#{name}", value) unless value.nil?
+          instance_variable_get("@#{name}")
+        end
+      end
+    end
+
+    def call(turnkit_context:, **arguments)
+      turnkit_context.turn.paint(
+        prompt(**arguments),
+        model: self.class.model,
+        provider: self.class.provider,
+        size: self.class.size,
+        assume_model_exists: self.class.assume_model_exists,
+        params: self.class.params || {},
+        metadata: metadata(**arguments)
+      ).to_h
+    end
+
+    def metadata(**)
+      {}
+    end
+  end
+end

data/lib/turnkit/media_analysis_result.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class MediaAnalysisResult
+    attr_reader :text, :data, :model, :provider, :usage, :params, :media, :metadata, :error
+
+    def self.from_h(value)
+      new(**value.transform_keys(&:to_sym))
+    end
+
+    def initialize(text: "", data: nil, model: nil, provider: nil, usage: Usage.new, params: {}, media: {}, metadata: {}, error: nil, **)
+      @text = text.to_s
+      @data = data
+      @model = model
+      @provider = provider
+      @usage = usage.is_a?(Usage) ? usage : Usage.from_h(usage || {})
+      @params = params || {}
+      @media = media || {}
+      @metadata = metadata || {}
+      @error = error
+    end
+
+    def data?
+      !data.nil?
+    end
+
+    alias structured? data?
+
+    def cost
+      Cost.from_usage(usage, model: model)
+    end
+
+    def to_h
+      {
+        "text" => text,
+        "data" => data,
+        "model" => model,
+        "provider" => provider,
+        "usage" => usage.to_h,
+        "cost" => cost.to_h,
+        "params" => params,
+        "media" => media,
+        "metadata" => metadata,
+        "error" => error
+      }.compact
+    end
+  end
+end

data/lib/turnkit/media_input.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+require "uri"
+
+module TurnKit
+  class MediaInput
+    SUPPORTED_MIME_TYPES = %w[image/png image/jpeg image/webp image/gif application/pdf].freeze
+    EXTENSION_MIME_TYPES = {
+      ".png" => "image/png",
+      ".jpg" => "image/jpeg",
+      ".jpeg" => "image/jpeg",
+      ".webp" => "image/webp",
+      ".gif" => "image/gif",
+      ".pdf" => "application/pdf",
+      ".mp3" => "audio/mpeg",
+      ".wav" => "audio/wav",
+      ".m4a" => "audio/mp4",
+      ".mp4" => "video/mp4",
+      ".mov" => "video/quicktime",
+      ".webm" => "video/webm"
+    }.freeze
+
+    attr_reader :source, :mime_type, :filename, :metadata, :source_type
+
+    def self.wrap(value, **options)
+      value.is_a?(self) && options.empty? ? value : new(value, **options)
+    end
+
+    def self.bytes(data, mime_type:, filename: nil, metadata: {})
+      new(data, source_type: :bytes, mime_type: mime_type, filename: filename, metadata: metadata)
+    end
+
+    def initialize(source, mime_type: nil, filename: nil, metadata: {}, source_type: nil)
+      @source = source
+      @source_type = (source_type || infer_source_type).to_s
+      @filename = filename || infer_filename
+      @mime_type = mime_type || infer_mime_type
+      @metadata = metadata || {}
+
+      validate!
+    end
+
+    def kind
+      return "image" if mime_type&.start_with?("image/")
+      return "audio" if mime_type&.start_with?("audio/")
+      return "video" if mime_type&.start_with?("video/")
+      return "pdf" if mime_type == "application/pdf"
+
+      nil
+    end
+
+    def byte_size
+      case source_type
+      when "path"
+        File.size(source.to_s) if File.file?(source.to_s)
+      when "bytes"
+        source.bytesize
+      when "io"
+        source.size if source.respond_to?(:size)
+      when "active_storage"
+        active_storage_byte_size
+      end
+    end
+
+    def url
+      source.to_s if source_type == "url"
+    end
+
+    def path
+      source.to_s if source_type == "path"
+    end
+
+    def attachment_source
+      case source_type
+      when "bytes"
+        StringIO.new(source)
+      else
+        source
+      end
+    end
+
+    def to_h
+      {
+        "kind" => kind,
+        "mime_type" => mime_type,
+        "filename" => filename,
+        "byte_size" => byte_size,
+        "url" => url,
+        "path" => path,
+        "metadata" => metadata
+      }.compact
+    end
+
+    private
+      def infer_source_type
+        return :url if source.to_s.match?(%r{\Ahttps?://})
+        return :active_storage if active_storage?
+        return :path if source.is_a?(Pathname) || (source.is_a?(String) && File.exist?(source))
+        return :io if source.respond_to?(:read)
+        return :bytes if source.is_a?(String)
+
+        raise ArgumentError, "unsupported media input: #{source.class}"
+      end
+
+      def infer_filename
+        case source_type
+        when "url"
+          basename = File.basename(URI(source.to_s).path).to_s
+          basename.empty? ? nil : basename
+        when "path"
+          File.basename(source.to_s)
+        when "io"
+          source.respond_to?(:path) ? File.basename(source.path.to_s) : nil
+        when "active_storage"
+          active_storage_filename
+        end
+      end
+
+      def infer_mime_type
+        active_storage_content_type || mime_from_filename || mime_from_marcel
+      end
+
+      def mime_from_filename
+        EXTENSION_MIME_TYPES[File.extname(filename.to_s).downcase]
+      end
+
+      def mime_from_marcel
+        require "marcel"
+
+        Marcel::MimeType.for(marcel_io, name: filename)
+      rescue LoadError
+        nil
+      ensure
+        rewind_source
+      end
+
+      def marcel_io
+        case source_type
+        when "path"
+          Pathname.new(source.to_s)
+        when "bytes"
+          StringIO.new(source)
+        when "io"
+          source
+        else
+          nil
+        end
+      end
+
+      def validate!
+        return if mime_type.nil?
+        return if SUPPORTED_MIME_TYPES.include?(mime_type)
+        return if mime_type.start_with?("audio/", "video/")
+
+        raise ArgumentError, "unsupported media type: #{mime_type}"
+      end
+
+      def active_storage?
+        return false unless defined?(ActiveStorage)
+
+        (defined?(ActiveStorage::Blob) && source.is_a?(ActiveStorage::Blob)) ||
+          (defined?(ActiveStorage::Attached::One) && source.is_a?(ActiveStorage::Attached::One)) ||
+          (defined?(ActiveStorage::Attached::Many) && source.is_a?(ActiveStorage::Attached::Many))
+      end
+
+      def active_storage_filename
+        if defined?(ActiveStorage::Blob) && source.is_a?(ActiveStorage::Blob)
+          source.filename.to_s
+        elsif source.respond_to?(:filename)
+          source.filename.to_s
+        elsif source.respond_to?(:blob)
+          source.blob&.filename&.to_s
+        elsif source.respond_to?(:blobs)
+          source.blobs.first&.filename&.to_s
+        end
+      end
+
+      def active_storage_content_type
+        if defined?(ActiveStorage::Blob) && source.is_a?(ActiveStorage::Blob)
+          source.content_type
+        elsif source.respond_to?(:content_type)
+          source.content_type
+        elsif source.respond_to?(:blob)
+          source.blob&.content_type
+        elsif source.respond_to?(:blobs)
+          source.blobs.first&.content_type
+        end
+      end
+
+      def active_storage_byte_size
+        if defined?(ActiveStorage::Blob) && source.is_a?(ActiveStorage::Blob)
+          source.byte_size
+        elsif source.respond_to?(:byte_size)
+          source.byte_size
+        elsif source.respond_to?(:blob)
+          source.blob&.byte_size
+        elsif source.respond_to?(:blobs)
+          source.blobs.first&.byte_size
+        end
+      end
+
+      def rewind_source
+        source.rewind if source_type == "io" && source.respond_to?(:rewind)
+      end
+  end
+end

data/lib/turnkit/message.rb

@@ -3,7 +3,7 @@
 module TurnKit
   class Message
     ROLES = %w[user assistant tool].freeze
-    KINDS = %w[text tool_call tool_result context_summary].freeze
+    KINDS = %w[text tool_call tool_result context_summary image media_analysis].freeze
 
     attr_reader :id, :conversation_id, :turn_id, :role, :kind, :sequence
     attr_reader :content, :tool_execution_id, :provider_message_id, :metadata, :created_at
@@ -57,6 +57,14 @@ module TurnKit
       kind == "context_summary"
     end
 
+    def image?
+      kind == "image"
+    end
+
+    def media_analysis?
+      kind == "media_analysis"
+    end
+
     def text
       content.filter_map do |part|
         attrs = stringify(part)

data/lib/turnkit/message_projection.rb

@@ -44,6 +44,10 @@ module TurnKit
       when "tool_result"
         part = message.content.find { |candidate| candidate.fetch("type") == "tool_result" }
         { role: :tool, content: part&.fetch("text", message.text) || message.text, tool_call_id: part&.fetch("tool_call_id", nil) }
+      when "image"
+        { role: :assistant, content: projected_images }
+      when "media_analysis"
+        { role: :assistant, content: projected_media_analyses }
       else
         { role: message.role.to_sym, content: message.text }
       end
@@ -65,5 +69,23 @@ module TurnKit
           { "id" => part.fetch("id"), "name" => part.fetch("name"), "arguments" => part["arguments"] || {} }
         end
       end
+
+      def projected_images
+        message.content.filter_map do |part|
+          next unless part.fetch("type") == "image"
+
+          attrs = part.slice("url", "mime_type", "model", "provider", "revised_prompt").compact
+          "Generated image: #{attrs.to_json}"
+        end.join("\n")
+      end
+
+      def projected_media_analyses
+        message.content.filter_map do |part|
+          next unless part.fetch("type") == "media_analysis"
+
+          media = part.fetch("media", {}).slice("kind", "mime_type", "filename", "url").compact
+          [ "Media analysis: #{media.to_json}", part["text"].to_s ].reject(&:empty?).join("\n")
+        end.join("\n")
+      end
   end
 end

data/lib/turnkit/output_policy.rb

@@ -31,6 +31,24 @@ module TurnKit
       new(name: skill.key, content: skill.content, **options)
     end
 
+    def self.require_image
+      lambda do |output, output_data: nil, turn: nil, **|
+        data = output_data.is_a?(Hash) ? output_data : output
+        images = data.is_a?(Hash) ? data["images"] || data[:images] : nil
+        has_image = Array(images).any? || turn&.conversation&.messages_for_turn(turn)&.any?(&:image?)
+        { rule: "image_required", message: "output must include an image result" } unless has_image
+      end
+    end
+
+    def self.require_media_analysis
+      lambda do |output, output_data: nil, turn: nil, **|
+        data = output_data.is_a?(Hash) ? output_data : output
+        analyses = data.is_a?(Hash) ? data["media_analyses"] || data[:media_analyses] : nil
+        has_analysis = Array(analyses).any? || turn&.conversation&.messages_for_turn(turn)&.any?(&:media_analysis?)
+        { rule: "media_analysis_required", message: "output must include a media analysis result" } unless has_analysis
+      end
+    end
+
     def initialize(content:, name: "output_policy", model: nil, thinking: nil, client: nil)
       @name = name.to_s
       @content = content.to_s

data/lib/turnkit/result.rb

@@ -28,6 +28,30 @@ module TurnKit
       tool_calls.any?
     end
 
+    def images
+      parts.filter_map do |part|
+        next unless part["type"] == "image"
+
+        ImageResult.from_h(part)
+      end
+    end
+
+    def image?
+      images.any?
+    end
+
+    def media_analyses
+      parts.filter_map do |part|
+        next unless part["type"] == "media_analysis"
+
+        MediaAnalysisResult.from_h(part)
+      end
+    end
+
+    def media_analysis?
+      media_analyses.any?
+    end
+
     private
       def synthesize_parts(text:, tool_calls:)
         parts = []

data/lib/turnkit/tool_runner.rb

@@ -49,6 +49,9 @@ module TurnKit
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
           normalize_payload(call_tool(tool, tool_call.arguments, context: context))
+        rescue BudgetError => error
+          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+          raise
         rescue StandardError => error
           return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
         end

data/lib/turnkit/turn.rb

@@ -167,6 +167,112 @@ module TurnKit
       result
     end
 
+    def paint(prompt, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: {}, client: nil)
+      claimed_standalone = false
+      case status
+      when "pending"
+        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+        raise Error, "turn is already running" unless claimed
+
+        @record = claimed
+        @started_at = @record["started_at"]
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+        claimed_standalone = true
+        emit("turn.started", status: status, model: model)
+      when "running"
+        # Image tools call this while their parent turn is running.
+      else
+        raise Error, "cannot paint for #{status} turn"
+      end
+
+      image_client = client || agent.effective_client
+      request = {
+        prompt: prompt,
+        model: model,
+        provider: provider,
+        size: size,
+        assume_model_exists: assume_model_exists,
+        input_images: input_images,
+        mask: mask,
+        params: params || {},
+        metadata: { turn_id: id, conversation_id: conversation.id }.merge(metadata || {})
+      }
+
+      image_client.validate!(model: model)
+      emit("image.requested", request.except(:input_images, :mask))
+      result = call_image_client(image_client, request)
+      result_cost = Cost.from_usage(result.usage, model: result.model || model)
+      add_usage!(result.usage, cost: result_cost)
+      budget.add_cost!(result_cost.total)
+      image = result.images.first
+      raise Error, "image client returned no image" unless image
+      raise Error, "image client returned image without url or data" if image.url.to_s.empty? && image.data.to_s.empty?
+
+      persist_image_message(image)
+      emit("image.completed", image: image.to_h, model: image.model || model, provider: image.provider || provider&.to_s, mime_type: image.mime_type, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
+      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed_standalone
+      image
+    rescue StandardError => error
+      if claimed_standalone
+        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
+      end
+      raise
+    end
+
+    def view_media(media, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: {}, client: nil)
+      claimed_standalone = false
+      case status
+      when "pending"
+        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+        raise Error, "turn is already running" unless claimed
+
+        @record = claimed
+        @started_at = @record["started_at"]
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+        claimed_standalone = true
+        emit("turn.started", status: status, model: model)
+      when "running"
+        # Media tools call this while their parent turn is running.
+      else
+        raise Error, "cannot view media for #{status} turn"
+      end
+
+      media_input = MediaInput.wrap(media)
+      media_client = client || agent.effective_client
+      request = {
+        media: media_input,
+        objective: objective,
+        model: model,
+        provider: provider,
+        output_schema: output_schema,
+        params: params || {},
+        metadata: { turn_id: id, conversation_id: conversation.id }.merge(metadata || {})
+      }
+
+      media_client.validate!(model: model)
+      emit("media.requested", request.except(:media).merge(media: media_input.to_h))
+      result = call_media_client(media_client, request)
+      result_cost = Cost.from_usage(result.usage, model: result.model || model)
+      add_usage!(result.usage, cost: result_cost)
+      budget.add_cost!(result_cost.total)
+      analysis = result.media_analyses.first
+      raise Error, "media client returned no media analysis" unless analysis
+
+      persist_media_analysis_message(analysis)
+      output_data = { "type" => "media_analysis", "media_analyses" => [ analysis.to_h ] }
+      emit("media.completed", analysis: analysis.to_h, model: analysis.model || model, provider: analysis.provider || provider&.to_s, media: media_input.to_h, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
+      complete_with_output(analysis.text, output_data: output_data, audit: check_policy(analysis.text, output_data: output_data)) if claimed_standalone
+      analysis
+    rescue StandardError => error
+      emit("media.failed", error: { "class" => error.class.name, "message" => error.message }, metadata: metadata || {}) if status == "running" || claimed_standalone
+      if claimed_standalone
+        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
+      end
+      raise
+    end
+
     private
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
@@ -214,6 +320,26 @@ module TurnKit
         end
       end
 
+      def call_image_client(client, request)
+        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
+        accepted = client.method(:paint).parameters.filter_map do |kind, name|
+          return client.paint(**kwargs) if kind == :keyrest
+
+          name if %i[key keyreq].include?(kind)
+        end
+        client.paint(**kwargs.slice(*accepted))
+      end
+
+      def call_media_client(client, request)
+        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
+        accepted = client.method(:view_media).parameters.filter_map do |kind, name|
+          return client.view_media(**kwargs) if kind == :keyrest
+
+          name if %i[key keyreq].include?(kind)
+        end
+        client.view_media(**kwargs.slice(*accepted))
+      end
+
       def llm_messages
         MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
@@ -271,12 +397,28 @@ module TurnKit
           )
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
           result.tool_calls.each { |call| emit("tool_call.created", id: call.id, name: call.name) }
+        elsif result.image?
+          message = conversation.append_message(role: "assistant", kind: "image", content: result.images.map { |image| image.to_h.merge("type" => "image") }, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
+          emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+        elsif result.media_analysis?
+          message = conversation.append_message(role: "assistant", kind: "media_analysis", content: result.media_analyses.map { |analysis| analysis.to_h.merge("type" => "media_analysis") }, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
+          emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         else
           message = conversation.append_message(role: "assistant", kind: "text", text: result.text, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         end
       end
 
+      def persist_image_message(image)
+        message = conversation.append_message(role: "assistant", kind: "image", content: [ image.to_h.merge("type" => "image") ], turn_id: id, metadata: { "output_data" => { "type" => "image", "images" => [ image.to_h ] } })
+        emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+      end
+
+      def persist_media_analysis_message(analysis)
+        message = conversation.append_message(role: "assistant", kind: "media_analysis", content: [ analysis.to_h.merge("type" => "media_analysis") ], turn_id: id, metadata: { "output_data" => { "type" => "media_analysis", "media_analyses" => [ analysis.to_h ] } })
+        emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+      end
+
       def append_terminal_completion(runner, execution)
         message = runner.completion_message(execution)
         assistant = conversation.append_message(role: "assistant", kind: "text", text: message, turn_id: id)

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

data/lib/turnkit/view_media_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ViewMediaTool < Tool
+    class << self
+      %i[model provider output_schema params].each do |name|
+        define_method(name) do |value = nil|
+          instance_variable_set("@#{name}", value) unless value.nil?
+          instance_variable_get("@#{name}")
+        end
+      end
+    end
+
+    def call(turnkit_context:, **arguments)
+      turnkit_context.turn.view_media(
+        media(**arguments),
+        objective: objective(**arguments),
+        model: self.class.model,
+        provider: self.class.provider,
+        output_schema: self.class.output_schema,
+        params: self.class.params || {},
+        metadata: metadata(**arguments)
+      ).to_h
+    end
+
+    def metadata(**)
+      {}
+    end
+  end
+end

data/lib/turnkit.rb

@@ -22,6 +22,9 @@ require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
 require_relative "turnkit/record"
+require_relative "turnkit/image_result"
+require_relative "turnkit/media_input"
+require_relative "turnkit/media_analysis_result"
 require_relative "turnkit/result"
 require_relative "turnkit/skill"
 require_relative "turnkit/output_audit"
@@ -34,6 +37,8 @@ require_relative "turnkit/store"
 require_relative "turnkit/memory_store"
 require_relative "turnkit/compaction"
 require_relative "turnkit/tool"
+require_relative "turnkit/image_tool"
+require_relative "turnkit/view_media_tool"
 require_relative "turnkit/tool_call"
 require_relative "turnkit/tool_execution"
 require_relative "turnkit/sub_agent_tool"
@@ -109,4 +114,14 @@ module TurnKit
   def self.check_output_policy(output, constraints: [], context: {})
     OutputAudit.check(output, constraints: constraints, context: context)
   end
+
+  def self.paint(prompt, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: {}, client: nil)
+    image_client = client || self.client
+    image_client.paint(prompt: prompt, model: model, provider: provider, size: size, assume_model_exists: assume_model_exists, input_images: input_images, mask: mask, params: params, metadata: metadata).images.first
+  end
+
+  def self.view_media(media, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: {}, client: nil)
+    media_client = client || self.client
+    media_client.view_media(media: media, objective: objective, model: model, provider: provider, output_schema: output_schema, params: params, metadata: metadata).media_analyses.first
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -57,7 +57,11 @@ files:
 - lib/turnkit/generators/turnkit/install/templates/turn.rb
 - lib/turnkit/generators/turnkit/install_generator.rb
 - lib/turnkit/id.rb
+- lib/turnkit/image_result.rb
+- lib/turnkit/image_tool.rb
 - lib/turnkit/load_skill_tool.rb
+- lib/turnkit/media_analysis_result.rb
+- lib/turnkit/media_input.rb
 - lib/turnkit/memory_store.rb
 - lib/turnkit/message.rb
 - lib/turnkit/message_projection.rb
@@ -84,6 +88,7 @@ files:
 - lib/turnkit/turn.rb
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
+- lib/turnkit/view_media_tool.rb
 - lib/turnkit/workflow.rb
 homepage: https://github.com/samuelcouch/turnkit
 licenses: