ai-lite 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6f864c2c29ee79c0aa144c940fa34a3a4b84189239436cab38fcd1862401726
+  data.tar.gz: 293507b5e1af278ab17658f81f63dc257a7d6ce2b00c79b77d64c6ba1e9fb434
+SHA512:
+  metadata.gz: 77bf79ade3eec73d1cbd06b269dd0d4566d4b06f96d7919dfa74a6f514572ff24fe36a93e65e9e43aa4a369e7c9a3db2e771e5c4419c8e22fc8f19d6f63db1af
+  data.tar.gz: 2033b7e8215841e2b57eb46355cef483e5badc30d56affffd1cd47b7e245442612fee91ec0918fda4828064fca7a7dc62e2268b329730ae0534e8ec07ed16aee

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Basmayor
+
+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,150 @@
+# AI Lite
+
+AI Lite is a pure Ruby, dependency-light client for simple chat-style calls through OpenAI's Responses API.
+
+It is built for Rails apps and plain Ruby projects where installing a full OpenAI SDK is too heavy, incompatible, or unnecessary. It is especially useful in legacy Rails apps where Rails, ActiveSupport, Ruby, or HTTP-client dependency constraints make larger client libraries difficult to add.
+
+Use AI Lite when you want a small OpenAI client that works without tying your app to a specific Rails version or a larger dependency stack.
+
+This gem is intentionally small:
+
+- No Rails dependency
+- No official OpenAI gem dependency
+- No Faraday, HTTParty, ActiveSupport, or connection pool dependency
+- Uses only Ruby stdlib: `Net::HTTP`, `URI`, and `JSON`
+
+It is not meant to replace the official OpenAI SDK. It is a small wrapper for projects that only need one clean interface:
+
+```ruby
+ai.chat("Say hello")
+```
+
+## Usage
+
+```ruby
+require "ai_lite"
+
+ai = AiLite.new
+result = ai.chat("Say hello")
+
+puts result["content"]
+```
+
+By default, the client looks for an API key in `OPENAI_API_KEY`, then falls back to `OPEN_AI_TOKEN`.
+
+You can also pass the key directly:
+
+```ruby
+ai = AiLite.new(api_key: "sk-...")
+```
+
+## Configuration
+
+In Rails, configure the default client from an initializer:
+
+```ruby
+# config/initializers/ai_lite.rb
+AiLite.configure do |config|
+  config.api_key = ENV["OPENAI_API_KEY"]
+  config.model = "gpt-5.5"
+  config.timeout = 120
+  config.max_output_tokens = 2000
+end
+```
+
+Then use the configured singleton-style client:
+
+```ruby
+result = AiLite.chat("Say hello")
+```
+
+You can still instantiate a separate client for another token:
+
+```ruby
+client = AiLite.new(api_key: "sk-other-token")
+result = client.chat("Say hello")
+```
+
+## Chat
+
+```ruby
+result = ai.chat(
+  "Return JSON confirming whether this is valid.",
+  instructions: "Return only minified JSON.",
+  max_output_tokens: 500,
+  options: {
+    text: { verbosity: "low" }
+  }
+)
+```
+
+`chat` sends a `POST` request to `/v1/responses` with:
+
+- `model`
+- `input`
+- `max_output_tokens`
+- optional `instructions`
+- optional `debug`
+- optional extra `options`
+
+The default model is `gpt-5.5`.
+
+The OpenAI API URL is fixed to `https://api.openai.com/v1/responses`.
+
+## Return Shape
+
+`chat` always returns a hash envelope.
+
+Text output:
+
+```ruby
+{
+  "content" => "Hello!",
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
+JSON-looking model output:
+
+```ruby
+{
+  "content" => { "valid" => true },
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
+Failure:
+
+```ruby
+{
+  "content" => nil,
+  "status" => 401,
+  "error" => "Invalid API key",
+  "raw" => nil
+}
+```
+
+Pass `debug: true` to include the raw OpenAI response:
+
+```ruby
+result = ai.chat("Say hello", debug: true)
+
+{
+  "content" => "Hello!",
+  "status" => 200,
+  "error" => nil,
+  "raw" => { ... }
+}
+```
+
+## Development
+
+Run the test suite:
+
+```sh
+ruby -Ilib:test test/ai_lite_test.rb
+```

data/lib/ai_lite/version.rb

@@ -0,0 +1,3 @@
+class AiLite
+  VERSION = "0.1.0".freeze
+end

data/lib/ai_lite.rb

@@ -0,0 +1,165 @@
+require "json"
+require "net/http"
+require "uri"
+require_relative "ai_lite/version"
+
+class AiLite
+  API_BASE_URL = "https://api.openai.com/v1".freeze
+  DEFAULT_MODEL = "gpt-5.5".freeze
+  DEFAULT_TIMEOUT = 120
+  DEFAULT_MAX_OUTPUT_TOKENS = 2000
+
+  class Configuration
+    attr_accessor :api_key, :model, :timeout, :max_output_tokens
+
+    def initialize
+      @api_key = nil
+      @model = DEFAULT_MODEL
+      @timeout = DEFAULT_TIMEOUT
+      @max_output_tokens = DEFAULT_MAX_OUTPUT_TOKENS
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      reset_client!
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      reset_client!
+      configuration
+    end
+
+    def client
+      @client ||= new
+    end
+
+    def chat(message, **kwargs)
+      client.chat(message, **kwargs)
+    end
+
+    def reset_client!
+      @client = nil
+    end
+  end
+
+  attr_reader :api_key, :model, :timeout, :max_output_tokens, :headers
+
+  def initialize(api_key: nil, model: nil, timeout: nil, max_output_tokens: nil)
+    @api_key = api_key || self.class.configuration.api_key || ENV["OPENAI_API_KEY"] || ENV["OPEN_AI_TOKEN"]
+    raise ArgumentError, "Missing OpenAI API key" if @api_key.to_s.strip.empty?
+
+    @model = model || self.class.configuration.model
+    @timeout = timeout || self.class.configuration.timeout
+    @max_output_tokens = max_output_tokens || self.class.configuration.max_output_tokens
+    @headers = {
+      "Authorization" => "Bearer #{@api_key}",
+      "Content-Type" => "application/json"
+    }
+  end
+
+  def chat(message, model: nil, instructions: nil, max_output_tokens: nil, debug: false, options: {})
+    payload = options.merge(
+      model: model || self.model,
+      input: message,
+      max_output_tokens: max_output_tokens || self.max_output_tokens
+    )
+    payload[:instructions] = instructions if instructions
+
+    extract_content(post(payload), debug: debug)
+  rescue => e
+    prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
+  end
+
+  private
+
+  def post(payload)
+    uri = URI.parse(response_endpoint)
+    request = Net::HTTP::Post.new(uri)
+
+    headers.each do |key, value|
+      request[key] = value
+    end
+
+    request.body = JSON.generate(payload)
+
+    Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+      http.open_timeout = timeout if http.respond_to?(:open_timeout=)
+      http.read_timeout = timeout if http.respond_to?(:read_timeout=)
+      http.request(request)
+    end
+  end
+
+  def response_endpoint
+    "#{API_BASE_URL}/responses"
+  end
+
+  def extract_content(response, debug: false)
+    status = response.code.to_i
+    parsed_response = JSON.parse(response.body)
+
+    unless success_status?(status)
+      return prettify_data(status: status, error: error_message(parsed_response), raw: parsed_response, debug: debug)
+    end
+
+    raw_content = extract_output_text(parsed_response)
+    content = parse_content(raw_content)
+    prettify_data(status: status, content: content, raw: parsed_response, debug: debug)
+  rescue JSON::ParserError => e
+    prettify_data(status: response_status(response), error: e.message, raw: response&.body, debug: debug)
+  rescue => e
+    prettify_data(status: response_status(response), error: e.message, raw: nil, debug: debug)
+  end
+
+  def extract_output_text(raw)
+    Array(raw["output"]).flat_map do |item|
+      next [] unless item.is_a?(Hash) && item["type"] == "message"
+
+      Array(item["content"]).map do |content|
+        next unless content.is_a?(Hash) && content["type"] == "output_text"
+
+        content["text"]
+      end.compact
+    end.join.strip
+  end
+
+  def parse_content(raw_text)
+    return nil if raw_text.nil? || raw_text.empty?
+
+    JSON.parse(raw_text)
+  rescue JSON::ParserError
+    raw_text
+  end
+
+  def success_status?(status)
+    status >= 200 && status < 300
+  end
+
+  def error_message(raw)
+    if raw.is_a?(Hash)
+      raw.dig("error", "message") || raw["error"] || raw["message"] || raw.to_s
+    else
+      raw.to_s
+    end
+  end
+
+  def response_status(response)
+    response&.code&.to_i || "unknown"
+  end
+
+  def prettify_data(status:, content: nil, error: nil, raw:, debug: false)
+    {
+      "content" => content,
+      "status" => status,
+      "error" => error,
+      "raw" => debug ? raw : nil
+    }
+  end
+end

data/test/ai_lite_test.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class AiLiteTest < Minitest::Test
+  FakeResponse = Struct.new(:code, :body)
+
+  class FakeHttp
+    attr_accessor :open_timeout, :read_timeout
+    attr_reader :last_request
+
+    def initialize(response)
+      @response = response
+    end
+
+    def request(request)
+      @last_request = request
+      @response
+    end
+  end
+
+  def setup
+    AiLite.reset_configuration!
+  end
+
+  def test_has_a_version_number
+    refute_nil AiLite::VERSION
+  end
+
+  def test_stores_initializer_config_and_headers
+    with_env("OPENAI_API_KEY" => nil, "OPEN_AI_TOKEN" => nil) do
+      client = AiLite.new(
+        api_key: "explicit-key",
+        model: "gpt-test",
+        timeout: 10
+      )
+
+      assert_equal "explicit-key", client.api_key
+      assert_equal "gpt-test", client.model
+      assert_equal 10, client.timeout
+      assert_equal 2000, client.max_output_tokens
+      assert_equal "Bearer explicit-key", client.headers["Authorization"]
+      assert_equal "application/json", client.headers["Content-Type"]
+    end
+  end
+
+  def test_configure_sets_defaults_for_client
+    with_env("OPENAI_API_KEY" => nil, "OPEN_AI_TOKEN" => nil) do
+      AiLite.configure do |config|
+        config.api_key = "configured-key"
+        config.model = "gpt-config"
+        config.timeout = 15
+        config.max_output_tokens = 750
+      end
+
+      client = AiLite.client
+
+      assert_equal "configured-key", client.api_key
+      assert_equal "gpt-config", client.model
+      assert_equal 15, client.timeout
+      assert_equal 750, client.max_output_tokens
+      assert_same client, AiLite.client
+    end
+  end
+
+  def test_configure_resets_cached_client
+    AiLite.configure { |config| config.api_key = "first-key" }
+    first_client = AiLite.client
+
+    AiLite.configure { |config| config.api_key = "second-key" }
+    second_client = AiLite.client
+
+    refute_same first_client, second_client
+    assert_equal "second-key", second_client.api_key
+  end
+
+  def test_instance_arguments_override_configuration
+    AiLite.configure do |config|
+      config.api_key = "configured-key"
+      config.model = "gpt-config"
+      config.timeout = 15
+      config.max_output_tokens = 750
+    end
+
+    client = AiLite.new(
+      api_key: "explicit-key",
+      model: "gpt-explicit",
+      timeout: 5,
+      max_output_tokens: 300
+    )
+
+    assert_equal "explicit-key", client.api_key
+    assert_equal "gpt-explicit", client.model
+    assert_equal 5, client.timeout
+    assert_equal 300, client.max_output_tokens
+  end
+
+  def test_api_key_fallback_order
+    with_env("OPENAI_API_KEY" => "openai-key", "OPEN_AI_TOKEN" => "legacy-key") do
+      assert_equal "openai-key", AiLite.new.api_key
+      assert_equal "explicit-key", AiLite.new(api_key: "explicit-key").api_key
+    end
+
+    with_env("OPENAI_API_KEY" => nil, "OPEN_AI_TOKEN" => "legacy-key") do
+      assert_equal "legacy-key", AiLite.new.api_key
+    end
+  end
+
+  def test_configured_api_key_takes_precedence_over_env
+    AiLite.configure { |config| config.api_key = "configured-key" }
+
+    with_env("OPENAI_API_KEY" => "openai-key", "OPEN_AI_TOKEN" => "legacy-key") do
+      assert_equal "configured-key", AiLite.new.api_key
+      assert_equal "explicit-key", AiLite.new(api_key: "explicit-key").api_key
+    end
+  end
+
+  def test_missing_api_key_raises
+    with_env("OPENAI_API_KEY" => nil, "OPEN_AI_TOKEN" => nil) do
+      assert_raises(ArgumentError) { AiLite.new }
+    end
+  end
+
+  def test_chat_sends_post_to_responses_with_default_payload
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Hello!")) do |captured, _response|
+      result = client.chat("Say hello")
+      request = captured[:http].last_request
+      payload = JSON.parse(request.body)
+
+      assert_equal "Hello!", result["content"]
+      assert_equal 200, result["status"]
+      assert_nil result["error"]
+      assert_nil result["raw"]
+      assert_equal "api.openai.com", captured[:host]
+      assert_equal 443, captured[:port]
+      assert_equal true, captured[:use_ssl]
+      assert_instance_of Net::HTTP::Post, request
+      assert_equal "/v1/responses", request.path
+      assert_equal "Bearer token-abc", request["Authorization"]
+      assert_equal "application/json", request["Content-Type"]
+      assert_equal "gpt-5.5", payload["model"]
+      assert_equal "Say hello", payload["input"]
+      assert_equal 2000, payload["max_output_tokens"]
+    end
+  end
+
+  def test_chat_allows_overriding_max_output_tokens
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Short")) do |captured, _response|
+      client.chat("Summarize", max_output_tokens: 500)
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal 500, payload["max_output_tokens"]
+    end
+  end
+
+  def test_chat_uses_configured_max_output_tokens
+    AiLite.configure do |config|
+      config.api_key = "configured-key"
+      config.max_output_tokens = 750
+    end
+
+    with_stubbed_http(success_response("Configured")) do |captured, _response|
+      AiLite.chat("Use configured defaults")
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal 750, payload["max_output_tokens"]
+      assert_equal "Bearer configured-key", captured[:http].last_request["Authorization"]
+    end
+  end
+
+  def test_chat_includes_instructions_model_and_options
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Aye")) do |captured, _response|
+      client.chat(
+        "Are semicolons optional in JavaScript?",
+        model: "gpt-5.4-mini",
+        instructions: "Be concise.",
+        options: {
+          reasoning: { effort: "none" },
+          text: { verbosity: "low" },
+          store: false
+        }
+      )
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "gpt-5.4-mini", payload["model"]
+      assert_equal "Be concise.", payload["instructions"]
+      assert_equal({ "effort" => "none" }, payload["reasoning"])
+      assert_equal({ "verbosity" => "low" }, payload["text"])
+      assert_equal false, payload["store"]
+    end
+  end
+
+  def test_extracts_text_from_nested_output_text_items
+    client = AiLite.new(api_key: "token-abc")
+    body = JSON.generate(
+      "output" => [
+        { "type" => "reasoning", "content" => [] },
+        {
+          "type" => "message",
+          "content" => [
+            { "type" => "output_text", "text" => "Hello" },
+            { "type" => "output_text", "text" => " world" }
+          ]
+        }
+      ]
+    )
+
+    with_stubbed_http(FakeResponse.new("200", body)) do |_captured, _response|
+      result = client.chat("Say hello")
+
+      assert_equal "Hello world", result["content"]
+      assert_equal 200, result["status"]
+      assert_nil result["error"]
+    end
+  end
+
+  def test_parses_json_looking_output_with_string_keys
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response(JSON.generate("valid" => true))) do |_captured, _response|
+      result = client.chat("Validate")
+
+      assert_equal({ "valid" => true }, result["content"])
+      assert_equal 200, result["status"]
+      assert_nil result["error"]
+      assert_nil result["raw"]
+    end
+  end
+
+  def test_debug_true_returns_raw_success_response
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Hello!")) do |_captured, _response|
+      result = client.chat("Say hello", debug: true)
+
+      assert_equal "Hello!", result["content"]
+      assert_equal 200, result["status"]
+      assert_nil result["error"]
+      assert_equal(
+        [
+          {
+            "type" => "message",
+            "content" => [
+              { "type" => "output_text", "text" => "Hello!" }
+            ]
+          }
+        ],
+        result["raw"]["output"]
+      )
+    end
+  end
+
+  def test_http_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+    body = JSON.generate("error" => { "message" => "Invalid API key" })
+
+    with_stubbed_http(FakeResponse.new("401", body)) do |_captured, _response|
+      result = client.chat("Say hello")
+
+      assert_nil result["content"]
+      assert_equal 401, result["status"]
+      assert_equal "Invalid API key", result["error"]
+      assert_nil result["raw"]
+    end
+  end
+
+  def test_debug_true_returns_raw_http_error_response
+    client = AiLite.new(api_key: "token-abc")
+    body = JSON.generate("error" => { "message" => "Invalid API key" })
+
+    with_stubbed_http(FakeResponse.new("401", body)) do |_captured, _response|
+      result = client.chat("Say hello", debug: true)
+
+      assert_nil result["content"]
+      assert_equal 401, result["status"]
+      assert_equal "Invalid API key", result["error"]
+      assert_equal({ "error" => { "message" => "Invalid API key" } }, result["raw"])
+    end
+  end
+
+  def test_response_parse_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(FakeResponse.new("200", "not-json")) do |_captured, _response|
+      result = client.chat("Say hello")
+
+      assert_nil result["content"]
+      assert_equal 200, result["status"]
+      assert_match(/unexpected token|unexpected character|parse/i, result["error"])
+      assert_nil result["raw"]
+    end
+  end
+
+  def test_debug_true_returns_raw_response_parse_error_body
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(FakeResponse.new("200", "not-json")) do |_captured, _response|
+      result = client.chat("Say hello", debug: true)
+
+      assert_nil result["content"]
+      assert_equal 200, result["status"]
+      assert_match(/unexpected token|unexpected character|parse/i, result["error"])
+      assert_equal "not-json", result["raw"]
+    end
+  end
+
+  def test_network_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+    original_start = Net::HTTP.method(:start)
+
+    Net::HTTP.singleton_class.send(:define_method, :start) do |_host, _port, use_ssl:, &_block|
+      raise IOError, "connection failed"
+    end
+
+    result = client.chat("Say hello")
+
+    assert_nil result["content"]
+    assert_equal "unknown", result["status"]
+    assert_equal "connection failed", result["error"]
+    assert_nil result["raw"]
+  ensure
+    Net::HTTP.singleton_class.send(:define_method, :start, original_start)
+  end
+
+  private
+
+  def success_response(content)
+    body = JSON.generate(
+      "output" => [
+        {
+          "type" => "message",
+          "content" => [
+            { "type" => "output_text", "text" => content }
+          ]
+        }
+      ]
+    )
+    FakeResponse.new("200", body)
+  end
+
+  def with_env(values)
+    originals = {}
+
+    values.each do |key, value|
+      originals[key] = ENV.key?(key) ? ENV[key] : :missing
+      value.nil? ? ENV.delete(key) : ENV[key] = value
+    end
+
+    yield
+  ensure
+    originals.each do |key, value|
+      value == :missing ? ENV.delete(key) : ENV[key] = value
+    end
+  end
+
+  def with_stubbed_http(response)
+    captured = {}
+    original_start = Net::HTTP.method(:start)
+
+    Net::HTTP.singleton_class.send(:define_method, :start) do |host, port, use_ssl:, &block|
+      http = FakeHttp.new(response)
+      captured[:host] = host
+      captured[:port] = port
+      captured[:use_ssl] = use_ssl
+      captured[:http] = http
+      block.call(http)
+    end
+
+    yield captured, response
+  ensure
+    Net::HTTP.singleton_class.send(:define_method, :start, original_start)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "minitest/autorun"
+require "ai_lite"

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: ai-lite
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- William Basmayor
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-13 00:00:00.000000000 Z
+dependencies: []
+description: AI Lite is a dependency-light Ruby client for Rails apps and plain Ruby
+  projects that need simple OpenAI Responses API calls.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ai_lite.rb
+- lib/ai_lite/version.rb
+- test/ai_lite_test.rb
+- test/test_helper.rb
+homepage: https://github.com/wbasmayor/ai-lite
+licenses:
+- MIT
+metadata: {}
+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.5.22
+signing_key:
+specification_version: 4
+summary: Minimal Ruby client for simple AI chat calls through the OpenAI Responses
+  API.
+test_files: []