turnkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7aec304178bd79782515aaacd238e19de0556e64947406f14cdc8d6ccf05f71b
+  data.tar.gz: 92691d763c7cc007fb5cde9b9af2fbc28c69db9078b334f6b9a10892971a4644
+SHA512:
+  metadata.gz: ab078a5e371c67774b9232ef90f3726fb630f1d1b4d13b71cdd09e51263074f9135ab87b9371e31e149b2d982e6ec4dea9950a2cf0fac7677fe334e950bc0071
+  data.tar.gz: c0637c433abbfc2e2c03bdc4632b3416c6596ffa20cc1855d537c68e4b54120033b78a435ffd8a311f9d29f8e0c0ae6f3ca06dd9a75d9a29f26e5a87f173bb78

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-06-04
+
+- Initial release of TurnKit.
+- Add durable conversations, turns, messages, tool calls, tool executions, and usage tracking.
+- Add in-memory storage and optional Active Record-backed persistence.
+- Add RubyLLM adapter support for model calls and provider API keys.
+- Add tool, terminal-tool, skill, and sub-agent primitives.

data/LICENSE.md

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

data/README.md

@@ -0,0 +1,193 @@
+# TurnKit
+
+[![Gem Version](https://badge.fury.io/rb/turnkit.svg)](https://rubygems.org/gems/turnkit)
+[![Build](https://github.com/samuelcouch/turnkit/actions/workflows/ci.yml/badge.svg)](https://github.com/samuelcouch/turnkit/actions)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.md)
+
+Ruby AI agent runtime with durable turns, tools, skills, and Rails persistence.
+
+## Installation
+
+Add this line to your application's **Gemfile**:
+
+```ruby
+gem "turnkit"
+```
+
+Run:
+
+```sh
+bundle install
+```
+
+## Quick Start
+
+Set a provider key, then ask an agent:
+
+```sh
+export ANTHROPIC_API_KEY=...
+```
+
+```ruby
+require "turnkit"
+
+agent = TurnKit::Agent.new(
+  name: "helper",
+  instructions: "Answer briefly."
+)
+
+turn = agent.conversation.ask("Explain Ruby blocks in one sentence.")
+puts turn.output_text
+```
+
+## Usage
+
+Create a conversation:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "writer",
+  instructions: "Write clear release notes."
+)
+
+conversation = agent.conversation(subject: "v1 launch")
+conversation.say("Mention faster tool execution.")
+
+turn = conversation.run!
+puts turn.output_text
+```
+
+Create a tool:
+
+```ruby
+class SaveReport < TurnKit::Tool
+  description "Save a report."
+  parameter :title, :string, required: true
+  parameter :body, :string, required: true
+
+  def self.ends_turn? = true
+  def self.completion_message(result) = "Saved #{result.fetch("report_id")}."
+
+  def call(title:, body:, context:)
+    { report_id: "rep_1", title: title, body: body }
+  end
+end
+```
+
+Use the tool:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "reporter",
+  instructions: "Save reports when asked.",
+  tools: [SaveReport]
+)
+
+turn = agent.conversation.ask("Save a short status report.")
+puts turn.output_text
+```
+
+Add skills:
+
+```ruby
+skill = TurnKit::Skill.from_file("skills/research.md")
+
+agent = TurnKit::Agent.new(
+  name: "researcher",
+  skills: [skill]
+)
+```
+
+Delegate to sub-agents:
+
+```ruby
+writer = TurnKit::Agent.new(
+  name: "writer",
+  description: "Draft concise copy."
+)
+
+editor = TurnKit::Agent.new(
+  name: "editor",
+  sub_agents: [writer]
+)
+
+turn = editor.conversation.ask("Ask the writer for three headlines.")
+puts turn.output_text
+```
+
+Install Rails persistence:
+
+```sh
+bin/rails generate turnkit:install
+bin/rails db:migrate
+```
+
+Configure Rails:
+
+```ruby
+# config/initializers/turnkit.rb
+TurnKit.store = TurnKit::ActiveRecordStore.new
+TurnKit.default_model = "claude-sonnet-4-5"
+TurnKit.timeout = 300
+```
+
+Reconcile stale turns:
+
+```ruby
+TurnKit.reconcile_stale!
+```
+
+## Options
+
+Configure defaults globally:
+
+```ruby
+TurnKit.default_model = "claude-sonnet-4-5"
+TurnKit.max_iterations = 25
+TurnKit.timeout = 300
+TurnKit.max_depth = 3
+TurnKit.max_tool_executions = 100
+TurnKit.cost_limit = nil
+```
+
+Override defaults per agent:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "analyst",
+  model: "gpt-4.1-mini",
+  max_iterations: 10,
+  timeout: 60,
+  cost_limit: 0.25
+)
+```
+
+| Option | Description |
+| --- | --- |
+| `default_model` | Default model for new turns. |
+| `client` | Client adapter for model calls. |
+| `store` | Store for conversations and turns. |
+| `max_iterations` | Maximum model calls per turn. |
+| `timeout` | Maximum seconds per root turn. |
+| `max_depth` | Maximum sub-agent nesting depth. |
+| `max_tool_executions` | Maximum tool calls per root turn. |
+| `cost_limit` | Maximum cost per root turn. |
+
+## Contributing
+
+Open bug reports and pull requests on GitHub:
+
+```text
+https://github.com/samuelcouch/turnkit
+```
+
+Run tests:
+
+```sh
+bundle exec rake test
+```
+
+## License
+
+See the MIT License.

data/lib/turnkit/adapters/ruby_llm.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module TurnKit
+  module Adapters
+    class RubyLLM < Client
+      def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+        require "ruby_llm"
+
+        configure_from_environment
+
+        chat = ::RubyLLM.chat(model: model)
+        chat.with_instructions(instructions) if instructions && !instructions.empty?
+        chat.with_temperature(temperature) if temperature
+        Array(tools).each { |tool| chat.with_tool(ruby_llm_tool(tool)) }
+        Array(messages).each { |message| add_message(chat, message) }
+
+        response = complete_without_tool_execution(chat)
+        normalize_response(response, model: model)
+      end
+
+      private
+        def configure_from_environment
+          config = ::RubyLLM.config
+          config.openai_api_key ||= ENV["OPENAI_API_KEY"]
+          config.gemini_api_key ||= ENV["GEMINI_API_KEY"]
+          config.anthropic_api_key ||= ENV["ANTHROPIC_API_KEY"]
+          config.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
+        end
+
+        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)
+          )
+        end
+
+        def add_message(chat, message)
+          role = (message[:role] || message["role"]).to_sym
+          content = message[:content] || message["content"] || ""
+          chat.add_message(
+            {
+              role: role,
+              content: content,
+              tool_calls: ruby_llm_tool_calls(message[:tool_calls] || message["tool_calls"]),
+              tool_call_id: message[:tool_call_id] || message["tool_call_id"]
+            }.compact
+          )
+        end
+
+        def ruby_llm_tool_calls(tool_calls)
+          return nil if tool_calls.nil? || tool_calls.empty?
+
+          calls = tool_calls.is_a?(Hash) ? tool_calls.values : Array(tool_calls)
+          calls.to_h do |tool_call|
+            attrs = tool_call.respond_to?(:to_h) ? tool_call.to_h : tool_call
+            attrs = attrs.transform_keys(&:to_s)
+            id = attrs.fetch("id")
+            [ id, ::RubyLLM::ToolCall.new(id: id, name: attrs.fetch("name"), arguments: attrs["arguments"] || {}) ]
+          end
+        end
+
+        def ruby_llm_tool(tool)
+          require "ruby_llm"
+
+          Class.new(::RubyLLM::Tool) do
+            define_singleton_method(:name) { tool.tool_name }
+            description tool.description
+            tool.parameters.each do |param|
+              param(param.fetch(:name).to_sym, type: param.fetch(:type), required: param.fetch(:required), desc: param.fetch(:description))
+            end
+
+            define_method(:execute) do |**arguments|
+              raise ToolError, "tools must be executed by TurnKit turns, not the RubyLLM adapter"
+            end
+          end
+        end
+
+        def normalize_response(response, model:)
+          tool_calls = Array(response.respond_to?(:tool_calls) ? response.tool_calls&.values : []).map do |call|
+            ToolCall.new(id: call.id, name: call.name, arguments: call.arguments)
+          end
+          usage = Usage.new(
+            input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : 0,
+            output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : 0,
+            cached_tokens: response.respond_to?(:cached_tokens) ? response.cached_tokens : 0
+          )
+          Result.new(
+            text: response.respond_to?(:content) ? response.content.to_s : response.to_s,
+            tool_calls: tool_calls,
+            usage: usage,
+            model: response.respond_to?(:model_id) ? response.model_id : model
+          )
+        end
+    end
+  end
+end

data/lib/turnkit/agent.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Agent
+    attr_reader :name, :description, :model, :instructions, :tools, :skills, :sub_agents
+    attr_reader :client, :store, :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions
+
+    def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], sub_agents: [], client: nil, store: nil,
+      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil)
+      @name = name.to_s
+      @description = description.to_s
+      @model = model
+      @instructions = instructions.to_s
+      @tools = Array(tools)
+      @skills = Array(skills)
+      @sub_agents = Array(sub_agents)
+      @client = client
+      @store = store
+      @max_iterations = max_iterations
+      @timeout = timeout
+      @cost_limit = cost_limit
+      @max_depth = max_depth
+      @max_tool_executions = max_tool_executions
+      raise ArgumentError, "name is required" if @name.empty?
+    end
+
+    def conversation(model: nil, subject: nil, metadata: {})
+      store = effective_store
+      record = store.create_conversation(
+        "agent_name" => name,
+        "model" => model || effective_model,
+        "subject" => subject,
+        "metadata" => metadata
+      )
+      Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
+    end
+
+    def effective_model
+      model || TurnKit.default_model
+    end
+
+    def effective_client
+      client || TurnKit.client
+    end
+
+    def effective_store
+      store || TurnKit.store
+    end
+
+    def effective_tools
+      tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
+    end
+
+    def build_budget(root_started_at: Clock.now)
+      Budget.new(
+        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,
+        cost_limit: cost_limit || TurnKit.cost_limit,
+        root_started_at: root_started_at
+      )
+    end
+
+    def instructions_with_skills
+      parts = [ instructions ]
+      skills.each do |skill|
+        parts << "## Skill: #{skill.name}\n\n#{skill.content}"
+      end
+      parts.reject(&:empty?).join("\n\n")
+    end
+  end
+end

data/lib/turnkit/budget.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Budget
+    attr_reader :root_started_at, :max_iterations, :timeout, :max_depth, :max_tool_executions, :cost_limit
+
+    def initialize(max_iterations:, timeout:, max_depth:, max_tool_executions:, cost_limit: nil, root_started_at: Clock.now)
+      @root_started_at = root_started_at
+      @max_iterations = max_iterations
+      @timeout = timeout
+      @max_depth = max_depth
+      @max_tool_executions = max_tool_executions
+      @cost_limit = cost_limit
+      @iterations = 0
+      @tool_executions = 0
+      @cost = 0
+      @mutex = Mutex.new
+    end
+
+    def count_iteration!
+      @mutex.synchronize do
+        @iterations += 1
+        raise Error, "maximum iterations reached" if max_iterations && @iterations > max_iterations
+      end
+    end
+
+    def count_tool_execution!
+      @mutex.synchronize do
+        @tool_executions += 1
+        raise Error, "maximum tool executions reached" if max_tool_executions && @tool_executions > max_tool_executions
+      end
+    end
+
+    def add_usage!(usage)
+      return unless usage&.cost && cost_limit
+
+      @mutex.synchronize do
+        @cost += usage.cost.to_f
+        raise Error, "cost limit reached" if @cost > cost_limit
+      end
+    end
+
+    def check!(depth:)
+      raise Error, "maximum sub-agent depth reached" if max_depth && depth > max_depth
+      raise Error, "turn timed out" if timeout && Clock.now >= root_started_at + timeout
+    end
+  end
+end

data/lib/turnkit/client.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Client
+    def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/turnkit/clock.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TurnKit
+  module Clock
+    module_function
+
+    def now
+      Time.now.utc
+    end
+  end
+end

data/lib/turnkit/conversation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Conversation
+    attr_reader :agent, :id, :store, :model, :subject, :metadata
+
+    def initialize(agent:, record:, store:, model:, subject: nil, metadata: {})
+      @agent = agent
+      @record = record.transform_keys(&:to_s)
+      @id = @record.fetch("id")
+      @store = store
+      @model = model
+      @subject = subject
+      @metadata = metadata || {}
+    end
+
+    def say(text, metadata: {})
+      append_message(role: "user", kind: "text", text: text, metadata: metadata)
+    end
+
+    def ask(text, async: false, **options)
+      trigger = say(text)
+      turn = build_turn(trigger_message_id: trigger.id, **options)
+      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!
+    end
+
+    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent)
+      snapshot = latest_message_sequence
+      record = store.create_turn(
+        "conversation_id" => id,
+        "agent_name" => agent.name,
+        "parent_turn_id" => parent_turn&.id,
+        "parent_tool_execution_id" => parent_tool_execution&.id,
+        "root_turn_id" => parent_turn&.root_turn_id,
+        "context_message_sequence" => snapshot,
+        "status" => "pending",
+        "model" => model || self.model || agent.effective_model,
+        "options" => { "trigger_message_id" => trigger_message_id }.compact
+      )
+      Turn.new(agent: agent, conversation: self, record: record, store: store, budget: budget, depth: depth)
+    end
+
+    def messages
+      store.list_messages(id).map { |attrs| Message.new(attrs) }
+    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
+
+    def append_message(role:, kind:, text: nil, content: nil, turn_id: nil, tool_execution_id: nil, metadata: {})
+      attrs = store.append_message(
+        "conversation_id" => id,
+        "turn_id" => turn_id,
+        "role" => role,
+        "kind" => kind,
+        "text" => text,
+        "content" => content,
+        "tool_execution_id" => tool_execution_id,
+        "metadata" => metadata
+      )
+      Message.new(attrs)
+    end
+
+    def latest_message_sequence
+      if store.respond_to?(:latest_message_sequence)
+        store.latest_message_sequence(id)
+      else
+        messages.map(&:sequence).max.to_i
+      end
+    end
+  end
+end

data/lib/turnkit/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Error < StandardError; end
+  class ConfigError < Error; end
+  class StoreError < Error; end
+  class ToolError < Error; end
+end

data/lib/turnkit/generators/turnkit/install/templates/conversation.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Turnkit
+  class Conversation < ApplicationRecord
+    self.table_name = "<%= table_prefix %>_conversations"
+
+    has_many :turns, class_name: "Turnkit::Turn", foreign_key: :conversation_uid, primary_key: :uid, dependent: :destroy, inverse_of: :conversation
+    has_many :messages, class_name: "Turnkit::Message", foreign_key: :conversation_uid, primary_key: :uid, dependent: :destroy, inverse_of: :conversation
+  end
+end

data/lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class CreateTurnkitTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :<%= table_prefix %>_conversations do |t|
+      t.string :uid, null: false
+      t.string :agent_name, null: false
+      t.string :model
+      t.string :subject_type
+      t.string :subject_id
+      t.json :metadata, null: false, default: {}
+      t.timestamps
+
+      t.index :uid, unique: true
+      t.index [ :subject_type, :subject_id ]
+    end
+
+    create_table :<%= table_prefix %>_turns do |t|
+      t.string :uid, null: false
+      t.string :conversation_uid, null: false
+      t.string :agent_name, null: false
+      t.string :parent_turn_uid
+      t.string :parent_tool_execution_uid
+      t.string :root_turn_uid, null: false
+      t.integer :context_message_sequence, null: false, default: 0
+      t.string :status, null: false, default: "pending"
+      t.string :model
+      t.json :options, null: false, default: {}
+      t.json :usage, null: false, default: {}
+      t.decimal :cost, precision: 14, scale: 6
+      t.json :error
+      t.text :output_text
+      t.datetime :started_at
+      t.datetime :heartbeat_at
+      t.datetime :completed_at
+      t.timestamps
+
+      t.index :uid, unique: true
+      t.index :conversation_uid
+      t.index :root_turn_uid
+      t.index [ :status, :heartbeat_at ]
+    end
+
+    create_table :<%= table_prefix %>_messages do |t|
+      t.string :uid, null: false
+      t.string :conversation_uid, null: false
+      t.string :turn_uid
+      t.string :role, null: false
+      t.string :kind, null: false
+      t.integer :sequence, null: false
+      t.json :content, null: false, default: []
+      t.text :text
+      t.string :tool_execution_uid
+      t.string :provider_message_id
+      t.json :metadata, null: false, default: {}
+      t.timestamps
+
+      t.index :uid, unique: true
+      t.index [ :conversation_uid, :sequence ], unique: true
+      t.index [ :conversation_uid, :turn_uid ]
+      t.index :turn_uid
+    end
+
+    create_table :<%= table_prefix %>_tool_executions do |t|
+      t.string :uid, null: false
+      t.string :turn_uid, null: false
+      t.string :tool_call_id, null: false
+      t.string :tool_name, null: false
+      t.string :status, null: false, default: "pending"
+      t.json :arguments, null: false, default: {}
+      t.json :result
+      t.json :error
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.timestamps
+
+      t.index :uid, unique: true
+      t.index [ :turn_uid, :tool_call_id ], unique: true
+      t.index [ :turn_uid, :status ]
+    end
+  end
+end

data/lib/turnkit/generators/turnkit/install/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+TurnKit.store = TurnKit::ActiveRecordStore.new
+
+TurnKit.conversation_record_class = "Turnkit::Conversation"
+TurnKit.turn_record_class = "Turnkit::Turn"
+TurnKit.message_record_class = "Turnkit::Message"
+TurnKit.tool_execution_record_class = "Turnkit::ToolExecution"
+
+# TurnKit.default_model = "claude-sonnet-4-5"
+# TurnKit.max_iterations = 25
+# TurnKit.timeout = 300
+# TurnKit.max_depth = 3
+# TurnKit.max_tool_executions = 100

data/lib/turnkit/generators/turnkit/install/templates/message.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Turnkit
+  class Message < ApplicationRecord
+    self.table_name = "<%= table_prefix %>_messages"
+
+    belongs_to :conversation, class_name: "Turnkit::Conversation", foreign_key: :conversation_uid, primary_key: :uid, inverse_of: :messages
+    belongs_to :turn, class_name: "Turnkit::Turn", foreign_key: :turn_uid, primary_key: :uid, optional: true, inverse_of: :messages
+    belongs_to :tool_execution, class_name: "Turnkit::ToolExecution", foreign_key: :tool_execution_uid, primary_key: :uid, optional: true
+  end
+end