ai-lite 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f75f42caf4d74f3abf2ec982b7c3830c715b1d1c54f2ae0fdf02a1dec5151db
-  data.tar.gz: ff953a4533862067eee149c04ac5f348bf3b97e7e9f7b87fbcd18a3fe3d63233
+  metadata.gz: cb52e45732e37e363b41144d47cc4136dab1feb450890f10cf84f7cc15593b2a
+  data.tar.gz: 2a05669e6fccdf8da0d1a3a68dc21598806e6072de2fda487e9b436751add386
 SHA512:
-  metadata.gz: c2c91c198575156c15e0100c3fa12709b1cf09395785d4a634e46bf06e9bc9dbf9e8073a95e990f54c4e19a0b72322379317299443899d83eef5c587864b6781
-  data.tar.gz: c528951faf3fe8f453def5a8dbaf7eb00c7da77fc5135c22ccfe2ac5765a2603a0c5cf50dcdfcbe1dda7aaedf6f69ca210a19424b67ef2866c627cd40e17104e
+  metadata.gz: 307ffdbea749aac0eeca74b678d8af55a96add4924e1ef5e5f9157a83138b0929adc2db3282d79a924a24929d8c532fe1742f8ecb801409cf4d5c38fff3639ee
+  data.tar.gz: a50f9ef6171f3ee7249fc46d02e77698820272df70fe3ddbef777f6ab3159879c92c6d6d5fd7eddf29ceda3387308480a2622f95772b85b21fdbc2037808eda7

data/README.md

@@ -20,6 +20,7 @@ ai.chat("Say hello")
 ai.moderate("User submitted text")
 ai.embed("Text to vectorize")
 ai.image("A simple app icon")
+ai.speak("Read this aloud")
 ```
 
 ## Usage
@@ -53,6 +54,8 @@ AiLite.configure do |config|
   config.moderation_model = "omni-moderation-latest"
   config.embedding_model = "text-embedding-3-small"
   config.image_model = "gpt-image-2"
+  config.speech_model = "gpt-4o-mini-tts"
+  config.speech_voice = "alloy"
   config.timeout = 120
   config.max_output_tokens = 2000
 end
@@ -97,6 +100,23 @@ The default model is `gpt-5.5`.
 
 The OpenAI API URL is fixed to `https://api.openai.com/v1/responses`.
 
+### Multi-Turn Chat
+
+Responses include a `response_id` that can be passed back through `options` as `previous_response_id`:
+
+```ruby
+first = ai.chat("Tell me a short joke.")
+
+follow_up = ai.chat(
+  "Explain why that is funny.",
+  options: {
+    previous_response_id: first["response_id"]
+  }
+)
+
+puts follow_up["content"]
+```
+
 ## Moderation
 
 Use `moderate` to classify user-submitted text or images for potentially harmful content before saving, publishing, or sending it into another AI call.
@@ -304,21 +324,93 @@ result["content"]       # base64 image data
 result["raw"]["usage"]  # token usage, when returned
 ```
 
-## Multi-Turn Chat
+## Speech
 
-Responses include a `response_id` that can be passed back through `options` as `previous_response_id`:
+Use `speak` to generate audio from text.
 
 ```ruby
-first = ai.chat("Tell me a short joke.")
+result = ai.speak("Hello from AI Lite")
+audio_bytes = result["content"]
+```
 
-follow_up = ai.chat(
-  "Explain why that is funny.",
-  options: {
-    previous_response_id: first["response_id"]
-  }
+By default, `content` is the raw audio bytes returned by OpenAI:
+
+```ruby
+{
+  "content" => "...binary audio bytes...",
+  "response_id" => nil,
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
+Write the generated audio directly to a file with `output_path`:
+
+```ruby
+result = ai.speak(
+  "Hello from AI Lite",
+  output_path: "tmp/hello.mp3"
 )
+```
 
-puts follow_up["content"]
+When `output_path` is used, `content` is file metadata:
+
+```ruby
+{
+  "content" => {
+    "path" => "tmp/hello.mp3",
+    "bytes" => 12345,
+    "format" => "mp3"
+  },
+  "response_id" => nil,
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
+Use `base64: true` when you want text-safe audio data that can be transported in JSON and decoded later:
+
+```ruby
+result = ai.speak("Hello from AI Lite", base64: true)
+
+File.binwrite("tmp/hello.mp3", Base64.decode64(result["content"]))
+```
+
+`speak` sends a `POST` request to `/v1/audio/speech` with:
+
+- `model`
+- `input`
+- `voice`
+- optional `response_format`
+- optional `speed`
+- optional `instructions`
+- optional `debug`
+- optional extra `options`
+
+The default speech model is `gpt-4o-mini-tts`.
+The default speech voice is `alloy`.
+The default response format is `mp3`.
+
+Set `voice` per call when you want a different built-in voice:
+
+```ruby
+result = ai.speak(
+  "Hello from AI Lite",
+  voice: "sage",
+  output_path: "tmp/hello.mp3"
+)
+```
+
+Use `response_format` to request `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm` output:
+
+```ruby
+result = ai.speak(
+  "Export this as a WAV file",
+  response_format: "wav",
+  output_path: "tmp/hello.wav"
+)
 ```
 
 ## Return Shape

data/lib/ai_lite/version.rb

@@ -1,3 +1,3 @@
 class AiLite
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.0".freeze
 end

data/lib/ai_lite.rb

@@ -10,6 +10,9 @@ class AiLite
   DEFAULT_MODERATION_MODEL = "omni-moderation-latest".freeze
   DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small".freeze
   DEFAULT_IMAGE_MODEL = "gpt-image-2".freeze
+  DEFAULT_SPEECH_MODEL = "gpt-4o-mini-tts".freeze
+  DEFAULT_SPEECH_VOICE = "alloy".freeze
+  DEFAULT_SPEECH_FORMAT = "mp3".freeze
   DEFAULT_TIMEOUT = 120
   DEFAULT_MAX_OUTPUT_TOKENS = 2000
   IMAGE_MIME_TYPES = {
@@ -21,7 +24,7 @@ class AiLite
   }.freeze
 
   class Configuration
-    attr_accessor :api_key, :model, :moderation_model, :embedding_model, :image_model, :timeout, :max_output_tokens
+    attr_accessor :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :timeout, :max_output_tokens
 
     def initialize
       @api_key = nil
@@ -29,6 +32,8 @@ class AiLite
       @moderation_model = DEFAULT_MODERATION_MODEL
       @embedding_model = DEFAULT_EMBEDDING_MODEL
       @image_model = DEFAULT_IMAGE_MODEL
+      @speech_model = DEFAULT_SPEECH_MODEL
+      @speech_voice = DEFAULT_SPEECH_VOICE
       @timeout = DEFAULT_TIMEOUT
       @max_output_tokens = DEFAULT_MAX_OUTPUT_TOKENS
     end
@@ -71,14 +76,18 @@ class AiLite
       client.image(prompt, **kwargs)
     end
 
+    def speak(text, **kwargs)
+      client.speak(text, **kwargs)
+    end
+
     def reset_client!
       @client = nil
     end
   end
 
-  attr_reader :api_key, :model, :moderation_model, :embedding_model, :image_model, :timeout, :max_output_tokens, :headers
+  attr_reader :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :timeout, :max_output_tokens, :headers
 
-  def initialize(api_key: nil, model: nil, moderation_model: nil, embedding_model: nil, image_model: nil, timeout: nil, max_output_tokens: nil)
+  def initialize(api_key: nil, model: nil, moderation_model: nil, embedding_model: nil, image_model: nil, speech_model: nil, speech_voice: 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?
 
@@ -86,6 +95,8 @@ class AiLite
     @moderation_model = moderation_model || self.class.configuration.moderation_model
     @embedding_model = embedding_model || self.class.configuration.embedding_model
     @image_model = image_model || self.class.configuration.image_model
+    @speech_model = speech_model || self.class.configuration.speech_model
+    @speech_voice = speech_voice || self.class.configuration.speech_voice
     @timeout = timeout || self.class.configuration.timeout
     @max_output_tokens = max_output_tokens || self.class.configuration.max_output_tokens
     @headers = {
@@ -146,6 +157,27 @@ class AiLite
     prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
   end
 
+  def speak(text, model: nil, voice: nil, response_format: nil, speed: nil, instructions: nil, output_path: nil, base64: false, debug: false, options: {})
+    payload = options.merge(
+      model: model || speech_model,
+      input: text,
+      voice: voice || speech_voice
+    )
+    payload[:response_format] = response_format if response_format
+    payload[:speed] = speed if speed
+    payload[:instructions] = instructions if instructions
+
+    extract_speech(
+      post(payload, endpoint: speech_endpoint),
+      output_path: output_path,
+      base64: base64,
+      response_format: payload[:response_format] || payload["response_format"] || DEFAULT_SPEECH_FORMAT,
+      debug: debug
+    )
+  rescue => e
+    prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
+  end
+
   private
 
   def post(payload, endpoint: response_endpoint)
@@ -181,6 +213,10 @@ class AiLite
     "#{API_BASE_URL}/images/generations"
   end
 
+  def speech_endpoint
+    "#{API_BASE_URL}/audio/speech"
+  end
+
   def extract_content(response, debug: false)
     status = response.code.to_i
     parsed_response = JSON.parse(response.body)
@@ -294,6 +330,35 @@ class AiLite
     prettify_data(status: response_status(response), error: e.message, raw: nil, debug: debug)
   end
 
+  def extract_speech(response, output_path:, base64:, response_format:, debug: false)
+    status = response.code.to_i
+
+    unless success_status?(status)
+      parsed_response = parse_error_response(response.body)
+
+      return prettify_data(
+        status: status,
+        error: error_message(parsed_response),
+        response_id: parsed_response.is_a?(Hash) ? parsed_response["id"] : nil,
+        raw: parsed_response,
+        debug: debug
+      )
+    end
+
+    audio = response.body
+    File.binwrite(output_path, audio) if output_path
+
+    prettify_data(
+      status: status,
+      content: speech_content(audio, output_path: output_path, base64: base64, response_format: response_format),
+      response_id: nil,
+      raw: audio,
+      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"
@@ -379,6 +444,23 @@ class AiLite
     File.binwrite(path, Base64.decode64(content))
   end
 
+  def speech_content(audio, output_path:, base64:, response_format:)
+    return Base64.strict_encode64(audio) if base64
+    return audio unless output_path
+
+    {
+      "path" => output_path,
+      "bytes" => audio.bytesize,
+      "format" => response_format
+    }
+  end
+
+  def parse_error_response(body)
+    JSON.parse(body)
+  rescue JSON::ParserError
+    body
+  end
+
   def success_status?(status)
     status >= 200 && status < 300
   end

data/test/ai_lite_test.rb

@@ -34,6 +34,8 @@ class AiLiteTest < Minitest::Test
         api_key: "explicit-key",
         model: "gpt-test",
         image_model: "gpt-image-test",
+        speech_model: "gpt-speech-test",
+        speech_voice: "verse",
         timeout: 10
       )
 
@@ -42,6 +44,8 @@ class AiLiteTest < Minitest::Test
       assert_equal "omni-moderation-latest", client.moderation_model
       assert_equal "text-embedding-3-small", client.embedding_model
       assert_equal "gpt-image-test", client.image_model
+      assert_equal "gpt-speech-test", client.speech_model
+      assert_equal "verse", client.speech_voice
       assert_equal 10, client.timeout
       assert_equal 2000, client.max_output_tokens
       assert_equal "Bearer explicit-key", client.headers["Authorization"]
@@ -57,6 +61,8 @@ class AiLiteTest < Minitest::Test
         config.moderation_model = "omni-moderation-test"
         config.embedding_model = "text-embedding-test"
         config.image_model = "gpt-image-test"
+        config.speech_model = "gpt-speech-test"
+        config.speech_voice = "verse"
         config.timeout = 15
         config.max_output_tokens = 750
       end
@@ -68,6 +74,8 @@ class AiLiteTest < Minitest::Test
       assert_equal "omni-moderation-test", client.moderation_model
       assert_equal "text-embedding-test", client.embedding_model
       assert_equal "gpt-image-test", client.image_model
+      assert_equal "gpt-speech-test", client.speech_model
+      assert_equal "verse", client.speech_voice
       assert_equal 15, client.timeout
       assert_equal 750, client.max_output_tokens
       assert_same client, AiLite.client
@@ -92,6 +100,8 @@ class AiLiteTest < Minitest::Test
       config.moderation_model = "omni-moderation-config"
       config.embedding_model = "text-embedding-config"
       config.image_model = "gpt-image-config"
+      config.speech_model = "gpt-speech-config"
+      config.speech_voice = "sage"
       config.timeout = 15
       config.max_output_tokens = 750
     end
@@ -102,6 +112,8 @@ class AiLiteTest < Minitest::Test
       moderation_model: "omni-moderation-explicit",
       embedding_model: "text-embedding-explicit",
       image_model: "gpt-image-explicit",
+      speech_model: "gpt-speech-explicit",
+      speech_voice: "coral",
       timeout: 5,
       max_output_tokens: 300
     )
@@ -111,6 +123,8 @@ class AiLiteTest < Minitest::Test
     assert_equal "omni-moderation-explicit", client.moderation_model
     assert_equal "text-embedding-explicit", client.embedding_model
     assert_equal "gpt-image-explicit", client.image_model
+    assert_equal "gpt-speech-explicit", client.speech_model
+    assert_equal "coral", client.speech_voice
     assert_equal 5, client.timeout
     assert_equal 300, client.max_output_tokens
   end
@@ -644,6 +658,133 @@ class AiLiteTest < Minitest::Test
     end
   end
 
+  def test_speak_sends_post_to_audio_speech_with_default_payload
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(speech_response("fake audio")) do |captured, _response|
+      result = client.speak("Read this aloud")
+      request = captured[:http].last_request
+      payload = JSON.parse(request.body)
+
+      assert_equal "fake audio", result["content"]
+      assert_nil 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/audio/speech", request.path
+      assert_equal "Bearer token-abc", request["Authorization"]
+      assert_equal "application/json", request["Content-Type"]
+      assert_equal "gpt-4o-mini-tts", payload["model"]
+      assert_equal "Read this aloud", payload["input"]
+      assert_equal "alloy", payload["voice"]
+    end
+  end
+
+  def test_speak_includes_options_response_format_speed_instructions_model_and_voice
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(speech_response) do |captured, _response|
+      client.speak(
+        "Use a clear support tone",
+        model: "gpt-speech-test",
+        voice: "sage",
+        response_format: "wav",
+        speed: 1.2,
+        instructions: "Speak warmly.",
+        options: {
+          stream_format: "audio"
+        }
+      )
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "gpt-speech-test", payload["model"]
+      assert_equal "Use a clear support tone", payload["input"]
+      assert_equal "sage", payload["voice"]
+      assert_equal "wav", payload["response_format"]
+      assert_equal 1.2, payload["speed"]
+      assert_equal "Speak warmly.", payload["instructions"]
+      assert_equal "audio", payload["stream_format"]
+    end
+  end
+
+  def test_speak_uses_class_level_configured_client
+    AiLite.configure do |config|
+      config.api_key = "configured-key"
+      config.speech_model = "gpt-speech-config"
+      config.speech_voice = "marin"
+    end
+
+    with_stubbed_http(speech_response) do |captured, _response|
+      AiLite.speak("Use configured defaults")
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "gpt-speech-config", payload["model"]
+      assert_equal "marin", payload["voice"]
+      assert_equal "Bearer configured-key", captured[:http].last_request["Authorization"]
+    end
+  end
+
+  def test_speak_writes_audio_to_output_path_and_returns_metadata
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["speech", ".mp3"]) do |file|
+      with_stubbed_http(speech_response("fake audio")) do |_captured, _response|
+        result = client.speak("Save this", output_path: file.path)
+
+        assert_equal(
+          {
+            "path" => file.path,
+            "bytes" => 10,
+            "format" => "mp3"
+          },
+          result["content"]
+        )
+        assert_equal "fake audio", File.binread(file.path)
+      end
+    end
+  end
+
+  def test_speak_base64_true_returns_encoded_audio
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(speech_response("fake audio")) do |_captured, _response|
+      result = client.speak("Encode this", base64: true)
+
+      assert_equal Base64.strict_encode64("fake audio"), result["content"]
+      assert_nil result["raw"]
+    end
+  end
+
+  def test_speak_debug_true_returns_raw_audio
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(speech_response("fake audio")) do |_captured, _response|
+      result = client.speak("Debug this", debug: true)
+
+      assert_equal "fake audio", result["content"]
+      assert_equal "fake audio", result["raw"]
+    end
+  end
+
+  def test_speak_http_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+    body = JSON.generate("error" => { "message" => "Unsupported voice" })
+
+    with_stubbed_http(FakeResponse.new("400", body)) do |_captured, _response|
+      result = client.speak("Say hello")
+
+      assert_nil result["content"]
+      assert_nil result["response_id"]
+      assert_equal 400, result["status"]
+      assert_equal "Unsupported voice", result["error"]
+      assert_nil result["raw"]
+    end
+  end
+
   def test_http_errors_return_standard_envelope
     client = AiLite.new(api_key: "token-abc")
     body = JSON.generate("error" => { "message" => "Invalid API key" })
@@ -798,6 +939,10 @@ class AiLiteTest < Minitest::Test
     FakeResponse.new("200", body)
   end
 
+  def speech_response(audio = "fake audio")
+    FakeResponse.new("200", audio)
+  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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - William Basmayor
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-24 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.