turnkit 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aec304178bd79782515aaacd238e19de0556e64947406f14cdc8d6ccf05f71b
-  data.tar.gz: 92691d763c7cc007fb5cde9b9af2fbc28c69db9078b334f6b9a10892971a4644
+  metadata.gz: 5eaf1e8d25237f97b607cf5a1c80fced59e8e737cd4cdbf3a9d6dca61227b19b
+  data.tar.gz: da3cc66e95e3ce0ec5df6fbc8b051fc0f6750a0c2175d0cdc09f8eb4dc4ef96e
 SHA512:
-  metadata.gz: ab078a5e371c67774b9232ef90f3726fb630f1d1b4d13b71cdd09e51263074f9135ab87b9371e31e149b2d982e6ec4dea9950a2cf0fac7677fe334e950bc0071
-  data.tar.gz: c0637c433abbfc2e2c03bdc4632b3416c6596ffa20cc1855d537c68e4b54120033b78a435ffd8a311f9d29f8e0c0ae6f3ca06dd9a75d9a29f26e5a87f173bb78
+  metadata.gz: 9c50e9bd40a36392496a88f202bb5dbda51883c4ae686d8089849c6cb2fef903102efcb2a868617cca80891860849b65140888bc3bf250f620ac8bf9ea61a8e8
+  data.tar.gz: a054d0de8955d20f4d9ac60351507f56e98bf8137828d599ac5681ff593b5039f4d672dc16323f30a700a4f25aef3360fb6f97c64d75ce08f10eedf3fde692c0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 - 2026-06-04
+
+- Add configurable system prompt sections and custom system prompt builders.
+- Add globally and per-agent available skills for prompt guidance.
+- Add skill loading from directories.
+
 ## 0.1.0 - 2026-06-04
 
 - Initial release of TurnKit.

data/README.md

@@ -1,11 +1,10 @@
 # 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.
+Build durable Ruby AI agents with turns, tools, skills, and Rails persistence.
 
 ## Installation
 
@@ -23,12 +22,38 @@ bundle install
 
 ## Quick Start
 
-Set a provider key, then ask an agent:
+Set a provider key:
 
 ```sh
 export ANTHROPIC_API_KEY=...
+# or OPENAI_API_KEY=..., GEMINI_API_KEY=..., OPENROUTER_API_KEY=...
 ```
 
+TurnKit uses RubyLLM by default. Choose the provider by choosing a RubyLLM model name:
+
+```ruby
+TurnKit.default_model = "claude-sonnet-4-5" # Anthropic
+# TurnKit.default_model = "gpt-4.1-mini"    # OpenAI
+# TurnKit.default_model = "gemini-2.5-flash" # Gemini
+```
+
+You can also override the model per agent or per run.
+
+To use a different model SDK, provide a client object that responds to `chat`:
+
+```ruby
+class MyClient < TurnKit::Client
+  def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+    # Call your provider here.
+    TurnKit::Result.new(text: "provider response", model: model)
+  end
+end
+
+TurnKit.client = MyClient.new
+```
+
+Ask an agent:
+
 ```ruby
 require "turnkit"
 
@@ -99,6 +124,55 @@ agent = TurnKit::Agent.new(
 )
 ```
 
+List available skills:
+
+```ruby
+research = TurnKit::Skill.from_file(
+  "skills/research.md",
+  description: "Use for source-backed research tasks."
+)
+
+agent = TurnKit::Agent.new(
+  name: "researcher",
+  instructions: "Prefer primary sources.",
+  tools: [WebSearch, ReadWebPage],
+  available_skills: [research]
+)
+```
+
+Add subject context:
+
+```ruby
+article = Article.find(1)
+conversation = agent.conversation(subject: article)
+```
+
+Choose prompt sections:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "writer",
+  instructions: "Write plainly.",
+  prompt_sections: %i[agent instructions tools environment]
+)
+```
+
+Build a custom prompt:
+
+```ruby
+agent = TurnKit::Agent.new(
+  name: "custom",
+  instructions: "Answer in JSON.",
+  system_prompt: ->(prompt) {
+    [
+      prompt.agent_section,
+      prompt.instructions_section,
+      "Return only valid JSON."
+    ].compact.join("\n\n")
+  }
+)
+```
+
 Delegate to sub-agents:
 
 ```ruby
@@ -126,7 +200,6 @@ 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
@@ -140,7 +213,7 @@ TurnKit.reconcile_stale!
 
 ## Options
 
-Configure defaults globally:
+Configure defaults:
 
 ```ruby
 TurnKit.default_model = "claude-sonnet-4-5"
@@ -163,20 +236,27 @@ agent = TurnKit::Agent.new(
 )
 ```
 
+Override the model for a single conversation or turn:
+
+```ruby
+conversation = agent.conversation(model: "claude-opus-4-1")
+turn = conversation.run!(model: "gpt-4.1-mini")
+```
+
 | 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. |
+| `default_model` | Set the default RubyLLM model. The model name determines the provider. |
+| `client` | Set the model client. Defaults to `TurnKit::Adapters::RubyLLM.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. |
 
 ## Contributing
 
-Open bug reports and pull requests on GitHub:
+Report bugs and open pull requests on GitHub:
 
 ```text
 https://github.com/samuelcouch/turnkit

data/lib/turnkit/agent.rb

@@ -2,10 +2,12 @@
 
 module TurnKit
   class Agent
-    attr_reader :name, :description, :model, :instructions, :tools, :skills, :sub_agents
+    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
 
-    def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], sub_agents: [], client: nil, store: nil,
+    def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
+      system_prompt: nil, prompt_sections: nil, 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
@@ -13,7 +15,10 @@ module TurnKit
       @instructions = instructions.to_s
       @tools = Array(tools)
       @skills = Array(skills)
+      @available_skills = Array(available_skills)
       @sub_agents = Array(sub_agents)
+      @system_prompt = system_prompt
+      @prompt_sections = prompt_sections
       @client = client
       @store = store
       @max_iterations = max_iterations
@@ -51,6 +56,27 @@ module TurnKit
       tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
     end
 
+    def effective_available_skills
+      (Array(TurnKit.available_skills) + available_skills).uniq { |skill| skill.key }
+    end
+
+    def effective_prompt_sections
+      prompt_sections || TurnKit.prompt_sections
+    end
+
+    def system_prompt_for(turn:, conversation:)
+      prompt = SystemPrompt.new(agent: self, turn: turn, conversation: conversation)
+
+      case system_prompt
+      when nil
+        prompt.to_s
+      when String
+        system_prompt
+      else
+        system_prompt.call(prompt).to_s
+      end
+    end
+
     def build_budget(root_started_at: Clock.now)
       Budget.new(
         max_iterations: max_iterations || TurnKit.max_iterations,
@@ -64,9 +90,7 @@ module TurnKit
 
     def instructions_with_skills
       parts = [ instructions ]
-      skills.each do |skill|
-        parts << "## Skill: #{skill.name}\n\n#{skill.content}"
-      end
+      parts << SystemPrompt.loaded_skills_text(skills)
       parts.reject(&:empty?).join("\n\n")
     end
   end

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

@@ -12,3 +12,8 @@ TurnKit.tool_execution_record_class = "Turnkit::ToolExecution"
 # TurnKit.timeout = 300
 # TurnKit.max_depth = 3
 # TurnKit.max_tool_executions = 100
+
+# TurnKit builds each system prompt from these sections by default.
+# TurnKit.prompt_sections = %i[agent instructions behavior loaded_skills available_skills tools subject environment]
+# TurnKit.prompt_behavior = "Custom behavior instructions."
+# TurnKit.available_skills = TurnKit::Skill.from_directory(Rails.root.join("app/ai/skills"))

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

@@ -8,6 +8,8 @@ module TurnKit
     class InstallGenerator < Rails::Generators::Base
       include Rails::Generators::Migration
 
+      namespace "turnkit:install"
+
       source_root File.expand_path("install/templates", __dir__)
 
       class_option :table_prefix, type: :string, default: "turnkit", desc: "Database table prefix."
@@ -28,13 +30,21 @@ module TurnKit
       end
 
       def self.next_migration_number(dirname)
-        if ActiveRecord::Base.timestamped_migrations
+        if timestamped_migrations?
           Time.now.utc.strftime("%Y%m%d%H%M%S")
         else
           "%.3d" % (current_migration_number(dirname) + 1)
         end
       end
 
+      def self.timestamped_migrations?
+        if ActiveRecord.respond_to?(:timestamped_migrations)
+          ActiveRecord.timestamped_migrations
+        else
+          ActiveRecord::Base.timestamped_migrations
+        end
+      end
+
       private
         def table_prefix
           options[:table_prefix]

data/lib/turnkit/skill.rb

@@ -10,6 +10,10 @@ module TurnKit
       new(key: key || base, name: name || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description, content: content)
     end
 
+    def self.from_directory(path, pattern: "*.md")
+      Dir.glob(File.join(path, pattern)).sort.map { |file| from_file(file) }
+    end
+
     def initialize(key:, name:, content:, description: "")
       @key = key.to_s
       @name = name.to_s

data/lib/turnkit/system_prompt.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class SystemPrompt
+    DEFAULT_SECTIONS = %i[agent instructions behavior loaded_skills available_skills tools subject environment].freeze
+    SECTION_METHODS = {
+      agent: :agent_section,
+      instructions: :instructions_section,
+      behavior: :behavior_section,
+      loaded_skills: :loaded_skills_section,
+      available_skills: :available_skills_section,
+      tools: :tools_section,
+      subject: :subject_section,
+      environment: :environment_section
+    }.freeze
+
+    DEFAULT_BEHAVIOR = <<~TEXT.strip
+      Treat each user message as a constraint on the current task. Follow the
+      agent instructions and loaded skills first, then use tools when they are
+      available and needed.
+
+      Use the provided environment as the source of truth for the current date
+      and time. Do not guess relative dates like "today", "tomorrow", or
+      "yesterday" when the environment gives an exact calendar anchor.
+
+      Only use tools listed in <tools_available>. If a tool you want is not
+      listed, it is unavailable for this turn; adjust your answer instead of
+      pretending to call it.
+
+      If a tool returns an error, read the error and fix your inputs before
+      trying again. Do not retry the identical failing call blindly.
+
+      Report outcomes honestly. If you cannot verify something, say so or omit
+      the claim instead of inventing details.
+    TEXT
+
+    attr_reader :agent, :turn, :conversation, :sections
+
+    def initialize(agent:, turn:, conversation:, sections: nil)
+      @agent = agent
+      @turn = turn
+      @conversation = conversation
+      @sections = Array(sections || agent.effective_prompt_sections)
+    end
+
+    def to_s
+      sections.map { |section| render(section) }.compact.reject { |value| value.strip.empty? }.join("\n\n")
+    end
+
+    def render(section)
+      method = SECTION_METHODS[section.to_sym]
+      raise ArgumentError, "unknown prompt section: #{section}" unless method
+
+      public_send(method)
+    end
+
+    def agent_section
+      lines = [
+        "- Name: #{agent.name}",
+        agent.description.empty? ? nil : "- Description: #{agent.description}",
+        "- Model: #{turn.model || agent.effective_model}"
+      ].compact
+
+      tagged("agent", lines.join("\n"))
+    end
+
+    def instructions_section
+      return nil if agent.instructions.empty?
+
+      tagged("instructions", agent.instructions)
+    end
+
+    def behavior_section
+      tagged("behavior", TurnKit.prompt_behavior || DEFAULT_BEHAVIOR)
+    end
+
+    def loaded_skills_section
+      return nil if agent.skills.empty?
+
+      tagged(
+        "skills_loaded",
+        self.class.loaded_skills_text(agent.skills)
+      )
+    end
+
+    def self.loaded_skills_text(skills)
+      skills.map { |skill| "## Skill: #{skill.key}\n\n#{skill.content}" }.join("\n\n")
+    end
+
+    def available_skills_section
+      skills = agent.effective_available_skills
+      return nil if skills.empty?
+
+      entries = skills.map do |skill|
+        description = skill.description.empty? ? nil : " — #{skill.description}"
+        "- #{skill.key}: #{skill.name}#{description}"
+      end
+
+      tagged(
+        "skills_available",
+        "Load or follow a skill when the task matches its description.\n\n#{entries.join("\n")}"
+      )
+    end
+
+    def tools_section
+      tools = agent.effective_tools
+
+      if tools.empty?
+        tagged("tools_available", "(none)\n\nNo tools are available for this turn.")
+      else
+        tagged("tools_available", tools.map { |tool| tool_line(tool) }.join("\n"))
+      end
+    end
+
+    def subject_section
+      return nil unless conversation.subject&.respond_to?(:to_prompt)
+
+      value = conversation.subject.to_prompt.to_s.strip
+      return nil if value.empty?
+
+      tagged("subject_context", value)
+    end
+
+    def environment_section
+      anchor = turn.started_at || Clock.now
+      today = anchor.to_date
+      yesterday = today - 1
+      tomorrow = today + 1
+
+      tagged(
+        "environment",
+        [
+          "- Today: #{today.strftime('%A, %B %-d, %Y')} (#{today.iso8601})",
+          "- Current time: #{anchor.strftime('%-I:%M %Z')}",
+          "- Yesterday: #{yesterday.strftime('%A, %B %-d, %Y')} (#{yesterday.iso8601})",
+          "- Tomorrow: #{tomorrow.strftime('%A, %B %-d, %Y')} (#{tomorrow.iso8601})"
+        ].join("\n")
+      )
+    end
+
+    private
+      def tagged(name, content)
+        "<#{name}>\n#{content}\n</#{name}>"
+      end
+
+      def tool_line(tool)
+        description = tool.description.empty? ? nil : ": #{tool.description}"
+        params = tool.parameters.map do |param|
+          required = param.fetch(:required) ? " required" : ""
+          enum = param[:enum] ? " enum=#{Array(param[:enum]).join('|')}" : ""
+          "#{param.fetch(:name)}(#{param.fetch(:type)}#{required}#{enum})"
+        end
+        suffix = params.empty? ? "" : " Parameters: #{params.join(', ')}."
+        terminal = tool.ends_turn? ? " Ends the turn." : ""
+        "- #{tool.tool_name}#{description}#{suffix}#{terminal}"
+      end
+  end
+end

data/lib/turnkit/turn.rb

@@ -7,6 +7,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 :started_at
 
     def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0)
       @agent = agent
@@ -21,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
+      @started_at = @record["started_at"]
       @budget = budget || agent.build_budget
       @depth = depth
     end
@@ -37,7 +39,7 @@ module TurnKit
           model: model,
           messages: llm_messages,
           tools: agent.effective_tools,
-          instructions: agent.instructions_with_skills,
+          instructions: agent.system_prompt_for(turn: self, conversation: conversation),
           metadata: { turn_id: id, conversation_id: conversation.id }
         )
 
@@ -128,6 +130,9 @@ module TurnKit
 
       def update!(attributes)
         @record = store.update_turn(id, attributes)
+        @started_at = @record["started_at"]
+        @model = @record["model"] || agent.effective_model
+        @record
       end
   end
 

data/lib/turnkit/version.rb

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

data/lib/turnkit.rb

@@ -3,6 +3,7 @@
 require "json"
 require "securerandom"
 require "time"
+require "date"
 
 require_relative "turnkit/version"
 require_relative "turnkit/error"
@@ -16,6 +17,7 @@ require_relative "turnkit/message"
 require_relative "turnkit/record"
 require_relative "turnkit/result"
 require_relative "turnkit/skill"
+require_relative "turnkit/system_prompt"
 require_relative "turnkit/store"
 require_relative "turnkit/memory_store"
 require_relative "turnkit/tool"
@@ -36,6 +38,7 @@ module TurnKit
     attr_accessor :default_model, :client, :store, :logger
     attr_accessor :max_iterations, :timeout, :max_depth, :max_tool_executions
     attr_accessor :cost_limit
+    attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :conversation_record_class, :turn_record_class
     attr_accessor :message_record_class, :tool_execution_record_class
   end
@@ -47,6 +50,8 @@ module TurnKit
   self.timeout = 300
   self.max_depth = 3
   self.max_tool_executions = 100
+  self.prompt_sections = SystemPrompt::DEFAULT_SECTIONS.dup
+  self.available_skills = []
 
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -62,6 +62,7 @@ files:
 - lib/turnkit/store.rb
 - lib/turnkit/stores/active_record_store.rb
 - lib/turnkit/sub_agent_tool.rb
+- lib/turnkit/system_prompt.rb
 - lib/turnkit/tool.rb
 - lib/turnkit/tool_call.rb
 - lib/turnkit/tool_execution.rb