ai-lite 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb52e45732e37e363b41144d47cc4136dab1feb450890f10cf84f7cc15593b2a
-  data.tar.gz: 2a05669e6fccdf8da0d1a3a68dc21598806e6072de2fda487e9b436751add386
+  metadata.gz: 6f7c5581a41c1371b086b33502200da2ad06cab07cc202efd0f943616effb738
+  data.tar.gz: 3a1c897735f7aa945e4cca0fb3bea1a86c3beefc7e823e8a149b78e93ac3b7c8
 SHA512:
-  metadata.gz: 307ffdbea749aac0eeca74b678d8af55a96add4924e1ef5e5f9157a83138b0929adc2db3282d79a924a24929d8c532fe1742f8ecb801409cf4d5c38fff3639ee
-  data.tar.gz: a50f9ef6171f3ee7249fc46d02e77698820272df70fe3ddbef777f6ab3159879c92c6d6d5fd7eddf29ceda3387308480a2622f95772b85b21fdbc2037808eda7
+  metadata.gz: 6c5f349cdf43703435f4ab0c08216ce59c73737042ad179ed675339a37238b175dffdc96d5a0014ac0a89dca554e4ed4d4279c417bd13a25fd9dc80d4d9dadc7
+  data.tar.gz: 0475ffdba930c5a5dc6c463f78c6abfc7c14306b233b1d05c17e6e6aa5f20bb706271c994e4aec0f2f350f656bcda3c681716751e280968ec8962222cfdea432

data/README.md

@@ -11,7 +11,7 @@ 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`, `JSON`, and `Base64`
+- Uses only Ruby stdlib: `Net::HTTP`, `URI`, `JSON`, `Base64`, and `SecureRandom`
 
 It is not meant to replace the official OpenAI SDK. It is a small wrapper for projects that only need a few clean interfaces:
 
@@ -21,6 +21,7 @@ ai.moderate("User submitted text")
 ai.embed("Text to vectorize")
 ai.image("A simple app icon")
 ai.speak("Read this aloud")
+ai.transcribe("tmp/meeting.mp3")
 ```
 
 ## Usage
@@ -56,11 +57,26 @@ AiLite.configure do |config|
   config.image_model = "gpt-image-2"
   config.speech_model = "gpt-4o-mini-tts"
   config.speech_voice = "alloy"
+  config.transcription_model = "gpt-transcribe"
   config.timeout = 120
   config.max_output_tokens = 2000
 end
 ```
 
+Any value left unset falls back to AI Lite's default:
+
+- `model`: `gpt-5.5`
+- `moderation_model`: `omni-moderation-latest`
+- `embedding_model`: `text-embedding-3-small`
+- `image_model`: `gpt-image-2`
+- `speech_model`: `gpt-4o-mini-tts`
+- `speech_voice`: `alloy`
+- `transcription_model`: `gpt-transcribe`
+- `timeout`: `120`
+- `max_output_tokens`: `2000`
+
+`timeout` is applied to both the HTTP connection timeout and the HTTP read timeout.
+
 Then use the configured singleton-style client:
 
 ```ruby
@@ -93,6 +109,7 @@ result = ai.chat(
 - `input`
 - `max_output_tokens`
 - optional `instructions`
+- optional `previous_response_id`
 - optional `debug`
 - optional extra `options`
 
@@ -100,23 +117,36 @@ The default model is `gpt-5.5`.
 
 The OpenAI API URL is fixed to `https://api.openai.com/v1/responses`.
 
+### Message-Array Input
+
+For a conversation with multiple input messages, pass an array using the OpenAI Responses API message shape:
+
+```ruby
+result = ai.chat([
+  { role: "developer", content: "Be concise." },
+  { role: "user", content: "Explain dependency injection." }
+])
+```
+
+AI Lite sends the array unchanged as `input`, so you can also use richer Responses API content items when needed.
+
 ### Multi-Turn Chat
 
-Responses include a `response_id` that can be passed back through `options` as `previous_response_id`:
+Responses include a `response_id`. Pass it to the next call as `previous_response_id` to continue the conversation:
 
 ```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"]
-  }
+  previous_response_id: first["response_id"]
 )
 
 puts follow_up["content"]
 ```
 
+Passing `previous_response_id` through `options` remains supported for backward compatibility.
+
 ## Moderation
 
 Use `moderate` to classify user-submitted text or images for potentially harmful content before saving, publishing, or sending it into another AI call.
@@ -413,6 +443,71 @@ result = ai.speak(
 )
 ```
 
+## Transcription
+
+Use `transcribe` to turn an audio file into text.
+
+```ruby
+result = ai.transcribe("tmp/meeting.mp3")
+
+puts result["content"]
+```
+
+By default, `content` is the transcript text:
+
+```ruby
+{
+  "content" => "Welcome everyone, let's get started.",
+  "response_id" => nil,
+  "status" => 200,
+  "error" => nil,
+  "raw" => nil
+}
+```
+
+`transcribe` sends a multipart `POST` request to `/v1/audio/transcriptions` with:
+
+- `file`
+- `model`
+- optional `language`
+- optional `prompt`
+- optional `response_format`
+- optional `temperature`
+- optional `timestamp_granularities`
+- optional `debug`
+- optional extra `options`
+
+The default transcription model is `gpt-transcribe`.
+
+Supported local audio extensions are `.flac`, `.m4a`, `.mp3`, `.mp4`, `.mpeg`, `.mpga`, `.ogg`, `.wav`, and `.webm`.
+
+Pass `language` in ISO-639-1 format when you know the input language:
+
+```ruby
+result = ai.transcribe(
+  "tmp/meeting.mp3",
+  language: "en"
+)
+```
+
+Use `prompt` to provide words, names, or style context that may help the transcription:
+
+```ruby
+result = ai.transcribe(
+  "tmp/support-call.mp3",
+  prompt: "The speakers may mention AI Lite, RubyGems, and Net::HTTP."
+)
+```
+
+Pass `debug: true` to include the raw OpenAI response:
+
+```ruby
+result = ai.transcribe("tmp/meeting.mp3", debug: true)
+
+result["content"]  # transcript text
+result["raw"]      # full response body when available
+```
+
 ## Return Shape
 
 Methods return a hash envelope.

data/lib/ai_lite/version.rb

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

data/lib/ai_lite.rb

@@ -1,6 +1,7 @@
 require "base64"
 require "json"
 require "net/http"
+require "securerandom"
 require "uri"
 require_relative "ai_lite/version"
 
@@ -13,6 +14,7 @@ class AiLite
   DEFAULT_SPEECH_MODEL = "gpt-4o-mini-tts".freeze
   DEFAULT_SPEECH_VOICE = "alloy".freeze
   DEFAULT_SPEECH_FORMAT = "mp3".freeze
+  DEFAULT_TRANSCRIPTION_MODEL = "gpt-transcribe".freeze
   DEFAULT_TIMEOUT = 120
   DEFAULT_MAX_OUTPUT_TOKENS = 2000
   IMAGE_MIME_TYPES = {
@@ -22,9 +24,20 @@ class AiLite
     ".png" => "image/png",
     ".webp" => "image/webp"
   }.freeze
+  AUDIO_MIME_TYPES = {
+    ".flac" => "audio/flac",
+    ".m4a" => "audio/mp4",
+    ".mp3" => "audio/mpeg",
+    ".mp4" => "audio/mp4",
+    ".mpeg" => "audio/mpeg",
+    ".mpga" => "audio/mpeg",
+    ".ogg" => "audio/ogg",
+    ".wav" => "audio/wav",
+    ".webm" => "audio/webm"
+  }.freeze
 
   class Configuration
-    attr_accessor :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :timeout, :max_output_tokens
+    attr_accessor :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :transcription_model, :timeout, :max_output_tokens
 
     def initialize
       @api_key = nil
@@ -34,6 +47,7 @@ class AiLite
       @image_model = DEFAULT_IMAGE_MODEL
       @speech_model = DEFAULT_SPEECH_MODEL
       @speech_voice = DEFAULT_SPEECH_VOICE
+      @transcription_model = DEFAULT_TRANSCRIPTION_MODEL
       @timeout = DEFAULT_TIMEOUT
       @max_output_tokens = DEFAULT_MAX_OUTPUT_TOKENS
     end
@@ -80,14 +94,18 @@ class AiLite
       client.speak(text, **kwargs)
     end
 
+    def transcribe(file_path, **kwargs)
+      client.transcribe(file_path, **kwargs)
+    end
+
     def reset_client!
       @client = nil
     end
   end
 
-  attr_reader :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :timeout, :max_output_tokens, :headers
+  attr_reader :api_key, :model, :moderation_model, :embedding_model, :image_model, :speech_model, :speech_voice, :transcription_model, :timeout, :max_output_tokens, :headers
 
-  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)
+  def initialize(api_key: nil, model: nil, moderation_model: nil, embedding_model: nil, image_model: nil, speech_model: nil, speech_voice: nil, transcription_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?
 
@@ -97,6 +115,7 @@ class AiLite
     @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
+    @transcription_model = transcription_model || self.class.configuration.transcription_model
     @timeout = timeout || self.class.configuration.timeout
     @max_output_tokens = max_output_tokens || self.class.configuration.max_output_tokens
     @headers = {
@@ -105,13 +124,14 @@ class AiLite
     }
   end
 
-  def chat(message, model: nil, instructions: nil, max_output_tokens: nil, debug: false, options: {})
+  def chat(message, model: nil, instructions: nil, previous_response_id: 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
+    payload[:previous_response_id] = previous_response_id if previous_response_id
 
     extract_content(post(payload), debug: debug)
   rescue => e
@@ -178,6 +198,24 @@ class AiLite
     prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
   end
 
+  def transcribe(file_path, model: nil, language: nil, prompt: nil, response_format: nil, temperature: nil, timestamp_granularities: nil, debug: false, options: {})
+    fields = options.merge(
+      model: model || transcription_model
+    )
+    fields[:language] = language if language
+    fields[:prompt] = prompt if prompt
+    fields[:response_format] = response_format if response_format
+    fields[:temperature] = temperature unless temperature.nil?
+    fields[:timestamp_granularities] = timestamp_granularities if timestamp_granularities
+
+    extract_transcription(
+      post_multipart(fields, file_field: audio_file_field(file_path), endpoint: transcription_endpoint),
+      debug: debug
+    )
+  rescue => e
+    prettify_data(status: "unknown", error: e.message, raw: nil, debug: debug)
+  end
+
   private
 
   def post(payload, endpoint: response_endpoint)
@@ -197,6 +235,21 @@ class AiLite
     end
   end
 
+  def post_multipart(fields, file_field:, endpoint:)
+    uri = URI.parse(endpoint)
+    boundary = "----AiLiteBoundary#{SecureRandom.hex(16)}"
+    request = Net::HTTP::Post.new(uri)
+    request["Authorization"] = headers["Authorization"]
+    request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+    request.body = multipart_body(fields, file_field: file_field, boundary: boundary)
+
+    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
@@ -217,6 +270,10 @@ class AiLite
     "#{API_BASE_URL}/audio/speech"
   end
 
+  def transcription_endpoint
+    "#{API_BASE_URL}/audio/transcriptions"
+  end
+
   def extract_content(response, debug: false)
     status = response.code.to_i
     parsed_response = JSON.parse(response.body)
@@ -359,6 +416,31 @@ class AiLite
     prettify_data(status: response_status(response), error: e.message, raw: nil, debug: debug)
   end
 
+  def extract_transcription(response, debug: false)
+    status = response.code.to_i
+    parsed_response = parse_error_response(response.body)
+
+    unless success_status?(status)
+      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
+
+    prettify_data(
+      status: status,
+      content: transcription_content(parsed_response),
+      response_id: parsed_response.is_a?(Hash) ? parsed_response["id"] : nil,
+      raw: parsed_response,
+      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"
@@ -418,6 +500,24 @@ class AiLite
     end
   end
 
+  def audio_file_field(path)
+    raise ArgumentError, "Audio file not found: #{path}" unless File.file?(path)
+
+    {
+      name: "file",
+      path: path,
+      filename: File.basename(path),
+      content_type: audio_mime_type(path)
+    }
+  end
+
+  def audio_mime_type(path)
+    extension = File.extname(path).downcase
+    AUDIO_MIME_TYPES.fetch(extension) do
+      raise ArgumentError, "Unsupported audio type for transcription: #{extension}"
+    end
+  end
+
   def moderation_content(raw)
     results = raw["results"]
     return nil unless results.is_a?(Array)
@@ -455,6 +555,55 @@ class AiLite
     }
   end
 
+  def transcription_content(raw)
+    return raw["text"] if raw.is_a?(Hash) && raw.key?("text")
+
+    raw
+  end
+
+  def multipart_body(fields, file_field:, boundary:)
+    body = String.new(encoding: Encoding::BINARY)
+
+    fields.each do |name, value|
+      multipart_field_parts(name, value).each do |field_name, field_value|
+        body << "--#{boundary}\r\n".b
+        body << "Content-Disposition: form-data; name=\"#{multipart_quote(field_name)}\"\r\n\r\n".b
+        body << field_value.to_s.b
+        body << "\r\n".b
+      end
+    end
+
+    body << "--#{boundary}\r\n".b
+    body << "Content-Disposition: form-data; name=\"#{multipart_quote(file_field[:name])}\"; filename=\"#{multipart_quote(file_field[:filename])}\"\r\n".b
+    body << "Content-Type: #{file_field[:content_type]}\r\n\r\n".b
+    body << File.binread(file_field[:path])
+    body << "\r\n--#{boundary}--\r\n".b
+    body
+  end
+
+  def multipart_field_parts(name, value)
+    return [] if value.nil?
+
+    if value.is_a?(Array)
+      value.map { |item| ["#{name}[]", multipart_value(item)] }
+    else
+      [[name.to_s, multipart_value(value)]]
+    end
+  end
+
+  def multipart_value(value)
+    case value
+    when Hash
+      JSON.generate(value)
+    else
+      value
+    end
+  end
+
+  def multipart_quote(value)
+    value.to_s.gsub("\\", "\\\\").gsub("\"", "\\\"").delete("\r\n")
+  end
+
   def parse_error_response(body)
     JSON.parse(body)
   rescue JSON::ParserError

data/test/ai_lite_test.rb

@@ -36,6 +36,7 @@ class AiLiteTest < Minitest::Test
         image_model: "gpt-image-test",
         speech_model: "gpt-speech-test",
         speech_voice: "verse",
+        transcription_model: "gpt-transcribe-test",
         timeout: 10
       )
 
@@ -46,6 +47,7 @@ class AiLiteTest < Minitest::Test
       assert_equal "gpt-image-test", client.image_model
       assert_equal "gpt-speech-test", client.speech_model
       assert_equal "verse", client.speech_voice
+      assert_equal "gpt-transcribe-test", client.transcription_model
       assert_equal 10, client.timeout
       assert_equal 2000, client.max_output_tokens
       assert_equal "Bearer explicit-key", client.headers["Authorization"]
@@ -63,6 +65,7 @@ class AiLiteTest < Minitest::Test
         config.image_model = "gpt-image-test"
         config.speech_model = "gpt-speech-test"
         config.speech_voice = "verse"
+        config.transcription_model = "gpt-transcribe-test"
         config.timeout = 15
         config.max_output_tokens = 750
       end
@@ -76,6 +79,7 @@ class AiLiteTest < Minitest::Test
       assert_equal "gpt-image-test", client.image_model
       assert_equal "gpt-speech-test", client.speech_model
       assert_equal "verse", client.speech_voice
+      assert_equal "gpt-transcribe-test", client.transcription_model
       assert_equal 15, client.timeout
       assert_equal 750, client.max_output_tokens
       assert_same client, AiLite.client
@@ -102,6 +106,7 @@ class AiLiteTest < Minitest::Test
       config.image_model = "gpt-image-config"
       config.speech_model = "gpt-speech-config"
       config.speech_voice = "sage"
+      config.transcription_model = "gpt-transcribe-config"
       config.timeout = 15
       config.max_output_tokens = 750
     end
@@ -114,6 +119,7 @@ class AiLiteTest < Minitest::Test
       image_model: "gpt-image-explicit",
       speech_model: "gpt-speech-explicit",
       speech_voice: "coral",
+      transcription_model: "gpt-transcribe-explicit",
       timeout: 5,
       max_output_tokens: 300
     )
@@ -125,6 +131,7 @@ class AiLiteTest < Minitest::Test
     assert_equal "gpt-image-explicit", client.image_model
     assert_equal "gpt-speech-explicit", client.speech_model
     assert_equal "coral", client.speech_voice
+    assert_equal "gpt-transcribe-explicit", client.transcription_model
     assert_equal 5, client.timeout
     assert_equal 300, client.max_output_tokens
   end
@@ -231,15 +238,13 @@ class AiLiteTest < Minitest::Test
     end
   end
 
-  def test_chat_supports_previous_response_id_through_options
+  def test_chat_supports_previous_response_id
     client = AiLite.new(api_key: "token-abc")
 
     with_stubbed_http(success_response("Follow-up")) do |captured, _response|
       result = client.chat(
         "Explain why that is funny",
-        options: {
-          previous_response_id: "resp_previous_123"
-        }
+        previous_response_id: "resp_previous_123"
       )
       payload = JSON.parse(captured[:http].last_request.body)
 
@@ -249,6 +254,53 @@ class AiLiteTest < Minitest::Test
     end
   end
 
+  def test_chat_supports_message_array_input
+    client = AiLite.new(api_key: "token-abc")
+    messages = [
+      { role: "developer", content: "Be concise." },
+      { role: "user", content: "Say hello." }
+    ]
+
+    with_stubbed_http(success_response("Hello!")) do |captured, _response|
+      client.chat(messages)
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal(
+        [
+          { "role" => "developer", "content" => "Be concise." },
+          { "role" => "user", "content" => "Say hello." }
+        ],
+        payload["input"]
+      )
+    end
+  end
+
+  def test_chat_first_class_previous_response_id_overrides_options
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Follow-up")) do |captured, _response|
+      client.chat(
+        "Continue",
+        previous_response_id: "resp_keyword",
+        options: { previous_response_id: "resp_options" }
+      )
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "resp_keyword", payload["previous_response_id"]
+    end
+  end
+
+  def test_chat_keeps_supporting_previous_response_id_through_options
+    client = AiLite.new(api_key: "token-abc")
+
+    with_stubbed_http(success_response("Follow-up")) do |captured, _response|
+      client.chat("Continue", options: { previous_response_id: "resp_options" })
+      payload = JSON.parse(captured[:http].last_request.body)
+
+      assert_equal "resp_options", payload["previous_response_id"]
+    end
+  end
+
   def test_extracts_text_from_nested_output_text_items
     client = AiLite.new(api_key: "token-abc")
     body = JSON.generate(
@@ -785,6 +837,171 @@ class AiLiteTest < Minitest::Test
     end
   end
 
+  def test_transcribe_sends_post_to_audio_transcriptions_with_default_multipart_payload
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["meeting", ".mp3"]) do |file|
+      file.binmode
+      file.write("fake audio")
+      file.flush
+
+      with_stubbed_http(transcription_response("Hello from the file")) do |captured, _response|
+        result = client.transcribe(file.path)
+        request = captured[:http].last_request
+
+        assert_equal "Hello from the file", 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/transcriptions", request.path
+        assert_equal "Bearer token-abc", request["Authorization"]
+        assert_match(/\Amultipart\/form-data; boundary=----AiLiteBoundary/, request["Content-Type"])
+        assert_multipart_field request.body, "model", "gpt-transcribe"
+        assert_multipart_file request.body, "file", File.basename(file.path), "audio/mpeg", "fake audio"
+      end
+    end
+  end
+
+  def test_transcribe_includes_options_and_optional_fields
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["meeting", ".wav"]) do |file|
+      file.binmode
+      file.write("fake wav")
+      file.flush
+
+      with_stubbed_http(transcription_response("Detailed transcript")) do |captured, _response|
+        client.transcribe(
+          file.path,
+          model: "gpt-4o-transcribe",
+          language: "en",
+          prompt: "The speaker may say AI Lite.",
+          response_format: "verbose_json",
+          temperature: 0,
+          timestamp_granularities: ["word", "segment"],
+          options: {
+            chunking_strategy: "auto",
+            include: ["logprobs"],
+            metadata: { source: "test" }
+          }
+        )
+        body = captured[:http].last_request.body
+
+        assert_multipart_field body, "model", "gpt-4o-transcribe"
+        assert_multipart_field body, "language", "en"
+        assert_multipart_field body, "prompt", "The speaker may say AI Lite."
+        assert_multipart_field body, "response_format", "verbose_json"
+        assert_multipart_field body, "temperature", "0"
+        assert_multipart_field body, "timestamp_granularities[]", "word"
+        assert_multipart_field body, "timestamp_granularities[]", "segment"
+        assert_multipart_field body, "chunking_strategy", "auto"
+        assert_multipart_field body, "include[]", "logprobs"
+        assert_multipart_field body, "metadata", JSON.generate("source" => "test")
+        assert_multipart_file body, "file", File.basename(file.path), "audio/wav", "fake wav"
+      end
+    end
+  end
+
+  def test_transcribe_uses_class_level_configured_client
+    AiLite.configure do |config|
+      config.api_key = "configured-key"
+      config.transcription_model = "gpt-transcription-config"
+    end
+
+    Tempfile.create(["meeting", ".m4a"]) do |file|
+      file.binmode
+      file.write("fake m4a")
+      file.flush
+
+      with_stubbed_http(transcription_response) do |captured, _response|
+        AiLite.transcribe(file.path)
+        request = captured[:http].last_request
+
+        assert_multipart_field request.body, "model", "gpt-transcription-config"
+        assert_equal "Bearer configured-key", request["Authorization"]
+      end
+    end
+  end
+
+  def test_transcribe_returns_plain_text_response_formats
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["meeting", ".webm"]) do |file|
+      file.binmode
+      file.write("fake webm")
+      file.flush
+
+      with_stubbed_http(FakeResponse.new("200", "plain transcript")) do |_captured, _response|
+        result = client.transcribe(file.path, response_format: "text")
+
+        assert_equal "plain transcript", result["content"]
+        assert_equal 200, result["status"]
+        assert_nil result["error"]
+        assert_nil result["raw"]
+      end
+    end
+  end
+
+  def test_transcribe_debug_true_returns_raw_response
+    client = AiLite.new(api_key: "token-abc")
+
+    Tempfile.create(["meeting", ".ogg"]) do |file|
+      file.binmode
+      file.write("fake ogg")
+      file.flush
+
+      with_stubbed_http(transcription_response("Debug transcript", usage: { "input_tokens" => 4 })) do |_captured, _response|
+        result = client.transcribe(file.path, debug: true)
+
+        assert_equal "Debug transcript", result["content"]
+        assert_equal({ "input_tokens" => 4 }, result["raw"]["usage"])
+      end
+    end
+  end
+
+  def test_transcribe_http_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+    body = JSON.generate("error" => { "message" => "Unsupported audio format" })
+
+    Tempfile.create(["meeting", ".mp3"]) do |file|
+      file.binmode
+      file.write("fake audio")
+      file.flush
+
+      with_stubbed_http(FakeResponse.new("400", body)) do |_captured, _response|
+        result = client.transcribe(file.path)
+
+        assert_nil result["content"]
+        assert_nil result["response_id"]
+        assert_equal 400, result["status"]
+        assert_equal "Unsupported audio format", result["error"]
+        assert_nil result["raw"]
+      end
+    end
+  end
+
+  def test_transcribe_local_file_errors_return_standard_envelope
+    client = AiLite.new(api_key: "token-abc")
+
+    missing_result = client.transcribe("tmp/missing-audio.mp3")
+    assert_nil missing_result["content"]
+    assert_equal "unknown", missing_result["status"]
+    assert_equal "Audio file not found: tmp/missing-audio.mp3", missing_result["error"]
+
+    Tempfile.create(["meeting", ".txt"]) do |file|
+      result = client.transcribe(file.path)
+
+      assert_nil result["content"]
+      assert_equal "unknown", result["status"]
+      assert_equal "Unsupported audio type for transcription: .txt", result["error"]
+    end
+  end
+
   def test_http_errors_return_standard_envelope
     client = AiLite.new(api_key: "token-abc")
     body = JSON.generate("error" => { "message" => "Invalid API key" })
@@ -943,6 +1160,21 @@ class AiLiteTest < Minitest::Test
     FakeResponse.new("200", audio)
   end
 
+  def transcription_response(text = "Transcribed text", **extra)
+    FakeResponse.new("200", JSON.generate({ "text" => text }.merge(extra)))
+  end
+
+  def assert_multipart_field(body, name, value)
+    assert_includes body, "Content-Disposition: form-data; name=\"#{name}\""
+    assert_includes body, "\r\n\r\n#{value}\r\n"
+  end
+
+  def assert_multipart_file(body, name, filename, content_type, content)
+    assert_includes body, "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{filename}\""
+    assert_includes body, "Content-Type: #{content_type}"
+    assert_includes body, "\r\n\r\n#{content}\r\n"
+  end
+
   def with_env(values)
     originals = {}
 

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: ai-lite
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - William Basmayor
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-10-05 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.
+  projects that need simple OpenAI chat, moderation, embedding, image, speech, and
+  transcription calls.
 email:
 executables: []
 extensions: []
@@ -45,6 +46,5 @@ 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.
+summary: Minimal Ruby client for simple OpenAI API calls.
 test_files: []