gigachat-ruby 0.1.0

data/lib/gigachat/internal/transport.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Builds the Faraday connections (API and OAuth) with TLS settings and default headers.
+    class Transport
+      CA_FILE = File.expand_path("../certs/russian_trusted_root_ca.pem", __dir__)
+      USER_AGENT = "gigachat-ruby/#{VERSION} ruby/#{RUBY_VERSION}".freeze
+      X_HEADERS = %w[x-request-id x-session-id x-client-id].freeze
+      TLS_HINT = "GigaChat certificates chain to the Russian Trusted Root CA; " \
+                 "see the TLS section of the gigachat-ruby README"
+
+      def self.wrap_errors
+        yield
+      rescue Faraday::TimeoutError => e
+        raise APITimeoutError, e.message
+      rescue Faraday::SSLError => e
+        raise APIConnectionError, "#{e.message}. #{TLS_HINT}"
+      rescue Faraday::ConnectionFailed => e
+        raise APIConnectionError, e.message
+      end
+
+      def self.x_headers(headers) = X_HEADERS.to_h { [it, headers[it]] }.compact
+
+      @cert_stores = {}
+      @cert_stores_lock = Mutex.new
+
+      # System roots plus the bundled Russian root (and an optional extra bundle); additions never replace.
+      # Loading the system roots takes ~3 ms, so clients with the same CA settings share one store. A CA file
+      # replaced on disk is picked up after a restart.
+      def self.cert_store(bundled_ca:, ca_bundle_file:)
+        @cert_stores_lock.synchronize do
+          @cert_stores[[bundled_ca, ca_bundle_file]] ||= OpenSSL::X509::Store.new.tap do |store|
+            store.set_default_paths
+            store.add_file(CA_FILE) if bundled_ca
+            add_ca_bundle(store, ca_bundle_file) if ca_bundle_file
+          end
+        end
+      end
+
+      def self.add_ca_bundle(store, path)
+        store.add_file(path)
+      rescue OpenSSL::X509::StoreError => e
+        raise ConfigurationError, "Cannot load ca_bundle_file #{path}: #{e.message}"
+      end
+      private_class_method :add_ca_bundle
+
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+        warn_insecure unless config.verify_ssl_certs
+      end
+
+      def api = @api ||= connection(base_url, client_cert: true)
+
+      def auth = @auth ||= connection(config.auth_url)
+
+      def base_url = @base_url ||= config.base_url.end_with?("/") ? config.base_url : "#{config.base_url}/"
+
+      # v2 chat lives next to the versioned base path: .../v1/ -> .../v2/chat/completions.
+      def chat_v2_url = @chat_v2_url ||= "#{base_url.sub(%r{/v\d+/\z}, "/")}v2/chat/completions"
+
+      def cert_store
+        @cert_store ||= self.class.cert_store(bundled_ca: config.bundled_ca, ca_bundle_file: config.ca_bundle_file)
+      end
+
+      private
+
+      def connection(url, client_cert: false)
+        request = { timeout: config.timeout, open_timeout: config.open_timeout, write_timeout: config.timeout }
+        Faraday.new(url:, headers: default_headers, ssl: ssl_options(client_cert), request:) do |f|
+          f.request :multipart
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def default_headers
+        { "User-Agent" => USER_AGENT, "X-Client-ID" => config.client_id, "X-Session-ID" => config.session_id }.compact
+      end
+
+      def ssl_options(client_cert)
+        options = { verify: config.verify_ssl_certs, cert_store: }
+        return options unless client_cert && config.cert_file
+
+        options[:client_cert] = OpenSSL::X509::Certificate.new(File.read(config.cert_file))
+        if config.key_file
+          options[:client_key] = OpenSSL::PKey.read(File.read(config.key_file), config.key_file_password)
+        end
+        options
+      end
+
+      def warn_insecure
+        message = "GigaChat: TLS certificate verification is disabled (verify_ssl_certs: false)"
+        config.logger ? config.logger.warn(message) : Kernel.warn(message)
+      end
+    end
+  end
+end

data/lib/gigachat/internal/util.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    module Util
+      module_function
+
+      # Parses JSON into symbol-keyed data. Proxies and gateways return HTML or empty bodies on errors,
+      # so anything that is not JSON comes back as the (UTF-8) text itself.
+      def parse_json(text)
+        string = text.to_s.dup.force_encoding(Encoding::UTF_8)
+        string = string.scrub unless string.valid_encoding? # e.g. a Windows-1251 proxy error page
+        return string if string.strip.empty?
+
+        JSON.parse(string, symbolize_names: true)
+      rescue JSON::ParserError
+        string
+      end
+    end
+  end
+end

data/lib/gigachat/internal/v1_chat_accumulator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Internal
+    # Folds v1 stream chunks into one V1::ChatCompletion, per choice index.
+    class V1ChatAccumulator
+      META = %i[created model object usage].freeze
+
+      def initialize
+        @meta = {}
+        @choices = {}
+      end
+
+      def <<(chunk)
+        @meta.merge!(chunk.to_h.slice(*META).compact)
+        (chunk.choices || []).each { merge_choice(it) }
+        self
+      end
+
+      def result(x_headers: {})
+        choices = @choices.sort.map { |index, choice| choice.merge(index:) }
+        Types::V1::ChatCompletion.new({ **@meta, choices: }, x_headers:)
+      end
+
+      private
+
+      def merge_choice(choice)
+        entry = @choices[choice.index || 0] ||= { message: { role: "assistant", content: +"" } }
+        entry[:finish_reason] = choice.finish_reason if choice.finish_reason
+        delta = choice.delta
+        return if delta.nil? || delta.role == "function_in_progress" # built-in function progress, not content
+
+        message = entry[:message]
+        message[:content] << delta.content.to_s
+        message[:role] = delta.role if delta.role
+        message[:function_call] = delta[:function_call] if delta[:function_call]
+        message[:functions_state_id] = delta.functions_state_id if delta.functions_state_id
+      end
+    end
+  end
+end

data/lib/gigachat/resources/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    # Shared plumbing for resource classes: they only build bodies and pick response types.
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def escape(segment) = URI.encode_uri_component(segment.to_s)
+
+      def reject_stream_flag!(params)
+        raise ArgumentError, "Use #stream for streaming; #create does not accept stream: true" if params[:stream]
+      end
+
+      # Block given: iterate now and return the accumulated response. No block: return the lazy stream.
+      def build_stream(protocol:, path:, body:, request_options:, &block)
+        stream = GigaChat::Stream.new(protocol:) do |&on_chunk|
+          @client.request_stream(path:, body: body.merge(stream: true), request_options:, &on_chunk)
+        end
+        return stream unless block
+
+        stream.each(&block)
+        stream.response
+      end
+    end
+  end
+end

data/lib/gigachat/resources/batches.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    # Asynchronous batch processing (pay-as-you-go/CORP only).
+    class Batches < Base
+      METHODS = %w[chat_completions embedder].freeze
+
+      def create(input, method:, request_options: {})
+        kind = method.to_s
+        raise ArgumentError, "method: must be one of #{METHODS.join(", ")}" unless METHODS.include?(kind)
+
+        @client.request(method: :post, path: "batches", query: { method: kind }, body: jsonl(input),
+                        headers: { "Content-Type" => "application/octet-stream" }, type: Types::Batch,
+                        request_options:)
+      end
+
+      def list(request_options: {})
+        @client.request(method: :get, path: "batches", type: Types::BatchList, request_options:)
+      end
+
+      def retrieve(id, request_options: {})
+        found = @client.request(method: :get, path: "batches", query: { batch_id: id }, type: Types::BatchList,
+                                request_options:)
+        return Types::Batch.new(found.to_h, x_headers: found.x_headers) if found[:id]
+
+        found.first || raise(NotFoundError.new(status: 404, body: found.to_h, headers: found.x_headers,
+                                               message: "Batch #{id} not found"))
+      end
+
+      # Downloads the batch output (JSONL) and parses one Hash per non-empty line.
+      def results(batch, request_options: {})
+        file_id = batch.is_a?(Types::Batch) ? batch.output_file_id : batch.to_s
+        raise Error, "The batch has no output file yet" if file_id.to_s.empty?
+
+        @client.files.content(file_id, request_options:).force_encoding(Encoding::UTF_8).each_line.filter_map do |line|
+          JSON.parse(line, symbolize_names: true) unless line.strip.empty?
+        end
+      end
+
+      private
+
+      def jsonl(input)
+        case input
+        when Array then input.map { "#{JSON.generate(it)}\n" }.join
+        when String, Pathname then File.binread(input)
+        else
+          raise ArgumentError, "input must be an Array of requests, a path or an IO" unless input.respond_to?(:read)
+
+          input.read
+        end
+      end
+    end
+  end
+end

data/lib/gigachat/resources/chat.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    # Chat completions v2 (primary API). v1 lives under #v1.
+    class Chat < Base
+      attr_reader :v1
+
+      def initialize(client)
+        super
+        @v1 = ChatV1.new(client)
+      end
+
+      def create(messages:, model: nil, request_options: {}, **params)
+        reject_stream_flag!(params)
+        @client.request(method: :post, path: @client.chat_v2_url, body: body(messages, model, params),
+                        type: Types::ChatCompletion, request_options:)
+      end
+
+      def stream(messages:, model: nil, request_options: {}, **params, &)
+        build_stream(protocol: :v2, path: @client.chat_v2_url, body: body(messages, model, params), request_options:, &)
+      end
+
+      private
+
+      def body(messages, model, params)
+        { model: @client.config.resolve_model(model), messages: messages.map { normalize(it) }, **params }
+      end
+
+      # v2 content is an array of parts; accept the familiar `content: "text"` shorthand.
+      def normalize(message)
+        return message unless message.is_a?(Hash)
+
+        key = message.key?(:content) ? :content : "content"
+        case message[key]
+        when String then message.merge(key => [{ text: message[key] }])
+        when Hash then message.merge(key => [message[key]])
+        else message
+        end
+      end
+    end
+  end
+end

data/lib/gigachat/resources/chat_v1.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    # Chat completions v1 (POST /chat/completions). Fully supported, not deprecated.
+    class ChatV1 < Base
+      PATH = "chat/completions"
+
+      def create(messages:, model: nil, request_options: {}, **params)
+        reject_stream_flag!(params)
+        @client.request(method: :post, path: PATH, body: body(messages, model, params),
+                        type: Types::V1::ChatCompletion, request_options:)
+      end
+
+      def stream(messages:, model: nil, request_options: {}, **params, &)
+        build_stream(protocol: :v1, path: PATH, body: body(messages, model, params), request_options:, &)
+      end
+
+      private
+
+      def body(messages, model, params) = { model: @client.config.resolve_model(model), messages:, **params }
+    end
+  end
+end

data/lib/gigachat/resources/embeddings.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    class Embeddings < Base
+      # The chat model from config does not apply here; "Embeddings" matches both official SDKs.
+      def create(input:, model: "Embeddings", request_options: {}, **params)
+        @client.request(method: :post, path: "embeddings", body: { model:, input:, **params },
+                        type: Types::Embeddings, request_options:)
+      end
+    end
+  end
+end

data/lib/gigachat/resources/files.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    class Files < Base
+      def upload(file, purpose: "general", filename: nil, content_type: nil, request_options: {})
+        io, name, owned = open_upload(file, filename)
+        part = Faraday::Multipart::FilePart.new(io, content_type || Internal::MimeTypes.for(name), name)
+        @client.request(method: :post, path: "files", form: { file: part, purpose: }, type: Types::FileObject,
+                        request_options:)
+      ensure
+        io.close if owned && io
+      end
+
+      def list(request_options: {})
+        @client.request(method: :get, path: "files", type: Types::FileList, request_options:)
+      end
+
+      def retrieve(id, request_options: {})
+        @client.request(method: :get, path: "files/#{escape(id)}", type: Types::FileObject, request_options:)
+      end
+
+      # The API deletes with POST /files/{id}/delete, not DELETE.
+      def delete(id, request_options: {})
+        @client.request(method: :post, path: "files/#{escape(id)}/delete", type: Types::FileDeleted, request_options:)
+      end
+
+      def content(id, request_options: {})
+        @client.request(method: :get, path: "files/#{escape(id)}/content", headers: { "Accept" => "*/*" },
+                        binary: true, request_options:)
+      end
+
+      private
+
+      # Returns [io, filename, owned]; `owned` IOs are opened here and closed after the request.
+      def open_upload(file, filename)
+        case file
+        when String, Pathname
+          path = Pathname(file)
+          [path.open("rb"), nfc(filename || path.basename.to_s), true]
+        else
+          raise ArgumentError, "file must be a path or an IO-like object" unless file.respond_to?(:read)
+
+          name = filename || (File.basename(file.path) if file.respond_to?(:path) && file.path)
+          raise ArgumentError, "filename: is required when the IO has no path" if name.to_s.empty?
+
+          [file, nfc(name), false]
+        end
+      end
+
+      # macOS returns NFD names from the file system ("й" as "и" + U+0306); send the composed form.
+      def nfc(name) = name.unicode_normalize(:nfc)
+    end
+  end
+end

data/lib/gigachat/resources/functions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    class Functions < Base
+      # Accepts a function description as a Hash, as keywords, or both (keywords win).
+      def validate(function = nil, request_options: {}, **attributes)
+        body = (function || {}).to_h.merge(attributes)
+        @client.request(method: :post, path: "functions/validate", body:, type: Types::FunctionValidation,
+                        request_options:)
+      end
+    end
+  end
+end

data/lib/gigachat/resources/models.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Resources
+    class Models < Base
+      def list(request_options: {})
+        @client.request(method: :get, path: "models", type: Types::ModelList, request_options:)
+      end
+
+      def retrieve(id, request_options: {})
+        @client.request(method: :get, path: "models/#{escape(id)}", type: Types::Model, request_options:)
+      end
+    end
+  end
+end

data/lib/gigachat/stream.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module GigaChat
+  # A lazily performed chat stream. The HTTP request starts on the first #each; the stream is single-use.
+  # Breaking out of #each closes the connection; #response returns what was accumulated so far.
+  class Stream
+    include Enumerable
+
+    def initialize(protocol:, &requester)
+      @protocol = protocol
+      @requester = requester
+      @accumulator = protocol == :v2 ? Internal::ChatAccumulator.new : Internal::V1ChatAccumulator.new
+      @state = :pending
+      @x_headers = {}
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+      raise Error, "Stream has already been consumed" unless @state == :pending
+
+      @state = :streaming
+      consume(&block)
+      @state = :finished
+      self
+    end
+
+    def text
+      return enum_for(:text) unless block_given?
+
+      each do |event|
+        piece = event.text
+        yield piece unless piece.empty?
+      end
+    end
+
+    def response
+      each { nil } if @state == :pending
+      @accumulator.result(x_headers: @x_headers)
+    end
+
+    private
+
+    def consume(&)
+      decoder = Internal::SSEDecoder.new
+      catch(:done) do
+        @requester.call do |chunk, headers|
+          @x_headers = Internal::Transport.x_headers(headers) if headers && @x_headers.empty?
+          decoder.feed(chunk) { |sse| handle(sse, &) }
+        end
+        decoder.finish { |sse| handle(sse, &) }
+      end
+    end
+
+    def handle(sse)
+      raise_error(sse) if sse.event == "error"
+      return unless (event = parse(sse))
+
+      @accumulator << event
+      yield event
+      throw :done if event.is_a?(Types::ChatEvent) && event.done?
+    end
+
+    def parse(sse)
+      if @protocol == :v1
+        throw :done if sse.data == "[DONE]"
+        Types::V1::ChatCompletionChunk.new(decode(sse))
+      else
+        Types::ChatEvent.new(decode(sse), type: sse.event)
+      end
+    end
+
+    def decode(sse)
+      JSON.parse(sse.data, symbolize_names: true)
+    rescue JSON::ParserError
+      raise APIError.new(status: 200, body: sse.data, headers: @x_headers,
+                         message: "Malformed stream event: #{sse.data[0, 200]}")
+    end
+
+    def raise_error(sse)
+      body = Internal::Util.parse_json(sse.data)
+      status = body.is_a?(Hash) && body[:status].is_a?(Integer) ? body[:status] : 500
+      raise APIError.for(status:, body:, headers: @x_headers)
+    end
+  end
+end

data/lib/gigachat/types/ai_check_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    class AiCheckResult < Base
+      attribute :category
+      attribute :characters
+      attribute :tokens
+      attribute :ai_intervals
+
+      def ai? = category == "ai"
+
+      def human? = category == "human"
+
+      def mixed? = category == "mixed"
+    end
+  end
+end

data/lib/gigachat/types/balance.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    class Balance < Base
+      enumerable :balance, BalanceEntry
+    end
+  end
+end

data/lib/gigachat/types/balance_entry.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    class BalanceEntry < Base
+      attribute :usage
+      attribute :value
+    end
+  end
+end

data/lib/gigachat/types/base.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    # Lenient response object: typed readers for documented fields, raw access for everything else.
+    # The API adds fields without notice, so unknown keys are kept and never raise.
+    class Base
+      class << self
+        def attributes
+          @attributes ||= superclass.respond_to?(:attributes) ? superclass.attributes.dup : {}
+        end
+
+        def attribute(name, type = nil, array: false)
+          attributes[name] = [type, array]
+          define_method(name) { read_attribute(name) }
+        end
+
+        # Declares the list field the object enumerates over.
+        def enumerable(name, type)
+          attribute(name, type, array: true)
+          include Enumerable
+
+          define_method(:each) { |&block| (public_send(name) || []).each(&block) }
+          define_method(:to_h) { @data } # Enumerable#to_h would otherwise shadow Base#to_h
+        end
+
+        def coerce(value)
+          return new(value.to_h) if value.is_a?(Base) && !value.is_a?(self)
+          return new(value) if value.is_a?(Hash)
+
+          value
+        end
+      end
+
+      attr_reader :x_headers
+
+      def initialize(data = {}, x_headers: nil)
+        @data = data.to_h.transform_keys(&:to_sym).freeze
+        @x_headers = x_headers || {}
+        @cache = {}
+      end
+
+      def [](key) = @data[key.to_sym]
+
+      def dig(*keys) = @data.dig(*keys)
+
+      def to_h = @data
+
+      def to_json(*) = @data.to_json(*)
+
+      def deconstruct_keys(keys) = keys ? @data.slice(*keys) : @data
+
+      def request_id = @x_headers["x-request-id"]
+
+      def ==(other) = other.class == self.class && other.to_h == @data
+
+      alias eql? ==
+
+      def hash = [self.class, @data].hash
+
+      def inspect = "#<#{self.class.name} #{@data.inspect}>"
+
+      alias to_s inspect
+
+      private
+
+      def read_attribute(name)
+        return @cache[name] if @cache.key?(name)
+
+        type, array = self.class.attributes.fetch(name)
+        raw = @data[name]
+        @cache[name] =
+          if type.nil? || raw.nil? then raw
+          elsif array then (raw.is_a?(Array) ? raw : [raw]).map { type.coerce(it) }
+          else type.coerce(raw)
+          end
+      end
+    end
+  end
+end

data/lib/gigachat/types/batch.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    class Batch < Base
+      class RequestCounts < Base
+        attribute :total
+        attribute :completed
+        attribute :failed
+      end
+
+      attribute :id
+      attribute :request_counts, RequestCounts
+      attribute :status
+      attribute :output_file_id
+      attribute :created_at
+      attribute :updated_at
+
+      # A `method` reader would shadow Object#method; the raw value stays available via `[:method]`.
+      def batch_method = self[:method]
+
+      def created? = status == "created"
+
+      def in_progress? = status == "in_progress"
+
+      def completed? = status == "completed"
+    end
+  end
+end

data/lib/gigachat/types/batch_list.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Types
+    # GET /batches. The spec documents `{ batches: [...] }`; the JS SDK assumes a bare array, which the
+    # client wraps as `{ data: [...] }`. Both shapes enumerate the same way.
+    class BatchList < Base
+      include Enumerable
+
+      def batches = @batches ||= (self[:batches] || self[:data] || []).map { Batch.coerce(it) }
+
+      def each(&) = batches.each(&)
+
+      def to_h = @data
+    end
+  end
+end