ruby_llm-modes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b5c39593331641f16a7a0f41b3467091e82f4aad359be7be1aa96a9a07074094
+  data.tar.gz: b075c2888ddae01f0197e76893be2c04c8ead01c9362395f55f011e6407d3db5
+SHA512:
+  metadata.gz: 8f42966bb7c51173c3326170a1d1d0eda2364964ae4ebd69b05184726127497d1ab6a489ec341bde98d7d20f92a55e686378d089ffa04e187e6d6a7c269ac55d
+  data.tar.gz: ec5b553284f1c6ff88c6295e82ab7ea0592d3831c02e8b2441258690ae375d0a118359aee4a89d83978c5dd6efa4e8fac3c28cd06bb080cdf85e8c0817e13943

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- `RubyLLM::Modes::Mode` with `description` and `mode_name`, and
+  `RubyLLM::ModeAgent`, an Agent with Mode extended. A mode that declares
+  no `description` reads `app/prompts/<agent path>/description.txt.erb`,
+  following Agent's convention for `instructions`.
+- `Mode#instructions` defaults to `append: true, persist: false`, for the
+  conventional `instructions.txt.erb` template as well: a mode's prompt
+  follows the chat's own and stays out of a Rails record's history, so the
+  call site is `route.mode.complete`.
+- `RubyLLM::Modes::Router` with the declaration DSL (`inputs`, `mode`,
+  `instructions`, `history`, `fallback`, `classify_with`, `on_error`),
+  inheritance that copies declarations, validation in `new`, availability
+  via `if:`, `route(chat)`, `force(name, chat:)`, and the ordered outcome
+  table. `route` reads the chat with `each` and routes the last non-system
+  entry, which must be a user message. History keeps nonblank user/assistant
+  text and plain strings, excluding tool results and metadata before
+  applying `history last: n` / `history :all`. Assistant text is kept even
+  alongside tool calls.
+- `Router#route(chat, messages: transcript)` accepts a custom transcript
+  with the same formats, filtering, and limits. The route and its agent
+  stay bound to `chat`.
+- `Registration` value objects: what `Router#modes` returns and what a
+  classifier receives as `modes:`.
+- `Decision` and `Route` value objects; `Route#decided_by` (`:caller`,
+  `:classifier`, `:fallback`), `Route#duration_ms`, and `to_h` on both with
+  the field names as string keys, for logs.
+- `Route#chat` is the chat the route was decided for; `Route#mode` builds
+  the mode's agent on it with the router's inputs as the agent's `inputs:`;
+  `Route#mode_class` is the class.
+- `Router.instructions` mirrors `Agent.instructions`: a string, a block, or
+  the conventional template `app/prompts/<router_path>/instructions.txt.erb`
+  with keyword locals; `prompt(name, **locals)` inside a block renders a
+  template from the same directory.
+- The `:chat` classifier backend with the built-in routing frame, the
+  selection schema, and `chat_factory:`.
+- `DeclarationError`, `UnknownMode` (a `KeyError`), and `ContractError`.
+- The `:judge` classifier backend on `RubyLLM.judge`: one `choice` question
+  over the modes, `confidence` as the concentration of the probability
+  distribution, `provider:` and `judge:` options. A RubyLLM release without
+  `RubyLLM.judge` rejects the backend at `new` unless `judge:` is given.
+- A classifier that responds to `trace` is traced by its own answer.
+- `truncate message:, history_entry:` caps, in characters, what reaches any
+  classifier: the message keeps its head and tail, each history entry its
+  head, with a marker for the cut. Defaults 30,000 and 2,000; `nil`
+  disables a cap. Jev rejects a request over about 170k characters.
+- The `Classifier failed` reason carries the first line of the exception's
+  message after the class, so a provider's error body reaches the logged
+  route.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Samsonov
+
+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,268 @@
+# RubyLLM::Modes
+
+[![Gem Version](https://img.shields.io/gem/v/ruby_llm-modes.svg)](https://rubygems.org/gems/ruby_llm-modes)
+[![CI](https://github.com/kryzhovnik/ruby_llm-modes/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/kryzhovnik/ruby_llm-modes/actions/workflows/ci.yml)
+[![Ruby >= 3.2](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](#installation)
+
+One chat, many modes: a cheap classifier picks the configuration of each turn before the answer.
+
+Two messages in the same chat can need different configurations. A question about sizes calls for a quick answer; returning a jacket needs order lookup, return tools, and more time. With one configuration for both, every turn carries every tool description and uses the same model and effort level. Similar tools compete, and the choice of what to do stays inside the answering model, where you cannot log or test it separately.
+
+![Two turns in an expanded support chat. With one configuration, both turns carry Help, Returns, Orders, and Escalation instructions and tools. With modes, each turn carries only its selected mode. The earlier conversation remains available.](assets/one-configuration-vs-modes.svg)
+
+*The diagram shows an expanded support router; the example below keeps two modes.*
+
+A **mode** is a named configuration of one turn: instructions, tools, model, thinking. All modes share one history. Before each answer a small classifier reads the latest user message and a window of history and answers one cheap question: *which mode should take this turn?* The model that answers never sees another mode's tools or instructions. The decision is a value you can log and test: which mode, why, and what the classifier actually said. A judgment model or a small chat model answers the question in a fraction of a second, for less than the full toolset costs on every turn.
+
+```ruby
+class HelpAgent < RubyLLM::ModeAgent
+  description "Answers questions about delivery, payment, sizes, and store policy."
+  thinking effort: :low
+  # instructions from app/prompts/help_agent/instructions.txt.erb
+end
+
+class ReturnsAgent < RubyLLM::ModeAgent
+  description "Returns, exchanges, and refunds for an order the customer already has."
+  tools FindOrder, CreateReturn
+  thinking effort: :high
+end
+
+class SupportRouter < RubyLLM::Modes::Router
+  mode HelpAgent
+  mode ReturnsAgent
+  fallback HelpAgent, below_confidence: 0.6
+  classify_with :judge
+end
+
+chat.ask_later("The jacket is too small, I want to send it back")
+route = SupportRouter.new.route(chat)
+route.mode.complete
+
+route.to_h
+# {
+#   "mode_name" => "returns",
+#   "decided_by" => "classifier",
+#   "reason" => nil,
+#   "decision" => {
+#     "mode_name" => "returns",
+#     "confidence" => 0.88,
+#     "reason" => nil,
+#     "probabilities" => { "help" => 0.06, "returns" => 0.94 }
+#   },
+#   "duration_ms" => 351,
+#   "classifier" => { "with" => "judge", "model" => "jev-1.13.0" }
+# }
+```
+
+## Installation
+
+```ruby
+gem "ruby_llm-modes"
+```
+
+Requires [RubyLLM](https://rubyllm.com) 2.0 or newer and Ruby 3.2 or newer.
+
+The `:judge` example above currently requires RubyLLM from its `main` branch; RubyLLM 2.0.0 supports `:chat`.
+
+## Modes
+
+A mode is a `RubyLLM::Agent` with a `description`. Subclass `RubyLLM::ModeAgent`, or extend `RubyLLM::Modes::Mode` into your own agent base class.
+
+```ruby
+class HelpAgent < RubyLLM::ModeAgent
+  description <<~TEXT
+    Answers questions about delivery, payment, sizes, and store policy.
+    No account access: a question about a specific order is not for this mode.
+  TEXT
+
+  thinking effort: :low
+end
+
+class ReturnsAndExchangesAgent < RubyLLM::ModeAgent
+  description "Returns, exchanges, and refunds for an order the customer already has. Only when the customer asks for one."
+  mode_name "returns"        # optional; default derived from the class name
+
+  tools FindOrder, CreateReturn, ExchangeItem
+  thinking effort: :high
+end
+```
+
+`description` tells the router what the mode does and when to pick it, as a Tool's `description` tells the model when to call the tool. `instructions` are for the model that answers, and the router never reads them. Write the description from the customer's side: what they ask for, and what is not for this mode.
+
+A mode that declares no `description` reads `app/prompts/help_agent/description.txt.erb`, rendered without locals: the convention Agent has for `instructions`, applied to the other text. The router resolves each description when its `mode` declaration runs.
+
+The default `mode_name` is the class name with the trailing `Agent` removed, namespaces kept, underscored: `HelpAgent` is `"help"`, `Support::HelpAgent` is `"support/help"`. Neither `description` nor `mode_name` is inherited.
+
+A mode takes one turn of a chat that already has its own system prompt, so `instructions` in a mode defaults to `append: true, persist: false`: the mode's prompt follows the chat's and stays out of a Rails record's stored history. Declare either option to override. The defaults apply to the prompt file as well as to an explicit declaration.
+
+One of the modes can be for clarifying questions: a short prompt, low effort, no tools, and a description like "Asks one question when the request is ambiguous on its own." It is not the fallback. The fallback takes the turn when the classifier could not choose; the clarifying mode is what the classifier chooses confidently when asking is the right answer.
+
+## The declaration
+
+```ruby
+class SupportRouter < RubyLLM::Modes::Router
+  inputs :customer, :order                  # runtime context, as in Agent
+
+  mode HelpAgent                            # description from the class
+  mode ClarifyAgent
+  mode ReturnsAndExchangesAgent
+  mode OrdersAgent, "Order status, tracking, and delivery dates"   # inline description wins
+  mode ConciergeAgent, if: -> { customer.vip? }                    # availability per call
+  mode Support::EscalationAgent, as: :escalate                     # registration name
+
+  instructions do                           # optional; string, block, or template
+    text = "Route by what the customer wants done now."
+    text += "\nThe customer is looking at order #{order.number}." if order
+    text
+  end
+
+  history last: 6                           # optional; default: all given
+  truncate message: 30_000, history_entry: 2_000   # optional; these are the defaults
+  fallback HelpAgent, below_confidence: 0.6
+  classify_with :chat, model: "gemini-3.5-flash-lite"
+  on_error { |error| Rails.error.report(error, handled: true) }   # optional
+end
+```
+
+- `inputs` are required keywords of `new` (`order: nil` counts as passed) and become methods inside `if:` and `instructions` blocks.
+- `instructions` takes the same forms as in an Agent: a string, a block, or the conventional `app/prompts/support_router/instructions.txt.erb` template with keyword locals. It resolves on the router instance, and every backend receives the same string.
+- `history last: n` keeps the last `n` history entries after filtering. `history :all` is the default; it lets a subclass undo an inherited `last:`.
+- `truncate` cuts the routed message to its first and last half and each history entry to its head, with a marker for the cut. `nil` disables a cap. Keep `entries × history_entry + message` under your provider's request limit.
+- `fallback` is the mode used whenever the classifier is ignored (see the [outcome table](#outcomes)). Pass no threshold to accept any confidence.
+- Subclassing copies the declarations. `mode` appends to the inherited list; the other macros replace.
+
+The declaration is validated when the router is built with `new`; every problem raises `DeclarationError`.
+
+## Routing a turn
+
+By default, the router reads the conversation from the chat itself. Stage the user's message with `ask_later` (RubyLLM's `ask` is `ask_later` followed by `complete`), route, then let the mode complete the turn:
+
+```ruby
+router = SupportRouter.new(customer: current_customer, order: current_order)
+router.modes                    # modes available for this call
+
+chat.ask_later(text)            # a RubyLLM::Chat, or a Rails chat record
+route = router.route(chat)
+route.mode.complete
+```
+
+`route` reads messages with `each`, as supported by `RubyLLM::Chat`, Rails chat records, and agents. Entries can be `RubyLLM::Message` objects, records responding to `to_llm`, `{ role:, content: }` hashes, or plain strings in history. The last entry after removing system messages must be a user message (`ArgumentError` otherwise). It becomes the routed message.
+
+History keeps only nonblank user/assistant text and plain strings. Assistant text is kept even alongside tool calls; tool results and metadata are excluded. Filtering happens before `history last:` and `truncate`. The classifier is skipped when only the fallback mode is available.
+
+Pass `messages:` for a custom transcript: text extracted from JSON or UI cards, relevant tool state, or a snapshot ending at the current user message. The router cannot infer UI visibility; remove internal user/assistant text here.
+
+```ruby
+route = router.route(chat, messages: transcript)
+route.mode.complete
+```
+
+`messages:` uses the same formats, filtering, and limits. Include extra context as user/assistant text or plain strings. It can be combined with `classifier:`. Only the classifier reads this transcript; `route.chat` and the answering agent still use the original chat.
+
+Omit `messages:` to read the chat. Passing `messages: nil` raises `ArgumentError`; it does not select the default. If an optional transcript uses `nil` to mean "read the chat", pass `messages: transcript || chat`.
+
+`force` is for the turns the app has already decided, such as a button that starts a mode by name: no classifier runs and no messages are read, `if:` still applies, and the result is a `Route` like any other. It raises `UnknownMode` when the name is not available.
+
+```ruby
+route = router.force("returns", chat:)      # the customer pressed "Return an item"
+```
+
+## Applying a mode
+
+`route.mode` is the mode's `Agent.new(chat: route.chat, inputs: route.inputs)`: it configures the chat the route was decided for and returns the agent wrapping it. The agent takes the inputs it declared and ignores the rest. Extra keywords go to `Agent.new` as given: `route.mode(session:)`. A `chat:` keyword is refused: the route is bound to its chat.
+
+```ruby
+route.mode.complete
+```
+
+Run the turn through the agent, not the chat, so the agent's `rescue_from` handlers apply. Agent's constructor **adds** configuration to the chat, so call `mode` once per turn: mode instructions append to the system prompt; tools, schema, and thinking are set only when the mode declares them. A chat built for the turn (a Rails chat record, or a fresh `RubyLLM.chat`) needs nothing else. A chat object reused across turns keeps the previous mode's configuration and needs a reset before the next mode.
+
+## Backends and what `confidence` means
+
+### `:chat`
+
+One structured-output turn on `RubyLLM.chat(model:)`. The system prompt is a fixed frame around your `instructions`, the modes, and the conversation; the latest message is the user turn. The model returns `mode` (an enum of the available names), `confidence`, and `reason`.
+
+`confidence` is the model's **self-report** from 0 to 1. It tells a hedge from a clear call, but it is not calibrated, and its scale depends on the model. Tune `below_confidence` per model from your logs, and do not carry a threshold from one backend to another.
+
+`chat_factory: ->(model:) { ... }` replaces the chat constructor. The frame is not configurable: subclass `RubyLLM::Modes::Classifiers::Chat` and override `self.prompt`, or plug a custom classifier.
+
+### `:judge`
+
+One `RubyLLM.judge` call with a single `choice` question whose options are the modes and their descriptions. The answer is a probability per mode: the decision's `mode_name` is the most likely one and `probabilities` carries the distribution.
+
+`confidence` comes from the judgment model with the distribution and reflects how **concentrated** it is on one mode, not a self-report. The gem passes it through as is. There is no free text, so `reason` is nil and a clarification has to be a mode of its own.
+
+`model:` and `provider:` are passed to `RubyLLM.judge` as given; without them RubyLLM's defaults apply. `judge:` replaces `RubyLLM.judge` with any callable taking the same arguments and returning a `RubyLLM::Judgment`. `RubyLLM.judge` is not in ruby_llm 2.0.0; it is on RubyLLM's main branch. On a release without it, `classify_with :judge` raises `DeclarationError` unless `judge:` is given.
+
+## Custom classifiers
+
+A classifier is any object with this method:
+
+```ruby
+class KeywordClassifier
+  def call(message:, history:, modes:, instructions:, inputs:)
+    name = modes.map(&:name).find { |candidate| message.downcase.include?(candidate) }
+    RubyLLM::Modes::Decision.new(mode_name: name, confidence: name ? 1.0 : nil, reason: "keyword match")
+  end
+end
+
+classify_with KeywordClassifier.new
+```
+
+A class is accepted only if the class itself responds to `call`; the router never calls `new`. Pass `classifier:` to `route` to replace the declared backend for one call, for tests or shadow runs:
+
+```ruby
+router.route(chat, classifier: FakeClassifier.new(decision))
+```
+
+## Reference
+
+### Classifier contract
+
+`call(message:, history:, modes:, instructions:, inputs:)` returns a `Decision`.
+
+- `message` is the content of the routed message, cut to the `truncate` cap.
+- `history` is `[{ role:, content: }]`: the filtered history after `history last:` and `truncate`. Plain strings have `role: nil`.
+- `modes` is what `router.modes` returns: the modes available on this call, each responding to `name`, `description`, and `klass`.
+- `instructions` is the resolved string or nil; `inputs` is the hash passed to `new`.
+- `Decision`: `mode_name` is a String or nil, `confidence` a number from 0 to 1 or nil for "not scored", `reason` and `probabilities` optional. Anything else is a `ContractError` and routes to the fallback.
+- A classifier responding to `trace` is traced by its own `{ with:, model: }`; otherwise as `{ with: "custom", model: nil }`.
+
+### Route
+
+| Field         | Value                                                        |
+|---------------|--------------------------------------------------------------|
+| `mode_class`  | the agent class                                              |
+| `mode_name`   | its registration name                                        |
+| `decided_by`  | `:caller`, `:classifier`, or `:fallback`                  |
+| `reason`      | why this mode (see below)                                    |
+| `decision`    | the classifier's `Decision`, or nil when none ran            |
+| `duration_ms` | classifier time, nil on caller-decided routes                |
+| `classifier`  | `{ with:, model: }`, or nil when no backend was called       |
+
+`route.chat` is the chat the route was decided for, `route.error` the exception a failed classifier raised, and `route.inputs` the router's inputs; `route.mode(**options)` is `mode_class.new(chat:, inputs:, **options)`. `to_h` is the fields above with string keys and `decided_by` as a string, minus `mode_class`; `Decision#to_h` has string keys and omits `probabilities` when nil.
+
+### Outcomes
+
+The route is decided by the first rule that applies:
+
+| Situation                                     | decided_by     | reason                                 |
+|-----------------------------------------------|----------------|----------------------------------------|
+| `force(name, chat:)`                          | `:caller`     | `"Mode requested by caller"`           |
+| only the fallback is available                | `:fallback`   | `"No other mode available"`            |
+| classifier raised, or violated the contract   | `:fallback`   | `"Classifier failed: <class>: <message>"` |
+| decision names an unknown or unavailable mode | `:fallback`   | `"Unknown mode <name>"`                |
+| threshold on, confidence nil                  | `:fallback`   | `"Confidence not scored"`              |
+| threshold on, confidence below it             | `:fallback`   | `"Below confidence threshold"`         |
+| otherwise                                     | `:classifier` | the decision's reason                  |
+
+`<message>` is the first line of the exception's message, cut at 200 characters, so a provider's error body reaches the log.
+
+### Errors
+
+`Router.new` raises `DeclarationError` for any problem in the declaration and says which. `route` raises `ArgumentError` when the chat has no user message to route; `force` raises `UnknownMode`, a `KeyError`. A classifier that raised, or broke the contract (a `ContractError`), does not fail the turn: the route falls back and the exception is on `route.error`. To fail instead, raise from `on_error`; whatever the handler raises escapes `route`. An exception from an `instructions` block or template is a declaration bug and escapes `route` as well.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/assets/one-configuration-vs-modes.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="530" viewBox="0 0 980 530" role="img" aria-labelledby="title desc">
+  <title id="title">Context sent with one configuration and with modes</title>
+  <desc id="desc">Two turns in an expanded support chat. Each horizontal bar represents the total input context for one turn: instructions, tool declarations, earlier messages, and the new user message. Without modes, one prompt contains sections for Help, Returns, Orders, and Escalation, separated by dashed lines, followed by the tools for all modes. With modes, each turn includes only the selected mode's instructions and tools. The second turn's history contains the complete earlier user message and reply. Widths are illustrative.</desc>
+  <defs>
+    <style>
+      text { font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #17212f; }
+      .heading { font-size: 21px; font-weight: 700; }
+      .subtitle, .note { font-size: 14px; fill: #475569; }
+      .message { font-size: 15px; }
+      .route { font-size: 13px; font-weight: 600; fill: #1d4ed8; }
+      .cell-label { font-size: 12px; font-weight: 600; }
+      .outline { stroke: #64748b; stroke-width: 1; }
+      .divider { stroke: #64748b; stroke-width: 1.2; stroke-dasharray: 4 3; }
+    </style>
+    <g id="all-instructions">
+      <rect width="405" height="34" fill="#dbeafe" class="outline"/>
+      <rect width="50" height="34" fill="#bfdbfe"/>
+      <line x1="50" y1="3" x2="50" y2="31" class="divider"/>
+      <line x1="125" y1="3" x2="125" y2="31" class="divider"/>
+      <line x1="220" y1="3" x2="220" y2="31" class="divider"/>
+      <line x1="305" y1="3" x2="305" y2="31" class="divider"/>
+      <text x="25" y="22" text-anchor="middle" class="cell-label">Base</text>
+      <text x="87.5" y="22" text-anchor="middle" class="cell-label">Help</text>
+      <text x="172.5" y="22" text-anchor="middle" class="cell-label">Returns</text>
+      <text x="262.5" y="22" text-anchor="middle" class="cell-label">Orders</text>
+      <text x="355" y="22" text-anchor="middle" class="cell-label">Escalation</text>
+    </g>
+    <g id="all-tools">
+      <rect width="18" height="34" fill="#fde68a" class="outline"/>
+      <rect x="18" width="25" height="34" fill="#fde68a" class="outline"/>
+      <rect x="43" width="22" height="34" fill="#fde68a" class="outline"/>
+      <rect x="65" width="28" height="34" fill="#fde68a" class="outline"/>
+      <rect x="93" width="19" height="34" fill="#fde68a" class="outline"/>
+    </g>
+    <g id="help-config">
+      <rect width="50" height="34" fill="#bfdbfe" class="outline"/>
+      <rect x="50" width="75" height="34" fill="#dbeafe" class="outline"/>
+      <text x="25" y="22" text-anchor="middle" class="cell-label">Base</text>
+      <text x="87.5" y="22" text-anchor="middle" class="cell-label">Help</text>
+    </g>
+    <g id="returns-config">
+      <rect width="50" height="34" fill="#bfdbfe" class="outline"/>
+      <rect x="50" width="95" height="34" fill="#dbeafe" class="outline"/>
+      <rect x="145" width="18" height="34" fill="#fde68a" class="outline"/>
+      <rect x="163" width="25" height="34" fill="#fde68a" class="outline"/>
+      <text x="25" y="22" text-anchor="middle" class="cell-label">Base</text>
+      <text x="97.5" y="22" text-anchor="middle" class="cell-label">Returns</text>
+    </g>
+    <g id="first-message">
+      <rect width="120" height="34" fill="#334155" class="outline"/>
+      <text x="60" y="22" text-anchor="middle" class="cell-label" style="fill:#fff">New user</text>
+    </g>
+    <g id="second-message">
+      <rect width="200" height="34" fill="#e2e8f0" class="outline"/>
+      <rect x="200" width="180" height="34" fill="#334155" class="outline"/>
+      <text x="100" y="22" text-anchor="middle" class="cell-label">History</text>
+      <text x="290" y="22" text-anchor="middle" class="cell-label" style="fill:#fff">New user</text>
+    </g>
+  </defs>
+  <rect width="980" height="530" fill="#fff"/>
+  <text x="32" y="38" class="heading">One configuration</text>
+  <text x="32" y="61" class="subtitle">One prompt covers every mode; all tools are sent on every turn</text>
+
+  <text x="32" y="103" class="message">“What sizes do you have?”</text>
+  <use href="#all-instructions" x="32" y="114"/>
+  <use href="#all-tools" x="437" y="114"/>
+  <use href="#first-message" x="549" y="114"/>
+
+  <text x="32" y="184" class="message">“The jacket is too small, I want to send it back”</text>
+  <use href="#all-instructions" x="32" y="195"/>
+  <use href="#all-tools" x="437" y="195"/>
+  <use href="#second-message" x="549" y="195"/>
+
+  <line x1="32" y1="260" x2="929" y2="260" stroke="#cbd5e1"/>
+  <text x="32" y="299" class="heading">With modes</text>
+  <text x="32" y="322" class="subtitle">Only the selected mode's instructions and tools are sent</text>
+
+  <text x="32" y="364" class="message">“What sizes do you have?”</text>
+  <text x="258" y="364" class="route">router → help</text>
+  <use href="#help-config" x="32" y="375"/>
+  <use href="#first-message" x="157" y="375"/>
+
+  <text x="32" y="445" class="message">“The jacket is too small, I want to send it back”</text>
+  <text x="436" y="445" class="route">router → returns</text>
+  <use href="#returns-config" x="32" y="456"/>
+  <use href="#second-message" x="220" y="456"/>
+
+  <text x="32" y="513" class="note">Total context, shown schematically. Yellow blocks are separate tool declarations; gray blocks are history.</text>
+</svg>

data/lib/ruby_llm/mode_agent.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A RubyLLM::Agent that is routable: subclass it and declare a
+  # description. Its instructions append to the chat's system prompt
+  # and are not persisted (see Modes::Mode). Apps with their own agent base
+  # class extend RubyLLM::Modes::Mode into that base instead.
+  class ModeAgent < Agent
+    extend Modes::Mode
+  end
+end

data/lib/ruby_llm/modes/classifiers/chat.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Modes
+    module Classifiers
+      # The +:chat+ backend: one structured-output turn on a RubyLLM chat.
+      #
+      # The system prompt is the built-in frame (Chat.prompt): the router's
+      # instructions, the modes, and the conversation.
+      # +chat_factory:+ replaces RubyLLM.chat; it is called with +model:+
+      # and must return a chat. +confidence+ is the model's self-report.
+      #
+      # Any object with the same +call+ signature is a valid classifier:
+      #
+      #   call(message:, history:, modes:, instructions:, inputs:) # => Decision
+      #
+      class Chat
+        FRAME_HEAD = <<~TEXT.strip
+          You route the latest user message to one of the modes below.
+          Choose exactly one. Use the conversation only to understand what the
+          latest message refers to. Do not answer the user.
+        TEXT
+
+        FRAME_TAIL = "Return the structured selection: mode, confidence from 0 to 1, reason."
+
+        attr_reader :model, :chat_factory
+
+        def initialize(model: nil, chat_factory: nil)
+          @model = model
+          @chat_factory = chat_factory
+        end
+
+        def call(message:, history:, modes:, instructions:, inputs:)
+          @resolved_model = nil
+          text = self.class.prompt(message:, history:, modes:, instructions:)
+          chat = build_chat
+          response = chat.with_instructions(text).with_schema(self.class.schema_for(modes)).ask(message)
+          decision_from(response)
+        end
+
+        # What ran, for Route#classifier: the resolved model id once a chat
+        # was built, else the declared model.
+        def trace
+          { with: "chat", model: @resolved_model || model }
+        end
+
+        # The system prompt for +modes+ (Registration values) and the
+        # normalised +history+, with the router's +instructions+ between
+        # the frame and the modes. The latest +message+ is the user turn,
+        # so it is not repeated here.
+        def self.prompt(message:, history:, modes:, instructions: nil)
+          sections = [ FRAME_HEAD ]
+          sections << instructions unless instructions.nil? || instructions.empty?
+          sections << "Modes:\n#{modes.map { |mode| "- #{mode.name}: #{indent(mode.description)}" }.join("\n")}"
+          sections << "Conversation:\n#{history.map { |entry| transcript_line(entry) }.join("\n")}" if history.any?
+          sections << FRAME_TAIL
+          sections.join("\n\n")
+        end
+
+        # The selection schema: +mode+ is an enum of the available names.
+        def self.schema_for(modes)
+          names = modes.map(&:name)
+          Schematist::Schema.create do
+            string :mode, enum: names
+            number :confidence, minimum: 0, maximum: 1
+            string :reason
+          end
+        end
+
+        def self.indent(description)
+          description.to_s.lines.map(&:chomp).join("\n  ")
+        end
+
+        def self.transcript_line(entry)
+          entry[:role] ? "#{entry[:role]}: #{entry[:content]}" : entry[:content].to_s
+        end
+
+        private_class_method :indent, :transcript_line
+
+        private
+
+        # The trace is plain data for logs, so only a String model id is
+        # kept: a stand-in chat that answers every message with itself must
+        # not end up serialised into a route.
+        def build_chat
+          chat = chat_factory ? chat_factory.call(model: model) : RubyLLM.chat(model: model)
+          resolved = chat.model.id if chat.respond_to?(:model) && chat.model.respond_to?(:id)
+          @resolved_model = resolved if resolved.is_a?(String)
+          chat
+        end
+
+        def decision_from(response)
+          selection = response.parsed
+          raise ContractError, "chat backend returned #{selection.class}, expected a JSON object" unless selection.is_a?(Hash)
+
+          confidence = selection["confidence"]
+          Decision.new(
+            mode_name: selection["mode"]&.to_s,
+            confidence: confidence.is_a?(Numeric) ? confidence.to_f : confidence,
+            reason: selection["reason"]&.to_s,
+            probabilities: nil
+          )
+        end
+      end
+    end
+  end
+end