turnkit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5694bc97b2f735e5076574e2863ee5addc41926bd85edf02e1835263ffb3516
-  data.tar.gz: 65286330a1d0b4bbd0e3e6c11ba73abd836fb22a44ae4b3ab48a58ecf9d19425
+  metadata.gz: 2b34c1c2760df56b69b055246a8afcccaec42c5493cce13ca30303c9c7e1e809
+  data.tar.gz: d3ff91766661eddbd6bb8eefba627ceaf13d8d2b2daa673781819cfe71b41a79
 SHA512:
-  metadata.gz: 2b3674abf0cae37286a04431f0ceb02a30e282c715e4d6d96e51c0a08d600c94a9fee6c82bf178c0b97ff080ee221b00a18b5409e72003d92c7a5430b34d5733
-  data.tar.gz: 7141f5cc00df42bfaf0e9b035d75f54e0b7c9b14ff71a8c95805242b32835fb410358f7f42ff2161f89896425b62fd840c05dcc2504f555430450517dc61bf9b
+  metadata.gz: 02a3e913bcfa72bc5fcbd8e18faaf60def5f62b75981c7e72220e994b7874df2a67fd306dd01cde4f9c3a0d5082aa90271bf210c5c4c5876a5015812077df79f
+  data.tar.gz: 0d6d917eeeef41a3a624a31daccdc60f28e4c121b8959ad0ab3d57301be63427e83f2a349a920fa9707bd9f5e2fa2310721f72a8151fbbb44c26a3ec75466259

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,61 @@ 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`.
+
 ### Structured Output
 
 Define a schema:

data/lib/turnkit/adapters/ruby_llm.rb

@@ -41,6 +41,23 @@ 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
+
       private
         def configure_from_environment
           config = ::RubyLLM.config
@@ -246,6 +263,47 @@ 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 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,9 @@ 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
   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/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].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,10 @@ module TurnKit
       kind == "context_summary"
     end
 
+    def image?
+      kind == "image"
+    end
+
     def text
       content.filter_map do |part|
         attrs = stringify(part)

data/lib/turnkit/message_projection.rb

@@ -44,6 +44,8 @@ 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 }
       else
         { role: message.role.to_sym, content: message.text }
       end
@@ -65,5 +67,14 @@ 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
   end
 end

data/lib/turnkit/output_policy.rb

@@ -31,6 +31,15 @@ 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 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,18 @@ 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
+
     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,59 @@ 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
+
     private
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
@@ -214,6 +267,16 @@ 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 llm_messages
         MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
@@ -271,12 +334,20 @@ 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)
         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 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.0"
 end

data/lib/turnkit.rb

@@ -22,6 +22,7 @@ require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
 require_relative "turnkit/record"
+require_relative "turnkit/image_result"
 require_relative "turnkit/result"
 require_relative "turnkit/skill"
 require_relative "turnkit/output_audit"
@@ -34,6 +35,7 @@ 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/tool_call"
 require_relative "turnkit/tool_execution"
 require_relative "turnkit/sub_agent_tool"
@@ -109,4 +111,9 @@ 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
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 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,6 +57,8 @@ 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/memory_store.rb
 - lib/turnkit/message.rb