turnkit 0.4.0 → 0.4.2

data/lib/turnkit/adapters/ruby_llm.rb

@@ -11,8 +11,7 @@ module TurnKit
       }.freeze
 
       def validate!(model:)
-        require "ruby_llm"
-
+        ensure_ruby_llm!
         raise ModelAccessError, "model is required" if model.to_s.empty?
 
         configure_from_environment
@@ -24,13 +23,12 @@ module TurnKit
         raise ModelAccessError, "#{key_name} is required for #{model}. Set ENV[#{key_name.inspect}] or configure RubyLLM before running TurnKit."
       end
 
-      def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
-        require "ruby_llm"
-
+      def chat(model:, messages:, tools:, instructions:, dynamic_instructions: nil, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
+        ensure_ruby_llm!
         configure_from_environment
 
         chat = ::RubyLLM.chat(model: model)
-        add_instructions(chat, instructions, model: model)
+        add_instructions(chat, instructions, dynamic_instructions, model: model)
         chat.with_temperature(temperature) if temperature
         apply_thinking(chat, thinking)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
@@ -42,10 +40,10 @@ module TurnKit
       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"
-
+        ensure_ruby_llm!
         configure_from_environment
-        kwargs = paint_kwargs(
+        image = ::RubyLLM.paint(
+          prompt,
           model: model,
           provider: provider,
           assume_model_exists: assume_model_exists || false,
@@ -54,11 +52,32 @@ module TurnKit
           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)
+        ensure_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 ensure_ruby_llm!
+          require "ruby_llm"
+        rescue LoadError
+          raise ConfigError, "TurnKit::Adapters::RubyLLM requires the ruby_llm gem (>= 1.16). Add `gem \"ruby_llm\"` to your Gemfile."
+        end
+
         def configure_from_environment
           config = ::RubyLLM.config
           config.openai_api_key ||= ENV["OPENAI_API_KEY"]
@@ -100,19 +119,17 @@ module TurnKit
           end
         end
 
+        # RubyLLM has no public API to request a completion without executing
+        # tool calls, so this depends on the private RubyLLM::Chat#provider_completion
+        # (added in ruby_llm 1.16). TurnKit must run tools itself (to persist
+        # executions and enforce budgets). Guarded by a canary test in the
+        # suite; revisit when RubyLLM exposes a public equivalent.
         def complete_without_tool_execution(chat)
-          provider = chat.instance_variable_get(:@provider)
-          provider.complete(
-            chat.messages,
-            tools: chat.tools,
-            tool_prefs: chat.tool_prefs,
-            temperature: chat.instance_variable_get(:@temperature),
-            model: chat.model,
-            params: chat.params,
-            headers: chat.headers,
-            schema: chat.schema,
-            thinking: chat.instance_variable_get(:@thinking)
-          )
+          unless chat.respond_to?(:provider_completion, true)
+            raise ConfigError, "TurnKit::Adapters::RubyLLM requires ruby_llm >= 1.16 (RubyLLM::Chat#provider_completion not found)"
+          end
+
+          chat.send(:provider_completion)
         end
 
         def add_message(chat, message)
@@ -128,15 +145,16 @@ module TurnKit
           )
         end
 
-        def add_instructions(chat, instructions, model:)
-          return if instructions.nil? || instructions.empty?
+        def add_instructions(chat, instructions, dynamic_instructions, model:)
+          stable = instructions.to_s
+          dynamic = dynamic_instructions.to_s
+          return if stable.empty? && dynamic.empty?
 
-          if prompt_cache_enabled? && anthropic_model?(model) && instructions.include?(SystemPrompt::CACHE_BOUNDARY)
-            stable, dynamic = SystemPrompt.split_cache_boundary(instructions)
+          if prompt_cache_enabled? && anthropic_model?(model) && !dynamic.empty?
             add_system_message(chat, stable, cache: true)
             add_system_message(chat, dynamic, cache: false)
           else
-            chat.with_instructions(instructions)
+            chat.with_instructions([ stable, dynamic ].reject(&:empty?).join("\n\n"))
           end
         end
 
@@ -172,8 +190,6 @@ module TurnKit
         end
 
         def ruby_llm_tool(tool)
-          require "ruby_llm"
-
           Class.new(::RubyLLM::Tool) do
             define_singleton_method(:name) { tool.tool_name }
             description tool.description
@@ -264,21 +280,6 @@ 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"),
@@ -300,6 +301,29 @@ module TurnKit
           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

data/lib/turnkit/agent.rb

@@ -2,26 +2,46 @@
 
 module TurnKit
   class Agent
+    ORCHESTRATOR_PREAMBLE = <<~TEXT.strip
+      You are an autonomous task orchestrator. Navigate from the application
+      request to a final output without asking the user follow-up questions.
+
+      Use the available tools to gather context, inspect sources, take actions,
+      persist outputs, and verify work. Use loaded skills as reusable workflow
+      patterns. Iterate when work needs missing context, critique, revision, or
+      verification.
+
+      When multiple independent items need the same kind of fetch or read, and
+      an available batch tool can handle them in one call, prefer the batch tool
+      over repeated one-item tool calls.
+
+      Stop when the task is complete, when the available context and tools are
+      sufficient for the best possible answer, or when further iteration would
+      not materially improve the result. Respect runtime, cost, and iteration
+      limits.
+    TEXT
+
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
     attr_reader :client, :store, :max_iterations, :timeout, :max_spend, :max_depth, :max_tool_executions, :max_tool_executions_by_name
     attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction, :output_schema, :input_schema, :on_event
     attr_reader :output_policy, :output_policy_mode, :output_policy_model, :output_retries
 
-    def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
+    def initialize(name:, description: "", model: nil, instructions: "", orchestrator: false, tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
       max_iterations: nil, timeout: nil, max_spend: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil,
       output_schema: nil, input_schema: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, output_retries: 0, on_event: nil)
       @name = name.to_s
       @description = description.to_s
       @model = model
-      @instructions = instructions.to_s
+      @orchestrator = orchestrator ? true : false
+      @instructions = compose_instructions(instructions)
       @tools = Array(tools)
       @skills = Array(skills)
       @available_skills = Array(available_skills)
       @sub_agents = Array(sub_agents)
       @system_prompt = system_prompt
       @prompt_sections = prompt_sections
-      @prompt_mode = prompt_mode&.to_sym
+      @prompt_mode = prompt_mode&.to_sym || (:task if @orchestrator)
       @client = client
       @store = store
       @max_iterations = max_iterations
@@ -69,8 +89,11 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
-      task = task || prompt
+    def orchestrator?
+      @orchestrator
+    end
+
+    def run(task, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
       raise ArgumentError, "task is required" if task.to_s.empty?
       SchemaCheck.validate!(input, input_schema, error_class: InputError, label: "input") if input_schema
 
@@ -151,16 +174,19 @@ module TurnKit
       end
     end
 
-    def build_budget(root_started_at: Clock.now)
-      Budget.new(
+    def budget_limits
+      {
         max_iterations: max_iterations || TurnKit.max_iterations,
         timeout: timeout || TurnKit.timeout,
         max_depth: max_depth || TurnKit.max_depth,
         max_tool_executions: max_tool_executions || TurnKit.max_tool_executions,
         max_tool_executions_by_name: max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
-        max_spend: max_spend || TurnKit.max_spend,
-        root_started_at: root_started_at
-      )
+        max_spend: max_spend || TurnKit.max_spend
+      }
+    end
+
+    def build_budget(root_started_at: Clock.now)
+      Budget.new(**budget_limits, root_started_at: root_started_at)
     end
 
     def instructions_with_skills
@@ -170,6 +196,13 @@ module TurnKit
     end
 
     private
+      def compose_instructions(instructions)
+        parts = []
+        parts << ORCHESTRATOR_PREAMBLE if @orchestrator
+        parts << instructions.to_s.strip unless instructions.to_s.strip.empty?
+        parts.join("\n\n")
+      end
+
       def validate_tools!
         effective_tools.each do |tool|
           next if tool.is_a?(Class) && tool < Tool

data/lib/turnkit/budget.rb

@@ -29,7 +29,7 @@ module TurnKit
 
     def seed!(turns:, tool_executions:)
       @mutex.synchronize do
-        @iterations = Array(turns).sum { |turn| (turn["options"] || {})["iterations"].to_i }
+        @iterations = Array(turns).sum { |turn| Turn.iterations_for(turn) }
         completed = Array(tool_executions).select { |execution| %w[completed failed].include?(execution["status"]) && !execution.dig("error", "details", "budget_denied") }
         @tool_executions = completed.length
         completed.each { |execution| @tool_executions_by_name[execution.fetch("tool_name").to_s] += 1 }

data/lib/turnkit/client.rb

@@ -1,17 +1,25 @@
 # frozen_string_literal: true
 
 module TurnKit
+  # The adapter contract. TurnKit calls clients with the full keyword
+  # signatures below. Custom adapters should subclass TurnKit::Client (or
+  # accept the same keywords) and must not execute tools themselves; TurnKit
+  # runs tools and persists their results.
   class Client
     def validate!(model:)
       true
     end
 
-    def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
+    def chat(model:, messages:, tools:, instructions:, dynamic_instructions: nil, 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/compaction.rb

@@ -3,19 +3,19 @@
 module TurnKit
   module Compaction
     DEFAULTS = {
-      "enabled" => true,
-      "threshold" => 0.75,
-      "context_limit" => 128_000,
-      "reserved_tokens" => 20_000,
-      "head_messages" => 0,
-      "tail_messages" => 12,
-      "tail_tokens" => 8_000,
-      "summary_ratio" => 0.20,
-      "min_summary_tokens" => 1_000,
-      "max_summary_tokens" => 12_000,
-      "tool_output_max_chars" => 2_000,
-      "model" => nil,
-      "client" => nil
+      enabled: true,
+      threshold: 0.75,
+      context_limit: 128_000,
+      reserved_tokens: 20_000,
+      head_messages: 0,
+      tail_messages: 12,
+      tail_tokens: 8_000,
+      summary_ratio: 0.20,
+      min_summary_tokens: 1_000,
+      max_summary_tokens: 12_000,
+      tool_output_max_chars: 2_000,
+      model: nil,
+      client: nil
     }.freeze
 
     KNOWN_KEYS = DEFAULTS.keys.freeze
@@ -92,7 +92,7 @@ module TurnKit
     module_function
 
     def enabled_for?(agent, overrides = {})
-      policy_for(agent, overrides)["enabled"]
+      policy_for(agent, overrides)[:enabled]
     end
 
     def policy_for(agent, overrides = {})
@@ -100,9 +100,9 @@ module TurnKit
       local = normalize_config(agent.compaction)
       override = normalize_config(overrides)
 
-      return DEFAULTS.merge("enabled" => false) if global == false
-      return DEFAULTS.merge("enabled" => false) if local == false
-      return DEFAULTS.merge("enabled" => false) if override == false
+      return DEFAULTS.merge(enabled: false) if global == false
+      return DEFAULTS.merge(enabled: false) if local == false
+      return DEFAULTS.merge(enabled: false) if override == false
 
       DEFAULTS.merge(global || {}).merge(local || {}).merge(override || {})
     end
@@ -112,7 +112,7 @@ module TurnKit
 
       force = turn.compact == true if force.nil?
       policy = policy_for(turn.agent)
-      return unless policy["enabled"]
+      return unless policy[:enabled]
 
       messages = project(turn.conversation.messages_for_turn(turn))
       return unless force || over_threshold?(messages, policy)
@@ -127,7 +127,7 @@ module TurnKit
 
     def compact!(conversation, agent:, turn: nil, focus: nil, auto: false, overrides: {}, force: true)
       policy = policy_for(agent, overrides)
-      raise CompactionError, "compaction is disabled" unless policy["enabled"]
+      raise CompactionError, "compaction is disabled" unless policy[:enabled]
 
       messages = turn ? conversation.messages_for_turn(turn) : conversation.messages
       projected = project(messages)
@@ -135,14 +135,14 @@ module TurnKit
       return nil if selected.nil? && auto
       raise CompactionError, "not enough messages to compact" unless selected
 
-      selected_tokens = estimate_messages_tokens(selected.fetch("middle"))
+      selected_tokens = estimate_messages_tokens(selected.fetch(:middle))
       return nil if auto && !force && !over_threshold?(projected, policy)
 
       summary = generate_summary(
         agent: agent,
         policy: policy,
-        messages: selected.fetch("middle"),
-        previous_summary: selected["previous_summary"]&.text,
+        messages: selected.fetch(:middle),
+        previous_summary: selected[:previous_summary]&.text,
         focus: focus,
         target_tokens: summary_budget(selected_tokens, policy),
         fallback_model: turn&.model || conversation.model || agent.effective_model,
@@ -209,25 +209,25 @@ module TurnKit
     end
 
     def summary_budget(input_tokens, policy)
-      budget = (input_tokens.to_i * policy["summary_ratio"].to_f).ceil
-      budget = [ budget, policy["min_summary_tokens"].to_i ].max
-      [ budget, policy["max_summary_tokens"].to_i ].min
+      budget = (input_tokens.to_i * policy[:summary_ratio].to_f).ceil
+      budget = [ budget, policy[:min_summary_tokens].to_i ].max
+      [ budget, policy[:max_summary_tokens].to_i ].min
     end
 
     def over_threshold?(messages, policy)
-      usable = [ policy["context_limit"].to_i - policy["reserved_tokens"].to_i, 1 ].max
-      estimate_messages_tokens(messages) >= (usable * policy["threshold"].to_f)
+      usable = [ policy[:context_limit].to_i - policy[:reserved_tokens].to_i, 1 ].max
+      estimate_messages_tokens(messages) >= (usable * policy[:threshold].to_f)
     end
 
     def select_messages(messages, policy)
       rows = Array(messages)
-      return nil if rows.length <= policy["head_messages"].to_i + 1
+      return nil if rows.length <= policy[:head_messages].to_i + 1
 
       previous_summary = rows.reverse.find(&:context_summary?)
       candidates = rows.reject(&:context_summary?)
-      return nil if candidates.length <= policy["head_messages"].to_i + 1
+      return nil if candidates.length <= policy[:head_messages].to_i + 1
 
-      head_count = policy["head_messages"].to_i
+      head_count = policy[:head_messages].to_i
       tail_start = tail_start_index(candidates, policy)
       tail_start = [ tail_start, head_count ].max
       tail_start = expand_tail_start_for_tool_pairs(candidates, tail_start)
@@ -242,11 +242,11 @@ module TurnKit
       end
 
       {
-        "middle" => middle,
-        "previous_summary" => previous_summary,
-        "replaces_from_sequence" => from_sequence,
-        "replaces_through_sequence" => through_sequence,
-        "tail_start_sequence" => candidates[tail_start]&.sequence
+        middle: middle,
+        previous_summary: previous_summary,
+        replaces_from_sequence: from_sequence,
+        replaces_through_sequence: through_sequence,
+        tail_start_sequence: candidates[tail_start]&.sequence
       }
     end
 
@@ -290,7 +290,7 @@ module TurnKit
       when false
         false
       when Hash
-        attrs = value.transform_keys(&:to_s)
+        attrs = value.transform_keys(&:to_sym)
         unknown = attrs.keys - KNOWN_KEYS
         raise ConfigError, "unknown compaction options: #{unknown.join(", ")}" if unknown.any?
 
@@ -323,8 +323,8 @@ module TurnKit
     end
 
     def tail_start_index(messages, policy)
-      max_messages = policy["tail_messages"].to_i
-      max_tokens = policy["tail_tokens"].to_i
+      max_messages = policy[:tail_messages].to_i
+      max_tokens = policy[:tail_tokens].to_i
       count = 0
       tokens = 0
       index = messages.length
@@ -357,8 +357,8 @@ module TurnKit
     end
 
     def generate_summary(agent:, policy:, messages:, previous_summary:, focus:, target_tokens:, fallback_model:, conversation_id:, turn_id:, turn: nil)
-      client = policy["client"] || agent.effective_client
-      model = policy["model"] || fallback_model
+      client = policy[:client] || agent.effective_client
+      model = policy[:model] || fallback_model
       safe_messages = messages.map { |message| sanitize_message(message, policy) }
       prompt = build_prompt(previous_summary: previous_summary, focus: focus, target_tokens: target_tokens)
       attrs = {
@@ -369,7 +369,7 @@ module TurnKit
         metadata: { compaction: true, conversation_id: conversation_id, turn_id: turn_id }
       }
       result = if turn
-        turn.internal_model_call(**attrs, purpose: "compaction", client: policy["client"])
+        turn.internal_model_call(**attrs, purpose: "compaction", client: policy[:client])
       else
         client.validate!(model: model)
         client.chat(**attrs)
@@ -383,7 +383,7 @@ module TurnKit
     def sanitize_message(message, policy)
       return message unless message.tool_result?
 
-      max = policy["tool_output_max_chars"].to_i
+      max = policy[:tool_output_max_chars].to_i
       return message if max <= 0 || message.text.length <= max
 
       attrs = message.to_h
@@ -392,7 +392,7 @@ module TurnKit
     end
 
     def append_summary(conversation, turn:, summary:, selected:, policy:, focus:, auto:, input_tokens:)
-      model = policy["model"] || turn&.model || conversation.model || conversation.agent.effective_model
+      model = policy[:model] || turn&.model || conversation.model || conversation.agent.effective_model
       conversation.append_message(
         role: "assistant",
         kind: "context_summary",
@@ -402,9 +402,9 @@ module TurnKit
           "compaction" => {
             "auto" => auto,
             "focus" => focus,
-            "replaces_from_sequence" => selected.fetch("replaces_from_sequence"),
-            "replaces_through_sequence" => selected.fetch("replaces_through_sequence"),
-            "tail_start_sequence" => selected["tail_start_sequence"],
+            "replaces_from_sequence" => selected.fetch(:replaces_from_sequence),
+            "replaces_through_sequence" => selected.fetch(:replaces_through_sequence),
+            "tail_start_sequence" => selected[:tail_start_sequence],
             "summary_model" => model,
             "input_tokens" => input_tokens,
             "summary_tokens" => estimate_text_tokens(summary),

data/lib/turnkit/cost.rb

@@ -48,42 +48,40 @@ module TurnKit
       from_usage(Usage.from_h(usage), model: attrs["model"])
     end
 
+    RATE_KEYS = %i[input output cache_read cache_write thinking].freeze
+
+    # Rates are USD per million tokens, keyed by component.
     def self.from_rates(usage, rates)
       rates = rates.transform_keys(&:to_sym)
+      unknown = rates.keys - RATE_KEYS
+      raise ConfigError, "unknown cost rate keys: #{unknown.join(", ")} (use: #{RATE_KEYS.join(", ")})" if unknown.any?
+
       new(
-        input: amount(usage.input_tokens, rates[:input] || rates[:input_per_million]),
-        output: amount(usage.output_tokens, rates[:output] || rates[:output_per_million]),
-        cache_read: amount(usage.cached_tokens, rates[:cache_read] || rates[:cached_input] || rates[:cache_read_input_per_million] || rates[:cached_input_per_million]),
-        cache_write: amount(usage.cache_write_tokens, rates[:cache_write] || rates[:cache_creation] || rates[:cache_write_input_per_million] || rates[:cache_creation_input_per_million]),
-        thinking: amount(usage.thinking_tokens, rates[:thinking] || rates[:reasoning] || rates[:thinking_output] || rates[:reasoning_output] || rates[:thinking_output_per_million] || rates[:reasoning_output_per_million]),
+        input: amount(usage.input_tokens, rates[:input]),
+        output: amount(usage.output_tokens, rates[:output]),
+        cache_read: amount(usage.cached_tokens, rates[:cache_read]),
+        cache_write: amount(usage.cache_write_tokens, rates[:cache_write]),
+        thinking: amount(usage.thinking_tokens, rates[:thinking]),
         strict: true
       )
     end
 
+    # Estimates cost from RubyLLM's model pricing registry (ruby_llm >= 1.16).
+    # Returns an empty Cost when ruby_llm is not loaded or the model is not in
+    # the registry; any other failure raises.
     def self.from_ruby_llm(usage, model)
-      require "ruby_llm"
-
-      model_info = ::RubyLLM.models.find(model) if model
-      return new unless model_info
-
-      if defined?(::RubyLLM::Cost)
-        tokens = ::RubyLLM::Tokens.new(
-          input: usage.input_tokens,
-          output: usage.output_tokens,
-          cached: usage.cached_tokens,
-          cache_creation: usage.cache_write_tokens,
-          thinking: usage.thinking_tokens
-        )
-        from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
-      else
-        from_rates(
-          usage,
-          input: model_info.input_price_per_million,
-          output: model_info.output_price_per_million,
-          cached_input: model_info.pricing&.text_tokens&.cached_input
-        )
-      end
-    rescue LoadError, StandardError
+      return new unless defined?(::RubyLLM) && model
+
+      model_info = ::RubyLLM.models.find(model)
+      tokens = ::RubyLLM::Tokens.new(
+        input: usage.input_tokens,
+        output: usage.output_tokens,
+        cached: usage.cached_tokens,
+        cache_creation: usage.cache_write_tokens,
+        thinking: usage.thinking_tokens
+      )
+      from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
+    rescue ::RubyLLM::ModelNotFoundError
       new
     end
 
@@ -92,9 +90,9 @@ module TurnKit
       new(
         input: hash[:input],
         output: hash[:output],
-        cache_read: hash[:cache_read] || hash[:cached_input],
-        cache_write: hash[:cache_write] || hash[:cache_creation],
-        thinking: hash[:thinking] || hash[:reasoning] || hash[:thinking_output] || hash[:reasoning_output],
+        cache_read: hash[:cache_read],
+        cache_write: hash[:cache_write],
+        thinking: hash[:thinking],
         total: hash[:total]
       )
     end

data/lib/turnkit/image_result.rb

@@ -23,6 +23,7 @@ module TurnKit
       @metadata = metadata || {}
     end
 
+    # Performs network IO when the image is URL-backed.
     def to_blob
       raise Error, "image has no url or data" if url.to_s.empty? && data.to_s.empty?
 

data/lib/turnkit/image_tool.rb

@@ -11,8 +11,8 @@ module TurnKit
       end
     end
 
-    def call(turnkit_context:, **arguments)
-      turnkit_context.turn.paint(
+    def call(context:, **arguments)
+      context.turn.paint(
         prompt(**arguments),
         model: self.class.model,
         provider: self.class.provider,