ai-lite 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b1ae1b32c854b4f99a6fd8275a375c3d1870c93e5507756c9e6c3089ee220ea
-  data.tar.gz: fafd0e42607277bead469d0628d106af48cf7334ebecb100ca60b5ae5074b47a
+  metadata.gz: 2fbb65bf2c01cdc7950a76cc5a273c0b495174bb9d671f7b5d32d49a79274b34
+  data.tar.gz: e8e909ff9c107f552e1f6a81772b3800bb2b1904bf9a5da50cfe6a2ca2380bd4
 SHA512:
-  metadata.gz: eae14b861938c6a351a1b0430eb8ec03569a41fec7896af012addfb2fb5e4f60d6a28345c2cde6c1b82270ccd40cda21da9db470fa7694a2368930ab3e1f1072
-  data.tar.gz: a31f91cf5db94e669f992b03added0312d287aeb991b327adc3f7703d8cc582e460d26d3e7e2c4692a3a29693f2de6cf9998b4e59be593e7a64569b6fb66758d
+  metadata.gz: ef2a0f01ea606b121b583134f6026c7d23388b3a58732a5a1f197275cb7178d2547ffea5040956955fd39452f944f1703833a4ba4925d0d2314ef2693372b904
+  data.tar.gz: 272108490b47700c06f49fb817d684fa6a2dbd003e02eff35fa59f19db8fe120e41983d941c32a50c640ef6776aee00038bc5ed841bef60cdde04fee854ea0c4

data/README.md

@@ -1,6 +1,6 @@
 # AI Lite
 
-AI Lite is a pure Ruby, dependency-light client for simple chat-style calls through OpenAI's Responses API.
+AI Lite is a pure Ruby, dependency-light client for simple OpenAI API calls.
 
 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.
 
@@ -11,12 +11,13 @@ 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`
+- Uses only Ruby stdlib: `Net::HTTP`, `URI`, `JSON`, and `Base64`
 
-It is not meant to replace the official OpenAI SDK. It is a small wrapper for projects that only need one clean interface:
+It is not meant to replace the official OpenAI SDK. It is a small wrapper for projects that only need a few clean interfaces:
 
 ```ruby
 ai.chat("Say hello")
+ai.moderate("User submitted text")
 ```
 
 ## Usage
@@ -47,6 +48,7 @@ In Rails, configure the default client from an initializer:
 AiLite.configure do |config|
   config.api_key = ENV["OPENAI_API_KEY"]
   config.model = "gpt-5.5"
+  config.moderation_model = "omni-moderation-latest"
   config.timeout = 120
   config.max_output_tokens = 2000
 end
@@ -91,6 +93,57 @@ The default model is `gpt-5.5`.
 
 The OpenAI API URL is fixed to `https://api.openai.com/v1/responses`.
 
+## Moderation
+
+Use `moderate` to classify text or images for potentially harmful content:
+
+```ruby
+result = ai.moderate("User submitted text")
+
+if result["content"]["flagged"]
+  # hide, block, or route to review
+end
+```
+
+`moderate` sends a `POST` request to `/v1/moderations` with:
+
+- `model`
+- `input`
+- optional extra `options`
+
+The default moderation model is `omni-moderation-latest`.
+
+You can pass an image URL:
+
+```ruby
+result = ai.moderate(
+  text: "Profile caption",
+  image_url: "https://example.com/image.png"
+)
+```
+
+Or a local image path:
+
+```ruby
+result = ai.moderate(image_path: "tmp/upload.png")
+```
+
+Local images are read, base64 encoded, and sent as JSON data URLs. They do not use multipart uploads. Supported local image extensions are `.gif`, `.jpeg`, `.jpg`, `.png`, and `.webp`.
+
+You can also pass OpenAI's raw moderation input shape directly:
+
+```ruby
+result = ai.moderate([
+  { type: "text", text: "Caption" },
+  {
+    type: "image_url",
+    image_url: {
+      url: "https://example.com/image.png"
+    }
+  }
+])
+```
+
 ## Multi-Turn Chat
 
 Responses include a `response_id` that can be passed back through `options` as `previous_response_id`:
@@ -110,7 +163,7 @@ puts follow_up["content"]
 
 ## Return Shape
 
-`chat` always returns a hash envelope.
+Methods return a hash envelope.
 
 Text output:
 
@@ -136,6 +189,22 @@ JSON-looking model output:
 }
 ```
 
+Moderation output:
+
+```ruby
+{
+  "content" => {
+    "flagged" => false,
+    "categories" => { ... },
+    "category_scores" => { ... }
+  },
+  "response_id" => "modr_...",
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
 Failure:
 
 ```ruby

data/lib/ai_lite/version.rb

@@ -1,3 +1,3 @@
 class AiLite
-  VERSION = "0.1.1".freeze
+  VERSION = "0.2.0".freeze
 end

data/lib/ai_lite.rb

@@ -1,3 +1,4 @@
+require "base64"
 require "json"
 require "net/http"
 require "uri"
@@ -6,15 +7,24 @@ require_relative "ai_lite/version"
 class AiLite
   API_BASE_URL = "https://api.openai.com/v1".freeze
   DEFAULT_MODEL = "gpt-5.5".freeze
+  DEFAULT_MODERATION_MODEL = "omni-moderation-latest".freeze
   DEFAULT_TIMEOUT = 120
   DEFAULT_MAX_OUTPUT_TOKENS = 2000
+  IMAGE_MIME_TYPES = {
+    ".gif" => "image/gif",
+    ".jpeg" => "image/jpeg",
+    ".jpg" => "image/jpeg",
+    ".png" => "image/png",
+    ".webp" => "image/webp"
+  }.freeze
 
   class Configuration
-    attr_accessor :api_key, :model, :timeout, :max_output_tokens
+    attr_accessor :api_key, :model, :moderation_model, :timeout, :max_output_tokens
 
     def initialize
       @api_key = nil
       @model = DEFAULT_MODEL
+      @moderation_model = DEFAULT_MODERATION_MODEL
       @timeout = DEFAULT_TIMEOUT
       @max_output_tokens = DEFAULT_MAX_OUTPUT_TOKENS
     end
@@ -45,18 +55,23 @@ class AiLite
       client.chat(message, **kwargs)
     end
 
+    def moderate(input = nil, **kwargs)
+      client.moderate(input, **kwargs)
+    end
+
     def reset_client!
       @client = nil
     end
   end
 
-  attr_reader :api_key, :model, :timeout, :max_output_tokens, :headers
+  attr_reader :api_key, :model, :moderation_model, :timeout, :max_output_tokens, :headers
 
-  def initialize(api_key: nil, model: nil, timeout: nil, max_output_tokens: nil)
+  def initialize(api_key: nil, model: nil, moderation_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
+    @moderation_model = moderation_model || self.class.configuration.moderation_model
     @timeout = timeout || self.class.configuration.timeout
     @max_output_tokens = max_output_tokens || self.class.configuration.max_output_tokens
     @headers = {
@@ -78,10 +93,21 @@ class AiLite
     prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
   end
 
+  def moderate(input = nil, model: nil, text: nil, image_url: nil, image_path: nil, debug: false, options: {})
+    payload = options.merge(
+      model: model || moderation_model,
+      input: moderation_input(input, text: text, image_url: image_url, image_path: image_path)
+    )
+
+    extract_moderation(post(payload, endpoint: moderation_endpoint), 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)
+  def post(payload, endpoint: response_endpoint)
+    uri = URI.parse(endpoint)
     request = Net::HTTP::Post.new(uri)
 
     headers.each do |key, value|
@@ -101,6 +127,10 @@ class AiLite
     "#{API_BASE_URL}/responses"
   end
 
+  def moderation_endpoint
+    "#{API_BASE_URL}/moderations"
+  end
+
   def extract_content(response, debug: false)
     status = response.code.to_i
     parsed_response = JSON.parse(response.body)
@@ -130,6 +160,33 @@ class AiLite
     prettify_data(status: response_status(response), error: e.message, raw: nil, debug: debug)
   end
 
+  def extract_moderation(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),
+        response_id: parsed_response["id"],
+        raw: parsed_response,
+        debug: debug
+      )
+    end
+
+    prettify_data(
+      status: status,
+      content: moderation_content(parsed_response),
+      response_id: parsed_response["id"],
+      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"
@@ -150,6 +207,52 @@ class AiLite
     raw_text
   end
 
+  def moderation_input(input, text:, image_url:, image_path:)
+    unless text || image_url || image_path
+      raise ArgumentError, "Missing moderation input" if input.nil?
+
+      return input
+    end
+
+    items = []
+    items.concat(Array(input).map { |value| moderation_input_item(value) }) unless input.nil?
+    items << { type: "text", text: text } if text
+    items << { type: "image_url", image_url: { url: image_url } } if image_url
+    items << { type: "image_url", image_url: { url: image_data_url(image_path) } } if image_path
+    raise ArgumentError, "Missing moderation input" if items.empty?
+
+    items
+  end
+
+  def moderation_input_item(value)
+    case value
+    when String
+      { type: "text", text: value }
+    when Hash
+      value
+    else
+      raise ArgumentError, "Unsupported moderation input item: #{value.class}"
+    end
+  end
+
+  def image_data_url(path)
+    mime_type = image_mime_type(path)
+    "data:#{mime_type};base64,#{Base64.strict_encode64(File.binread(path))}"
+  end
+
+  def image_mime_type(path)
+    IMAGE_MIME_TYPES.fetch(File.extname(path).downcase) do
+      raise ArgumentError, "Unsupported image type for moderation: #{File.extname(path)}"
+    end
+  end
+
+  def moderation_content(raw)
+    results = raw["results"]
+    return nil unless results.is_a?(Array)
+
+    results.length == 1 ? results.first : results
+  end
+
   def success_status?(status)
     status >= 200 && status < 300
   end

data/test/ai_lite_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "test_helper"
+require "tempfile"
 
 class AiLiteTest < Minitest::Test
   FakeResponse = Struct.new(:code, :body)
@@ -37,6 +38,7 @@ class AiLiteTest < Minitest::Test
 
       assert_equal "explicit-key", client.api_key
       assert_equal "gpt-test", client.model
+      assert_equal "omni-moderation-latest", client.moderation_model
       assert_equal 10, client.timeout
       assert_equal 2000, client.max_output_tokens
       assert_equal "Bearer explicit-key", client.headers["Authorization"]
@@ -49,6 +51,7 @@ class AiLiteTest < Minitest::Test
       AiLite.configure do |config|
         config.api_key = "configured-key"
         config.model = "gpt-config"
+        config.moderation_model = "omni-moderation-test"
         config.timeout = 15
         config.max_output_tokens = 750
       end
@@ -57,6 +60,7 @@ class AiLiteTest < Minitest::Test
 
       assert_equal "configured-key", client.api_key
       assert_equal "gpt-config", client.model
+      assert_equal "omni-moderation-test", client.moderation_model
       assert_equal 15, client.timeout
       assert_equal 750, client.max_output_tokens
       assert_same client, AiLite.client
@@ -78,6 +82,7 @@ class AiLiteTest < Minitest::Test
     AiLite.configure do |config|
       config.api_key = "configured-key"
       config.model = "gpt-config"
+      config.moderation_model = "omni-moderation-config"
       config.timeout = 15
       config.max_output_tokens = 750
     end
@@ -85,12 +90,14 @@ class AiLiteTest < Minitest::Test
     client = AiLite.new(
       api_key: "explicit-key",
       model: "gpt-explicit",
+      moderation_model: "omni-moderation-explicit",
       timeout: 5,
       max_output_tokens: 300
     )
 
     assert_equal "explicit-key", client.api_key
     assert_equal "gpt-explicit", client.model
+    assert_equal "omni-moderation-explicit", client.moderation_model
     assert_equal 5, client.timeout
     assert_equal 300, client.max_output_tokens
   end
@@ -277,6 +284,149 @@ class AiLiteTest < Minitest::Test
     end
   end
 
+  def test_moderate_sends_post_to_moderations_with_default_payload
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(moderation_response) do |captured, _response|
+      result = client.moderate("Some user submitted text")
+      request = captured[:http].last_request
+      payload = JSON.parse(request.body)
+
+      assert_equal false, result["content"]["flagged"]
+      assert_equal "modr_test_123", result["response_id"]
+      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/moderations", request.path
+      assert_equal "Bearer token-abc", request["Authorization"]
+      assert_equal "application/json", request["Content-Type"]
+      assert_equal "omni-moderation-latest", payload["model"]
+      assert_equal "Some user submitted text", payload["input"]
+    end
+  end
+
+  def test_moderate_uses_class_level_configured_client
+    AiLite.configure do |config|
+      config.api_key = "configured-key"
+      config.moderation_model = "omni-moderation-config"
+    end
+
+    with_stubbed_http(moderation_response) do |captured, _response|
+      AiLite.moderate("Use configured defaults")
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "omni-moderation-config", payload["model"]
+      assert_equal "Bearer configured-key", captured[:http].last_request["Authorization"]
+    end
+  end
+
+  def test_moderate_accepts_text_and_image_url_keywords
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(moderation_response) do |captured, _response|
+      client.moderate(
+        text: "Profile caption",
+        image_url: "https://example.com/image.png"
+      )
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal(
+        [
+          { "type" => "text", "text" => "Profile caption" },
+          {
+            "type" => "image_url",
+            "image_url" => { "url" => "https://example.com/image.png" }
+          }
+        ],
+        payload["input"]
+      )
+    end
+  end
+
+  def test_moderate_accepts_raw_openai_input_shape
+    client = AiLite.new(api_key: "token-abc")
+    input = [
+      { type: "text", text: "Caption" },
+      {
+        type: "image_url",
+        image_url: {
+          url: "https://example.com/image.png"
+        }
+      }
+    ]
+
+    with_stubbed_http(moderation_response) do |captured, _response|
+      client.moderate(input)
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal(
+        [
+          { "type" => "text", "text" => "Caption" },
+          {
+            "type" => "image_url",
+            "image_url" => { "url" => "https://example.com/image.png" }
+          }
+        ],
+        payload["input"]
+      )
+    end
+  end
+
+  def test_moderate_reads_image_path_as_data_url
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["moderation", ".png"]) do |file|
+      file.binmode
+      file.write("fake image")
+      file.flush
+
+      with_stubbed_http(moderation_response) do |captured, _response|
+        client.moderate(image_path: file.path)
+        payload = JSON.parse(captured[:http].last_request.body)
+
+        assert_equal(
+          [
+            {
+              "type" => "image_url",
+              "image_url" => { "url" => "data:image/png;base64,ZmFrZSBpbWFnZQ==" }
+            }
+          ],
+          payload["input"]
+        )
+      end
+    end
+  end
+
+  def test_moderate_returns_all_results_for_multiple_inputs
+    client = AiLite.new(api_key: "token-abc")
+    safe_result = moderation_result(flagged: false)
+    flagged_result = moderation_result(flagged: true)
+
+    with_stubbed_http(moderation_response(results: [safe_result, flagged_result])) do |_captured, _response|
+      result = client.moderate(["Safe text", "Risky text"])
+
+      assert_equal [safe_result, flagged_result], result["content"]
+      assert_equal 200, result["status"]
+      assert_nil result["error"]
+    end
+  end
+
+  def test_moderate_local_input_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+
+    result = client.moderate
+
+    assert_nil result["content"]
+    assert_nil result["response_id"]
+    assert_equal "unknown", result["status"]
+    assert_equal "Missing moderation input", result["error"]
+    assert_nil result["raw"]
+  end
+
   def test_http_errors_return_standard_envelope
     client = AiLite.new(api_key: "token-abc")
     body = JSON.generate("error" => { "message" => "Invalid API key" })
@@ -369,6 +519,29 @@ class AiLiteTest < Minitest::Test
     FakeResponse.new("200", body)
   end
 
+  def moderation_response(results: [moderation_result])
+    body = JSON.generate(
+      "id" => "modr_test_123",
+      "model" => "omni-moderation-latest",
+      "results" => results
+    )
+    FakeResponse.new("200", body)
+  end
+
+  def moderation_result(flagged: false)
+    {
+      "flagged" => flagged,
+      "categories" => {
+        "hate" => false,
+        "violence" => flagged
+      },
+      "category_scores" => {
+        "hate" => 0.01,
+        "violence" => flagged ? 0.95 : 0.02
+      }
+    }
+  end
+
   def with_env(values)
     originals = {}
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ai-lite
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - William Basmayor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-06-19 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.