turnkit 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c02ad5eef683595c702a33806438f414ed2da9e18c607a8b314bba4ae442404
-  data.tar.gz: 4da3877b7c20aecae1dd77e6df4497bb64a3909d28419fb1413feb37fa5fa298
+  metadata.gz: 271ce272a71a97aa2991a580f36205e4cef8e19466e2e480b0ac6f0f0225d51f
+  data.tar.gz: b9a0503f499d3eb850e7eece6f508b6fbc206d6398263f6005520b7ef716493b
 SHA512:
-  metadata.gz: b5de4c365826d8a4154d2ee013fe0f7289796b91b63eb34ad81693993eb55b8f8d0282f8415e7798f9eb698d2f6f4aa52b79949e1c89c0c64effe506cf26ef0b
-  data.tar.gz: b168324cf4f97485ce7854006565441fd0fe67e1f84835805d98d67f27a2a793fe2ce8bd27a6939c6ccbf3cc92023bc93c8aff5e8049fb0b2991a50548d211d6
+  metadata.gz: f8772f25a95c44b2ba3d1a17a3e89d0ba142d862e798cee6daef9c54e04deaa3d8dee77deae48b5a77f7b6051b467a14c355aabf5115b1ce89832a27c87eb1b6
+  data.tar.gz: 9b12cccaa55c8d791168eca90655e3b9db89409b69fe59f8b45d23bef71aeec296c538696af44e484da9884dfde4ace67bbfd81d4a6647783f1f7f299ef0e485

data/CHANGELOG.md

@@ -1,9 +1,14 @@
 # Changelog
 
-## 0.2.3 - 2026-06-06
+## 0.2.5 - 2026-06-06
+
+- Add per-agent and per-turn provider thinking configuration.
+
+## 0.2.4 - 2026-06-06
 
 - Add Anthropic prompt cache support for stable system prompt sections.
-- Track cache write tokens and aggregate model costs on turns.
+- Track cache write tokens and expose model cost totals for turns, conversations, and agents.
+- Calculate costs from RubyLLM model registry pricing with custom rate and calculator overrides.
 - Refresh README usage examples for prompt caching and usage tracking.
 
 ## 0.2.0 - 2026-06-04

data/README.md

@@ -22,12 +22,21 @@ bundle install
 
 ## Quick Start
 
-Set a provider key:
+Set a provider key. TurnKit uses RubyLLM under the hood and defaults to Anthropic Claude:
 
 ```sh
 export ANTHROPIC_API_KEY=...
 ```
 
+| Provider | Env var | Example model |
+| --- | --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-5` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-4.1-mini` |
+| Gemini | `GEMINI_API_KEY` | `gemini-2.5-flash` |
+
+> [!WARNING]
+> TurnKit defaults to `claude-sonnet-4-5`. If `ANTHROPIC_API_KEY` is unset or blank, set `TurnKit.default_model` to a provider you have configured.
+
 Create an agent:
 
 ```ruby
@@ -37,14 +46,20 @@ agent = TurnKit::Agent.new(
   name: "helper",
   instructions: "Answer briefly."
 )
+```
 
+Ask a question:
+
+```ruby
 turn = agent.conversation.ask("Explain Ruby blocks in one sentence.")
 puts turn.output_text
 ```
 
 ## Usage
 
-Choose a model:
+### Models
+
+Set the default model:
 
 ```ruby
 TurnKit.default_model = "claude-sonnet-4-5"
@@ -56,10 +71,60 @@ Use OpenAI:
 export OPENAI_API_KEY=...
 ```
 
+Set an OpenAI model:
+
 ```ruby
 TurnKit.default_model = "gpt-4.1-mini"
 ```
 
+Use Gemini:
+
+```sh
+export GEMINI_API_KEY=...
+```
+
+Set a Gemini model:
+
+```ruby
+TurnKit.default_model = "gemini-2.5-flash"
+```
+
+### Thinking
+
+Enable provider reasoning or extended thinking per agent:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "reasoner",
+  model: "claude-sonnet-4-5",
+  thinking: { budget: 4_000 }
+)
+```
+
+Use effort-based thinking for providers that support it:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "reasoner",
+  model: "gemini-2.5-flash",
+  thinking: { effort: :high }
+)
+```
+
+Override or disable thinking for one turn:
+
+```ruby
+conversation = agent.conversation
+conversation.ask("Solve this carefully.", thinking: { budget: 8_000 })
+conversation.ask("Answer quickly.", thinking: nil)
+```
+
+TurnKit passes `thinking` to RubyLLM as `{ effort:, budget: }`. Anthropic requires `budget`; Gemini and OpenRouter can use `effort`, `budget`, or both depending on the model.
+
+When the provider reports reasoning usage, TurnKit records it as `thinking_tokens` and includes it in usage totals and cost calculation.
+
+### Conversations
+
 Create a conversation:
 
 ```ruby
@@ -67,14 +132,24 @@ agent = TurnKit::Agent.new(
   name: "writer",
   instructions: "Write clear release notes."
 )
+```
 
+Add context:
+
+```ruby
 conversation = agent.conversation(subject: "v1 launch")
 conversation.say("Mention faster tool execution.")
+```
 
+Run the agent:
+
+```ruby
 turn = conversation.run!
 puts turn.output_text
 ```
 
+### Tools
+
 Create a tool:
 
 ```ruby
@@ -93,7 +168,7 @@ class SaveReport < TurnKit::Tool
 end
 ```
 
-Use a tool:
+Use the tool:
 
 ```ruby
 agent = TurnKit::Agent.new(
@@ -101,40 +176,185 @@ agent = TurnKit::Agent.new(
   instructions: "Save reports when asked.",
   tools: [SaveReport]
 )
+```
+
+Ask for tool use:
 
+```ruby
 turn = agent.conversation.ask("Save a short status report.")
 puts turn.output_text
 ```
 
-Add skills:
+#### Defining application tools
+
+Tools are classes, not instances. Namespaced tools work fine, and the default tool name comes from the class name: `Assistant::Tools::WebSearch` becomes `web_search`.
+
+```ruby
+module Assistant
+  module Tools
+    class WebSearch < TurnKit::Tool
+      description "Search the web for current information."
+      usage_hint "Use when current external information is needed."
+
+      parameter :objective, :string, required: true
+      parameter :search_queries, :array, required: false
+
+      def call(objective:, search_queries: nil, context:)
+        ParallelClient.new.web_search(
+          objective: objective,
+          search_queries: search_queries
+        )
+      end
+    end
+  end
+end
+```
+
+Register tool classes on the agent:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "researcher",
+  tools: [
+    Assistant::Tools::WebSearch,
+    Assistant::Tools::ReadWebPage
+  ]
+)
+```
+
+#### Tool context
+
+Every tool receives a `context:` object. Use it for logging, correlation, persistence, and domain scoping:
+
+```ruby
+def call(query:, context:)
+  context.turn       # The TurnKit::Turn being run
+  context.execution  # The TurnKit::ToolExecution for this tool call
+
+  { query: query }
+end
+```
+
+If your application already uses a `context:` keyword for something else, use `turnkit_context:` instead:
+
+```ruby
+def call(query:, turnkit_context:)
+  { turn_id: turnkit_context.turn.id, query: query }
+end
+```
+
+#### Tool return values
+
+Prefer returning a `Hash`. TurnKit serializes the normalized value as the tool result:
+
+| Return value | Stored tool result |
+| --- | --- |
+| `Hash` | Keys are stringified. |
+| `Array` | Wrapped as `{ "items" => [...] }`. |
+| Scalar | Wrapped as `{ "result" => value.to_s }`. |
+
+Avoid returning arbitrary objects unless you convert them to a plain Hash or Array first.
+
+### Skills
+
+Load a skill:
 
 ```ruby
 skill = TurnKit::Skill.from_file("skills/research.md")
+```
+
+Use the skill:
 
+```ruby
 agent = TurnKit::Agent.new(
   name: "researcher",
   skills: [skill]
 )
 ```
 
-Delegate to sub-agents:
+### Sub-agents
+
+Create a sub-agent:
 
 ```ruby
 writer = TurnKit::Agent.new(
   name: "writer",
   description: "Draft concise copy."
 )
+```
+
+Delegate to it:
 
+```ruby
 editor = TurnKit::Agent.new(
   name: "editor",
   sub_agents: [writer]
 )
+```
+
+Ask the parent agent:
 
+```ruby
 turn = editor.conversation.ask("Ask the writer for three headlines.")
 puts turn.output_text
 ```
 
-Use prompt caching:
+### Usage and costs
+
+Inspect token usage:
+
+```ruby
+turn.usage.total_tokens
+conversation.usage.total_tokens
+agent.usage.total_tokens
+```
+
+Inspect costs:
+
+```ruby
+turn.cost.total
+conversation.cost.total
+agent.cost.total
+```
+
+Use RubyLLM registry prices by default.
+
+Override model rates:
+
+```ruby
+TurnKit.cost_rates = {
+  "my-model" => {
+    input: 0.25,
+    output: 1.00,
+    cached_input: 0.05,
+    cache_creation: 0.25
+  }
+}
+```
+
+Override cost calculation:
+
+```ruby
+TurnKit.cost_calculator = ->(usage, model) do
+  {
+    input: usage.input_tokens * 0.25 / 1_000_000.0,
+    output: usage.output_tokens * 1.00 / 1_000_000.0
+  }
+end
+```
+
+Limit turn cost:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "analyst",
+  cost_limit: 0.25
+)
+```
+
+### Prompt caching
+
+Enable prompt caching:
 
 ```ruby
 TurnKit.prompt_cache = :auto
@@ -159,18 +379,13 @@ agent = TurnKit::Agent.new(
 )
 ```
 
-Inspect usage:
-
-```ruby
-record = TurnKit.store.load_turn(turn.id)
-record.fetch("usage")
-```
+### Custom clients
 
-Return usage from custom clients:
+Create a client:
 
 ```ruby
 class MyClient < TurnKit::Client
-  def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+  def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
     TurnKit::Result.new(
       text: "provider response",
       model: model,
@@ -185,28 +400,37 @@ class MyClient < TurnKit::Client
 end
 ```
 
-Split instructions inside custom clients:
+Use the client:
 
 ```ruby
-stable, dynamic = TurnKit::SystemPrompt.split_cache_boundary(instructions)
+TurnKit.client = MyClient.new
 ```
 
-Send `stable` with provider cache controls.
-
-Send `dynamic` as normal prompt content.
-
-Use a custom client:
+Split cache sections:
 
 ```ruby
-TurnKit.client = MyClient.new
+stable, dynamic = TurnKit::SystemPrompt.split_cache_boundary(instructions)
 ```
 
+### Rails
+
 Install Rails persistence:
 
 ```sh
 bin/rails generate turnkit:install
 ```
 
+The installer creates:
+
+- `config/initializers/turnkit.rb`
+- `app/models/turnkit/conversation.rb`
+- `app/models/turnkit/turn.rb`
+- `app/models/turnkit/message.rb`
+- `app/models/turnkit/tool_execution.rb`
+- a migration for TurnKit persistence
+
+The generated migration currently uses `ActiveRecord::Migration[7.1]`. In a newer Rails app, update that version if your app requires it, for example `ActiveRecord::Migration[8.1]`.
+
 Run migrations:
 
 ```sh
@@ -217,7 +441,26 @@ Configure Rails:
 
 ```ruby
 TurnKit.store = TurnKit::ActiveRecordStore.new
-TurnKit.default_model = "claude-sonnet-4-5"
+```
+
+Suggested Rails file layout for your application AI code:
+
+```text
+app/models/assistant/
+  tools/
+    web_search.rb
+    read_web_page.rb
+  skills/
+  prompts/
+```
+
+If you prefer to keep AI infrastructure out of `app/models`, add an autoloaded directory such as:
+
+```text
+app/ai/
+  tools/
+  skills/
+  prompts/
 ```
 
 Reconcile stale turns:
@@ -226,6 +469,62 @@ Reconcile stale turns:
 TurnKit.reconcile_stale!
 ```
 
+#### Debugging Rails persistence
+
+Inspect the latest persisted turn in a Rails console:
+
+```ruby
+turn = Turnkit::Turn.order(created_at: :desc).first
+turn.status
+turn.error
+turn.output_text
+```
+
+Check whether the model actually called tools:
+
+```ruby
+Turnkit::ToolExecution
+  .where(turn_uid: turn.uid)
+  .order(:created_at)
+  .map { |execution|
+    {
+      name: execution.tool_name,
+      status: execution.status,
+      arguments: execution.arguments,
+      result_keys: execution.result&.keys,
+      error: execution.error
+    }
+  }
+```
+
+#### Live smoke test
+
+Use a model whose provider key is configured, then run a real tool-using turn:
+
+```ruby
+TurnKit.default_model = "gpt-4.1-mini"
+
+agent = TurnKit::Agent.new(
+  name: "researcher",
+  instructions: "Use web_search, then read_web_page, before answering.",
+  tools: [
+    Assistant::Tools::WebSearch,
+    Assistant::Tools::ReadWebPage
+  ]
+)
+
+turn = agent.conversation.ask(
+  "Search for the TurnKit Ruby gem, read the first useful result, then summarize it."
+)
+
+puts turn.output_text
+
+pp Turnkit::ToolExecution
+  .where(turn_uid: turn.id)
+  .order(:created_at)
+  .pluck(:tool_name, :status, :error)
+```
+
 ## Options
 
 Configure defaults:
@@ -237,6 +536,8 @@ TurnKit.timeout = 300
 TurnKit.max_depth = 3
 TurnKit.max_tool_executions = 100
 TurnKit.cost_limit = nil
+TurnKit.cost_rates = {}
+TurnKit.cost_calculator = nil
 TurnKit.prompt_cache = :auto
 ```
 
@@ -248,7 +549,8 @@ agent = TurnKit::Agent.new(
   model: "gpt-4.1-mini",
   max_iterations: 10,
   timeout: 60,
-  cost_limit: 0.25
+  cost_limit: 0.25,
+  thinking: { effort: :low }
 )
 ```
 
@@ -259,11 +561,12 @@ agent = TurnKit::Agent.new(
 | `store` | Set the conversation store. |
 | `max_iterations` | Limit model calls per turn. |
 | `timeout` | Limit seconds per root turn. |
-| `max_depth` | Limit sub-agent nesting. |
 | `max_tool_executions` | Limit tool calls per root turn. |
 | `cost_limit` | Limit cost per root turn. |
+| `thinking` | Configure provider reasoning or extended thinking per agent. |
+| `cost_rates` | Override prices by model. |
+| `cost_calculator` | Override cost calculation. |
 | `prompt_cache` | Use provider prompt caching. |
-| `prompt_sections` | Set default prompt sections. |
 
 ## Contributing
 

data/lib/turnkit/adapters/ruby_llm.rb

@@ -3,7 +3,7 @@
 module TurnKit
   module Adapters
     class RubyLLM < Client
-      def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+      def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
         require "ruby_llm"
 
         configure_from_environment
@@ -11,6 +11,7 @@ module TurnKit
         chat = ::RubyLLM.chat(model: model)
         add_instructions(chat, instructions, model: model)
         chat.with_temperature(temperature) if temperature
+        apply_thinking(chat, thinking)
         Array(tools).each { |tool| chat.with_tool(ruby_llm_tool(tool)) }
         Array(messages).each { |message| add_message(chat, message) }
 
@@ -27,6 +28,11 @@ module TurnKit
           config.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
         end
 
+        def apply_thinking(chat, thinking)
+          thinking = Agent.normalize_thinking(thinking)
+          chat.with_thinking(**thinking) if thinking
+        end
+
         def complete_without_tool_execution(chat)
           provider = chat.instance_variable_get(:@provider)
           provider.complete(
@@ -122,7 +128,9 @@ module TurnKit
             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)
+            cache_write_tokens: token_value(response, :cache_creation_tokens),
+            thinking_tokens: thinking_token_value(response),
+            cost: response_cost(response)
           )
           Result.new(
             text: response.respond_to?(:content) ? response.content.to_s : response.to_s,
@@ -135,6 +143,16 @@ module TurnKit
         def token_value(response, method)
           response.respond_to?(method) ? response.public_send(method).to_i : 0
         end
+
+        def thinking_token_value(response)
+          token_value(response, :thinking_tokens).nonzero? || token_value(response, :reasoning_tokens)
+        end
+
+        def response_cost(response)
+          return unless response.respond_to?(:cost)
+
+          response.cost&.total
+        end
     end
   end
 end

data/lib/turnkit/agent.rb

@@ -4,11 +4,11 @@ module TurnKit
   class Agent
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
     attr_reader :client, :store, :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions
-    attr_reader :prompt_sections, :system_prompt, :prompt_mode
+    attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking
 
     def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
-      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil)
+      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, thinking: nil)
       @name = name.to_s
       @description = description.to_s
       @model = model
@@ -27,9 +27,25 @@ module TurnKit
       @cost_limit = cost_limit
       @max_depth = max_depth
       @max_tool_executions = max_tool_executions
+      @thinking = self.class.normalize_thinking(thinking)
       raise ArgumentError, "name is required" if @name.empty?
     end
 
+    def self.normalize_thinking(value)
+      return nil if value.nil?
+
+      attrs = value.respond_to?(:to_h) ? value.to_h : value
+      raise ArgumentError, "thinking must be a hash" unless attrs.is_a?(Hash)
+
+      attrs = attrs.transform_keys(&:to_sym)
+      unknown = attrs.keys - %i[effort budget]
+      raise ArgumentError, "unknown thinking attributes: #{unknown.join(", ")}" if unknown.any?
+      raise ArgumentError, "thinking requires :effort or :budget" if attrs[:effort].nil? && attrs[:budget].nil?
+      raise ArgumentError, "thinking budget must be an Integer" if attrs[:budget] && !attrs[:budget].is_a?(Integer)
+
+      attrs.slice(:effort, :budget).compact
+    end
+
     def conversation(model: nil, subject: nil, metadata: {})
       store = effective_store
       record = store.create_conversation(
@@ -41,10 +57,22 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
+    def cost
+      Cost.from_records(effective_store.list_turns(agent_name: name))
+    end
+
+    def usage
+      Usage.from_records(effective_store.list_turns(agent_name: name))
+    end
+
     def effective_model
       model || TurnKit.default_model
     end
 
+    def effective_thinking
+      thinking
+    end
+
     def effective_client
       client || TurnKit.client
     end

data/lib/turnkit/budget.rb

@@ -32,10 +32,14 @@ module TurnKit
     end
 
     def add_usage!(usage)
-      return unless usage&.cost && cost_limit
+      add_cost!(usage&.cost)
+    end
+
+    def add_cost!(cost)
+      return unless cost && cost_limit
 
       @mutex.synchronize do
-        @cost += usage.cost.to_f
+        @cost += cost.to_f
         raise Error, "cost limit reached" if @cost > cost_limit
       end
     end

data/lib/turnkit/client.rb

@@ -2,7 +2,7 @@
 
 module TurnKit
   class Client
-    def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+    def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
       raise NotImplementedError
     end
   end

data/lib/turnkit/conversation.rb

@@ -2,6 +2,8 @@
 
 module TurnKit
   class Conversation
+    THINKING_UNSET = Object.new.freeze
+
     attr_reader :agent, :id, :store, :model, :subject, :metadata
 
     def initialize(agent:, record:, store:, model:, subject: nil, metadata: {})
@@ -24,12 +26,15 @@ module TurnKit
       async ? turn : turn.run!
     end
 
-    def run!(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent)
-      build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, depth: depth, agent: agent).run!
+    def run!(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET)
+      build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, depth: depth, agent: agent, thinking: thinking).run!
     end
 
-    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent)
+    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET)
       snapshot = latest_message_sequence
+      effective_thinking = thinking.equal?(THINKING_UNSET) ? agent.effective_thinking : Agent.normalize_thinking(thinking)
+      options = { "trigger_message_id" => trigger_message_id }.compact
+      options["thinking"] = effective_thinking
       record = store.create_turn(
         "conversation_id" => id,
         "agent_name" => agent.name,
@@ -39,7 +44,7 @@ module TurnKit
         "context_message_sequence" => snapshot,
         "status" => "pending",
         "model" => model || self.model || agent.effective_model,
-        "options" => { "trigger_message_id" => trigger_message_id }.compact
+        "options" => options
       )
       Turn.new(agent: agent, conversation: self, record: record, store: store, budget: budget, depth: depth)
     end
@@ -48,6 +53,14 @@ module TurnKit
       store.list_messages(id).map { |attrs| Message.new(attrs) }
     end
 
+    def usage
+      Usage.from_records(store.list_turns(conversation_id: id))
+    end
+
+    def cost
+      Cost.from_records(store.list_turns(conversation_id: id))
+    end
+
     def messages_for_turn(turn)
       store.list_messages(id, through_sequence: turn.context_message_sequence, turn_id: turn.id).map { |attrs| Message.new(attrs) }
     end

data/lib/turnkit/cost.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Cost
+    COMPONENTS = %i[input output cache_read cache_write thinking].freeze
+    PER_MILLION = 1_000_000.0
+
+    attr_reader :input, :output, :cache_read, :cache_write, :thinking
+
+    def self.aggregate(costs)
+      costs = costs.compact
+      return new unless costs.any?
+
+      if costs.any? { |cost| COMPONENTS.any? { |component| !cost.public_send(component).nil? } }
+        values = COMPONENTS.to_h do |component|
+          amounts = costs.filter_map { |cost| cost.public_send(component) }
+          [ component, amounts.any? ? amounts.sum : nil ]
+        end
+        return new(**values)
+      end
+
+      totals = costs.map(&:total)
+      return new(total: totals.sum) if totals.none?(&:nil?)
+
+      new
+    end
+
+    def self.from_usage(usage, model: nil)
+      return new(total: usage.cost) if usage.cost
+
+      custom = custom_cost(usage, model)
+      return custom if custom
+
+      rates = TurnKit.cost_rates[model.to_s] || TurnKit.cost_rates[model&.to_sym]
+      rates ? from_rates(usage, rates) : from_ruby_llm(usage, model)
+    end
+
+    def self.from_records(records)
+      aggregate(records.map { |record| from_record(record) })
+    end
+
+    def self.from_record(record)
+      attrs = record.transform_keys(&:to_s)
+      usage = attrs["usage"] || {}
+      return from_hash(usage["cost_details"] || usage[:cost_details]) if usage["cost_details"] || usage[:cost_details]
+      return new(total: attrs["cost"]) if attrs["cost"]
+
+      from_usage(Usage.from_h(usage), model: attrs["model"])
+    end
+
+    def self.from_rates(usage, rates)
+      rates = rates.transform_keys(&:to_sym)
+      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]),
+        strict: true
+      )
+    end
+
+    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
+      new
+    end
+
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+      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],
+        total: hash[:total]
+      )
+    end
+
+    def self.custom_cost(usage, model)
+      return unless TurnKit.cost_calculator
+
+      value = TurnKit.cost_calculator.call(usage, model)
+      case value
+      when nil
+        nil
+      when Cost
+        value
+      when Hash
+        from_hash(value)
+      else
+        new(total: value)
+      end
+    end
+
+    def self.amount(tokens, price)
+      return nil if tokens.to_i.positive? && price.nil?
+      return 0.0 if tokens.to_i.zero?
+
+      tokens.to_i * price.to_f / PER_MILLION
+    end
+
+    def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil, thinking: nil, total: nil, strict: false)
+      @input = number(input)
+      @output = number(output)
+      @cache_read = number(cache_read)
+      @cache_write = number(cache_write)
+      @thinking = number(thinking)
+      @total = number(total)
+      @strict = strict
+    end
+
+    def total
+      return @total if @total
+      return nil if @strict && COMPONENTS.any? { |component| public_send(component).nil? }
+
+      values = COMPONENTS.filter_map { |component| public_send(component) }
+      values.empty? ? nil : values.sum
+    end
+
+    def to_h
+      {
+        "input" => input,
+        "output" => output,
+        "cache_read" => cache_read,
+        "cache_write" => cache_write,
+        "thinking" => thinking,
+        "total" => total
+      }.compact
+    end
+
+    private
+      def number(value)
+        value.nil? ? nil : value.to_f
+      end
+  end
+end

data/lib/turnkit/memory_store.rb

@@ -68,11 +68,12 @@ module TurnKit
       end
     end
 
-    def list_turns(root_turn_id: nil, conversation_id: nil)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       @mutex.synchronize do
         rows = @turns.values
         rows = rows.select { |turn| turn["root_turn_id"] == root_turn_id } if root_turn_id
         rows = rows.select { |turn| turn["conversation_id"] == conversation_id } if conversation_id
+        rows = rows.select { |turn| turn["agent_name"] == agent_name } if agent_name
         rows.sort_by { |turn| [ turn["created_at"].to_f, turn["id"] ] }.map { |turn| duplicate(turn) }
       end
     end

data/lib/turnkit/store.rb

@@ -12,7 +12,7 @@ module TurnKit
     def create_turn(_attributes) = raise(NotImplementedError)
     def load_turn(_id) = raise(NotImplementedError)
     def update_turn(_id, _attributes) = raise(NotImplementedError)
-    def list_turns(root_turn_id: nil, conversation_id: nil) = raise(NotImplementedError)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil) = raise(NotImplementedError)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)
     def load_tool_execution(_id) = raise(NotImplementedError)

data/lib/turnkit/stores/active_record_store.rb

@@ -89,10 +89,11 @@ module TurnKit
       turn_hash(record)
     end
 
-    def list_turns(root_turn_id: nil, conversation_id: nil)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       scope = turn_class.all
       scope = scope.where(root_turn_uid: root_turn_id) if root_turn_id
       scope = scope.where(conversation_uid: conversation_id) if conversation_id
+      scope = scope.where(agent_name: agent_name) if agent_name
       scope.order(:created_at, :uid).map { |record| turn_hash(record) }
     end
 

data/lib/turnkit/turn.rb

@@ -6,7 +6,7 @@ module TurnKit
 
     attr_reader :agent, :conversation, :store, :budget, :depth
     attr_reader :id, :conversation_id, :agent_name, :parent_turn_id, :parent_tool_execution_id
-    attr_reader :root_turn_id, :context_message_sequence, :model
+    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking
     attr_reader :started_at
 
     def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0)
@@ -22,6 +22,7 @@ module TurnKit
       @root_turn_id = @record["root_turn_id"] || id
       @context_message_sequence = @record["context_message_sequence"].to_i
       @model = @record["model"] || agent.effective_model
+      @thinking = thinking_from_options
       @started_at = @record["started_at"]
       @budget = budget || agent.build_budget
       @depth = depth
@@ -40,11 +41,13 @@ module TurnKit
           messages: llm_messages,
           tools: agent.effective_tools,
           instructions: agent.system_prompt_for(turn: self, conversation: conversation),
+          thinking: thinking,
           metadata: { turn_id: id, conversation_id: conversation.id }
         )
+        result_cost = Cost.from_usage(result.usage, model: result.model || model)
 
-        budget.add_usage!(result.usage)
-        add_usage!(result.usage)
+        budget.add_cost!(result_cost.total)
+        add_usage!(result.usage, cost: result_cost)
         persist_assistant_message(result)
 
         if result.tool_calls?
@@ -79,12 +82,21 @@ module TurnKit
       @record["output_text"].to_s
     end
 
+    def usage
+      Usage.from_h(@record["usage"] || {})
+    end
+
+    def cost
+      Cost.from_record(@record)
+    end
+
     def tool_executions
       store.list_tool_executions(turn_id: id).map { |attrs| ToolExecution.new(attrs) }
     end
 
     def reload
       @record = store.load_turn(id)
+      @thinking = thinking_from_options
       self
     end
 
@@ -97,6 +109,13 @@ module TurnKit
         MessageProjection.for(conversation.messages_for_turn(self))
       end
 
+      def thinking_from_options
+        options = (@record["options"] || {}).transform_keys(&:to_s)
+        return Agent.normalize_thinking(options["thinking"]) if options.key?("thinking")
+
+        agent.effective_thinking
+      end
+
       def persist_assistant_message(result)
         if result.tool_calls?
           conversation.append_message(
@@ -117,20 +136,28 @@ module TurnKit
         update!(status: "completed", output_text: message, completed_at: Clock.now)
       end
 
-      def add_usage!(usage)
+      def add_usage!(usage, cost: nil)
         current = @record["usage"] || {}
         totals = {
           "input_tokens" => current["input_tokens"].to_i + usage.input_tokens,
           "output_tokens" => current["output_tokens"].to_i + usage.output_tokens,
           "cached_tokens" => current["cached_tokens"].to_i + usage.cached_tokens,
           "cache_write_tokens" => current["cache_write_tokens"].to_i + usage.cache_write_tokens,
+          "thinking_tokens" => current["thinking_tokens"].to_i + usage.thinking_tokens,
           "total_tokens" => current["total_tokens"].to_i + usage.total_tokens
         }
+        totals["cost_details"] = aggregate_cost(current["cost_details"], cost).to_h if cost&.total
         attributes = { usage: totals, heartbeat_at: Clock.now }
-        attributes[:cost] = @record["cost"].to_f + usage.cost.to_f if usage.cost
+        attributes[:cost] = @record["cost"].to_f + cost.total if cost&.total
         update!(attributes)
       end
 
+      def aggregate_cost(current, cost)
+        return cost unless current
+
+        Cost.aggregate([ Cost.from_hash(current), cost ])
+      end
+
       def update!(attributes)
         @record = store.update_turn(id, attributes)
         @started_at = @record["started_at"]

data/lib/turnkit/usage.rb

@@ -2,18 +2,50 @@
 
 module TurnKit
   class Usage
-    attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_write_tokens, :cost
+    attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_write_tokens, :thinking_tokens, :cost
 
-    def initialize(input_tokens: 0, output_tokens: 0, cached_tokens: 0, cache_write_tokens: 0, cost: nil)
+    def self.aggregate(usages)
+      usages = usages.compact
+      costs = usages.map(&:cost).compact
+      cost = costs.sum if costs.any?
+      new(
+        input_tokens: usages.sum(&:input_tokens),
+        output_tokens: usages.sum(&:output_tokens),
+        cached_tokens: usages.sum(&:cached_tokens),
+        cache_write_tokens: usages.sum(&:cache_write_tokens),
+        thinking_tokens: usages.sum(&:thinking_tokens),
+        cost: cost
+      )
+    end
+
+    def self.from_records(records)
+      aggregate(records.map { |record| from_h(record.fetch("usage", {})) })
+    end
+
+    def self.from_h(hash)
+      attrs = hash.transform_keys(&:to_s)
+      cost = attrs["cost"] unless attrs["cost"].is_a?(Hash)
+      new(
+        input_tokens: attrs["input_tokens"],
+        output_tokens: attrs["output_tokens"],
+        cached_tokens: attrs["cached_tokens"],
+        cache_write_tokens: attrs["cache_write_tokens"],
+        thinking_tokens: attrs["thinking_tokens"] || attrs["reasoning_tokens"],
+        cost: cost
+      )
+    end
+
+    def initialize(input_tokens: 0, output_tokens: 0, cached_tokens: 0, cache_write_tokens: 0, thinking_tokens: 0, cost: nil)
       @input_tokens = input_tokens.to_i
       @output_tokens = output_tokens.to_i
       @cached_tokens = cached_tokens.to_i
       @cache_write_tokens = cache_write_tokens.to_i
+      @thinking_tokens = thinking_tokens.to_i
       @cost = cost
     end
 
     def total_tokens
-      input_tokens + output_tokens + cached_tokens + cache_write_tokens
+      input_tokens + output_tokens + cached_tokens + cache_write_tokens + thinking_tokens
     end
 
     def to_h
@@ -22,6 +54,7 @@ module TurnKit
         "output_tokens" => output_tokens,
         "cached_tokens" => cached_tokens,
         "cache_write_tokens" => cache_write_tokens,
+        "thinking_tokens" => thinking_tokens,
         "total_tokens" => total_tokens,
         "cost" => cost
       }.compact

data/lib/turnkit/version.rb

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

data/lib/turnkit.rb

@@ -10,6 +10,7 @@ require_relative "turnkit/version"
 require_relative "turnkit/error"
 require_relative "turnkit/id"
 require_relative "turnkit/clock"
+require_relative "turnkit/cost"
 require_relative "turnkit/budget"
 require_relative "turnkit/agent"
 require_relative "turnkit/client"
@@ -42,6 +43,7 @@ module TurnKit
     attr_accessor :default_model, :client, :store, :logger
     attr_accessor :max_iterations, :timeout, :max_depth, :max_tool_executions
     attr_accessor :cost_limit, :prompt_cache
+    attr_accessor :cost_rates, :cost_calculator
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
     attr_accessor :system_prompt_contributors, :model_prompt_contributors
@@ -57,6 +59,7 @@ module TurnKit
   self.max_depth = 3
   self.max_tool_executions = 100
   self.prompt_cache = :auto
+  self.cost_rates = {}
   self.prompt_sections = SystemPrompt::DEFAULT_SECTIONS.dup
   self.prompt_data_max_chars = 20_000
   self.available_skills = []

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Sam Couch
@@ -43,6 +43,7 @@ files:
 - lib/turnkit/client.rb
 - lib/turnkit/clock.rb
 - lib/turnkit/conversation.rb
+- lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/generators/turnkit/install/templates/conversation.rb
 - lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb