Fix OpenAI Chat transforms silently dropping :document shorthand

The normalize_message method in OpenAI Chat transforms handled :image
shorthand but not :document. When { document: "data:..." } was passed,
the document data was silently dropped and leaked as an extra param.

Changes:
- Add :document handling with URL and data URI support
- Add :document to extra_params.except() to prevent leaking
- Add build_file_content helper for file content blocks
- Add 4 tests covering document shorthand scenarios

Fixes #331

Author: TheRealNeil

lib/active_agent/providers/open_ai/chat/transforms.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/hash/keys"
+require "uri"
 
 module ActiveAgent
   module Providers
@@ -124,10 +125,19 @@ def normalize_message(message)
                     { type: "text", text: msg_hash[:text] },
                     { type: "image_url", image_url: { url: msg_hash[:image] } }
                   ]
+                elsif msg_hash.key?(:text) && msg_hash.key?(:document)
+                  # Shorthand with both text and document: { text: "...", document: "url" }
+                  [
+                    { type: "text", text: msg_hash[:text] },
+                    build_file_content(msg_hash[:document])
+                  ]
                 elsif msg_hash.key?(:image)
                   # Shorthand with only image: { image: "url" }
                   # Text comes from adjacent prompt arguments
                   [ { type: "image_url", image_url: { url: msg_hash[:image] } } ]
+                elsif msg_hash.key?(:document)
+                  # Shorthand with only document: { document: "url" }
+                  [ build_file_content(msg_hash[:document]) ]
                 elsif msg_hash.key?(:text)
                   # Shorthand: { text: "..." } or { role: "...", text: "..." }
                   msg_hash[:text]
@@ -137,13 +147,39 @@ def normalize_message(message)
                 end
 
                 # Create appropriate message param based on role and content
-                extra_params = msg_hash.except(:role, :content, :text, :image)
+                extra_params = msg_hash.except(:role, :content, :text, :image, :document)
                 create_message_param(role, content, extra_params)
               else
                 raise ArgumentError, "Cannot normalize #{message.class} to message"
               end
             end
 
+            # Builds a file content block for the Chat API file type
+            #
+            # Handles both URL and data URI formats:
+            # - URL: "http://example.com/document.pdf" → { type: "file", file: { filename: "...", url: "..." } }
+            # - Data URI: "data:application/pdf;base64,..." → { type: "file", file: { filename: "...", file_data: "..." } }
+            #
+            # @param document [String] URL or data URI
+            # @return [Hash] file content block
+            def build_file_content(document)
+              if document.start_with?("data:")
+                # Data URI - extract or infer filename from media type
+                media_type = document.match(%r{\Adata:([^;,]+)})&.[](1) || "application/octet-stream"
+                extension = media_type.split("/").last&.gsub(/[^a-zA-Z0-9]/, "_") || "bin"
+                filename = "document.#{extension}"
+                { type: "file", file: { filename: filename, file_data: document } }
+              else
+                # Regular URL
+                filename = File.basename(URI.parse(document).path.to_s)
+                filename = "document.pdf" if filename.empty?
+                { type: "file", file: { filename: filename, url: document } }
+              end
+            rescue URI::Error
+              # Fallback for invalid URLs
+              { type: "file", file: { filename: "document.pdf", url: document } }
+            end
+
             # Creates the appropriate gem message param class for the given role
             #
             # @param role [String] message role (developer, system, user, assistant, tool, function)

test/providers/open_ai/chat/transforms_test.rb

@@ -203,6 +203,53 @@ def transforms
           assert_equal "image_url", result.content[1][:type]
         end
 
+        test "normalize_message handles shorthand document format with URL" do
+          message = { document: "http://example.com/document.pdf" }
+
+          result =  transforms.normalize_message(message)
+
+          assert_equal :user, result.role
+          assert_equal 1, result.content.size
+          assert_equal "file", result.content[0][:type]
+          assert_equal "http://example.com/document.pdf", result.content[0][:file][:url]
+          assert_equal "document.pdf", result.content[0][:file][:filename]
+        end
+
+        test "normalize_message handles shorthand document format with data URI" do
+          message = { document: "data:application/pdf;base64,JVBERi0xL..." }
+
+          result =  transforms.normalize_message(message)
+
+          assert_equal :user, result.role
+          assert_equal 1, result.content.size
+          assert_equal "file", result.content[0][:type]
+          assert_equal "data:application/pdf;base64,JVBERi0xL...", result.content[0][:file][:file_data]
+          assert_equal "document.pdf", result.content[0][:file][:filename]
+        end
+
+        test "normalize_message handles text and document shorthand" do
+          message = { text: "Analyze this", document: "http://example.com/document.pdf" }
+
+          result =  transforms.normalize_message(message)
+
+          assert_equal :user, result.role
+          assert_equal 2, result.content.size
+          assert_equal "text", result.content[0][:type]
+          assert_equal "Analyze this", result.content[0][:text]
+          assert_equal "file", result.content[1][:type]
+          assert_equal "http://example.com/document.pdf", result.content[1][:file][:url]
+        end
+
+        test "normalize_message does not leak document as extra param" do
+          message = { role: "user", document: "http://example.com/document.pdf" }
+
+          result =  transforms.normalize_message(message)
+
+          # Document should be in content, not as an extra param on the message object
+          serialized = transforms.gem_to_hash(result)
+          assert_nil serialized[:document], "document key should not leak as extra param"
+        end
+
         test "normalize_message handles hash without role as user" do
           message = { content: "hello" }