gigachat-ruby 0.1.0

data/lib/gigachat/client.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module GigaChat
+  # Entry point to the GigaChat REST API. Thread-safe: share one instance across threads.
+  class Client
+    AUTH_OPTIONS = %i[credentials scope access_token user password auth_url base_url].freeze
+    REQUEST_OPTIONS = %i[timeout max_retries headers].freeze
+    STREAM_HEADERS = {
+      "Content-Type" => "application/json", "Accept" => "text/event-stream", "Cache-Control" => "no-store"
+    }.freeze
+
+    attr_reader :config
+
+    def initialize(**options)
+      setup(Configuration.resolve(options))
+    end
+
+    # A copy with some options changed. It reuses the cached access token unless an auth option changes.
+    def with_options(**overrides)
+      overrides = overrides.compact
+      config = Configuration.new(@config.to_h.merge(overrides))
+      token_manager = @token_manager unless overrides.keys.intersect?(AUTH_OPTIONS)
+      self.class.allocate.tap { it.send(:setup, config, token_manager:) }
+    end
+
+    # Forces authentication; nil when only mTLS is configured.
+    def token = @token_manager.token
+
+    def balance(request_options: {})
+      request(method: :get, path: "balance", type: Types::Balance, request_options:)
+    end
+
+    def tokens_count(input:, model: nil, request_options: {})
+      body = { model: config.resolve_model(model), input: Array(input) }
+      request(method: :post, path: "tokens/count", body:, type: Types::TokensCountList, request_options:)
+    end
+
+    def ai_check(input:, model:, request_options: {})
+      request(method: :post, path: "ai/check", body: { input:, model: }, type: Types::AiCheckResult, request_options:)
+    end
+
+    def chat = @chat ||= Resources::Chat.new(self)
+
+    def embeddings = @embeddings ||= Resources::Embeddings.new(self)
+
+    def models = @models ||= Resources::Models.new(self)
+
+    def functions = @functions ||= Resources::Functions.new(self)
+
+    def files = @files ||= Resources::Files.new(self)
+
+    def batches = @batches ||= Resources::Batches.new(self)
+
+    # @api private
+    def chat_v2_url = @transport.chat_v2_url
+
+    # @api private
+    # Streaming POST that yields raw SSE bytes and response headers. Retries and the 401 replay happen
+    # only until the first byte reaches the caller, so output is never duplicated.
+    def request_stream(path:, body:, request_options: {}, &on_chunk)
+      options = check_request_options(request_options)
+      headers = STREAM_HEADERS.merge(options[:headers] || {})
+      payload = JSON.generate(body)
+      delivered = false
+      fresh = -> { !delivered }
+      escape = Object.new
+      failure = catch(escape) do
+        return retry_policy(options).run(method: :post, retry_if: fresh) do
+          authenticated(headers, replay: fresh) do |signed|
+            stream_once(path, payload, signed, options) do |chunk, response_headers|
+              delivered = true
+              deliver(on_chunk, chunk, response_headers, escape)
+            end
+          end
+        end
+      end
+      raise failure
+    end
+
+    # Low-level call with auth, retries and error mapping; also the escape hatch for undocumented endpoints.
+    # Hash/Array bodies are sent as JSON and `form:` as multipart. A JSON array response is wrapped as
+    # `{ data: [...] }` before building `type`; `binary: true` returns the raw body as a binary String.
+    def request(method:, path:, query: nil, body: nil, form: nil, headers: {}, type: nil, binary: false,
+                request_options: {})
+      options = check_request_options(request_options)
+      payload, request_headers = encode(body, form, headers.merge(options[:headers] || {}))
+      response = execute(method:, url: path, query:, body: payload, headers: request_headers, options:,
+                         ios: upload_ios(form))
+      build_result(response, type, binary)
+    end
+
+    def inspect = "#<#{self.class.name} base_url=#{config.base_url.inspect} model=#{config.model.inspect}>"
+
+    private
+
+    def setup(config, token_manager: nil)
+      @config = config
+      @transport = Internal::Transport.new(config)
+      @token_manager = token_manager || Auth::TokenManager.new(config, @transport)
+    end
+
+    def check_request_options(options)
+      unknown = options.keys - REQUEST_OPTIONS
+      raise ArgumentError, "Unknown request option(s): #{unknown.join(", ")}" if unknown.any?
+
+      options
+    end
+
+    def encode(body, form, headers)
+      base = { "Accept" => "application/json" }
+      return [form, base.merge(headers)] if form
+      return [body, base.merge(headers)] unless body.is_a?(Hash) || body.is_a?(Array)
+
+      [JSON.generate(body), base.merge("Content-Type" => "application/json").merge(headers)]
+    end
+
+    def upload_ios(form)
+      return [] unless form
+
+      form.values.filter_map { it.io if it.respond_to?(:io) }
+    end
+
+    # Retry loop (outer) -> one 401 replay with a fresh token (inner) -> HTTP call.
+    def execute(method:, url:, query:, body:, headers:, options:, ios: [])
+      replayable = ios.all? { rewindable?(it) }
+      sends = 0
+      retry_policy(options).run(method:, replayable:) do
+        authenticated(headers, replay: -> { replayable }) do |signed|
+          ios.each(&:rewind) if (sends += 1) > 1
+          response = perform(method:, url:, query:, body:, headers: signed, options:)
+          next response if response.success?
+
+          raise APIError.for(status: response.status, body: Internal::Util.parse_json(response.body),
+                             headers: response.headers)
+        end
+      end
+    end
+
+    # Request headers merge after the token so a per-request Authorization wins (spec §4).
+    def authenticated(headers, replay:)
+      token = @token_manager.token
+      yield authorization(token).merge(headers)
+    rescue AuthenticationError => e
+      raise unless e.status == 401 && token && @token_manager.refreshable? && replay.call
+
+      @token_manager.invalidate!(token)
+      yield authorization(@token_manager.token).merge(headers)
+    end
+
+    def authorization(token) = token ? { "Authorization" => "Bearer #{token.access_token}" } : {}
+
+    # With on_data set, Faraday leaves response.body empty, so error bodies are collected here.
+    def stream_once(path, payload, headers, options)
+      sse = nil
+      seen = nil
+      error_body = +"".b
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      on_data = proc do |chunk, _bytes, env|
+        seen = env
+        sse = env.status.between?(200, 299) && event_stream?(env.response_headers) if sse.nil?
+        if sse
+          yield chunk, env.response_headers
+        else
+          error_body << chunk.b
+        end
+      end
+      response = perform(method: :post, url: path, body: payload, headers:, options:, on_data:)
+      seen = nil # perform has logged the request
+      sse = response.success? && event_stream?(response.headers) if sse.nil?
+      raise_stream_failure(response, error_body) unless sse
+      response
+    ensure
+      # A finished stream stops with throw (or the caller breaks), which unwinds past perform's log line.
+      log(:post, path, seen.status, seen.response_headers, started) if seen
+    end
+
+    # Faraday's adapter rescues IOError and SystemCallError raised inside on_data and re-raises them as
+    # ConnectionFailed. Caller exceptions are thrown past it so they surface unchanged and are never retried.
+    def deliver(on_chunk, chunk, headers, escape)
+      on_chunk.call(chunk, headers)
+    rescue StandardError => e
+      throw escape, e
+    end
+
+    def event_stream?(headers) = headers["content-type"].to_s.start_with?("text/event-stream")
+
+    def raise_stream_failure(response, error_body)
+      body = Internal::Util.parse_json(error_body)
+      raise APIError.for(status: response.status, body:, headers: response.headers) unless response.success?
+
+      raise APIError.new(status: response.status, body:, headers: response.headers,
+                         message: "Expected text/event-stream, got #{response.headers["content-type"].inspect}")
+    end
+
+    def perform(method:, url:, headers:, options:, query: nil, body: nil, on_data: nil)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = Internal::Transport.wrap_errors do
+        @transport.api.run_request(method, url, body, headers) do |req|
+          query&.each { |key, value| req.params[key.to_s] = value }
+          req.options.timeout = options[:timeout] if options[:timeout]
+          req.options.on_data = on_data if on_data
+        end
+      end
+      log(method, url, response.status, response.headers, started)
+      response
+    end
+
+    def build_result(response, type, binary)
+      return response.body.to_s.b if binary
+
+      parsed = Internal::Util.parse_json(response.body)
+      return parsed unless type
+
+      parsed = { data: parsed } if parsed.is_a?(Array)
+      unless parsed.is_a?(Hash)
+        raise APIError.new(status: response.status, body: parsed, headers: response.headers,
+                           message: "Unexpected non-JSON response")
+      end
+
+      type.new(parsed, x_headers: Internal::Transport.x_headers(response.headers))
+    end
+
+    def retry_policy(options)
+      Internal::RetryPolicy.new(max_retries: options.fetch(:max_retries, config.max_retries), logger: config.logger)
+    end
+
+    # Pipes and sockets cannot seek back, so a retry would resend a half-read body.
+    def rewindable?(io)
+      io.respond_to?(:rewind) && io.respond_to?(:pos) && io.pos.is_a?(Integer)
+    rescue IOError, SystemCallError
+      false
+    end
+
+    def log(method, url, status, headers, started)
+      return unless config.logger
+
+      elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+      config.logger.info("GigaChat: #{method.to_s.upcase} #{url} #{status} #{elapsed}ms " \
+                         "req=#{headers["x-request-id"]}")
+    end
+  end
+end

data/lib/gigachat/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module GigaChat
+  # Client settings. `GigaChat.config` holds global overrides; `Configuration.resolve` builds a client's
+  # effective settings with precedence: explicit options > global config > GIGACHAT_* env > defaults.
+  class Configuration
+    DEFAULTS = {
+      credentials: nil, scope: "GIGACHAT_API_PERS", access_token: nil, user: nil, password: nil,
+      base_url: "https://api.giga.chat/v1", auth_url: "https://ngw.devices.sberbank.ru:9443/api/v2/oauth",
+      model: nil, timeout: 60, open_timeout: 10, max_retries: 2,
+      verify_ssl_certs: true, bundled_ca: true, ca_bundle_file: nil,
+      cert_file: nil, key_file: nil, key_file_password: nil,
+      client_id: nil, session_id: nil, logger: nil
+    }.freeze
+
+    # Same names as the Python SDK, so one .env serves both.
+    ENV_VARS = {
+      credentials: "GIGACHAT_CREDENTIALS", scope: "GIGACHAT_SCOPE", access_token: "GIGACHAT_ACCESS_TOKEN",
+      user: "GIGACHAT_USER", password: "GIGACHAT_PASSWORD", base_url: "GIGACHAT_BASE_URL",
+      auth_url: "GIGACHAT_AUTH_URL", model: "GIGACHAT_MODEL", timeout: "GIGACHAT_TIMEOUT",
+      max_retries: "GIGACHAT_MAX_RETRIES", verify_ssl_certs: "GIGACHAT_VERIFY_SSL_CERTS",
+      ca_bundle_file: "GIGACHAT_CA_BUNDLE_FILE", cert_file: "GIGACHAT_CERT_FILE",
+      key_file: "GIGACHAT_KEY_FILE", key_file_password: "GIGACHAT_KEY_FILE_PASSWORD"
+    }.freeze
+
+    SECRETS = %i[credentials access_token password key_file_password].freeze
+    BOOLEANS = {
+      "true" => true, "1" => true, "yes" => true, "on" => true,
+      "false" => false, "0" => false, "no" => false, "off" => false
+    }.freeze
+
+    DEFAULTS.each_key do |key|
+      define_method(key) { @values[key] }
+      define_method(:"#{key}=") { |value| @values[key] = value }
+    end
+
+    def self.resolve(options = {}, global: GigaChat.config, env: ENV)
+      explicit = options.compact
+      config = new(explicit)
+      DEFAULTS.each do |key, default|
+        next if explicit.key?(key)
+
+        value = global.set?(key) ? global.public_send(key) : from_env(key, env, default)
+        config.public_send(:"#{key}=", value)
+      end
+      config
+    end
+
+    def self.from_env(key, env, default)
+      raw = ENV_VARS[key] && env[ENV_VARS[key]]
+      return default if raw.nil? || raw.strip.empty?
+
+      cast(key, raw)
+    end
+
+    def self.cast(key, raw)
+      case key
+      when :verify_ssl_certs then BOOLEANS.fetch(raw.strip.downcase) { invalid!(key, raw) }
+      when :max_retries then Integer(raw.strip, 10) # base 10: "010" is ten, not octal eight
+      when :timeout then Float(raw.strip)
+      else raw
+      end
+    rescue ArgumentError
+      invalid!(key, raw)
+    end
+
+    def self.invalid!(key, raw)
+      raise ConfigurationError, "Invalid value for #{ENV_VARS[key]}: #{raw.inspect}"
+    end
+
+    private_class_method :from_env, :cast, :invalid!
+
+    def initialize(values = {})
+      unknown = values.keys - DEFAULTS.keys
+      raise ConfigurationError, "Unknown option(s): #{unknown.join(", ")}" if unknown.any?
+
+      @values = values.dup
+    end
+
+    # nil means "not set", as for keyword options: `c.base_url = ENV["PROXY_URL"]` must not wipe the default.
+    def set?(key) = !@values[key].nil?
+
+    def to_h = @values.dup
+
+    def resolve_model(model)
+      model || self.model || raise(ModelNotSpecifiedError, "Pass model: or set a default model (GIGACHAT_MODEL)")
+    end
+
+    def inspect
+      pairs = @values.map { |key, value| "#{key}=#{SECRETS.include?(key) && value ? "[FILTERED]" : value.inspect}" }
+      "#<#{self.class.name} #{pairs.join(", ")}>"
+    end
+  end
+end

data/lib/gigachat/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module GigaChat
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ModelNotSpecifiedError < Error; end
+
+  class APIConnectionError < Error
+    def initialize(message = "Connection error") = super
+  end
+
+  class APITimeoutError < APIConnectionError
+    def initialize(message = "Request timed out") = super
+  end
+
+  # Non-2xx response. `body` is parsed JSON (symbol keys) when possible, otherwise the raw text.
+  class APIError < Error
+    attr_reader :status, :body, :headers
+
+    def self.for(status:, body: nil, headers: {})
+      error_class(status).new(status:, body:, headers:)
+    end
+
+    def self.error_class(status)
+      return ServerError if status >= 500
+
+      {
+        400 => BadRequestError, 401 => AuthenticationError, 403 => PermissionDeniedError,
+        404 => NotFoundError, 413 => RequestEntityTooLargeError, 422 => UnprocessableEntityError,
+        429 => RateLimitError
+      }.fetch(status, APIError)
+    end
+
+    def initialize(status:, body: nil, headers: {}, message: nil)
+      @status = status
+      @body = body
+      @headers = headers || {}
+      super(message || default_message)
+    end
+
+    def request_id = headers["x-request-id"]
+
+    private
+
+    def default_message
+      request = "(request_id: #{request_id})" if request_id
+      [status, detail, request].reject { it.nil? || it.to_s.empty? }.join(" ")
+    end
+
+    # The documented `message`, else the body itself (compact JSON or text), squashed to one short line.
+    def detail
+      text = body.is_a?(Hash) ? body[:message] || JSON.generate(body) : body.to_s
+      text.to_s.strip.gsub(/\s+/, " ")[0, 200]
+    end
+  end
+
+  class BadRequestError < APIError; end
+
+  class AuthenticationError < APIError; end
+
+  class PermissionDeniedError < APIError; end
+
+  class NotFoundError < APIError; end
+
+  class RequestEntityTooLargeError < APIError; end
+
+  class UnprocessableEntityError < APIError; end
+
+  class RateLimitError < APIError
+    # Seconds the server asked us to wait (Retry-After), or nil.
+    def retry_after = Internal::RetryPolicy.retry_after(headers)
+  end
+
+  class ServerError < APIError; end
+end

data/lib/gigachat/internal/chat_accumulator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Folds v2 stream events into one ChatCompletion: text parts are concatenated per message position,
+    # other parts (function calls, files, ...) are appended, and the last non-nil metadata wins.
+    class ChatAccumulator
+      META = %i[model created_at created thread_id message_id finish_reason usage additional_data].freeze
+      # Per-message fields; both state id spellings are kept as sent (see Types::Message#tools_state_id).
+      MESSAGE_KEYS = %i[role message_id tool_state_id tools_state_id].freeze
+
+      def initialize
+        @meta = {}
+        @messages = []
+      end
+
+      def <<(event)
+        return self if event.tool_in_progress? # progress ticks, not content
+
+        @meta.merge!(event.to_h.slice(*META).compact)
+        (event.messages || []).each_with_index { |message, index| merge_message(index, message) }
+        self
+      end
+
+      def result(x_headers: {})
+        Types::ChatCompletion.new({ **@meta, messages: @messages.compact.map { finalize(it) } }, x_headers:)
+      end
+
+      private
+
+      def merge_message(index, message)
+        entry = @messages[index] ||= { text: +"", parts: [] }
+        MESSAGE_KEYS.each { |key| entry[key] = message[key] if message[key] }
+        (message.content || []).each do |part|
+          entry[:text] << part.text if part.text
+          rest = part.to_h.except(:text)
+          entry[:parts] << rest unless rest.empty?
+        end
+      end
+
+      def finalize(entry)
+        content = entry[:text].empty? ? entry[:parts] : [{ text: entry[:text] }, *entry[:parts]]
+        entry.slice(*MESSAGE_KEYS).merge(content:)
+      end
+    end
+  end
+end

data/lib/gigachat/internal/mime_types.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Upload MIME types exactly as the spec's file-storage table lists them (`xlsx` really is
+    # application/vnd.ms-excel there). `jpg` and `tif` are aliases the table does not spell out.
+    module MimeTypes
+      TYPES = {
+        "txt" => "text/plain", "doc" => "application/msword",
+        "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "pdf" => "application/pdf", "epub" => "application/epub", "ppt" => "application/ppt",
+        "pptx" => "application/pptx", "xlsx" => "application/vnd.ms-excel",
+        "jpeg" => "image/jpeg", "jpg" => "image/jpeg", "png" => "image/png", "tiff" => "image/tiff",
+        "tif" => "image/tiff", "bmp" => "image/bmp",
+        "mp4" => "audio/mp4", "mp3" => "audio/mp3", "m4a" => "audio/x-m4a", "wav" => "audio/x-wav",
+        "weba" => "audio/webm", "ogg" => "audio/x-ogg", "opus" => "audio/opus"
+      }.freeze
+      DEFAULT = "application/octet-stream"
+
+      def self.for(filename) = TYPES.fetch(File.extname(filename.to_s).delete_prefix(".").downcase, DEFAULT)
+    end
+  end
+end

data/lib/gigachat/internal/retry_policy.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Decides whether a failed request is retried and how long to wait first.
+    class RetryPolicy
+      RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+      INITIAL_DELAY = 0.5
+      MAX_DELAY = 8.0
+      MAX_RETRY_AFTER = 60.0
+
+      class << self
+        # Injectable so tests can record delays instead of sleeping.
+        attr_writer :sleeper
+
+        def sleeper = @sleeper ||= ->(seconds) { Kernel.sleep(seconds) }
+
+        # Seconds from a Retry-After header (delta-seconds or HTTP-date), capped; nil when absent or invalid.
+        def retry_after(headers)
+          value = headers && headers["retry-after"]
+          return if value.nil? || value.to_s.strip.empty?
+
+          seconds = Float(value, exception: false) || (Time.httpdate(value.to_s) - Time.now)
+          seconds.clamp(0.0, MAX_RETRY_AFTER)
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      def initialize(max_retries:, logger: nil)
+        @max_retries = max_retries.to_i
+        @logger = logger
+      end
+
+      def run(method:, replayable: true, retry_if: nil)
+        attempt = 0
+        begin
+          yield
+        rescue APIError, APIConnectionError => e
+          raise unless attempt < @max_retries && replayable && (retry_if.nil? || retry_if.call)
+          raise unless retryable?(e, method)
+
+          delay = delay_for(e, attempt)
+          @logger&.debug("GigaChat: retry #{attempt + 1}/#{@max_retries} in #{delay.round(2)}s after #{e.class}")
+          self.class.sleeper.call(delay)
+          attempt += 1
+          retry
+        end
+      end
+
+      private
+
+      def retryable?(error, method)
+        case error
+        when APITimeoutError then method.to_s.casecmp?("get") # a timed-out POST may already be billed
+        when APIConnectionError then error.cause.is_a?(Faraday::ConnectionFailed) # never retry TLS errors
+        else RETRYABLE_STATUSES.include?(error.status)
+        end
+      end
+
+      def delay_for(error, attempt)
+        server = self.class.retry_after(error.headers) if error.is_a?(APIError)
+        server || ((INITIAL_DELAY * (2**attempt)).clamp(0.0, MAX_DELAY) * (1 - (0.25 * rand)))
+      end
+    end
+  end
+end

data/lib/gigachat/internal/sse_decoder.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Incremental Server-Sent Events parser (WHATWG). It buffers raw bytes and decodes UTF-8 only on
+    # complete lines, so Cyrillic split across TCP chunks survives.
+    class SSEDecoder
+      Event = Data.define(:event, :data, :id)
+
+      BOM = "\xEF\xBB\xBF".b.freeze
+      CR = 13
+      LF = 10
+
+      def initialize
+        @buffer = +"".b
+        @data = []
+        @event = nil
+        @id = nil
+        @bom_checked = false
+      end
+
+      def feed(chunk, &)
+        @buffer << chunk.b
+        strip_bom
+        while (line = next_line(final: false))
+          process(line, &)
+        end
+      end
+
+      def finish(&)
+        while (line = next_line(final: true))
+          process(line, &)
+        end
+        process(utf8(@buffer), &) unless @buffer.empty?
+        @buffer = +"".b
+        dispatch(&)
+      end
+
+      private
+
+      def strip_bom
+        return if @bom_checked || @buffer.bytesize < BOM.bytesize
+
+        @buffer = @buffer.byteslice(BOM.bytesize..) if @buffer.start_with?(BOM)
+        @bom_checked = true
+      end
+
+      # A lone trailing "\r" may be the first half of "\r\n", so wait for more bytes unless finishing.
+      def next_line(final:)
+        return unless (index = @buffer.index(/[\r\n]/n))
+
+        width = 1
+        if @buffer.getbyte(index) == CR
+          return if index == @buffer.bytesize - 1 && !final
+
+          width = 2 if @buffer.getbyte(index + 1) == LF
+        end
+        line = @buffer.byteslice(0, index)
+        @buffer = @buffer.byteslice((index + width)..)
+        utf8(line)
+      end
+
+      def utf8(bytes) = bytes.dup.force_encoding(Encoding::UTF_8)
+
+      def process(line, &)
+        return dispatch(&) if line.empty?
+        return if line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        value = value.to_s.delete_prefix(" ")
+        case field
+        when "event" then @event = value
+        when "data" then @data << value
+        when "id" then @id = value
+        end
+      end
+
+      def dispatch
+        yield Event.new(event: @event, data: @data.join("\n"), id: @id) unless @data.empty?
+        @event = nil
+        @data = []
+      end
+    end
+  end
+end