ask-decisions 0.1.1

data/lib/ask/decisions/tool_router.rb

@@ -0,0 +1,137 @@
+# 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

data/lib/ask/decisions/triage.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Ask
+  module Decisions
+    # Reads an incoming message once and answers every question the turn
+    # needs about it: which lane it belongs to, how the person sounds, and
+    # whether they want a human.
+    #
+    # Lanes are the coarse intents a message can be sorted into — "a
+    # question about the business", "wants to book", "wants a person" — and
+    # they are deliberately fewer and coarser than the tools they lead to.
+    #
+    # That coarseness is the point. Routing a message straight to one of
+    # twenty tools asks the model to make a distinction the message does not
+    # carry: seven tools may all answer from the same knowledge, and which
+    # one holds the answer is discovered by calling them, not by reading the
+    # request. Lanes are the part that *is* decidable from the message; code
+    # maps the lane to its tools, and a second, narrower decision happens
+    # only when one is needed.
+    #
+    # Ranks measured on a 19-tool roster: tool-level routing 10/16, lane
+    # routing 19/20 — same model, same messages.
+    #
+    #   triage = Ask::Decisions::Triage.new(provider, lanes: {
+    #     "knowledge" => "Asks about the business, its services, prices, hours, or policies",
+    #     "booking"   => "Wants to book an appointment or asks what times are free",
+    #     "human"     => "Wants to speak to a person, or describes an emergency",
+    #     "close"     => "Says goodbye or is done",
+    #     "chat"      => "Small talk or a greeting needing no action",
+    #     "unclear"   => "None of these is clear; a clarifying question is needed first"
+    #   })
+    #   verdict = triage.read(message: "What time do you close on Saturdays?")
+    #   verdict.lane        # => "knowledge"
+    #   verdict.confidence  # => 1.0
+    #   verdict.certain?(0.7) # => true
+    #
+    # All questions go in one request: asking more costs no extra latency.
+    class Triage
+      # The verdict on one message. +lane+ is always one of the lanes the
+      # caller supplied, or nil when the call failed.
+      class Verdict
+        attr_reader :lane, :confidence, :sentiment, :wants_human, :answers
+
+        def initialize(lane:, confidence:, sentiment: nil, wants_human: nil, answers: {})
+          @lane = lane
+          @confidence = confidence
+          @sentiment = sentiment
+          @wants_human = wants_human
+          @answers = answers
+        end
+
+        # A failed or unreadable call produces no verdict: nothing is known,
+        # and the caller keeps whatever it would have done without us.
+        def known? = !lane.nil?
+
+        # Is the lane above the threshold for acting on it without asking
+        # again? Callers pass the one threshold they are willing to be wrong
+        # at; there is no universal one.
+        def certain?(threshold = 0.7)
+          return false unless confidence
+          confidence >= threshold
+        end
+
+        # Does the person want a person? An unanswered question is not a yes,
+        # and neither is a coin flip: 0.5 means the model had no idea, which
+        # is the one answer that must not read as consent.
+        def wants_human?(threshold = 0.5)
+          return false unless wants_human
+          wants_human > threshold
+        end
+
+        def to_s
+          return "no verdict" unless known?
+          "#{lane} (#{format('%.2f', confidence || 0)})"
+        end
+      end
+
+      # The auxiliary questions every triage asks, on top of the lane.
+      # They ride along in the same request, so they are free — which is the
+      # whole reason to ask for them up front rather than in a second call.
+      SENTIMENT = Ask::Decision::Score.new(
+        instructions: "How does the person writing sound? Judge their mood, not the topic.",
+        criteria: ["Upset or angry", "Neutral", "Warm or pleased"]
+      )
+
+      WANTS_HUMAN = Ask::Decision::Noul.new(
+        instructions: "Does the person want to speak to a human rather than deal with a bot? " \
+                      "Contact details, business hours, and product questions do not count as wanting a human."
+      )
+
+      # The question the lanes answer.
+      DEFAULT_INSTRUCTIONS = "Which of these best describes what the person writing wants? " \
+                             "Choose by what they are asking for, not by how they phrase it."
+
+      attr_reader :lanes
+
+      # @param provider [Ask::DecisionProvider]
+      # @param lanes [Hash] lane name => a sentence describing what belongs in it
+      # @param instructions [String] the question the lanes answer
+      # @param context_limit [Integer] how much context to carry into state
+      def initialize(provider, lanes:, instructions: nil, context_limit: 600)
+        @provider = provider
+        @lanes = lanes
+        @instructions = instructions || DEFAULT_INSTRUCTIONS
+        @context_limit = context_limit
+      end
+
+      # Read a message and return a Verdict.
+      #
+      # @param message [String] the message to read
+      # @param context [String, nil] a short description of who is writing to whom
+      # @param model [String, nil] model override
+      # @return [Verdict]
+      def read(message:, context: nil, model: nil)
+        answers = reader.read(state: build_state(message, context), model: model)
+        lane = answers[reader.id]
+
+        Verdict.new(
+          lane: lane&.choice,
+          confidence: lane&.confidence,
+          sentiment: answers["sentiment"]&.score,
+          wants_human: answers["wants_human"]&.noul,
+          answers: {
+            "lane" => lane,
+            "sentiment" => answers["sentiment"],
+            "wants_human" => answers["wants_human"]
+          }
+        )
+      end
+
+      private
+
+      # The lane, the mood, and the want for a person — one request, because
+      # the questions are independent and the call costs the same either way.
+      def reader
+        @reader ||= Ask::Decisions::Reader.new(
+          @provider,
+          id: "lane",
+          instructions: @instructions,
+          options: @lanes,
+          also: {"sentiment" => SENTIMENT, "wants_human" => WANTS_HUMAN}
+        )
+      end
+
+      # The state is the message and a line of context. Longer state has
+      # been measured to make Jev worse, not better — everything irrelevant
+      # is a chance to misread what is relevant.
+      def build_state(message, context)
+        state = {message: truncate(message, 2000)}
+        state[:context] = truncate(context, @context_limit) if context && !context.to_s.empty?
+        state
+      end
+
+      def truncate(value, limit)
+        text = value.to_s
+        return text if text.length <= limit
+        "#{text[0, limit - 20]}…[#{text.length - limit + 20} chars elided]"
+      end
+    end
+  end
+end

data/lib/ask/decisions/typesafe.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+begin
+  require "ask-auth"
+rescue LoadError
+  # ask-auth is optional — only needed for automatic credential resolution.
+end
+
+module Ask
+  module Decisions
+    # HTTP client for the TypeSafe / System One API.
+    #
+    #   provider = Ask::Decisions::Typesafe.new
+    #   result = provider.evaluate(
+    #     state: "Help! My payouts are failing.",
+    #     decisions: {
+    #       "is_urgent" => Ask::Decision::Noul.new(instructions: "Does this convey urgency?"),
+    #       "route"     => Ask::Decision::Choice.new(
+    #         instructions: "Which team should handle this?",
+    #         criteria: { "billing" => "Payments", "technical" => "Bugs" }
+    #       )
+    #     }
+    #   )
+    #   result["is_urgent"].noul      # => 0.92
+    #   result["route"].choice        # => "technical"
+    #   result["route"].confidence   # => 0.82
+    #
+    # The API key is resolved in order:
+    # 1. +api_key+ passed to the constructor
+    # 2. +Ask::Decisions.configuration.api_key+
+    # 3. +Ask::Auth.resolve(:typesafe_api_key)+
+    # 4. +ENV["TYPESAFE_API_KEY"]+
+    #
+    class Typesafe < Ask::DecisionProvider
+      API_BASE = "https://api.typesafe.ai"
+      API_PATH = "/v1/systemone"
+
+      RETRYABLE_STATUSES = [429, 529].freeze
+
+      attr_reader :api_key, :api_base, :model, :timeout
+
+      def initialize(api_key: nil, api_base: nil, model: nil, timeout: nil, **_opts)
+        super()
+        @api_key = api_key || resolve_api_key
+        @api_base = (api_base || Ask::Decisions.configuration.api_base || API_BASE).chomp("/")
+        @model = model || Ask::Decisions.configuration.default_model || "jev-latest"
+        @timeout = timeout || Ask::Decisions.configuration.timeout || 5.0
+      end
+
+      # @return [DecisionResult::Batch]
+      def evaluate(state:, decisions:, model: nil)
+        model_name = model || @model
+        payload = build_payload(state, decisions, model_name)
+        response = post(payload)
+        parse_response(response, decisions.keys)
+      end
+
+      private
+
+      # --- Request building ---
+
+      def build_payload(state, decisions, model_name)
+        questions = decisions.transform_values(&:to_h)
+        {
+          state: state,
+          model: model_name,
+          questions: questions
+        }
+      end
+
+      def post(payload)
+        uri = URI.parse("#{@api_base}#{API_PATH}")
+        body = JSON.generate(payload)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "ask-decisions/#{Ask::Decisions::VERSION}"
+        request.body = body
+
+        response = http.request(request)
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        status = response.code.to_i
+        body = response.body
+
+        case status
+        when 200..299
+          JSON.parse(body)
+        when 401, 403
+          raise Ask::Unauthorized, "TypeSafe: #{status} #{extract_message(body)}"
+        when 429
+          retry_after = response["retry-after"]&.to_f
+          raise Ask::RateLimitError.new(
+            "TypeSafe: rate limited",
+            retry_after: retry_after
+          )
+        when 422
+          raise Ask::ProviderError.new("TypeSafe: #{extract_message(body)}", status_code: status)
+        when 500
+          raise Ask::ServerError, "TypeSafe: server error #{extract_message(body)}"
+        when 529
+          retry_after = response["retry-after"]&.to_f
+          raise Ask::RateLimitError.new(
+            "TypeSafe: overloaded",
+            retry_after: retry_after
+          )
+        else
+          raise Ask::ProviderError.new(
+            "TypeSafe: HTTP #{status} #{extract_message(body)}",
+            status_code: status
+          )
+        end
+      end
+
+      # --- Response parsing ---
+
+      def parse_response(parsed, question_ids)
+        answers = {}
+        question_ids.each do |id|
+          raw = parsed.dig("answers", id)
+          next unless raw
+
+          answers[id] = parse_answer(id, raw)
+        end
+
+        Ask::DecisionResult::Batch.new(
+          answers: answers,
+          model: parsed["model"],
+          usage: parsed["usage"],
+          latency: nil # set by caller if timing
+        )
+      end
+
+      def parse_answer(id, raw)
+        case raw["type"]
+        when "choice"
+          Ask::DecisionResult::ChoiceAnswer.new(
+            id: id,
+            choice: raw["choice"],
+            probabilities: raw["probabilities"] || {},
+            confidence: raw["confidence"]&.to_f
+          )
+        when "score"
+          Ask::DecisionResult::ScoreAnswer.new(
+            id: id,
+            score: raw["score"]&.to_f,
+            legend: raw["legend"] || {},
+            probabilities: raw["probabilities"] || {},
+            confidence: raw["confidence"]&.to_f
+          )
+        when "noul"
+          Ask::DecisionResult::NoulAnswer.new(
+            id: id,
+            noul: raw["noul"]&.to_f
+          )
+        else
+          raise Ask::ProviderError, "TypeSafe: unknown answer type #{raw["type"].inspect} for #{id}"
+        end
+      end
+
+      # --- Helpers ---
+
+      def resolve_api_key
+        Ask::Decisions.configuration.api_key ||
+          (defined?(Ask::Auth) && begin
+            Ask::Auth.resolve(:typesafe_api_key)
+          rescue Ask::Auth::MissingCredential
+            nil
+          end) ||
+          ENV["TYPESAFE_API_KEY"]
+      end
+
+      def extract_message(body)
+        parsed = JSON.parse(body)
+        parsed["error"]["message"] || parsed["error"] || body
+      rescue JSON::ParserError
+        body
+      end
+    end
+  end
+end

data/lib/ask/decisions/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Decisions
+    VERSION = "0.1.1"
+  end
+end

data/lib/ask/tools/decide.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Tools
+    # A tool that delegates a judgment to a decision model (e.g. Jev).
+    # This is the bridge for LLM-driven agents: instead of guessing which
+    # tool to call, the agent asks Decide and gets typed answers with
+    # calibrated probabilities.
+    #
+    # The agent sees this as one more tool alongside bash, read, etc.:
+    #
+    #   decide(state: "...", questions: '{
+    #     "route": {
+    #       "type": "choice",
+    #       "instructions": "Which tool should handle this?",
+    #       "criteria": {
+    #         "bash": "Run a shell command",
+    #         "read": "Read a file",
+    #         "none": "Answer directly without tools"
+    #       }
+    #     }
+    #   }')
+    #
+    class Decide < Ask::Tool
+      description "Delegate a judgment to a decision model. Returns typed answers " \
+                   "with calibrated probabilities. Use this when you need to classify, " \
+                   "route, score, or judge something — instead of guessing, ask the " \
+                   "decision model. One call can ask many questions at once."
+
+      param :state, type: :string, desc: "The content to evaluate (JSON string or plain text)", required: true
+      param :questions, type: :string, desc: "Questions as JSON: {\"id\": {\"type\": \"choice|score|noul\", \"instructions\": \"...\", \"criteria\": {...}}}", required: true
+
+      def execute(state:, questions:)
+        parsed_state = parse_json_safe(state)
+        parsed_questions = parse_json_safe(questions)
+
+        unless parsed_questions.is_a?(Hash)
+          return Ask::Result.failure("questions must be a JSON object mapping id → question")
+        end
+
+        decisions = build_decisions(parsed_questions)
+        if decisions.empty?
+          return Ask::Result.failure("no valid questions found in the input")
+        end
+
+        provider = resolve_provider
+        result = provider.evaluate(state: parsed_state, decisions: decisions)
+
+        # Format answers for the LLM — the agent needs to read this.
+        output = format_answers(result)
+        Ask::Result.success(output)
+      rescue JSON::ParserError => e
+        Ask::Result.failure("invalid JSON: #{e.message}")
+      rescue => e
+        Ask::Result.failure("decide failed: #{e.message}")
+      end
+
+      private
+
+      # Parse JSON, but return the original string if it's not JSON.
+      def parse_json_safe(str)
+        return str if str.is_a?(Hash) || str.is_a?(Array)
+        JSON.parse(str)
+      rescue JSON::ParserError
+        str
+      end
+
+      # Convert the raw JSON question map into Ask::Decision objects.
+      def build_decisions(parsed)
+        parsed.each_with_object({}) do |(id, q), h|
+          q = q.is_a?(Hash) ? q : {}
+          type = q["type"]&.downcase
+          instructions = q["instructions"]
+          next unless type && instructions
+
+          case type
+          when "choice"
+            criteria = q["criteria"] || {}
+            h[id] = Ask::Decision::Choice.new(instructions: instructions, criteria: criteria)
+          when "score"
+            criteria = Array(q["criteria"])
+            h[id] = Ask::Decision::Score.new(instructions: instructions, criteria: criteria)
+          when "noul"
+            criteria = q["criteria"] # optional
+            opts = { instructions: instructions }
+            opts[:criteria] = criteria if criteria
+            h[id] = Ask::Decision::Noul.new(**opts)
+          end
+        end
+      end
+
+      # Resolve the decision provider from configuration.
+      def resolve_provider
+        provider_name = Ask::Decisions.configuration.default_provider
+        Ask::Decisions.resolve_provider(provider_name)
+      end
+
+      # Format the result batch as a readable JSON string for the LLM.
+      def format_answers(result)
+        output = { model: result.model, answers: {} }
+        result.each do |answer|
+          case answer
+          when Ask::DecisionResult::ChoiceAnswer
+            output[:answers][answer.id] = {
+              type: "choice",
+              choice: answer.choice,
+              probabilities: answer.probabilities,
+              confidence: answer.confidence
+            }
+          when Ask::DecisionResult::ScoreAnswer
+            output[:answers][answer.id] = {
+              type: "score",
+              score: answer.score,
+              confidence: answer.confidence,
+              legend: answer.legend
+            }
+          when Ask::DecisionResult::NoulAnswer
+            output[:answers][answer.id] = {
+              type: "noul",
+              noul: answer.noul
+            }
+          end
+        end
+        JSON.generate(output)
+      end
+    end
+  end
+end