turnkit 0.1.0

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Turnkit
+  class ToolExecution < ApplicationRecord
+    self.table_name = "<%= table_prefix %>_tool_executions"
+
+    belongs_to :turn, class_name: "Turnkit::Turn", foreign_key: :turn_uid, primary_key: :uid, inverse_of: :tool_executions
+    has_many :messages, class_name: "Turnkit::Message", foreign_key: :tool_execution_uid, primary_key: :uid, dependent: :nullify
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Turnkit
+  class Turn < ApplicationRecord
+    self.table_name = "<%= table_prefix %>_turns"
+
+    belongs_to :conversation, class_name: "Turnkit::Conversation", foreign_key: :conversation_uid, primary_key: :uid, inverse_of: :turns
+    belongs_to :parent_turn, class_name: "Turnkit::Turn", foreign_key: :parent_turn_uid, primary_key: :uid, optional: true
+    belongs_to :parent_tool_execution, class_name: "Turnkit::ToolExecution", foreign_key: :parent_tool_execution_uid, primary_key: :uid, optional: true
+
+    has_many :messages, class_name: "Turnkit::Message", foreign_key: :turn_uid, primary_key: :uid, dependent: :nullify, inverse_of: :turn
+    has_many :tool_executions, class_name: "Turnkit::ToolExecution", foreign_key: :turn_uid, primary_key: :uid, dependent: :destroy, inverse_of: :turn
+  end
+end

data/lib/turnkit/generators/turnkit/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module TurnKit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("install/templates", __dir__)
+
+      class_option :table_prefix, type: :string, default: "turnkit", desc: "Database table prefix."
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/turnkit.rb"
+      end
+
+      def copy_models
+        template "conversation.rb", "app/models/turnkit/conversation.rb"
+        template "turn.rb", "app/models/turnkit/turn.rb"
+        template "message.rb", "app/models/turnkit/message.rb"
+        template "tool_execution.rb", "app/models/turnkit/tool_execution.rb"
+      end
+
+      def copy_migration
+        migration_template "create_turnkit_tables.rb", "db/migrate/create_turnkit_tables.rb"
+      end
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+
+      private
+        def table_prefix
+          options[:table_prefix]
+        end
+    end
+  end
+end

data/lib/turnkit/id.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TurnKit
+  module Id
+    PREFIXES = {
+      conversation: "conv",
+      message: "msg",
+      turn: "turn",
+      tool_execution: "tool"
+    }.freeze
+
+    module_function
+
+    def generate(type)
+      prefix = PREFIXES.fetch(type)
+      "#{prefix}_#{SecureRandom.hex(12)}"
+    end
+  end
+end

data/lib/turnkit/memory_store.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class MemoryStore < Store
+    def initialize
+      @mutex = Mutex.new
+      @conversations = {}
+      @turns = {}
+      @messages = {}
+      @tool_executions = {}
+      @message_sequences = Hash.new(0)
+    end
+
+    def create_conversation(attributes)
+      record = Record.conversation(attributes)
+
+      @mutex.synchronize { @conversations[record.fetch("id")] = record }
+      record.dup
+    end
+
+    def load_conversation(id)
+      @mutex.synchronize { duplicate(@conversations.fetch(id)) }
+    end
+
+    def next_message_sequence(conversation_id)
+      @mutex.synchronize do
+        @message_sequences[conversation_id] += 1
+      end
+    end
+
+    def latest_message_sequence(conversation_id)
+      @mutex.synchronize { @message_sequences[conversation_id].to_i }
+    end
+
+    def append_message(attributes)
+      attrs = stringify(attributes)
+      attrs["sequence"] ||= next_message_sequence(attrs.fetch("conversation_id"))
+      message = Record.message(attrs)
+      @mutex.synchronize { @messages[message.fetch("id")] = message }
+      duplicate(message)
+    end
+
+    def list_messages(conversation_id, through_sequence: nil, turn_id: nil)
+      @mutex.synchronize do
+        rows = @messages.values.select { |message| message["conversation_id"] == conversation_id }
+        rows = rows.select { |message| message["sequence"].to_i <= through_sequence.to_i || message["turn_id"] == turn_id } if through_sequence
+        rows.sort_by { |message| [ message["sequence"].to_i, message["created_at"].to_f, message["id"] ] }.map { |message| duplicate(message) }
+      end
+    end
+
+    def create_turn(attributes)
+      record = Record.turn(attributes)
+
+      @mutex.synchronize { @turns[record.fetch("id")] = record }
+      duplicate(record)
+    end
+
+    def load_turn(id)
+      @mutex.synchronize { duplicate(@turns.fetch(id)) }
+    end
+
+    def update_turn(id, attributes)
+      attrs = Record.turn_update(attributes)
+      @mutex.synchronize do
+        record = @turns.fetch(id)
+        record.merge!(attrs.merge("updated_at" => Clock.now))
+        duplicate(record)
+      end
+    end
+
+    def list_turns(root_turn_id: nil, conversation_id: 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.sort_by { |turn| [ turn["created_at"].to_f, turn["id"] ] }.map { |turn| duplicate(turn) }
+      end
+    end
+
+    def create_tool_execution(attributes)
+      record = Record.tool_execution(attributes)
+
+      @mutex.synchronize { @tool_executions[record.fetch("id")] = record }
+      duplicate(record)
+    end
+
+    def load_tool_execution(id)
+      @mutex.synchronize { duplicate(@tool_executions.fetch(id)) }
+    end
+
+    def update_tool_execution(id, attributes)
+      attrs = Record.tool_execution_update(attributes)
+      @mutex.synchronize do
+        record = @tool_executions.fetch(id)
+        record.merge!(attrs.merge("updated_at" => Clock.now))
+        duplicate(record)
+      end
+    end
+
+    def list_tool_executions(turn_id:)
+      @mutex.synchronize do
+        @tool_executions.values
+          .select { |execution| execution["turn_id"] == turn_id }
+          .sort_by { |execution| [ execution["created_at"].to_f, execution["id"] ] }
+          .map { |execution| duplicate(execution) }
+      end
+    end
+
+    def find_stale_turns(before:)
+      @mutex.synchronize do
+        @turns.values.select do |turn|
+          %w[pending running].include?(turn["status"]) && stale_anchor(turn) && stale_anchor(turn) < before
+        end.map { |turn| duplicate(turn) }
+      end
+    end
+
+    private
+      def stringify(hash)
+        hash.transform_keys(&:to_s)
+      end
+
+      def duplicate(value)
+        Marshal.load(Marshal.dump(value))
+      end
+
+      def stale_anchor(turn)
+        turn["heartbeat_at"] || turn["started_at"] || turn["created_at"]
+      end
+  end
+end

data/lib/turnkit/message.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Message
+    ROLES = %w[user assistant tool].freeze
+    KINDS = %w[text tool_call tool_result].freeze
+
+    attr_reader :id, :conversation_id, :turn_id, :role, :kind, :sequence
+    attr_reader :content, :text, :tool_execution_id, :provider_message_id, :metadata, :created_at
+
+    def initialize(attributes = {})
+      attrs = stringify(attributes)
+      @id = attrs["id"] || Id.generate(:message)
+      @conversation_id = attrs.fetch("conversation_id")
+      @turn_id = attrs["turn_id"]
+      @role = attrs.fetch("role").to_s
+      @kind = attrs.fetch("kind", "text").to_s
+      @sequence = attrs.fetch("sequence").to_i
+      @content = normalize_content(attrs["content"] || attrs["text"])
+      @text = attrs["text"] || extract_text(@content)
+      @tool_execution_id = attrs["tool_execution_id"]
+      @provider_message_id = attrs["provider_message_id"]
+      @metadata = attrs["metadata"] || {}
+      @created_at = attrs["created_at"] || Clock.now
+
+      validate!
+    end
+
+    def to_h
+      {
+        "id" => id,
+        "conversation_id" => conversation_id,
+        "turn_id" => turn_id,
+        "role" => role,
+        "kind" => kind,
+        "sequence" => sequence,
+        "content" => content,
+        "text" => text,
+        "tool_execution_id" => tool_execution_id,
+        "provider_message_id" => provider_message_id,
+        "metadata" => metadata,
+        "created_at" => created_at
+      }
+    end
+
+    private
+      def stringify(hash)
+        hash.transform_keys(&:to_s)
+      end
+
+      def normalize_content(value)
+        return value if value.is_a?(Array)
+
+        [ { "type" => "text", "text" => value.to_s } ]
+      end
+
+      def extract_text(blocks)
+        Array(blocks).filter_map { |block| block.is_a?(Hash) ? block["text"] || block[:text] : nil }.join("\n")
+      end
+
+      def validate!
+        raise ArgumentError, "unknown role: #{role}" unless ROLES.include?(role)
+        raise ArgumentError, "unknown kind: #{kind}" unless KINDS.include?(kind)
+        raise ArgumentError, "sequence must be positive" unless sequence.positive?
+      end
+  end
+end

data/lib/turnkit/message_projection.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class MessageProjection
+    def self.for(messages)
+      messages.map { |message| new(message).to_h }
+    end
+
+    def initialize(message)
+      @message = message
+    end
+
+    def to_h
+      case message.kind
+      when "tool_call"
+        { role: :assistant, content: message.text, tool_calls: message.metadata.fetch("tool_calls", []) }
+      when "tool_result"
+        { role: :tool, content: message.text, tool_call_id: message.metadata["tool_call_id"] }
+      else
+        { role: message.role.to_sym, content: message.text }
+      end
+    end
+
+    private
+      attr_reader :message
+  end
+end

data/lib/turnkit/rails/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "../generators/turnkit/install_generator"
+    end
+  end
+end

data/lib/turnkit/record.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module TurnKit
+  module Record
+    TURN_STATUSES = %w[pending running completed failed cancelled stale].freeze
+    TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled].freeze
+
+    TURN_UPDATE_KEYS = %w[status options usage cost error output_text started_at heartbeat_at completed_at].freeze
+    TOOL_EXECUTION_UPDATE_KEYS = %w[status result error started_at completed_at].freeze
+
+    module_function
+
+    def conversation(attributes)
+      attrs = stringify(attributes)
+      now = Clock.now
+      {
+        "id" => attrs["id"] || Id.generate(:conversation),
+        "agent_name" => attrs["agent_name"],
+        "model" => attrs["model"],
+        "subject" => attrs["subject"],
+        "metadata" => attrs["metadata"] || {},
+        "created_at" => attrs["created_at"] || now,
+        "updated_at" => attrs["updated_at"] || now
+      }
+    end
+
+    def message(attributes)
+      Message.new(attributes).to_h
+    end
+
+    def turn(attributes)
+      attrs = stringify(attributes)
+      id = attrs["id"] || Id.generate(:turn)
+      status = attrs["status"] || "pending"
+      assert_status!(status, TURN_STATUSES, "turn")
+      now = Clock.now
+      {
+        "id" => id,
+        "conversation_id" => attrs.fetch("conversation_id"),
+        "agent_name" => attrs["agent_name"],
+        "parent_turn_id" => attrs["parent_turn_id"],
+        "parent_tool_execution_id" => attrs["parent_tool_execution_id"],
+        "root_turn_id" => attrs["root_turn_id"] || id,
+        "context_message_sequence" => attrs["context_message_sequence"].to_i,
+        "status" => status,
+        "model" => attrs["model"],
+        "options" => attrs["options"] || {},
+        "usage" => attrs["usage"] || {},
+        "cost" => attrs["cost"],
+        "error" => attrs["error"],
+        "output_text" => attrs["output_text"],
+        "started_at" => attrs["started_at"],
+        "heartbeat_at" => attrs["heartbeat_at"],
+        "completed_at" => attrs["completed_at"],
+        "created_at" => attrs["created_at"] || now,
+        "updated_at" => attrs["updated_at"] || now
+      }
+    end
+
+    def tool_execution(attributes)
+      attrs = stringify(attributes)
+      status = attrs["status"] || "pending"
+      assert_status!(status, TOOL_EXECUTION_STATUSES, "tool execution")
+      now = Clock.now
+      {
+        "id" => attrs["id"] || Id.generate(:tool_execution),
+        "turn_id" => attrs.fetch("turn_id"),
+        "tool_call_id" => attrs.fetch("tool_call_id"),
+        "tool_name" => attrs.fetch("tool_name"),
+        "status" => status,
+        "arguments" => attrs["arguments"] || {},
+        "result" => attrs["result"],
+        "error" => attrs["error"],
+        "started_at" => attrs["started_at"],
+        "completed_at" => attrs["completed_at"],
+        "created_at" => attrs["created_at"] || now,
+        "updated_at" => attrs["updated_at"] || now
+      }
+    end
+
+    def turn_update(attributes)
+      update(attributes, TURN_UPDATE_KEYS, TURN_STATUSES, "turn")
+    end
+
+    def tool_execution_update(attributes)
+      update(attributes, TOOL_EXECUTION_UPDATE_KEYS, TOOL_EXECUTION_STATUSES, "tool execution")
+    end
+
+    def stringify(hash)
+      hash.transform_keys(&:to_s)
+    end
+
+    def subject_pair(subject)
+      case subject
+      when Hash
+        attrs = stringify(subject)
+        [ attrs["type"] || attrs["class"], attrs["id"] ]
+      else
+        [ subject&.class&.name, subject&.respond_to?(:id) ? subject.id : nil ]
+      end
+    end
+
+    def assert_status!(status, allowed, name)
+      raise ArgumentError, "unknown #{name} status: #{status}" unless allowed.include?(status.to_s)
+    end
+
+    def update(attributes, allowed_keys, allowed_statuses, name)
+      attrs = stringify(attributes)
+      unknown = attrs.keys - allowed_keys
+      raise ArgumentError, "unknown #{name} update attributes: #{unknown.join(", ")}" if unknown.any?
+
+      assert_status!(attrs["status"], allowed_statuses, name) if attrs.key?("status")
+      attrs
+    end
+  end
+end

data/lib/turnkit/result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Result
+    attr_reader :text, :tool_calls, :usage, :model, :finish_reason
+
+    def initialize(text: "", tool_calls: [], usage: Usage.new, model: nil, finish_reason: nil)
+      @text = text.to_s
+      @tool_calls = Array(tool_calls)
+      @usage = usage || Usage.new
+      @model = model
+      @finish_reason = finish_reason
+    end
+
+    def tool_calls?
+      tool_calls.any?
+    end
+  end
+end

data/lib/turnkit/skill.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Skill
+    attr_reader :key, :name, :description, :content
+
+    def self.from_file(path, key: nil, name: nil, description: "")
+      content = File.read(path)
+      base = File.basename(path, File.extname(path))
+      new(key: key || base, name: name || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description, content: content)
+    end
+
+    def initialize(key:, name:, content:, description: "")
+      @key = key.to_s
+      @name = name.to_s
+      @description = description.to_s
+      @content = content.to_s
+      raise ArgumentError, "key is required" if @key.empty?
+      raise ArgumentError, "name is required" if @name.empty?
+      raise ArgumentError, "content is required" if @content.empty?
+    end
+  end
+end

data/lib/turnkit/store.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Store
+    def create_conversation(_attributes) = raise(NotImplementedError)
+    def load_conversation(_id) = raise(NotImplementedError)
+
+    def next_message_sequence(_conversation_id) = raise(NotImplementedError)
+    def append_message(_attributes) = raise(NotImplementedError)
+    def list_messages(_conversation_id, through_sequence: nil, turn_id: nil) = raise(NotImplementedError)
+
+    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 create_tool_execution(_attributes) = raise(NotImplementedError)
+    def load_tool_execution(_id) = raise(NotImplementedError)
+    def update_tool_execution(_id, _attributes) = raise(NotImplementedError)
+    def list_tool_executions(turn_id:) = raise(NotImplementedError)
+
+    def find_stale_turns(before:) = []
+  end
+end