light-openai-lib 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef80a78645addf631aca9e546f1a94b286c20e455db25c5fd6e11cb02afa40e5
+  data.tar.gz: abcc70421db1ab139dda1af35927ed6f658adbb770f9074f87c3652c9001f871
+SHA512:
+  metadata.gz: b978a4668d93bb222d1facd514a40481e2044c13eba8224cc4cfd325cf733c83a6738921f8c5bf3fe0356efc0b0edc2f166c7971ef432c7218234d202a07c03b
+  data.tar.gz: a4b7eaad0b060ad4d63aafeecb33a7466576f979208620926bc57ff70bd4bb49d6a405c0e88b851b7cbc969224b3fc33fc10686509259d8920100f70f4bcc11f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gaetan Juvin
+
+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,81 @@
+# Light OpenAI Lib
+
+A tiny, dependency-light wrapper for the OpenAI Chat Completions API. It extracts the reusable client that powers several of my Ruby projects and packages it as a gem so it can be reused without copy/paste.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "light-openai-lib"
+```
+
+and run `bundle install`.
+
+If you are not using Bundler install it directly:
+
+```sh
+gem install light-openai-lib
+```
+
+## Usage
+
+```ruby
+require "light/openai"
+
+client = Light::OpenAI::Client.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  logger: Logger.new($stdout)
+)
+
+response = client.chat(
+  model: "gpt-4o-mini",
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Tell me a joke about Ruby." }
+  ],
+  temperature: 0.4
+)
+
+puts response.dig("choices", 0, "message", "content")
+```
+
+Environment variables control sane defaults:
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `OPENAI_CHAT_COMPLETIONS_URL` | API base URL | `https://api.openai.com/v1/chat/completions` |
+| `OPENAI_HTTP_TIMEOUT` | Request timeout in seconds | `900` |
+| `OPENAI_HTTP_RETRIES` | Number of retry attempts | `2` |
+| `OPENAI_HTTP_RETRY_INTERVAL` | Initial retry delay (exponential backoff) | `1.5` |
+
+You can also pass `response_format:` to `#chat` to opt into JSON mode. If the OpenAI API responds with a `response_format` error the client automatically falls back to a standard request and returns the first success payload.
+
+## Examples
+
+This repo carries runnable scripts under `examples/`. The simplest one invokes the client with your OpenAI key:
+
+```sh
+OPENAI_API_KEY=sk-... bundle exec ruby examples/chat.rb "Explain compounding interest like I'm 12"
+```
+
+## Compatibility
+
+- Ruby 3.0+
+- No runtime dependencies besides [`httparty`](https://github.com/jnunemaker/httparty)
+
+## Development
+
+After checking out the repo, run:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+`bin/console` gives you a REPL with the gem loaded. Update the version in `lib/light/openai/version.rb` before publishing, then build and push:
+
+```sh
+bundle exec rake build
+gem push pkg/light-openai-lib-<version>.gem
+```

data/examples/chat.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "light/openai"
+require "logger"
+
+abort "Set OPENAI_API_KEY before running." unless ENV["OPENAI_API_KEY"]
+
+prompt = ARGV.empty? ? "Say hello like a pirate." : ARGV.join(" ")
+model = ENV.fetch("OPENAI_MODEL", "gpt-4o-mini")
+
+client = Light::OpenAI::Client.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  logger: Logger.new($stdout)
+)
+
+messages = [
+  { role: "system", content: "You are a friendly assistant." },
+  { role: "user", content: prompt }
+]
+
+response = client.chat(model: model, messages: messages, temperature: 0.6)
+
+content = response.dig("choices", 0, "message", "content")
+puts(content || "<no response>")

data/lib/base64.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+native_loaded = false
+
+begin
+  require "rbconfig"
+  native_file = File.join(RbConfig::CONFIG["rubylibdir"], "base64.rb")
+  if native_file && File.exist?(native_file)
+    load native_file
+    native_loaded = true
+  end
+rescue LoadError
+  native_loaded = false
+end
+
+require_relative "light/openai/base64_fallback" unless native_loaded

data/lib/bigdecimal.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+native_loaded = false
+
+begin
+  require "rbconfig"
+  native_file = File.join(RbConfig::CONFIG["rubylibdir"], "bigdecimal.rb")
+  if native_file && File.exist?(native_file)
+    load native_file
+    native_loaded = true
+  end
+rescue LoadError
+  native_loaded = false
+end
+
+require_relative "light/openai/bigdecimal_fallback" unless native_loaded

data/lib/light/openai/base64_fallback.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Base64
+  module_function
+
+  def encode64(string)
+    [String(string)].pack("m")
+  end
+
+  def decode64(encoded)
+    String(encoded).unpack1("m")
+  end
+end

data/lib/light/openai/bigdecimal_fallback.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+class BigDecimal
+  def initialize(value, _precision = 0)
+    @value = value
+  end
+
+  def to_f
+    Float(@value)
+  rescue ArgumentError
+    0.0
+  end
+
+  def to_s(*)
+    @value.to_s
+  end
+
+  def to_i
+    to_f.to_i
+  end
+
+  def to_r
+    @value.to_r
+  rescue NoMethodError
+    Rational(to_f)
+  end
+
+  def coerce(other)
+    [self.class.new(other), self]
+  rescue ArgumentError, TypeError
+    [other.to_f, to_f]
+  end
+
+  def ==(other)
+    to_f == other.to_f
+  rescue NoMethodError
+    false
+  end
+
+  def +(other)
+    self.class.new(to_f + other.to_f)
+  end
+
+  def -(other)
+    self.class.new(to_f - other.to_f)
+  end
+
+  def *(other)
+    self.class.new(to_f * other.to_f)
+  end
+
+  def /(other)
+    self.class.new(to_f / other.to_f)
+  end
+
+  def method_missing(method_name, *args, &block)
+    if to_f.respond_to?(method_name)
+      to_f.public_send(method_name, *args, &block)
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(method_name, include_private = false)
+    to_f.respond_to?(method_name, include_private) || super
+  end
+end
+
+module Kernel
+  module_function
+
+  def BigDecimal(value, precision = 0)
+    ::BigDecimal.new(value, precision)
+  end
+end

data/lib/light/openai/client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "base64"
+require "bigdecimal"
+require "json"
+require "httparty"
+require "net/http"
+
+module Light
+  module OpenAI
+    # Minimal chat client that wraps the OpenAI API with retry/backoff logic.
+    class Client
+      DEFAULT_API_URL = ENV.fetch("OPENAI_CHAT_COMPLETIONS_URL", "https://api.openai.com/v1/chat/completions").freeze
+      DEFAULT_TIMEOUT = Integer(ENV.fetch("OPENAI_HTTP_TIMEOUT", 900))
+      DEFAULT_RETRIES = Integer(ENV.fetch("OPENAI_HTTP_RETRIES", 2))
+      DEFAULT_RETRY_INTERVAL = Float(ENV.fetch("OPENAI_HTTP_RETRY_INTERVAL", 1.5))
+
+      def initialize(api_key:, api_url: DEFAULT_API_URL, timeout: DEFAULT_TIMEOUT, retries: DEFAULT_RETRIES, retry_interval: DEFAULT_RETRY_INTERVAL, logger: nil)
+        raise ArgumentError, "api_key is required for OpenAIClient" if api_key.nil? || api_key.empty?
+
+        @api_key = api_key
+        @api_url = api_url
+        @timeout = timeout
+        @retries = [retries.to_i, 0].max
+        @retry_interval = [retry_interval.to_f, 0].max
+        @logger = logger
+      end
+
+      def chat(model:, messages:, temperature: 1, response_format: nil)
+        payload = {
+          model: model,
+          temperature: temperature,
+          messages: messages
+        }
+        payload[:response_format] = response_format if response_format
+
+        request(payload: payload, allow_fallback: !response_format.nil?)
+      end
+
+      private
+
+      def request(payload:, allow_fallback:)
+        attempts = 0
+        max_attempts = @retries + 1
+
+        loop do
+          attempts += 1
+          log_debug("POST #{@api_url} model=#{payload[:model]} (attempt #{attempts}/#{max_attempts})")
+
+          response = nil
+          begin
+            response = HTTParty.post(
+              @api_url,
+              headers: {
+                "Authorization" => "Bearer #{@api_key}",
+                "Content-Type" => "application/json"
+              },
+              body: JSON.dump(payload),
+              timeout: @timeout
+            )
+          rescue HTTParty::Error, SocketError, Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+            if attempts < max_attempts
+              wait = retry_delay(attempts)
+              log_warn("OpenAI API request failed (#{e.class} #{e.message}) on attempt #{attempts}/#{max_attempts}; retrying in #{format('%.2f', wait)}s")
+              sleep(wait)
+              next
+            end
+            raise(StandardError, "OpenAI API request failed after #{attempts} attempts: #{e.class} #{e.message}")
+          end
+
+          if retryable_status?(response.code) && attempts < max_attempts
+            wait = retry_delay(attempts)
+            log_warn("OpenAI API HTTP #{response.code} on attempt #{attempts}/#{max_attempts}; retrying in #{format('%.2f', wait)}s")
+            sleep(wait)
+            next
+          end
+
+          body = nil
+          begin
+            body = parse_body(response.body)
+          rescue JSON::ParserError => e
+            if attempts < max_attempts
+              wait = retry_delay(attempts)
+              log_warn("Failed to parse OpenAI response on attempt #{attempts}/#{max_attempts}: #{e.message}. Retrying in #{format('%.2f', wait)}s")
+              sleep(wait)
+              next
+            end
+            raise(StandardError, "failed to parse OpenAI API response: #{e.message}")
+          end
+
+          if response.code == 400 && allow_fallback
+            message = body.dig("error", "message").to_s
+            if message.match?(/response_format/i)
+              log_warn("response_format unsupported, retrying without JSON schema: #{message}")
+              fallback_payload = payload.dup
+              fallback_payload.delete(:response_format)
+              return request(payload: fallback_payload, allow_fallback: false)
+            end
+          end
+
+          unless response.code.between?(200, 299)
+            error_message = body.dig("error", "message") || response.body
+            raise(StandardError, "OpenAI API error (#{response.code}): #{error_message}")
+          end
+
+          return body
+        end
+      end
+
+      def log_debug(message)
+        @logger&.debug(message)
+      end
+
+      def log_warn(message)
+        @logger&.warn(message)
+      end
+
+      def retryable_status?(code)
+        return false if code.nil?
+
+        code >= 500 || code == 429 || code == 408
+      end
+
+      def retry_delay(attempt)
+        @retry_interval * (2**(attempt - 1))
+      end
+
+      def parse_body(raw_body)
+        return {} if raw_body.to_s.strip.empty?
+
+        JSON.parse(raw_body)
+      end
+    end
+  end
+end

data/lib/light/openai/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Light
+  module OpenAI
+    VERSION = "0.1.0"
+  end
+end

data/lib/light/openai.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "openai/version"
+require_relative "openai/client"
+
+module Light
+  module OpenAI
+    class Error < StandardError; end
+  end
+end
+
+# Backwards compatibility for applications that previously referenced OpenAIClient directly.
+OpenAIClient = Light::OpenAI::Client unless defined?(OpenAIClient)

data/lib/openai_client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "light/openai"

metadata

@@ -0,0 +1,147 @@
+--- !ruby/object:Gem::Specification
+name: light-openai-lib
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gaetan Juvin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-11-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Extracted reusable OpenAI API client that wraps chat completions with
+  sane defaults, logging hooks, and retry/backoff handling.
+email:
+- opensource@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- examples/chat.rb
+- lib/base64.rb
+- lib/bigdecimal.rb
+- lib/light/openai.rb
+- lib/light/openai/base64_fallback.rb
+- lib/light/openai/bigdecimal_fallback.rb
+- lib/light/openai/client.rb
+- lib/light/openai/version.rb
+- lib/openai_client.rb
+homepage: https://github.com/gaetanjuvin/light-openai-lib
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gaetanjuvin/light-openai-lib
+  source_code_uri: https://github.com/gaetanjuvin/light-openai-lib
+  changelog_uri: https://github.com/gaetanjuvin/light-openai-lib
+  bug_tracker_uri: https://github.com/gaetanjuvin/light-openai-lib/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Minimal OpenAI chat completions client with retry logic
+test_files: []