gigachat-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b0549b3d0c559ef154e36cfaa3fed6592068cdfbcf50e5fa29bda9d9167d8e2
+  data.tar.gz: 4264f7de916a13286744a74e2a8dec78c7e1b766dfcc0237d377352094b8ee34
+SHA512:
+  metadata.gz: 51bb690904f272e089051596a55d8d2f6cf558e96c5c9082cf10065a2c5c7bdef069602c556e6a37c507e5b8c6702f0a370dab263c8800eb5b9c94aa4212098d
+  data.tar.gz: f27d1bfa89ed131c70f46633927fbd90e446f72c183675487cdf52eb841e003dbff825ebdf899bc69b19330d1b5de86e2bbfdcfa17d7cd6c473d3ebc27f00262

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-02
+
+### Added
+
+- `GigaChat::Client`:
+  - authentication by OAuth (credentials + scope), static token, user/password or mTLS;
+  - thread-safe token caching with proactive refresh and a single replay on 401.
+- Chat v2 (`client.chat.create` / `client.chat.stream`) and v1 (`client.chat.v1`), with SSE streaming,
+  typed events and accumulated responses.
+- Embeddings, models, files (upload/list/retrieve/delete/content), token counting, balance, AI-text detection,
+  function validation, and batches (create/list/retrieve/results).
+- Lenient typed response objects:
+  - unknown fields are kept;
+  - `request_id` is exposed;
+  - pattern matching is supported.
+- Retries with exponential backoff and `Retry-After` support; a typed error hierarchy.
+- The bundled Russian Trusted Root CA, added to a per-client certificate store.
+- An opt-in live smoke suite (`rake test:live`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Dryzhuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,303 @@
+# gigachat-ruby
+
+Ruby client for Sber's [GigaChat REST API](https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/gigachat-api).
+It covers chat completions (v2 and v1) with streaming, embeddings, files, batches, token counting,
+AI-text detection and function validation.
+
+- Plain Ruby (4.0+). No Rails required.
+- Automatic OAuth token management, retries with backoff, and typed errors.
+- Works out of the box with GigaChat's TLS certificates (see [TLS](#tls)).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "gigachat-ruby"
+```
+
+```ruby
+require "gigachat"
+```
+
+## Quick start
+
+```ruby
+client = GigaChat::Client.new(credentials: ENV["GIGACHAT_CREDENTIALS"], model: "GigaChat-2-Max")
+
+completion = client.chat.create(messages: [{ role: "user", content: "Привет! Расскажи о себе." }])
+puts completion.text
+```
+
+`credentials` is the base64 **Authorization key** from your GigaChat Studio project. The client exchanges it for
+a 30-minute access token, caches the token, and refreshes it before it expires.
+
+## Configuration
+
+Options are resolved in this order: keyword arguments, then `GigaChat.configure`, then `GIGACHAT_*` environment
+variables, then defaults.
+
+```ruby
+GigaChat.configure do |c|
+  c.scope = "GIGACHAT_API_CORP"
+  c.model = "GigaChat-2-Max"
+end
+
+client = GigaChat::Client.new # picks up the global config and GIGACHAT_* variables
+```
+
+| Option | Env var | Default |
+|---|---|---|
+| `credentials` | `GIGACHAT_CREDENTIALS` | — |
+| `scope` | `GIGACHAT_SCOPE` | `GIGACHAT_API_PERS` (also `GIGACHAT_API_B2B`, `GIGACHAT_API_CORP`) |
+| `access_token` | `GIGACHAT_ACCESS_TOKEN` | — (a pre-obtained token) |
+| `user`, `password` | `GIGACHAT_USER`, `GIGACHAT_PASSWORD` | — (the `/token` flow; needs a `base_url` that serves it) |
+| `base_url` | `GIGACHAT_BASE_URL` | `https://api.giga.chat/v1` |
+| `auth_url` | `GIGACHAT_AUTH_URL` | `https://ngw.devices.sberbank.ru:9443/api/v2/oauth` |
+| `model` | `GIGACHAT_MODEL` | — (required for chat and token counting) |
+| `timeout` / `open_timeout` | `GIGACHAT_TIMEOUT` / — | `60` / `10` seconds |
+| `max_retries` | `GIGACHAT_MAX_RETRIES` | `2` |
+| `verify_ssl_certs` | `GIGACHAT_VERIFY_SSL_CERTS` | `true` |
+| `bundled_ca` | — | `true` |
+| `ca_bundle_file` | `GIGACHAT_CA_BUNDLE_FILE` | — |
+| `cert_file`, `key_file`, `key_file_password` | same names, `GIGACHAT_` prefix | — (mTLS) |
+| `client_id`, `session_id` | — | — (sent as `X-Client-ID` / `X-Session-ID`) |
+| `logger` | — | — |
+
+The environment variable names match the official Python SDK, so one `.env` file works for both.
+
+## TLS
+
+GigaChat's certificates chain to the **Russian Trusted Root CA** (Ministry of Digital Development). Ruby's default
+OpenSSL store doesn't include it, so plain HTTPS calls fail with `certificate verify failed`.
+
+This gem ships that root certificate (valid until 2032-02-27; its SHA-256 fingerprint is pinned in the test suite).
+It adds the certificate to a **per-client** certificate store, next to your system roots, so:
+
+- verification stays on;
+- nothing changes for other HTTPS connections in your process.
+
+Options:
+
+- `bundled_ca: false` uses only the system store, for example when your OS image already trusts the root.
+- `ca_bundle_file: "/path/to/ca.pem"` adds more trusted CAs; they are appended, never replacing the defaults.
+- `verify_ssl_certs: false` disables verification. Use it only for debugging; the client logs a warning.
+
+## Chat (v2)
+
+```ruby
+completion = client.chat.create(
+  messages: [
+    { role: "system", content: "Ты — профессиональный переводчик на английский язык." },
+    { role: "user", content: "GigaChat — это сервис для диалога с пользователем." }
+  ],
+  model_options: { temperature: 0.3 }
+)
+
+completion.text                # assistant text
+completion.usage.total_tokens
+completion.finish_reason       # "stop", "length", "function_call", ...
+completion.request_id          # x-request-id, useful for support tickets
+```
+
+`content: "text"` is shorthand for v2 content parts (`[{ text: "text" }]`). Any other keyword (`tools`,
+`tool_config`, `model_options`, `user_info`, `ranker_options`, …) is sent to the API as is.
+
+Keep the history by passing previous messages back, including response objects:
+
+```ruby
+history = [{ role: "user", content: "Привет!" }]
+reply = client.chat.create(messages: history)
+history += [reply.message, { role: "user", content: "Расскажи анекдот" }]
+client.chat.create(messages: history)
+```
+
+### Streaming
+
+```ruby
+# A block streams events and returns the accumulated completion.
+final = client.chat.stream(messages: [{ role: "user", content: "Напиши стих" }]) do |event|
+  print event.text if event.delta?
+end
+final.usage
+
+# Without a block you get a lazy, single-use stream.
+stream = client.chat.stream(messages: [{ role: "user", content: "Напиши стих" }])
+stream.text.each { print it } # text deltas only
+stream.response               # accumulated completion
+```
+
+Breaking out of the block closes the connection.
+
+### Function calling
+
+```ruby
+weather = {
+  name: "weather_forecast",
+  description: "Weather forecast for a city",
+  parameters: { type: "object", properties: { location: { type: "string" } }, required: ["location"] }
+}
+tools = [{ functions: { specifications: [weather] } }]
+messages = [{ role: "user", content: "Какая погода в Туле?" }]
+
+first = client.chat.create(messages:, tools:)
+if (call = first.function_call)
+  result = { temperature: 12 } # call your code with call.arguments (a Hash)
+  messages += [
+    first.message, # carries tool_state_id, which ties the result to this call
+    { role: "tool", content: [{ function_result: { name: call.name, result: JSON.generate(result) } }] }
+  ]
+  puts client.chat.create(messages:, tools:).text
+end
+```
+
+Pass the assistant message back unchanged: it carries the `tool_state_id` the API returned (also readable as
+`first.message.tools_state_id`).
+
+### Structured output
+
+```ruby
+client.chat.create(
+  messages: [{ role: "user", content: "27 октября 2023 года у меня родился сын" }],
+  model_options: {
+    response_format: {
+      type: "json_schema",
+      schema: { type: "object", properties: { date: { type: "string" } }, required: ["date"] },
+      strict: true
+    }
+  }
+)
+```
+
+## Chat (v1)
+
+The original `/chat/completions` API is fully supported:
+
+```ruby
+client.chat.v1.create(messages: [{ role: "user", content: "Привет!" }]).text
+client.chat.v1.stream(messages: [{ role: "user", content: "Привет!" }]) { |chunk| print chunk.text }
+```
+
+## Embeddings
+
+```ruby
+client.embeddings.create(input: ["Первый текст", "Второй текст"]).vectors # model defaults to "Embeddings"
+client.embeddings.create(input: "Текст", model: "EmbeddingsGigaR")
+```
+
+## Models
+
+```ruby
+client.models.list.map(&:id)
+client.models.retrieve("GigaChat-2-Max")
+```
+
+## Files
+
+```ruby
+file = client.files.upload("report.pdf")                      # a path or Pathname
+file = client.files.upload(io, filename: "notes.txt")        # any IO; filename needed when the IO has no path
+client.chat.create(messages: [{ role: "user", content: [{ text: "Summarize", files: [{ id: file.id }] }] }])
+
+client.files.list.map(&:filename)
+client.files.retrieve(file.id)
+client.files.content(image_id)                                # binary String, e.g. a generated image
+client.files.delete(file.id).deleted?
+```
+
+## Token counting and balance
+
+```ruby
+client.tokens_count(input: ["Я к вам пишу — чего же боле?"]).map(&:tokens)
+client.balance.map { [it.usage, it.value] } # prepaid packages only (403 on pay-as-you-go)
+```
+
+## AI-text detection
+
+```ruby
+client.ai_check(input: text, model: "GigaCheckClassification").category # "ai", "human" or "mixed"
+```
+
+## Function validation
+
+```ruby
+result = client.functions.validate(weather)
+result.valid?
+result.warnings.map(&:description)
+```
+
+## Batches
+
+Batches are available on pay-as-you-go (`GIGACHAT_API_CORP`).
+
+```ruby
+requests = [
+  { id: "1", request: { model: "GigaChat-2", messages: [{ role: "user", content: "Привет" }] } }
+]
+batch = client.batches.create(requests, method: :chat_completions) # or method: :embedder
+batch = client.batches.retrieve(batch.id)
+batch.batch_method                                                # "chat_completions"
+client.batches.results(batch) if batch.completed?                 # parsed JSONL lines
+```
+
+The API's `method` field is exposed as `batch_method`, because a `method` reader would shadow Ruby's
+`Object#method`. The raw value is also available as `batch[:method]`.
+
+## Errors
+
+| Status | Error |
+|---|---|
+| 400 | `GigaChat::BadRequestError` |
+| 401 | `GigaChat::AuthenticationError` |
+| 403 | `GigaChat::PermissionDeniedError` |
+| 404 | `GigaChat::NotFoundError` |
+| 413 | `GigaChat::RequestEntityTooLargeError` |
+| 422 | `GigaChat::UnprocessableEntityError` |
+| 429 | `GigaChat::RateLimitError` (`#retry_after`) |
+| 5xx | `GigaChat::ServerError` |
+| network | `GigaChat::APIConnectionError`, `GigaChat::APITimeoutError` |
+
+Every `GigaChat::APIError` carries `#status`, `#body`, `#headers` and `#request_id`. All errors inherit from
+`GigaChat::Error`.
+
+## Retries and timeouts
+
+Retries apply to statuses 429, 500, 502, 503 and 504, to connection failures, and to timeouts on GET requests.
+There are 2 retries by default:
+
+- the delay is exponential with jitter, capped at 8 seconds;
+- `Retry-After` wins over the default delay, capped at 60 seconds;
+- streams are retried only before the first event arrives.
+
+You can override this per call:
+
+```ruby
+client.chat.create(messages:, request_options: { timeout: 300, max_retries: 0, headers: { "X-Client-ID" => "u-1" } })
+client.with_options(session_id: "chat-42").chat.create(messages:) # a copy that reuses the access token
+```
+
+## Logging
+
+```ruby
+client = GigaChat::Client.new(logger: Logger.new($stdout))
+# GigaChat: POST https://api.giga.chat/v2/chat/completions 200 812ms req=…
+```
+
+The log never contains request or response bodies, tokens or credentials.
+
+## Low-level requests
+
+```ruby
+client.request(method: :get, path: "models") # auth, retries and error mapping included
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake            # unit tests + RuboCop
+GIGACHAT_CREDENTIALS=… GIGACHAT_SCOPE=GIGACHAT_API_PERS bundle exec rake test:live   # real API, opt-in
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/lib/gigachat/auth/access_token.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Auth
+    # `expires_at` is Unix time in milliseconds; 0 means "never expires locally" (a static token).
+    AccessToken = Data.define(:access_token, :expires_at) do
+      # The OAuth endpoint returns milliseconds, but /token (`exp`) may return seconds.
+      def self.normalize_ms(value) = value.positive? && value < 1_000_000_000_000 ? value * 1000 : value
+
+      def inspect = "#<#{self.class.name} access_token=[FILTERED] expires_at=#{expires_at}>"
+
+      alias_method :to_s, :inspect
+
+      # Data#pretty_print (used by pp and IRB) ignores #inspect and would print the token.
+      def pretty_print(printer) = printer.text(inspect)
+    end
+  end
+end

data/lib/gigachat/auth/token_manager.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module GigaChat
+  module Auth
+    # Obtains and caches access tokens. Thread-safe: one manager serves every thread of a client.
+    class TokenManager
+      EXPIRY_BUFFER_MS = 60_000
+
+      def initialize(config, transport)
+        @config = config
+        @transport = transport
+        @credentials = clean(config.credentials)
+        @mutex = Mutex.new
+        @token = AccessToken.new(access_token: config.access_token, expires_at: 0) if config.access_token
+      end
+
+      # A usable token, fetched when missing or about to expire; nil when only mTLS is configured.
+      def token
+        current = @token # read once: another thread may invalidate! between the check and the return
+        return current if usable?(current)
+        return unauthenticated unless refreshable?
+
+        @mutex.synchronize { usable?(@token) ? @token : (@token = fetch) }
+      end
+
+      def refreshable? = !@credentials.nil? || !(@config.user.nil? || @config.password.nil?)
+
+      # Drops the token only if it is still the stale one, so a fresh token from another thread survives.
+      def invalidate!(stale)
+        @mutex.synchronize { @token = nil if @token.equal?(stale) }
+      end
+
+      # The default #inspect would print the long-lived credentials.
+      def inspect = "#<#{self.class.name} token=#{@token ? "[FILTERED]" : "nil"}>"
+
+      private
+
+      def usable?(token)
+        !token.nil? && (token.expires_at.zero? || token.expires_at > now_ms + EXPIRY_BUFFER_MS)
+      end
+
+      def now_ms = (Time.now.to_f * 1000).to_i
+
+      def unauthenticated
+        return if @config.cert_file
+
+        raise ConfigurationError, "No authentication configured: set credentials, access_token, " \
+                                  "user/password or cert_file"
+      end
+
+      def fetch
+        response = Internal::Transport.wrap_errors { @credentials ? request_oauth : request_password }
+        token = parse(response)
+        @config.logger&.debug("GigaChat: access token refreshed (expires_at=#{token.expires_at})")
+        token
+      end
+
+      def request_oauth
+        @transport.auth.post do |req|
+          req.headers["Authorization"] = "Basic #{@credentials}"
+          req.headers["RqUID"] = SecureRandom.uuid
+          req.headers["Accept"] = "application/json"
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = URI.encode_www_form(scope: @config.scope)
+        end
+      end
+
+      def request_password
+        basic = ["#{@config.user}:#{@config.password}"].pack("m0")
+        @transport.api.post("token") do |req|
+          req.headers["Authorization"] = "Basic #{basic}"
+          req.headers["Accept"] = "application/json"
+        end
+      end
+
+      def parse(response)
+        body = Internal::Util.parse_json(response.body)
+        raise auth_error(response, body) unless response.success?
+
+        data = body.is_a?(Hash) ? body : {}
+        value = data[:access_token] || data[:tok]
+        expires = data[:expires_at] || data[:exp]
+        unless value && expires
+          raise AuthenticationError.new(status: response.status, body:, headers: response.headers,
+                                        message: "Unexpected token response")
+        end
+
+        AccessToken.new(access_token: value, expires_at: AccessToken.normalize_ms(Integer(expires)))
+      end
+
+      # 4xx from the auth endpoint means bad credentials or scope; 429/5xx stay retryable.
+      def auth_error(response, body)
+        status = response.status
+        return APIError.for(status:, body:, headers: response.headers) if status == 429 || status >= 500
+
+        AuthenticationError.new(status:, body:, headers: response.headers)
+      end
+
+      # Keys copied from the dashboard often carry a "Basic " prefix, and `base64` wraps lines at 76 columns.
+      # Base64 never contains whitespace, so any of it is noise (and a CR/LF would break the header).
+      def clean(credentials)
+        value = credentials.to_s.sub(/\A\s*basic\s+/i, "").gsub(/\s+/, "")
+        value.empty? ? nil : value
+      end
+    end
+  end
+end

data/lib/gigachat/certs/russian_trusted_root_ca.pem

@@ -0,0 +1,33 @@
+-----BEGIN CERTIFICATE-----
+MIIFwjCCA6qgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwcDELMAkGA1UEBhMCUlUx
+PzA9BgNVBAoMNlRoZSBNaW5pc3RyeSBvZiBEaWdpdGFsIERldmVsb3BtZW50IGFu
+ZCBDb21tdW5pY2F0aW9uczEgMB4GA1UEAwwXUnVzc2lhbiBUcnVzdGVkIFJvb3Qg
+Q0EwHhcNMjIwMzAxMjEwNDE1WhcNMzIwMjI3MjEwNDE1WjBwMQswCQYDVQQGEwJS
+VTE/MD0GA1UECgw2VGhlIE1pbmlzdHJ5IG9mIERpZ2l0YWwgRGV2ZWxvcG1lbnQg
+YW5kIENvbW11bmljYXRpb25zMSAwHgYDVQQDDBdSdXNzaWFuIFRydXN0ZWQgUm9v
+dCBDQTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAMfFOZ8pUAL3+r2n
+qqE0Zp52selXsKGFYoG0GM5bwz1bSFtCt+AZQMhkWQheI3poZAToYJu69pHLKS6Q
+XBiwBC1cvzYmUYKMYZC7jE5YhEU2bSL0mX7NaMxMDmH2/NwuOVRj8OImVa5s1F4U
+zn4Kv3PFlDBjjSjXKVY9kmjUBsXQrIHeaqmUIsPIlNWUnimXS0I0abExqkbdrXbX
+YwCOXhOO2pDUx3ckmJlCMUGacUTnylyQW2VsJIyIGA8V0xzdaeUXg0VZ6ZmNUr5Y
+Ber/EAOLPb8NYpsAhJe2mXjMB/J9HNsoFMBFJ0lLOT/+dQvjbdRZoOT8eqJpWnVD
+U+QL/qEZnz57N88OWM3rabJkRNdU/Z7x5SFIM9FrqtN8xewsiBWBI0K6XFuOBOTD
+4V08o4TzJ8+Ccq5XlCUW2L48pZNCYuBDfBh7FxkB7qDgGDiaftEkZZfApRg2E+M9
+G8wkNKTPLDc4wH0FDTijhgxR3Y4PiS1HL2Zhw7bD3CbslmEGgfnnZojNkJtcLeBH
+BLa52/dSwNU4WWLubaYSiAmA9IUMX1/RpfpxOxd4Ykmhz97oFbUaDJFipIggx5sX
+ePAlkTdWnv+RWBxlJwMQ25oEHmRguNYf4Zr/Rxr9cS93Y+mdXIZaBEE0KS2iLRqa
+OiWBki9IMQU4phqPOBAaG7A+eP8PAgMBAAGjZjBkMB0GA1UdDgQWBBTh0YHlzlpf
+BKrS6badZrHF+qwshzAfBgNVHSMEGDAWgBTh0YHlzlpfBKrS6badZrHF+qwshzAS
+BgNVHRMBAf8ECDAGAQH/AgEEMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsF
+AAOCAgEAALIY1wkilt/urfEVM5vKzr6utOeDWCUczmWX/RX4ljpRdgF+5fAIS4vH
+tmXkqpSCOVeWUrJV9QvZn6L227ZwuE15cWi8DCDal3Ue90WgAJJZMfTshN4OI8cq
+W9E4EG9wglbEtMnObHlms8F3CHmrw3k6KmUkWGoa+/ENmcVl68u/cMRl1JbW2bM+
+/3A+SAg2c6iPDlehczKx2oa95QW0SkPPWGuNA/CE8CpyANIhu9XFrj3RQ3EqeRcS
+AQQod1RNuHpfETLU/A2gMmvn/w/sx7TB3W5BPs6rprOA37tutPq9u6FTZOcG1Oqj
+C/B7yTqgI7rbyvox7DEXoX7rIiEqyNNUguTk/u3SZ4VXE2kmxdmSh3TQvybfbnXV
+4JbCZVaqiZraqc7oZMnRoWrXRG3ztbnbes/9qhRGI7PqXqeKJBztxRTEVj8ONs1d
+WN5szTwaPIvhkhO3CO5ErU2rVdUr89wKpNXbBODFKRtgxUT70YpmJ46VVaqdAhOZ
+D9EUUn4YaeLaS8AjSF/h7UkjOibNc4qVDiPP+rkehFWM66PVnP1Msh93tc+taIfC
+EYVMxjh8zNbFuoc7fzvvrFILLe7ifvEIUqSVIC/AzplM/Jxw7buXFeGP1qVCBEHq
+391d/9RAfaZ12zkwFsl+IKwE/OZxW8AHa9i1p4GO0YSNuczzEm4=
+-----END CERTIFICATE-----