ask-decisions 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eecbf122542bb526917a22123bd02d15ed9aaee01db6c3283024858cbb5a867
-  data.tar.gz: 6192d3b7bab381fe65d3f43119ee836598aa68b2639eae0fb87379b432bd838a
+  metadata.gz: '09c0d2c768b78986cc452b899fca0579c7030fe8d4e9b067dcc6d38b8aebe544'
+  data.tar.gz: 6af44122d2741d29f5897c655cba0f38e99596dff88fec8152a95237957d514f
 SHA512:
-  metadata.gz: f90ced1aac865272ac6bdbc55f734ba55be112d0178b3fdc07214b3758b12399606bc6ccb3df48f2ca20f2968288759fa02bf975e20add4e1faeb8f8b52fc7a3
-  data.tar.gz: efad93c3e452c09bc1b0e188c6445066dd6787a13ed9d6d9698e2198f7a90a17faff13b7aa5c26f92bd87c7c0fcefd1edda23dd84f489ae15ef7ae1497216ef4
+  metadata.gz: fd023d73dd39cffa709fbf27f651dfddfe39590bc77ca6874eac5d2c85fe10e8bcc3b1df51757eb6d612df6fde8f1691ad1cb704c74b26ace67349c845b6e8c3
+  data.tar.gz: ef8451ad571c3d52d20b17641ddee5a01e24ae39ea1e7a1e976ab0743dd375d2775f27d569b4cc451111df9543359a2bd00ce0f4ef5cc40ee8ce2cb3cdefeb14

data/CHANGELOG.md

@@ -4,7 +4,24 @@ 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/).
 
-## [0.1.0] - 2026-09-18
+## [0.2.0] - 2026-09-18
+
+### Removed
+
+- **`Ask::Decisions::ToolRouter` — a router that picks one of N tools from the
+  message alone.** It is gone because the measurement below is the argument
+  against it: routing to a tool was right 10/16 where routing to a lane was
+  right 19/20, on the same roster with the same model. Overlapping tools
+  cannot be separated by a message — which of seven knowledge tools holds the
+  answer is discovered by calling them — so a router answering that question
+  is guessing with confidence. The lane withholds the tools a turn cannot
+  need and the model chooses within the narrow roster, where it can see the
+  candidates' results.
+
+  Nothing in the ecosystem called it: not ask-agent, not ask-anychat, not any
+  app. Take this as the cheap moment — the class has no users yet.
+
+## [0.1.1] - 2026-09-18
 
 The first release, so everything here is new. It is a decision layer for the
 ask-rb ecosystem: ask Jev (or any System One model) typed questions and get
@@ -15,7 +32,7 @@ decide.
 
 - `Ask::Decisions::Reader` — asks a described set of options as one Choice,
   with anything else the caller needs riding along in the same request.
-  `ToolRouter` and `Triage` are façades over it.
+  `Triage` is a façade over it.
 - `Ask::Decisions::Triage` — reads a message into a caller-defined lane and
   asks the mood and whether the person wants a human, all in one request.
   Measured against a 19-tool roster: lane-level routing was right 19/20 where

data/README.md

@@ -177,16 +177,28 @@ not carry. A lane is the part that *is* decidable from the message alone.
 A reading should narrow, never grant: let the lane take tools away from a
 turn, and let the agent's own definition stay the ceiling.
 
-## ToolRouter
+### Why there is no tool router
 
-Routes user turns to the right tool:
+There was one — `ToolRouter`, a Choice over a tool roster. It is gone, because
+the measurement above is the argument against it: asked to pick one of
+nineteen tools the answer was right 10 times in 16, and asked to pick a lane
+19 times in 20. Same model, same messages.
 
-```ruby
-router = Ask::Decisions::ToolRouter.new(provider, tools: tool_roster)
-result = router.route(user_turn: "run the tests")
-result.tool         # => "bash"
-result.confidence   # => 0.92
-```
+The reason is structural, not a tuning problem. Overlapping tools cannot be
+separated by a message: which of seven knowledge tools holds the answer is
+discovered by *calling* them. Routing to a tool asks a question the message
+does not carry, so a router that answers it is guessing with confidence.
+
+What replaces it is the lane plus code:
+
+- the lane withholds the tools the turn cannot need,
+- the lane's pre-read fetches what the turn will obviously ask for,
+- and the model chooses within the narrow roster, where choosing is a
+  decision it can actually make — because it can see the candidates' results.
+
+If you do need a decider to pick a tool, the roster it picks from has to be
+small and disjoint — a handful of tools a message can actually distinguish.
+If it is not, the fix is a narrower lane or a pre-read, not a better prompt.
 
 ## ConfidencePolicy
 

data/lib/ask/decisions/reader.rb

@@ -12,8 +12,7 @@ module Ask
     # along in the same request.
     #
     # The caller owns *what* to ask — which options, in what words. This owns
-    # asking it once and handing back the answers. `ToolRouter` and `Triage`
-    # are both façades over it.
+    # asking it once and handing back the answers.
     #
     #   reader = Ask::Decisions::Reader.new(
     #     provider,

data/lib/ask/decisions/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Decisions
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
   end
 end

data/lib/ask-decisions.rb

@@ -15,7 +15,6 @@ require_relative "ask/decisions/gate"
 require_relative "ask/decisions/output_judge"
 require_relative "ask/decisions/reader"
 require_relative "ask/decisions/triage"
-require_relative "ask/decisions/tool_router"
 require_relative "ask/decisions/argument_resolver"
 require_relative "ask/decisions/decision_state"
 require_relative "ask/decisions/failure_classifier"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-decisions
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -169,7 +169,6 @@ files:
 - lib/ask/decisions/static.rb
 - lib/ask/decisions/structured_state_loop.rb
 - lib/ask/decisions/tool_repairer.rb
-- lib/ask/decisions/tool_router.rb
 - lib/ask/decisions/triage.rb
 - lib/ask/decisions/typesafe.rb
 - lib/ask/decisions/version.rb

data/lib/ask/decisions/tool_router.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Decisions
-    # Routes a user turn to the right tool by asking Jev to pick from the
-    # tool roster. Emits the same shape as a tool call so the existing
-    # ToolExecutor can run it unchanged.
-    #
-    #   router = Ask::Decisions::ToolRouter.new(provider, tools: tool_roster)
-    #   result = router.route(
-    #     user_turn: "check the weather in seattle tomorrow",
-    #     recent_turns: [...]
-    #   )
-    #   result.tool      # => "web_search"
-    #   result.confidence  # => 0.92
-    #   result.answer_directly?  # => false
-    #
-    class ToolRouter
-      # Non-tool outcomes that the Choice question includes.
-      NON_TOOL_OUTCOMES = {
-        "answer_directly" => "Answer the user directly without calling any tool",
-        "ask_clarifying_question" => "Ask the user a clarifying question before acting",
-        "none" => "No action needed; the turn is a follow-up or acknowledgment"
-      }.freeze
-
-      # The question the roster answers. The ids in +criteria+ are the tool
-      # names, so the answer comes back as a tool the caller can run.
-      INSTRUCTIONS = "Which tool should the assistant use to handle the user's latest request? " \
-                     "If no tool is needed, pick answer_directly, ask_clarifying_question, or none."
-
-      # @param provider [Ask::DecisionProvider]
-      # @param tools [Array<Hash>] tool roster, each with "name" and "description"
-      # @param none_threshold [Float] below this confidence, fall back to LLM
-      # @param criteria [Hash, nil] routing-grade descriptions, tool name =>
-      #   when to choose it. Worth supplying whenever the roster holds tools
-      #   that overlap: a tool's own description is written for the model that
-      #   already holds it, and two accurate descriptions can still fail to
-      #   separate their tools from the outside. Omitted, each tool's own
-      #   description is used.
-      # @param limit [Integer] characters kept per description
-      def initialize(provider, tools:, none_threshold: 0.5, criteria: nil, limit: 160)
-        @provider = provider
-        @tools = tools
-        @none_threshold = none_threshold
-        @criteria = criteria
-        @limit = limit
-      end
-
-      # Route a user turn to a tool or non-tool outcome.
-      #
-      # @param user_turn [String] the latest user message
-      # @param recent_turns [String, nil] recent conversation context (truncated)
-      # @param model [String, nil] model override
-      # @return [RouteResult]
-      def route(user_turn:, recent_turns: nil, model: nil)
-        state = build_state(user_turn: user_turn, recent_turns: recent_turns)
-        RouteResult.new(reader.choice(reader.read(state: state, model: model)))
-      end
-
-      private
-
-      # The roster, as the options of one Choice question.
-      def reader
-        @reader ||= Ask::Decisions::Reader.new(
-          @provider,
-          id: "tool.route",
-          instructions: INSTRUCTIONS,
-          options: described_roster,
-          limit: @limit
-        )
-      end
-
-      def described_roster
-        described = @tools.each_with_object({}) do |tool, options|
-          name = tool[:name] || tool["name"]
-          options[name] = @criteria&.dig(name) || @criteria&.dig(name.to_s) ||
-                          tool[:description] || tool["description"] || ""
-        end
-        described.merge(NON_TOOL_OUTCOMES)
-      end
-
-      def build_state(user_turn:, recent_turns: nil)
-        state = {user_turn: user_turn}
-        state[:recent_turns] = truncate(recent_turns, 2000) if recent_turns
-        state
-      end
-
-      def truncate(str, limit)
-        return "" if str.nil?
-        str.length > limit ? "#{str[0, limit]}…" : str
-      end
-
-
-      # Result of routing.
-      class RouteResult
-        attr_reader :choice_answer
-
-        def initialize(choice_answer)
-          @choice_answer = choice_answer
-        end
-
-        # The selected tool name or non-tool outcome.
-        def tool = choice_answer&.choice
-
-        def confidence = choice_answer&.confidence
-
-        def probabilities = choice_answer&.probabilities
-
-        # Should we call a tool, or handle this differently?
-        def answer_directly?  = tool == "answer_directly"
-        def ask_clarifying?   = tool == "ask_clarifying_question"
-        def no_action?        = tool == "none"
-        def call_tool?        = !answer_directly? && !ask_clarifying? && !no_action?
-
-        # Is the confidence above the threshold for autonomous action?
-        def confident?(threshold = nil)
-          threshold ||= 0.7
-          return false if confidence.nil?
-          confidence >= threshold
-        end
-
-        # Should we fall back to the LLM loop?
-        def fallback?(none_threshold = 0.5)
-          confidence.nil? || confidence < none_threshold
-        end
-
-        def to_s
-          if call_tool?
-            "tool: #{tool} (#{('%.2f' % (confidence || 0))})"
-          else
-            "#{tool} (#{('%.2f' % (confidence || 0))})"
-          end
-        end
-      end
-    end
-  end
-end