turnkit 0.2.6 → 0.2.8

data/README.md

@@ -4,7 +4,7 @@
 [![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)
 
-Build durable Ruby AI agents with turns, tools, skills, and Rails persistence.
+Build durable Ruby and Rails agents with tools, skills, sub-agents, and persistence.
 
 ## Installation
 
@@ -20,23 +20,16 @@ Run:
 bundle install
 ```
 
+Upgrading from an earlier TurnKit version? See the [Upgrade Guide](UPGRADE.md).
+
 ## Quick Start
 
-Set a provider key. TurnKit uses RubyLLM under the hood and defaults to Anthropic Claude:
+Set an API key:
 
 ```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
@@ -55,73 +48,49 @@ turn = agent.conversation.ask("Explain Ruby blocks in one sentence.")
 puts turn.output_text
 ```
 
-## Usage
-
-### Models
-
-Set the default model:
-
-```ruby
-TurnKit.default_model = "claude-sonnet-4-5"
-```
-
-Use OpenAI:
-
-```sh
-export OPENAI_API_KEY=...
-```
-
-Set an OpenAI model:
+Or run a non-interactive application task:
 
 ```ruby
-TurnKit.default_model = "gpt-4.1-mini"
+run = agent.run("Explain Ruby blocks in one sentence.")
+puts run.output
 ```
 
-Use Gemini:
+## Usage
 
-```sh
-export GEMINI_API_KEY=...
-```
+### Models
 
-Set a Gemini model:
+Set a model:
 
 ```ruby
-TurnKit.default_model = "gemini-2.5-flash"
+TurnKit.model = "gpt-4.1-mini"
 ```
 
-### Thinking
-
-Enable provider reasoning or extended thinking per agent:
+Or configure TurnKit in one place:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "reasoner",
-  model: "claude-sonnet-4-5",
-  thinking: { budget: 4_000 }
-)
+TurnKit.configure do |config|
+  config.model = "gpt-4.1-mini"
+  config.max_spend = 0.25
+  config.max_iterations = 12
+end
 ```
 
-Use effort-based thinking for providers that support it:
+Set the matching key:
 
-```ruby
-agent = TurnKit::Agent.new(
-  name: "reasoner",
-  model: "gemini-2.5-flash",
-  thinking: { effort: :high }
-)
+```sh
+export OPENAI_API_KEY=...
 ```
 
-Override or disable thinking for one turn:
+Use these common providers:
 
-```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.
+| Provider | Key | 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` |
+| OpenRouter | `OPENROUTER_API_KEY` | `openrouter/...` |
 
-When the provider reports reasoning usage, TurnKit records it as `thinking_tokens` and includes it in usage totals and cost calculation.
+Expect `TurnKit::ModelAccessError` for obvious key mistakes.
 
 ### Conversations
 
@@ -132,12 +101,13 @@ agent = TurnKit::Agent.new(
   name: "writer",
   instructions: "Write clear release notes."
 )
+
+conversation = agent.conversation(subject: "v1 launch")
 ```
 
 Add context:
 
 ```ruby
-conversation = agent.conversation(subject: "v1 launch")
 conversation.say("Mention faster tool execution.")
 ```
 
@@ -148,91 +118,146 @@ turn = conversation.run!
 puts turn.output_text
 ```
 
-### Context compaction
+### Application Tasks
 
-TurnKit automatically compacts long conversations. Older messages are summarized for future model calls, while the original transcript remains stored durably.
+Use `Agent#run` when your application is executing a task instead of chatting
+with a user:
 
 ```ruby
-conversation = agent.conversation
-conversation.ask("Work through this long task.")
+agent = TurnKit::Agent.new(
+  name: "lead_classifier",
+  instructions: "Classify leads and return routing data.",
+  output_schema: {
+    type: "object",
+    properties: {
+      priority: { type: "string" },
+      reason: { type: "string" }
+    },
+    required: ["priority", "reason"]
+  },
+  prompt_mode: :task
+)
+
+run = agent.run(
+  "Classify this lead.",
+  input: { company: "Acme", employees: 1_200 }
+)
+
+puts run.output_data
 ```
 
-By default, compaction is enabled and uses the current turn model for the summary call. If a turn runs with `gpt-5`, compaction uses `gpt-5` unless you configure a separate summary model.
+`Agent#run` is a small wrapper over TurnKit's existing conversation and turn
+engine. Existing `conversation.ask` usage is still supported.
 
-Disable compaction globally:
+Prepare a pending run without calling the model:
 
 ```ruby
-TurnKit.compaction = false
+run = agent.run(task: "Classify later.", async: true)
+request = run.preview
+run.run!
 ```
 
-Use a different model for summaries:
+### Fleets
+
+Use a fleet when you want to package a reusable autonomous workflow: one
+task-mode orchestrator, workflow skills, tools, defaults, and guardrails. A
+fleet is not a requirement for multi-agent work; it is the reusable runtime for
+getting from input to output.
 
 ```ruby
-TurnKit.compaction = {
-  model: "gpt-4.1-mini"
-}
+source_grounded_brief = TurnKit::Skill.from_file("app/ai/skills/source_grounded_brief.md")
+
+fleet = TurnKit.fleet(
+  "brief_writer",
+  instructions: "Create source-grounded briefs and verify claims before final output.",
+  skills: [source_grounded_brief],
+  tools: [WebSearch.new, ReadWebPage.new, SaveBrief],
+  max_spend: 0.25,
+  max_iterations: 12,
+  max_tool_executions: 25,
+  compaction: {
+    context_limit: 64_000,
+    threshold: 0.75
+  }
+)
+
+run = fleet.run(
+  "Create a source-grounded brief.",
+  input: { topic: "Rails 8 Solid Queue" }
+)
+
+puts run.output
+puts run.tool_calls.map(&:tool_name)
+puts run.cost.total
 ```
 
-You can also configure the compaction threshold and estimated context limit:
+This keeps the work in a single conversation and uses TurnKit's normal
+model-tool loop:
 
-```ruby
-TurnKit.compaction = {
-  model: "gpt-4.1-mini",
-  threshold: 0.75,
-  context_limit: 128_000
-}
+```text
+model → tool → result → model → tool → result → final
 ```
 
-Configure compaction for one agent:
+`auto_run` is an alias for `run` when you want the name to emphasize autonomous
+execution:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "engineer",
-  model: "gpt-5",
+run = fleet.auto_run(
+  "Create compliant outreach for this account.",
+  input: lead.attributes,
+  max_spend: 0.25,
+  max_iterations: 8,
+  max_tool_executions: 20,
   compaction: {
-    model: "gpt-4.1-mini",
-    threshold: 0.75,
-    context_limit: 128_000
+    context_limit: 64_000,
+    threshold: 0.75
   }
 )
 ```
 
-In this example, normal turns use `gpt-5` and compaction summaries use `gpt-4.1-mini`.
+Reach for separate agents and `sub_agents` only when the isolation is worth the
+extra model calls, such as different models, different tool permissions,
+parallel specialist review, or separate durable child conversations.
 
-Override the model for one manual compaction:
+Use `terminal!` for save or action tools that complete the run:
 
 ```ruby
-conversation.compact!(model: "gpt-4.1-mini")
-conversation.compact!(focus: "billing migration", model: "gpt-4.1-mini")
-```
+class SaveBrief < TurnKit::Tool
+  description "Save the final brief."
+  parameter :title, :string, required: true
+  parameter :body, :string, required: true
 
-Disable compaction for a single turn:
+  terminal! { |result| "Saved #{result.fetch("id")}." }
 
-```ruby
-conversation.ask("Continue", compact: false)
+  def call(title:, body:, context:)
+    Brief.create!(title: title, body: body).then { |brief| { id: brief.id } }
+  end
+end
 ```
 
-Manually compact a conversation:
+### Prompt Preview
+
+Preview a pending turn:
 
 ```ruby
-conversation.compact!
-conversation.compact!(focus: "billing migration")
+turn = conversation.ask("Draft the launch email.", async: true)
+request = turn.preview
 ```
 
-Compaction is append-only: TurnKit stores a `context_summary` message with metadata describing the message range it replaces for model projection. The original messages are not deleted, so `conversation.messages` remains the full durable transcript. Future model calls see a compacted projection that includes a reference-only summary and the recent tail.
-
-The model-visible projection uses a synthetic summary exchange followed by recent messages:
+Inspect the request:
 
-```text
-user: What did we do so far?
-assistant: [CONTEXT COMPACTION — REFERENCE ONLY] ...
-user: latest request
+```ruby
+request.model
+request.messages
+request.tool_names
+request.instructions
+request.report
 ```
 
-For a local smoke test without calling a real provider, run:
+Run the reviewed turn:
 
-```sh
-ruby script/manual_compaction.rb
+```ruby
+turn.run!
 ```
 
 ### Tools
@@ -243,11 +268,15 @@ Create a tool:
 class SaveReport < TurnKit::Tool
   description "Save a report."
   usage_hint "Use when the user asks to persist 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 self.completion_message(result)
+    "Saved #{result.fetch("report_id")}."
+  end
 
   def call(title:, body:, context:)
     { report_id: "rep_1", title: title, body: body }
@@ -255,7 +284,7 @@ class SaveReport < TurnKit::Tool
 end
 ```
 
-Use the tool:
+Register the tool:
 
 ```ruby
 agent = TurnKit::Agent.new(
@@ -265,82 +294,87 @@ agent = TurnKit::Agent.new(
 )
 ```
 
-Ask for tool use:
+Run the tool loop:
 
 ```ruby
 turn = agent.conversation.ask("Save a short status report.")
 puts turn.output_text
 ```
 
-#### Defining application tools
+Rely on TurnKit to validate tools and model-provided arguments.
 
-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`.
+### Structured Output
+
+Define a schema:
 
 ```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."
+schema = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    bullets: {
+      type: "array",
+      items: { type: "string" }
+    }
+  },
+  required: ["title", "bullets"]
+}
+```
 
-      parameter :objective, :string, required: true
-      parameter :search_queries, :array, required: false
+Use structured output:
 
-      def call(objective:, search_queries: nil, context:)
-        ParallelClient.new.web_search(
-          objective: objective,
-          search_queries: search_queries
-        )
-      end
-    end
-  end
-end
+```ruby
+agent = TurnKit::Agent.new(
+  name: "writer",
+  output_schema: schema
+)
+
+turn = agent.conversation.ask("Summarize the launch plan.")
+puts turn.output_data
 ```
 
-Register tool classes on the agent:
+Override the schema per turn:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "researcher",
-  tools: [
-    Assistant::Tools::WebSearch,
-    Assistant::Tools::ReadWebPage
-  ]
+conversation.ask(
+  "Return one decision.",
+  output_schema: {
+    type: "object",
+    properties: {
+      decision: { type: "string" }
+    }
+  }
 )
 ```
 
-#### Tool context
+### Events
 
-Every tool receives a `context:` object. Use it for logging, correlation, persistence, and domain scoping:
+Subscribe globally:
 
 ```ruby
-def call(query:, context:)
-  context.turn       # The TurnKit::Turn being run
-  context.execution  # The TurnKit::ToolExecution for this tool call
-
-  { query: query }
+TurnKit.on_event = ->(event) do
+  Rails.logger.info("turnkit.#{event.type}")
 end
 ```
 
-If your application already uses a `context:` keyword for something else, use `turnkit_context:` instead:
+Subscribe per agent:
 
 ```ruby
-def call(query:, turnkit_context:)
-  { turn_id: turnkit_context.turn.id, query: query }
-end
+agent = TurnKit::Agent.new(
+  name: "helper",
+  on_event: ->(event) { puts event.type }
+)
 ```
 
-#### Tool return values
+Subscribe per turn:
 
-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 }`. |
+```ruby
+turn.run! do |event|
+  puts event.type
+end
+```
 
-Avoid returning arbitrary objects unless you convert them to a plain Hash or Array first.
+Use events for turns, model calls, messages, and tool calls.
 
 ### Skills
 
@@ -370,7 +404,7 @@ writer = TurnKit::Agent.new(
 )
 ```
 
-Delegate to it:
+Register the sub-agent:
 
 ```ruby
 editor = TurnKit::Agent.new(
@@ -386,117 +420,36 @@ turn = editor.conversation.ask("Ask the writer for three headlines.")
 puts turn.output_text
 ```
 
-### Usage and costs
-
-Inspect token usage:
+Use sub-agents for isolated child conversations.
 
-```ruby
-turn.usage.total_tokens
-conversation.usage.total_tokens
-agent.usage.total_tokens
-```
+### Context Compaction
 
-Inspect costs:
+Disable compaction:
 
 ```ruby
-turn.cost.total
-conversation.cost.total
-agent.cost.total
+TurnKit.compaction = false
 ```
 
-Use RubyLLM registry prices by default.
-
-Override model rates:
+Configure compaction:
 
 ```ruby
-TurnKit.cost_rates = {
-  "my-model" => {
-    input: 0.25,
-    output: 1.00,
-    cached_input: 0.05,
-    cache_creation: 0.25
-  }
+TurnKit.compaction = {
+  model: "gpt-4.1-mini",
+  threshold: 0.75,
+  context_limit: 128_000
 }
 ```
 
-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
-```
-
-Disable prompt caching:
-
-```ruby
-TurnKit.prompt_cache = :off
-```
-
-Split custom prompts:
-
-```ruby
-agent = TurnKit::Agent.new(
-  name: "cached",
-  system_prompt: [
-    "Stable instructions and tool guidance.",
-    TurnKit::SystemPrompt::CACHE_BOUNDARY,
-    "Dynamic subject and live context."
-  ].join("\n")
-)
-```
-
-### Custom clients
-
-Create a client:
-
-```ruby
-class MyClient < TurnKit::Client
-  def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
-    TurnKit::Result.new(
-      text: "provider response",
-      model: model,
-      usage: TurnKit::Usage.new(
-        input_tokens: 100,
-        output_tokens: 20,
-        cached_tokens: 80,
-        cache_write_tokens: 100
-      )
-    )
-  end
-end
-```
-
-Use the client:
+Compact manually:
 
 ```ruby
-TurnKit.client = MyClient.new
+conversation.compact!(focus: "billing migration")
 ```
 
-Split cache sections:
+Run the local smoke test:
 
-```ruby
-stable, dynamic = TurnKit::SystemPrompt.split_cache_boundary(instructions)
+```sh
+ruby script/manual_compaction.rb
 ```
 
 ### Rails
@@ -507,47 +460,18 @@ Install Rails persistence:
 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
 bin/rails db:migrate
 ```
 
-Configure Rails:
-
-```ruby
-TurnKit.store = TurnKit::ActiveRecordStore.new
-```
-
-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:
+Use this layout:
 
 ```text
-app/ai/
-  tools/
-  skills/
-  prompts/
+app/ai/agents/
+app/ai/tools/
+app/ai/skills/
 ```
 
 Reconcile stale turns:
@@ -556,114 +480,63 @@ Reconcile stale turns:
 TurnKit.reconcile_stale!
 ```
 
-#### Debugging Rails persistence
-
-Inspect the latest persisted turn in a Rails console:
+## Options
 
-```ruby
-turn = Turnkit::Turn.order(created_at: :desc).first
-turn.status
-turn.error
-turn.output_text
-```
+| Option | Description |
+| --- | --- |
+| `TurnKit.default_model` | Set the default model. |
+| `TurnKit.client` | Set the model client. |
+| `TurnKit.store` | Set the persistence store. |
+| `TurnKit.max_iterations` | Limit model loop iterations. |
+| `TurnKit.max_depth` | Limit sub-agent depth. |
+| `TurnKit.max_tool_executions` | Limit tool calls per turn. |
+| `TurnKit.timeout` | Limit turn runtime. |
+| `TurnKit.cost_limit` | Limit estimated turn cost. |
+| `TurnKit.compaction` | Configure context compaction. |
+| `TurnKit.on_event` | Subscribe to lifecycle events. |
 
-Check whether the model actually called tools:
+Set options globally:
 
 ```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
-    }
-  }
+TurnKit.default_model = "gpt-4.1-mini"
+TurnKit.max_iterations = 25
+TurnKit.timeout = 300
 ```
 
-#### Live smoke test
-
-Use a model whose provider key is configured, then run a real tool-using turn:
+Set options per agent:
 
 ```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."
+  name: "engineer",
+  model: "gpt-4.1-mini",
+  max_iterations: 10,
+  max_depth: 2
 )
-
-puts turn.output_text
-
-pp Turnkit::ToolExecution
-  .where(turn_uid: turn.id)
-  .order(:created_at)
-  .pluck(:tool_name, :status, :error)
 ```
 
-## Options
-
-Configure defaults:
+Enable thinking:
 
 ```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
-TurnKit.cost_rates = {}
-TurnKit.cost_calculator = nil
-TurnKit.prompt_cache = :auto
-TurnKit.compaction = true
+agent = TurnKit::Agent.new(
+  name: "reasoner",
+  model: "claude-sonnet-4-5",
+  thinking: { budget: 4_000 }
+)
 ```
 
-Override an agent:
+## Upgrading
+
+Add `output_data` for structured output persistence.
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "analyst",
-  model: "gpt-4.1-mini",
-  max_iterations: 10,
-  timeout: 60,
-  cost_limit: 0.25,
-  thinking: { effort: :low }
-)
+add_column :turnkit_turns, :output_data, :json
 ```
 
-| Option | Description |
-| --- | --- |
-| `default_model` | Set the default RubyLLM model. |
-| `client` | Set the model client. |
-| `store` | Set the conversation store. |
-| `max_iterations` | Limit model calls per turn. |
-| `timeout` | Limit seconds per root turn. |
-| `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. |
-| `compaction` | Enable, disable, or configure automatic context compaction. |
+Skip this step for new installs.
 
 ## Contributing
 
-Report bugs and open pull requests on GitHub:
-
-```text
-https://github.com/samuelcouch/turnkit
-```
+Fork the project.
 
 Run tests:
 
@@ -671,6 +544,14 @@ Run tests:
 bundle exec rake test
 ```
 
+Run syntax checks:
+
+```sh
+find lib test examples -type f -name '*.rb' -print0 | xargs -0 ruby -c
+```
+
+Open a pull request.
+
 ## License
 
-See the MIT License.
+Use this gem under the MIT License.