samagotchi 0.64.0 → 0.66.0

data/lib/samagotchi/idle_recap.rb

@@ -287,10 +287,13 @@ module Samagotchi
                    sentences: RecapPrompt::DEFAULT_SENTENCES,
                    client: nil,
                    store: nil,
+                   session_id: -> {},
                    clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       raise ArgumentError, "IdleRecap requires an engine" unless engine
 
       @engine = engine
+      # The recapped session's id, sent with the request (IdleClient#summarize).
+      @session_id = session_id
       @target = target || lambda {
         IdleTarget.new(base_url: base_url, api_key_env: api_key_env, model: model, label: model)
       }
@@ -534,7 +537,7 @@ module Samagotchi
     def client_for(asked)
       return @client_override if @client_override
 
-      key = [asked.base_url, asked.api_key_env, asked.model]
+      key = asked
       unless @client && @client_key == key
         @client = IdleClient.for(asked, timeout: @timeout)
         @client_key = key
@@ -544,7 +547,7 @@ module Samagotchi
 
     def spawn_summarize(client, prompt)
       Thread.new do
-        client.summarize(prompt)
+        client.summarize(prompt, session_id: @session_id.call)
       rescue StandardError => e
         # No recap this time (the next idle window tries again); say why.
         Log.exception(:recap, "summarize_failed", e)

data/lib/samagotchi/idle_target.rb

@@ -2,13 +2,28 @@
 
 module Samagotchi
   # Where a side request goes (a recap, a plugin's ctx.ask_model, a
-  # broadcast's triage): a model on a host's OpenAI API, asked through its
+  # broadcast's triage): a model on a host's chat API, asked through its
   # own IdleClient (IdleClient.for), apart from the session's turns.
-  # @!attribute base_url [String] the host's OpenAI API base
+  # @!attribute base_url [String] the host's API base (HostEntry#api_base_url)
   # @!attribute api_key_env [String, nil] the variable holding its key
   # @!attribute model [String] the model id sent to the server
   # @!attribute label [String] the model as configured, for logs
-  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label) do
+  # @!attribute api [Symbol] the wire the side client talks (LLM::Adapters):
+  #   a chat host's api, else :openai (a raw host's server, or a bare url)
+  # @!attribute auth [Symbol, nil] the header its key goes in (the host's
+  #   auth:, LLM::ApiKey::SCHEMES); nil: the api's own default
+  # @!attribute dialect [String, nil] an api: anthropic host's dialect:
+  #   (LLM::Dialect), so a side request gets its auth and fields
+  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label, :api, :auth, :dialect) do
+    def initialize(api: :openai, auth: nil, dialect: nil, **) = super
+
+    # The api a side request to +entry+ talks: a chat host's own, else the
+    # OpenAI API (a raw host's llama.cpp serves /v1 too).
+    def self.api_of(entry) = entry.chat? ? entry.api : :openai
+
+    # The dialect a side request to +entry+ talks (only a chat host has one).
+    def self.dialect_of(entry) = entry.chat? ? entry.dialect : nil
+
     # A configured side model can't be resolved.
     # @!attribute reason [Symbol] :host_ref_unknown (no such host),
     #   :model_host_mismatch (the model names another host than host_ref)
@@ -32,8 +47,9 @@ module Samagotchi
     # @return [IdleTarget]
     def self.of_model(host_registry, name)
       resolved = host_registry.resolve(name)
-      new(base_url: resolved.openai_base_url, api_key_env: resolved.entry.api_key_env, model: resolved.bare_model,
-          label: name.to_s.strip)
+      entry = resolved.entry
+      new(base_url: entry.api_base_url, api_key_env: entry.api_key_env, model: resolved.bare_model,
+          label: name.to_s.strip, api: api_of(entry), auth: entry.auth, dialect: dialect_of(entry))
     end
 
     # A side model's settings (recap.*, broadcast.triage_*) as a target:
@@ -55,12 +71,18 @@ module Samagotchi
 
       host_ref ||= parsed.host_name if parsed && base_url.nil?
       api_key_env = nil
+      api = :openai
+      auth = nil
+      dialect = nil
       if host_ref
         entry = host_registry.find_entry(host_ref)
         raise self::Unresolved.new(:host_ref_unknown, model: model, host_ref: host_ref) unless entry
 
-        base_url = entry.openai_base_url
+        base_url = entry.api_base_url
         api_key_env = entry.api_key_env
+        api = api_of(entry)
+        auth = entry.auth
+        dialect = dialect_of(entry)
         named = parsed&.host_conflict || parsed&.host_name
         if named && named != entry.name
           raise self::Unresolved.new(:model_host_mismatch, model: model, host_ref: host_ref, named: named)
@@ -72,7 +94,8 @@ module Samagotchi
       end
       raise self::Unresolved.new(:incomplete, model: model, host_ref: host_ref) if blank(base_url).nil? || blank(model).nil?
 
-      new(base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.strip)
+      new(base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.strip, api: api, auth: auth,
+          dialect: dialect)
     end
 
     # Whether the settings fix a host (+base_url+, +host_ref+, or a model

data/lib/samagotchi/kernel_loop.rb

@@ -1067,9 +1067,17 @@ module Samagotchi
     # The error an unknown tool name gets back. A shell-like name with
     # `execute` offered this turn points at `execute`; every other unknown
     # name lists what is offered. Neither echoes the wrong name.
+    #
+    # A tool the session's toolkit leaves out is a real one, so its error
+    # does name it (deliberately, against the rule above): the model learns
+    # it exists and that only the user can load it.
     def unknown_tool_error(name, layers)
       names = @tools.names(layers: layers)
-      if SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
+      if @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
+        toolkit = @tools.toolkit&.name
+        "Error: #{name} isn't loaded in this session#{" (toolkit #{toolkit})" if toolkit} and can't be loaded from " \
+          "here; only the user can (/toolkit add #{name}). Available: #{names.join(", ")}"
+      elsif SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
         "Error: no such tool. Shell commands run with `execute` (same arguments)."
       else
         "Error: no such tool. Available: #{names.join(", ")}"

data/lib/samagotchi/llm/adapters.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "openai_chat"
+require_relative "anthropic_messages"
+
+module Samagotchi
+  module LLM
+    # Which chat adapter talks a host's api: the one place that names the
+    # adapter classes. A host whose api is a key of BY_API runs the chat loop
+    # (HostRegistry::HostEntry#chat?); any other api (nil, raw) the
+    # raw-prompt loop.
+    module Adapters
+      BY_API = { openai: OpenAIChat, anthropic: AnthropicMessages }.freeze
+
+      # true when +api+ (a Symbol or String) has a chat adapter.
+      def self.chat_api?(api) = !api.nil? && BY_API.key?(api.to_sym)
+
+      # A host entry's adapter (its api, API base, name, key and remoteness).
+      # @param entry [HostRegistry::HostEntry]
+      # @param options [Hash] more adapter options (models_ttl:, first_token_timeout:, ...)
+      # @raise [ArgumentError] the entry's api has no chat adapter
+      def self.for(entry, **)
+        adapter_class(entry.api).for(entry, **)
+      end
+
+      # An adapter by api, for a side request that has a url rather than a
+      # host entry (IdleClient: a recap, ctx.ask_model, a broadcast's triage).
+      # @param api [Symbol, String] a key of BY_API
+      # @param options [Hash] more adapter options (stream:, retries:, timeout:, ...)
+      # @raise [ArgumentError] +api+ has no chat adapter
+      def self.build(api:, base_url:, host_name:, api_key_env: nil, **)
+        adapter_class(api).new(base_url: base_url, host_name: host_name, api_key_env: api_key_env, **)
+      end
+
+      def self.adapter_class(api)
+        BY_API.fetch(api&.to_sym) { raise ArgumentError, "no chat adapter for api #{api.inspect}" }
+      end
+      private_class_method :adapter_class
+    end
+  end
+end

data/lib/samagotchi/llm/anthropic_assembly.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative "openai_chat"
+require_relative "usage"
+
+module Samagotchi
+  module LLM
+    # A Messages response put together as ChatResponse, from a whole body
+    # (.from_message) or a stream's events (#add, by content-block index):
+    # the content blocks
+    # in order (kept as received, string keys: ChatResponse#provider_content,
+    # which ChatLoop saves and sends back), the text and reasoning they
+    # carry, the tool calls, the usage and the stop reason in the chat
+    # loop's terms.
+    #
+    # Usage: Messages counts input_tokens without the cache, so the prompt
+    # is input + cache reads + cache writes, in the OpenAI shape the rest of
+    # chi reads (TokenUsage: prompt_tokens_details.cached_tokens /
+    # cache_write_tokens). Every field is optional (Splash sends no cache
+    # writes), and a later value wins per field.
+    class AnthropicAssembly
+      # stop_reason → ChatResponse#finish_reason (the chat loop's words);
+      # pause_turn and anything else pass as they are.
+      FINISH_REASONS = {
+        "end_turn" => "stop", "stop_sequence" => "stop", "max_tokens" => "length",
+        "model_context_window_exceeded" => "length", "tool_use" => "tool_calls", "refusal" => "refusal"
+      }.freeze
+      USAGE_KEYS = %w[input_tokens output_tokens cache_read_input_tokens cache_creation_input_tokens].freeze
+      # Blocks whose text is the answer or the reasoning.
+      THINKING = "thinking"
+      TEXT = "text"
+
+      def self.finish_reason(stop_reason) = stop_reason && FINISH_REASONS.fetch(stop_reason.to_s, stop_reason.to_s)
+
+      # A non-streamed body (a `message` object).
+      def self.from_message(body) = new.tap { |assembly| assembly.add_message(body) }
+
+      def initialize
+        @blocks = []
+        # A streamed block by its index, and a tool_use's input JSON so far.
+        @by_index = {}
+        @json = {}
+        @usage = {}
+        @stop_reason = nil
+        @stop_details = nil
+        @model = nil
+      end
+
+      # A whole message: its model, usage, stop reason and blocks.
+      def add_message(message)
+        return unless message.is_a?(Hash)
+
+        @model = served(message["model"]) || @model
+        merge_usage(message["usage"])
+        @stop_reason = message["stop_reason"] if message["stop_reason"]
+        @stop_details = message["stop_details"] if message["stop_details"].is_a?(Hash)
+        Array(message["content"]).each { |block| @blocks << block.dup if block.is_a?(Hash) }
+      end
+
+      # One streamed event: message_start (served model, usage),
+      # content_block_start (text / thinking / redacted_thinking / tool_use),
+      # content_block_delta (text_delta, thinking_delta, signature_delta,
+      # input_json_delta), content_block_stop, message_delta (stop reason,
+      # stop_details, usage); ping, message_stop and anything else change nothing.
+      # @return [Array(String, String)] the event's text and reasoning
+      def add(event)
+        case event["type"]
+        when "message_start" then start_message(event["message"])
+        when "content_block_start" then start_block(event["index"], event["content_block"])
+        when "content_block_delta" then add_delta(@by_index[event["index"]], event["index"], event["delta"])
+        when "message_delta"
+          if event["delta"].is_a?(Hash)
+            @stop_reason = event.dig("delta", "stop_reason") || @stop_reason
+            @stop_details = event.dig("delta", "stop_details") if event.dig("delta", "stop_details").is_a?(Hash)
+          end
+          merge_usage(event["usage"])
+          ["", ""]
+        else ["", ""]
+        end
+      end
+
+      # Whether a streamed +event+ shows something (a block started, a delta):
+      # what the first-token limit waits for.
+      def self.shows?(event) = %w[content_block_start content_block_delta].include?(event["type"])
+
+      # Whether a streamed +event+ carries part of a tool call.
+      def self.tool_call_delta?(event)
+        case event["type"]
+        when "content_block_start" then event.dig("content_block", "type") == "tool_use"
+        when "content_block_delta" then event.dig("delta", "type") == "input_json_delta"
+        else false
+        end
+      end
+
+      # +event+ as on_delta passes it on: one that carries usage gets the
+      # usage so far in the OpenAI shape as its `usage` (SessionMetrics,
+      # ContextStatus and ctx.js read that).
+      def with_usage(event)
+        return event unless %w[message_start message_delta].include?(event["type"]) && (payload = usage_payload)
+
+        event.merge("usage" => payload)
+      end
+
+      # The usage so far as an OpenAI-shaped `usage` object, nil when the
+      # server sent no counts, or only zeros (Fireworks' message_start: its
+      # counts come in the last message_delta; a 0 read as an empty context
+      # in the web's ctx meter while the answer streamed).
+      def usage_payload
+        return nil if @usage.values.none?(&:positive?)
+
+        read = @usage["cache_read_input_tokens"].to_i
+        write = @usage["cache_creation_input_tokens"].to_i
+        { "prompt_tokens" => @usage["input_tokens"].to_i + read + write, "completion_tokens" => @usage["output_tokens"].to_i,
+          "prompt_tokens_details" => { "cached_tokens" => read, "cache_write_tokens" => write } }
+      end
+
+      def response
+        blocks = content
+        ChatResponse.new(text: joined(blocks, TEXT, "text"), reasoning: joined(blocks, THINKING, "thinking"),
+                         tool_calls: tool_calls, usage: usage, finish_reason: self.class.finish_reason(@stop_reason),
+                         model: @model, provider_content: blocks, stop_details: @stop_details)
+      end
+
+      private
+
+      def usage
+        payload = usage_payload
+        (payload && Usage.from_payload({ "usage" => payload })) || Usage.none
+      end
+
+      def start_message(message)
+        return ["", ""] unless message.is_a?(Hash)
+
+        @model = served(message["model"]) || @model
+        merge_usage(message["usage"])
+        ["", ""]
+      end
+
+      def start_block(index, block)
+        return ["", ""] unless block.is_a?(Hash)
+
+        block = block.dup
+        @blocks << block
+        @by_index[index] = block
+        case block["type"]
+        when TEXT then [block["text"].to_s, ""]
+        when THINKING then ["", block["thinking"].to_s]
+        else ["", ""]
+        end
+      end
+
+      def add_delta(block, index, delta)
+        return ["", ""] unless block && delta.is_a?(Hash)
+
+        case delta["type"]
+        when "text_delta"
+          block["text"] = block["text"].to_s + delta["text"].to_s
+          [delta["text"].to_s, ""]
+        when "thinking_delta"
+          block["thinking"] = block["thinking"].to_s + delta["thinking"].to_s
+          ["", delta["thinking"].to_s]
+        when "signature_delta"
+          block["signature"] = block["signature"].to_s + delta["signature"].to_s
+          ["", ""]
+        when "input_json_delta"
+          (@json[index] ||= +"") << delta["partial_json"].to_s
+          block["input"] = @json[index]
+          ["", ""]
+        else ["", ""]
+        end
+      end
+
+      def merge_usage(usage)
+        return unless usage.is_a?(Hash)
+
+        USAGE_KEYS.each { |key| @usage[key] = usage[key] if usage[key].is_a?(Integer) }
+      end
+
+      # The blocks to keep and send back: an empty or blank text block is
+      # no text (Splash opens one after a thinking cut by max_tokens, and
+      # Messages refuses one sent back), a tool_use's input is an object,
+      # and a thinking block has a signature, "" when it came without one
+      # (a sent-back thinking block needs the key; Splash sends "", a
+      # provider may send none).
+      def content
+        @blocks.filter_map do |block|
+          type = block["type"].to_s
+          next if type == TEXT && block["text"].to_s.strip.empty?
+          next block.merge("signature" => "") if type == THINKING && !block.key?("signature")
+          next block unless type == "tool_use"
+
+          input = OpenAIChat.parse_arguments(block["input"])
+          block.merge("input" => input.is_a?(Hash) ? input : {})
+        end
+      end
+
+      def joined(blocks, type, key)
+        blocks.select { |block| block["type"] == type }.map { |block| block[key].to_s }.join
+      end
+
+      # The calls with their arguments as OpenAIChat.parse_arguments reads
+      # them: invalid JSON stays a String, so the tool reports it.
+      def tool_calls
+        @blocks.select { |block| block["type"] == "tool_use" }.map do |block|
+          ToolCall.new(id: block["id"], name: block["name"].to_s, arguments: OpenAIChat.parse_arguments(block["input"]))
+        end
+      end
+
+      def served(model) = model.is_a?(String) && !model.strip.empty? ? model : nil
+    end
+  end
+end