automatic 26.08 → 26.09

data/lib/automatic/version.rb

@@ -1,16 +1,16 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::VERSION
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
 # Created::     Feb 18, 2012
-# Updated::     Aug 14, 2026
+# Updated::     Aug 25, 2026
 # Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 
 module Automatic
   # The release version. The VERSION file at the repository root carries the
   # same number and the gemspec reads it from there; a spec asserts that the
   # two agree. See doc/POLICY.md section 10.
-  VERSION = '26.08'
+  VERSION = '26.09'
 end

data/lib/automatic.rb

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Ruby
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
 # Created::     Feb 18, 2012
-# Updated::     Aug 14, 2026
+# Updated::     Sep  6, 2026
 # Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 #
 # The framework module: the two directories everything else resolves paths
@@ -38,6 +38,14 @@ module Automatic
   # A Recipe parsed, but is not a document this framework can run.
   class InvalidRecipeError < Error; end
 
+  # Raised by require_optional when, and only when, the exact feature it was
+  # asked to require could not be found. A LoadError subtype rather than an
+  # Error subtype, so that a caller already rescuing LoadError still catches
+  # it; distinct from plain LoadError so that a caller can tell "the optional
+  # gem itself is missing" apart from a LoadError raised from inside that
+  # gem's own load. See doc/POLICY.md section 9.1.
+  class OptionalDependencyError < LoadError; end
+
   class << self
     attr_accessor :root_dir
 
@@ -55,7 +63,14 @@ module Automatic
     def require_optional(feature, needed_by:, gem_name: feature)
       require feature
     rescue LoadError => e
-      raise LoadError,
+      # e.path is the argument require failed to find. When it matches
+      # feature, this require itself is what failed, and the gem naming this
+      # feature is what is missing. When it does not, the failure happened
+      # somewhere inside feature's own load -- a different missing file -- and
+      # is not this gem's absence; it is re-raised unconverted.
+      raise e unless e.path == feature
+
+      raise OptionalDependencyError,
             "The `#{gem_name}` gem is not installed. It is needed by #{needed_by}. " \
             "Install it with `gem install #{gem_name}`, or in a source checkout add " \
             'its group to the bundle; see the optional plugin dependencies in ' \

data/plugins/custom_feed/web.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::CustomFeed::Web
 # Description:: Build a feed from the article links of an HTML index page.
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/absolute_uri.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::AbsoluteURI
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/batch.rb

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+# Name::        Automatic::Plugin::Filter::Batch
+# Description:: Group the whole pipeline into fixed-size item batches.
+# Author:       id774 (More info: https://id774.net)
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Aug 24, 2026
+# Updated::     Aug 24, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+
+module Automatic::Plugin
+  class FilterBatch
+    require 'rss'
+
+    # Where one source item ends and the next begins inside a batch's
+    # description, in the manner of FilterJoin's own delimiter -- but built
+    # independently, since a batch item is not a joined item.
+    HEADING = 'ARTICLE'.freeze
+
+    def initialize(config, pipeline = [])
+      @config      = config || {}
+      @pipeline    = pipeline
+      @batch_items = validated_batch_items
+    end
+
+    # Collects the whole pipeline into one Array, discarding feed boundaries,
+    # and slices it into fixed-size batches. Each batch becomes one item in one
+    # output feed.
+    def run
+      items = collect
+      return [] if items.empty?
+
+      feed(items.each_slice(@batch_items).to_a)
+    end
+
+    private
+
+    def validated_batch_items
+      value = begin
+        Integer(@config['batch_items'].to_s, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      if value.nil? || value < 1
+        raise ArgumentError, 'FilterBatch needs batch_items to be a positive integer'
+      end
+
+      value
+    end
+
+    def collect
+      @pipeline.each_with_object([]) do |feeds, items|
+        next if feeds.nil?
+
+        items.concat(feeds.items)
+      end
+    end
+
+    def feed(batches)
+      [RSS::Maker.make('2.0') { |maker|
+        maker.channel.title = 'Automatic Ruby'
+        maker.channel.description = 'Automatic::Plugin::FilterBatch'
+        maker.channel.link = 'https://github.com/id774/automaticruby'
+        maker.items.do_sort = false
+
+        batches.each_with_index do |batch, index|
+          item = maker.items.new_item
+          item.title = "Batch #{index + 1}"
+          item.description = description(batch)
+          item.date = Time.now
+        end
+      }]
+    end
+
+    def description(batch)
+      batch.each_with_index.map { |item, index| section(index + 1, item) }.join("\n\n")
+    end
+
+    def section(number, item)
+      ["#{HEADING} #{number}",
+       "Title: #{value(item, :title)}",
+       "URL: #{value(item, :link)}",
+       '',
+       value(item, :description)].join("\n")
+    end
+
+    # A field an item does not carry is empty rather than absent, so that every
+    # ARTICLE has the same shape whatever the feed it came from left out.
+    def value(item, name)
+      return '' unless item.respond_to?(name)
+
+      item.public_send(name).to_s.strip
+    end
+  end
+end

data/plugins/filter/claude.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Claude
 # Description:: Replace each item's description with what the Anthropic Claude API answers.
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/clear.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Clear
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/description_link.rb

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::DescriptionLink
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
 # Created::     Oct 03, 2014
-# Updated::     Aug 15, 2026
+# Updated::     Aug 24, 2026
 # Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 
 module Automatic::Plugin
@@ -63,10 +63,27 @@ module Automatic::Plugin
     def fetch_title(url)
       return nil unless Automatic::Http.fetchable?(url)
 
-      Nokogiri::HTML.parse(Automatic::Http.read(url)).xpath('//title').text
+      Nokogiri::HTML.parse(page(url)).xpath('//title').text
     rescue StandardError => e
       Automatic::Log.puts('warn', "Failed in get title for: #{url}, #{e.message}")
       nil
     end
+
+    # The one place this plugin actually reaches the network. `wait` runs in
+    # the `ensure` so that a fetch attempt is waited out whether it succeeded
+    # or raised -- a URL that is not fetchable never gets here at all, and so
+    # never waits.
+    def page(url)
+      Automatic::Http.read(url)
+    ensure
+      wait
+    end
+
+    # `interval` seconds after a real fetch attempt, positive values only. See
+    # doc/PLUGINS.md section 6.3.
+    def wait
+      seconds = @config['interval'].to_i
+      sleep(seconds) if seconds.positive?
+    end
   end
 end

data/plugins/filter/full_feed.rb

@@ -5,7 +5,7 @@
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
 # Created::     Apr 29, 2012
-# Updated::     Aug 15, 2026
+# Updated::     Aug 24, 2026
 # Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 
 module Automatic::Plugin
@@ -17,10 +17,8 @@ module Automatic::Plugin
     SITEINFO_TYPES = %w[SBM INDIVIDUAL IND SUBGENERAL SUB GENERAL GEN].freeze
 
     # One siteinfo record, reduced to the four things a match needs and with
-    # its URL pattern compiled once. The database ships with 3,504 usable
-    # records, so compiling them per item -- which is what matching against
-    # the raw JSON did -- was several thousand `Regexp.new` calls for every
-    # link in every feed.
+    # its URL pattern compiled once. Compiling patterns when the database is
+    # loaded avoids rebuilding regular expressions for every item.
     Entry = Struct.new(:url, :pattern, :xpath, :encoding)
 
     def initialize(config, pipeline = [])
@@ -107,13 +105,10 @@ module Automatic::Plugin
       @siteinfo.find { |record| links.any? { |candidate| record.pattern.match?(candidate) } }
     end
 
-    # The database was last updated in 2013 and 3,448 of its 3,504 records
-    # anchor on a scheme, nearly all of them `^http://`. The sites they name
-    # have since moved to HTTPS, so an https link out of a feed matches none of
-    # them and the filter silently does nothing. Matching the link under either
-    # scheme is what keeps those records reachable; a record is about a site's
-    # layout, not about how it is transported. Only the match is rewritten --
-    # the page is fetched from the link the feed gave.
+    # A stored siteinfo pattern may name HTTP while a current feed supplies HTTPS,
+    # or the reverse. A record describes a site's layout rather than its current
+    # transport scheme, so matching tries both schemes. Only the candidate used
+    # for matching changes; the page is fetched from the original item link.
     def schemes(link)
       case link
       when %r{\Ahttps://} then [link, link.sub(%r{\Ahttps://}, 'http://')]
@@ -150,17 +145,34 @@ module Automatic::Plugin
     # database is full of sites that declare their charset only in a meta tag,
     # and for those the difference is the whole article in mojibake.
     #
-    # A record's own `enc` is the last resort, for a page that declares nothing
-    # anywhere: it was recorded in 2013, and trusting it ahead of what the page
-    # says would break every site that has changed encoding since.
+    # A record's own `enc` is the last resort for a page that declares nothing.
+    # Page declarations take precedence because a site's encoding can change after
+    # a siteinfo record is written.
     def document(link, entry)
-      page, declared = Automatic::Http.open(link) { |io| [io.read, declared_charset?(io)] }
+      page, declared = fetch_page(link)
       parsed = Nokogiri::HTML.parse(StringIO.new(page))
       return parsed if declared || parsed.meta_encoding || entry.encoding.nil?
 
       Nokogiri::HTML.parse(StringIO.new(page), nil, entry.encoding)
     end
 
+    # The one place this plugin actually reaches the network. `wait` runs in
+    # the `ensure` so that a fetch attempt is waited out whether it succeeded
+    # or raised -- an item with no link and an item whose siteinfo did not
+    # match never get here at all, and so never wait.
+    def fetch_page(link)
+      Automatic::Http.open(link) { |io| [io.read, declared_charset?(io)] }
+    ensure
+      wait
+    end
+
+    # `interval` seconds after a real fetch attempt, positive values only. See
+    # doc/PLUGINS.md section 6.3.
+    def wait
+      seconds = @config['interval'].to_i
+      sleep(seconds) if seconds.positive?
+    end
+
     # Whether the response itself named a charset, as opposed to open-uri
     # having settled on one in the absence of an answer.
     def declared_charset?(io)

data/plugins/filter/gemini.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Gemini
 # Description:: Replace each item's description with what the Google Gemini API answers.
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/ignore.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Ignore
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/image.rb

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Image
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com

data/plugins/filter/image_source.rb

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::ImageSource
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
 # Created::     Feb 28, 2012
-# Updated::     Aug 15, 2026
+# Updated::     Aug 24, 2026
 # Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 
 module Automatic::Plugin
@@ -49,12 +49,29 @@ module Automatic::Plugin
     end
 
     def page_images(link)
-      sources(Automatic::Http.read(link), link)
+      sources(page(link), link)
     rescue StandardError => e
       Automatic::Log.puts('warn', "Failed to read images from #{link}: #{e.message}")
       []
     end
 
+    # The one place this plugin actually reaches the network. `wait` runs in
+    # the `ensure` so that a fetch attempt is waited out whether it succeeded
+    # or raised -- an item whose description already had images never gets
+    # here at all, and so never waits.
+    def page(link)
+      Automatic::Http.read(link)
+    ensure
+      wait
+    end
+
+    # `interval` seconds after a real fetch attempt, positive values only. See
+    # doc/PLUGINS.md section 6.3.
+    def wait
+      seconds = @config['interval'].to_i
+      sleep(seconds) if seconds.positive?
+    end
+
     # The images of an HTML fragment, as absolute URLs. This was a scan for
     # `<img src="` before, which found nothing in a document quoting its
     # attributes with apostrophes or writing src after another attribute; the

data/plugins/filter/join.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # Name::        Automatic::Plugin::Filter::Join
 # Description:: Join every item in the pipeline into one item.
-# Author:       id774 (More info: http://id774.net)
+# Author:       id774 (More info: https://id774.net)
 # Source Code:: https://github.com/id774/automaticruby
 # License::     The GPL version 3, or LGPL version 3 (Dual License).
 # Contact::     idnanashi@gmail.com
@@ -87,11 +87,9 @@ module Automatic::Plugin
       item.public_send(name).to_s.strip
     end
 
-    # Built here rather than through FeedMaker.create_pipeline, which drops an
-    # item whose link is nil -- and this item's link is nil deliberately. It is
-    # several articles at once, so there is no page it points at, and putting
-    # the first article's URL there would name a source for text that is not
-    # only from it.
+    # This joined item deliberately has no link. It is several articles at once,
+    # so there is no single page it points at; using the first article's URL would
+    # name a source for text that is not only from it.
     def feed(item_title, item_description)
       RSS::Maker.make('2.0') { |maker|
         maker.channel.title = 'Automatic Ruby'

data/plugins/filter/kimi.rb

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+# Name::        Automatic::Plugin::Filter::Kimi
+# Description:: Replace each item's description with what the Kimi API answers.
+# Author:       id774 (More info: https://id774.net)
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Sep 11, 2026
+# Updated::     Sep 11, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# One transformation: the item's description goes to the Kimi API under the
+# Recipe's prompt, and the answer becomes the item's description. What that
+# transformation is -- a summary, a translation, an extraction, a
+# classification -- is the prompt's business, not this plugin's.
+#
+# Moonshot AI's Kimi offers an OpenAI-compatible chat completions interface,
+# and this plugin is still its own rather than a mode of FilterOpenAI. It is a
+# different service: a different endpoint, a different account, a different
+# set of models, its own limits and its own errors, and any of those may move
+# without OpenAI moving. A Recipe naming FilterKimi says which service the
+# text is sent to, which a `provider:` setting would not.
+#
+# Kimi may return a `reasoning_content` alongside the answer's own `content`.
+# That reasoning is never read, logged or written anywhere by this plugin --
+# only `content` is the answer, and only once `finish_reason` says the model
+# is done.
+#
+# @see https://platform.moonshot.ai/docs/api/chat
+
+module Automatic::Plugin
+  class FilterKimi
+    require 'json'
+    require 'net/http'
+    require 'openssl'
+    require 'uri'
+
+    # The one endpoint the service publishes for this. It is not a setting: an
+    # operator has no version of this plugin that talks to a different host,
+    # and a setting for it would be a way to send the token somewhere else.
+    ENDPOINT = URI('https://api.moonshot.ai/v1/chat/completions')
+
+    OPEN_TIMEOUT = 10
+
+    # Generous, and bounded. A model given several articles thinks for a while;
+    # an unattended run that waits forever is the failure this exists against.
+    READ_TIMEOUT = 300
+
+    # A failure that another attempt will not get past: a setting that is
+    # wrong, a request the service refuses, an answer this plugin cannot read.
+    class Error < StandardError; end
+
+    # A failure that another attempt may get past: the network, a rate limit, a
+    # server error.
+    class TemporaryError < StandardError; end
+
+    def initialize(config, pipeline = [])
+      @config   = config || {}
+      @pipeline = pipeline
+    end
+
+    # Replaces each item's description with the answer. Nothing else about an
+    # item is touched, and the feeds and their items arrive and leave in the
+    # same number and the same order.
+    def run
+      validate_settings
+
+      @pipeline.each { |feeds|
+        next if feeds.nil?
+
+        feeds.items.each { |item| transform(item) }
+      }
+      @pipeline
+    end
+
+    private
+
+    # Checked before the first request, because a Recipe this plugin cannot
+    # carry out is the operator's mistake and will be the same mistake on every
+    # item. The token is never named in a message.
+    def validate_settings
+      raise ArgumentError, 'FilterKimi needs a token' if token.empty?
+      raise ArgumentError, 'FilterKimi needs a model' if model.empty?
+      raise ArgumentError, 'FilterKimi needs a prompt' if prompt.empty?
+    end
+
+    def token
+      @config['token'].to_s
+    end
+
+    def model
+      @config['model'].to_s.strip
+    end
+
+    def prompt
+      @config['prompt'].to_s.strip
+    end
+
+    def transform(item)
+      text = item.description.to_s
+      if text.strip.empty?
+        Automatic::Log.puts('warn', "FilterKimi: nothing to send for #{item.link}")
+        return
+      end
+
+      Automatic::Log.puts('info', "FilterKimi: asking #{model} about #{item.link}")
+      item.description = answer(text)
+    end
+
+    # The retry shape of doc/PLUGINS.md section 3.6, applied only to what
+    # retrying can help. A missing setting, a refused request or an answer in a
+    # shape this plugin cannot read is raised at once: trying again would fail
+    # the same way, more slowly.
+    def answer(text)
+      retries   = 0
+      retry_max = @config['retry'].to_i
+      begin
+        completion(text)
+      rescue TemporaryError => e
+        retries += 1
+        Automatic::Log.puts('error', "ErrorCount: #{retries}, FilterKimi: #{e.message}")
+        if retries <= retry_max
+          sleep(@config['interval'].to_i)
+          retry
+        end
+        raise Error, "FilterKimi gave up after #{retries} attempts: #{e.message}"
+      end
+    end
+
+    def completion(text)
+      # The prompt is the system turn and the description is the user turn it
+      # is applied to. They are separate messages, so that what an article says
+      # is never read as an instruction to this plugin or to the model. Nothing
+      # else -- no sampling or tool-use parameter -- is sent.
+      body = {
+        'model' => model,
+        'messages' => [
+          { 'role' => 'system', 'content' => prompt },
+          { 'role' => 'user', 'content' => text }
+        ]
+      }
+      content(post(JSON.generate(body)))
+    end
+
+    def post(body)
+      request = Net::HTTP::Post.new(ENDPOINT)
+      request['Authorization'] = "Bearer #{token}"
+      request['Content-Type']  = 'application/json'
+      request.body = body
+
+      # TLS with the certificate verified, which is Net::HTTP's own default and
+      # is named here because it is not a thing to be turned off.
+      Net::HTTP.start(ENDPOINT.host, ENDPOINT.port,
+                      use_ssl: true,
+                      verify_mode: OpenSSL::SSL::VERIFY_PEER,
+                      open_timeout: OPEN_TIMEOUT,
+                      read_timeout: READ_TIMEOUT) { |http| http.request(request) }
+    rescue Timeout::Error, SystemCallError, SocketError, IOError,
+           OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
+      raise TemporaryError, "the request to Kimi failed: #{e.message}"
+    end
+
+    def content(response)
+      case response
+      when Net::HTTPSuccess
+        answer_text(parse(response.body))
+      when Net::HTTPTooManyRequests, Net::HTTPServerError
+        raise TemporaryError, "Kimi answered #{response.code}: #{reason(response)}"
+      else
+        raise Error, "Kimi answered #{response.code}: #{reason(response)}"
+      end
+    end
+
+    def parse(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError => e
+      raise Error, "Kimi answered with something that is not JSON: #{e.message}"
+    end
+
+    # The first choice's message content, once the model says it is actually
+    # done. `reasoning_content`, when Kimi sends one alongside `content`, is
+    # never read here: it is not the answer, and it never becomes one. An
+    # answer this plugin cannot find is an error and not an empty description:
+    # a Recipe that published the empty string here would have thrown the
+    # article away and reported success.
+    def answer_text(body)
+      choices = body['choices']
+      unless choices.is_a?(Array) && choices.first.is_a?(Hash)
+        raise Error, 'Kimi answered without a choice'
+      end
+
+      choice  = choices.first
+      message = choice['message']
+      raise Error, 'Kimi answered without a message' unless message.is_a?(Hash)
+      raise Error, "Kimi did not finish: #{choice['finish_reason']}" unless choice['finish_reason'] == 'stop'
+
+      text = message['content'].to_s.strip
+      raise Error, 'Kimi answered with no content' if text.empty?
+
+      text
+    end
+
+    # The service's own explanation where it gave one, the status line
+    # otherwise. Neither carries the token, and the settings are never logged
+    # or raised wholesale.
+    def reason(response)
+      body = JSON.parse(response.body.to_s)
+      error = body['error']
+      return error['message'].to_s if error.is_a?(Hash) && !error['message'].to_s.empty?
+
+      response.message.to_s
+    rescue JSON::ParserError
+      response.message.to_s
+    end
+  end
+end