ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/agent_tool.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # The Tool an Agent class becomes when it goes wherever tools go, so a
+  # model can hand work to it: a subagent. Agent::to_tool returns one, and
+  # Chat#with_tools and Agent::tools convert an Agent class themselves.
+  #
+  #   class ResearchAgent < RubyLLM::Agent
+  #     description "Researches a question across the web and reports back"
+  #     tools WebSearch, ReadPage
+  #   end
+  #
+  #   chat.with_tools(ResearchAgent).ask "What changed in Ruby 4.0?"
+  #
+  # The tool is named after the agent (+research_agent+, or
+  # +billing_research_agent+ for <tt>Billing::ResearchAgent</tt>) and takes
+  # a +task+, everything the agent needs written to stand alone, plus the
+  # agent's ::inputs that ::to_tool was not given. Each call runs a fresh
+  # instance of the agent on the task, under the owner of the chat that
+  # called it, and returns the content of its last answer.
+  #
+  # The agent lives only as long as its call, so it has to finish within
+  # it. When it stops to wait instead, for an approval, a question, or a
+  # task, the call raises ConfigurationError. To let a subagent wait for a
+  # person, give it a chat of its own, as the Agents guide shows.
+  class AgentTool < Tool
+    GUIDE = 'https://rubyllm.com/agents/#subagents-that-wait-for-a-person'
+    private_constant :GUIDE
+
+    class << self
+      # The Agent class this tool runs.
+      attr_reader :agent_class
+
+      # The agent's ::inputs that the model supplies, as parameters.
+      attr_reader :input_parameters # :nodoc:
+
+      # Returns a Tool class for +agent_class+, with the inputs in +given+
+      # left out of its parameters.
+      def for(agent_class, given) # :nodoc:
+        raise ArgumentError, 'An agent needs a class name to become a tool' unless agent_class.name
+        if agent_class.inputs.include?(:task)
+          raise ArgumentError, "#{agent_class.name} has an input named task, which its tool takes for the prompt"
+        end
+
+        missing = agent_class.inputs - given.keys.map(&:to_sym)
+        Class.new(self) do
+          @agent_class = agent_class
+          @input_parameters = missing
+          description(agent_class.description || "Hands a task to the #{agent_class.name} agent, which reports back.")
+          parameter :task, description: 'Everything the agent needs to do the work, written to stand alone'
+          missing.each { |input| parameter input, description: "The agent's #{input}" }
+        end
+      end
+
+      # Returns the agent's name in snake case, such as +research_agent+.
+      def tool_name
+        Support::Utils.underscore(agent_class.name.gsub('::', '_'))
+      end
+    end
+
+    def initialize(inputs = {}) # :nodoc:
+      super()
+      @inputs = inputs
+    end
+
+    # Runs a fresh instance of the agent on +task+, with the inputs given to
+    # Agent::to_tool and those the model chose, and returns the content of
+    # its last answer. Raises ConfigurationError, naming what the agent
+    # waits for, when it stops to wait instead of answering.
+    def execute(task:, **inputs)
+      agent = self.class.agent_class.new(**@inputs, **inputs.slice(*self.class.input_parameters))
+      owner = Accounting::Usage.owner
+      agent.with_owner(owner) unless owner.nil?
+      message = agent.ask(task)
+      raise ConfigurationError, stopped(agent) if agent.waiting?
+
+      message&.content
+    end
+
+    private
+
+    def stopped(agent)
+      people = agent.pending_questions.map do |question|
+        "a person to #{question.approval? ? 'approve' : 'answer'} #{question.tool_call.name}"
+      end
+      tasks = agent.pending_tasks.map { |task| "the task of #{task.tool_call.name}" }
+      "#{self.class.agent_class.name} stopped to wait for #{(people + tasks).join(' and ')}, but an agent used " \
+        "as a tool has to finish within its call. To let it wait, give it a chat of its own: #{GUIDE}"
+    end
+  end
+end

data/lib/ruby_llm/aliases.json

@@ -1,4 +1,7 @@
 {
+  "antigravity-preview": {
+    "gemini": "antigravity-preview-latest"
+  },
   "claude-fable-5": {
     "anthropic": "claude-fable-5",
     "openrouter": "anthropic/claude-fable-5",
@@ -13,6 +16,13 @@
     "vertexai": "claude-fable-5-1",
     "azure": "claude-fable-5-1"
   },
+  "claude-fable-5-2": {
+    "anthropic": "claude-fable-5-2",
+    "openrouter": "anthropic/claude-fable-5.2",
+    "bedrock": "anthropic.claude-fable-5-2",
+    "vertexai": "claude-fable-5-2",
+    "azure": "claude-fable-5-2"
+  },
   "claude-haiku-4-5": {
     "anthropic": "claude-haiku-4-5-20251001",
     "openrouter": "anthropic/claude-haiku-4.5",
@@ -20,6 +30,13 @@
     "vertexai": "claude-haiku-4-5",
     "azure": "claude-haiku-4-5-20251001"
   },
+  "claude-haiku-5-5": {
+    "anthropic": "claude-haiku-5-5",
+    "openrouter": "anthropic/claude-haiku-5.5",
+    "bedrock": "anthropic.claude-haiku-5-5",
+    "vertexai": "claude-haiku-5-5",
+    "azure": "claude-haiku-5-5"
+  },
   "claude-opus-4-1": {
     "bedrock": "anthropic.claude-opus-4-1-20250805-v1:0",
     "vertexai": "claude-opus-4-1"
@@ -94,13 +111,6 @@
     "vertexai": "claude-sonnet-5-5",
     "azure": "claude-sonnet-5-5"
   },
-  "deepseek-ocr": {
-    "vertexai": "deepseek-ai/deepseek-ocr-maas"
-  },
-  "deepseek-r1-0528": {
-    "vertexai": "deepseek-ai/deepseek-r1-0528-maas",
-    "openrouter": "deepseek/deepseek-r1-0528"
-  },
   "deepseek-v3.1": {
     "vertexai": "deepseek-ai/deepseek-v3.1-maas"
   },
@@ -120,6 +130,10 @@
     "deepseek": "deepseek-v4-pro",
     "openrouter": "deepseek/deepseek-v4-pro"
   },
+  "deepseek-v4.1-flash": {
+    "vertexai": "deepseek-ai/deepseek-v4.1-flash-maas",
+    "openrouter": "deepseek/deepseek-v4.1-flash"
+  },
   "enhanced": {
     "deepgram": "enhanced-general"
   },
@@ -142,6 +156,9 @@
     "openrouter": "google/gemini-2.5-flash-lite",
     "vertexai": "gemini-2.5-flash-lite"
   },
+  "gemini-2.5-flash-native-audio": {
+    "gemini": "gemini-2.5-flash-native-audio-latest"
+  },
   "gemini-2.5-pro": {
     "gemini": "gemini-2.5-pro",
     "openrouter": "google/gemini-2.5-pro",
@@ -183,8 +200,7 @@
   },
   "gemini-3.1-flash-lite-preview": {
     "gemini": "gemini-3.1-flash-lite-preview",
-    "openrouter": "google/gemini-3.1-flash-lite-preview",
-    "vertexai": "gemini-3.1-flash-lite-preview"
+    "openrouter": "google/gemini-3.1-flash-lite-preview"
   },
   "gemini-3.1-flash-tts-preview": {
     "gemini": "gemini-3.1-flash-tts-preview",
@@ -217,7 +233,12 @@
   },
   "gemini-3.5-transcribe": {
     "gemini": "gemini-3.5-transcribe",
-    "openrouter": "google/gemini-3.5-transcribe"
+    "openrouter": "google/gemini-3.5-transcribe",
+    "vertexai": "gemini-3.5-transcribe"
+  },
+  "gemini-3.5-transcribe-live": {
+    "gemini": "gemini-3.5-transcribe-live",
+    "vertexai": "gemini-3.5-transcribe-live"
   },
   "gemini-3.6-flash": {
     "gemini": "gemini-3.6-flash",
@@ -236,16 +257,28 @@
   },
   "gemini-3.8-flash-lite-tts": {
     "gemini": "gemini-3.8-flash-lite-tts",
-    "openrouter": "google/gemini-3.8-flash-lite-tts"
+    "openrouter": "google/gemini-3.8-flash-lite-tts",
+    "vertexai": "gemini-3.8-flash-lite-tts"
   },
   "gemini-3.8-flash-tts": {
     "gemini": "gemini-3.8-flash-tts",
-    "openrouter": "google/gemini-3.8-flash-tts"
+    "openrouter": "google/gemini-3.8-flash-tts",
+    "vertexai": "gemini-3.8-flash-tts"
   },
   "gemini-3.8-live": {
     "gemini": "gemini-3.8-live",
     "vertexai": "gemini-3.8-live"
   },
+  "gemini-4-argon": {
+    "gemini": "gemini-4-argon",
+    "openrouter": "google/gemini-4-argon",
+    "vertexai": "gemini-4-argon"
+  },
+  "gemini-4-carbon": {
+    "gemini": "gemini-4-carbon",
+    "openrouter": "google/gemini-4-carbon",
+    "vertexai": "gemini-4-carbon"
+  },
   "gemini-embedding-001": {
     "gemini": "gemini-embedding-001",
     "openrouter": "google/gemini-embedding-001",
@@ -261,22 +294,36 @@
     "openrouter": "google/gemini-embedding-2-preview"
   },
   "gemini-flash": {
-    "gemini": "gemini-flash-latest",
-    "vertexai": "gemini-flash-latest"
+    "gemini": "gemini-flash-latest"
   },
   "gemini-flash-lite": {
-    "gemini": "gemini-flash-lite-latest",
-    "vertexai": "gemini-flash-lite-latest"
+    "gemini": "gemini-flash-lite-latest"
   },
   "gemini-nano-banana-2.1": {
     "gemini": "gemini-nano-banana-2.1",
     "openrouter": "google/gemini-nano-banana-2.1",
     "vertexai": "gemini-nano-banana-2.1"
   },
+  "gemini-omni-1.1-flash": {
+    "gemini": "gemini-omni-1.1-flash",
+    "openrouter": "google/gemini-omni-1.1-flash"
+  },
+  "gemini-omni-1.2-flash": {
+    "gemini": "gemini-omni-1.2-flash",
+    "openrouter": "google/gemini-omni-1.2-flash",
+    "vertexai": "gemini-omni-1.2-flash"
+  },
   "gemini-omni-flash-preview": {
     "gemini": "gemini-omni-flash-preview",
     "vertexai": "gemini-omni-flash-preview"
   },
+  "gemini-pro": {
+    "gemini": "gemini-pro-latest"
+  },
+  "gemini-robotics-er-2-preview": {
+    "gemini": "gemini-robotics-er-2-preview",
+    "vertexai": "gemini-robotics-er-2-preview"
+  },
   "gemma-4-26b-a4b-it": {
     "gemini": "gemma-4-26b-a4b-it",
     "openrouter": "google/gemma-4-26b-a4b-it",
@@ -298,28 +345,10 @@
     "vertexai": "zai-org/glm-5.2-maas",
     "openrouter": "z-ai/glm-5.2"
   },
-  "gpt-3.5-turbo": {
-    "openai": "gpt-3.5-turbo",
-    "openrouter": "openai/gpt-3.5-turbo"
-  },
-  "gpt-3.5-turbo-16k": {
-    "openai": "gpt-3.5-turbo-16k",
-    "openrouter": "openai/gpt-3.5-turbo-16k"
-  },
-  "gpt-3.5-turbo-instruct": {
-    "openai": "gpt-3.5-turbo-instruct",
-    "openrouter": "openai/gpt-3.5-turbo-instruct",
-    "azure": "gpt-3.5-turbo-instruct"
-  },
   "gpt-4": {
     "openai": "gpt-4",
     "openrouter": "openai/gpt-4"
   },
-  "gpt-4-turbo": {
-    "openai": "gpt-4-turbo",
-    "openrouter": "openai/gpt-4-turbo",
-    "azure": "gpt-4-turbo"
-  },
   "gpt-4.1": {
     "openai": "gpt-4.1",
     "openrouter": "openai/gpt-4.1",
@@ -400,31 +429,11 @@
     "openrouter": "openai/gpt-5.1",
     "azure": "gpt-5.1"
   },
-  "gpt-5.1-codex": {
-    "openai": "gpt-5.1-codex",
-    "openrouter": "openai/gpt-5.1-codex",
-    "azure": "gpt-5.1-codex"
-  },
-  "gpt-5.1-codex-max": {
-    "openai": "gpt-5.1-codex-max",
-    "openrouter": "openai/gpt-5.1-codex-max",
-    "azure": "gpt-5.1-codex-max"
-  },
-  "gpt-5.1-codex-mini": {
-    "openai": "gpt-5.1-codex-mini",
-    "openrouter": "openai/gpt-5.1-codex-mini",
-    "azure": "gpt-5.1-codex-mini"
-  },
   "gpt-5.2": {
     "openai": "gpt-5.2",
     "openrouter": "openai/gpt-5.2",
     "azure": "gpt-5.2"
   },
-  "gpt-5.2-codex": {
-    "openai": "gpt-5.2-codex",
-    "openrouter": "openai/gpt-5.2-codex",
-    "azure": "gpt-5.2-codex"
-  },
   "gpt-5.2-pro": {
     "openai": "gpt-5.2-pro",
     "openrouter": "openai/gpt-5.2-pro"
@@ -498,6 +507,11 @@
     "openrouter": "openai/gpt-6.1-sol",
     "azure": "gpt-6.1-sol"
   },
+  "gpt-6.1-terra": {
+    "openai": "gpt-6.1-terra",
+    "openrouter": "openai/gpt-6.1-terra",
+    "azure": "gpt-6.1-terra"
+  },
   "gpt-audio": {
     "openai": "gpt-audio",
     "openrouter": "openai/gpt-audio",
@@ -508,11 +522,6 @@
     "openrouter": "openai/gpt-audio-mini",
     "azure": "gpt-audio-mini"
   },
-  "gpt-image-1": {
-    "openai": "gpt-image-1",
-    "openrouter": "openai/gpt-image-1",
-    "azure": "gpt-image-1"
-  },
   "gpt-image-1-mini": {
     "openai": "gpt-image-1-mini",
     "openrouter": "openai/gpt-image-1-mini",
@@ -533,6 +542,14 @@
     "openrouter": "openai/gpt-image-2.5-sunburst",
     "azure": "gpt-image-2.5-sunburst"
   },
+  "gpt-image-2.6-flare": {
+    "openai": "gpt-image-2.6-flare",
+    "openrouter": "openai/gpt-image-2.6-flare"
+  },
+  "gpt-image-2.6-sunburst": {
+    "openai": "gpt-image-2.6-sunburst",
+    "openrouter": "openai/gpt-image-2.6-sunburst"
+  },
   "gpt-oss-120b": {
     "vertexai": "openai/gpt-oss-120b-maas",
     "openrouter": "openai/gpt-oss-120b"
@@ -612,6 +629,9 @@
   "grok-4.6": {
     "vertexai": "xai/grok-4.6"
   },
+  "grok-4.7": {
+    "vertexai": "xai/grok-4.7"
+  },
   "grok-latest": {
     "xai": "grok-4.3"
   },
@@ -626,6 +646,9 @@
   "llama-4-maverick-17b-128e-instruct": {
     "vertexai": "meta/llama-4-maverick-17b-128e-instruct-maas"
   },
+  "llama-4-scout-17b-16e-instruct": {
+    "vertexai": "meta/llama-4-scout-17b-16e-instruct-maas"
+  },
   "lyria-3-clip-preview": {
     "gemini": "lyria-3-clip-preview",
     "openrouter": "google/lyria-3-clip-preview"
@@ -648,49 +671,19 @@
   "nova-3": {
     "deepgram": "nova-3-general"
   },
-  "o1": {
-    "openai": "o1",
-    "openrouter": "openai/o1",
-    "azure": "o1"
-  },
-  "o1-pro": {
-    "openai": "o1-pro",
-    "openrouter": "openai/o1-pro",
-    "azure": "o1-pro"
-  },
   "o3": {
     "openai": "o3",
     "openrouter": "openai/o3",
     "azure": "o3"
   },
-  "o3-mini": {
-    "openai": "o3-mini",
-    "openrouter": "openai/o3-mini",
-    "azure": "o3-mini"
-  },
   "o3-pro": {
     "openai": "o3-pro",
-    "openrouter": "openai/o3-pro"
-  },
-  "o4-mini": {
-    "openai": "o4-mini",
-    "openrouter": "openai/o4-mini",
-    "azure": "o4-mini"
+    "openrouter": "openai/o3-pro",
+    "azure": "o3-pro"
   },
   "qwen3-235b-a22b-instruct-2507": {
     "vertexai": "qwen/qwen3-235b-a22b-instruct-2507-maas"
   },
-  "qwen3-coder-480b-a35b-instruct": {
-    "vertexai": "qwen/qwen3-coder-480b-a35b-instruct-maas"
-  },
-  "qwen3-next-80b-a3b-instruct": {
-    "vertexai": "qwen/qwen3-next-80b-a3b-instruct-maas",
-    "openrouter": "qwen/qwen3-next-80b-a3b-instruct"
-  },
-  "qwen3-next-80b-a3b-thinking": {
-    "vertexai": "qwen/qwen3-next-80b-a3b-thinking-maas",
-    "openrouter": "qwen/qwen3-next-80b-a3b-thinking"
-  },
   "text-embedding-3-large": {
     "openai": "text-embedding-3-large",
     "openrouter": "openai/text-embedding-3-large",

data/lib/ruby_llm/attachment.rb

@@ -37,6 +37,18 @@ module RubyLLM
     # Media resolutions accepted by +resolution:+.
     RESOLUTIONS = %i[low medium high ultra_high original].freeze
 
+    # How the model reads a video: +:static+, +:agentic+, or +nil+ for the
+    # provider default.
+    attr_reader :processing
+
+    # Video processing modes accepted by +processing:+.
+    PROCESSING_MODES = %i[static agentic].freeze
+
+    ATTRIBUTE_ESCAPES = { # :nodoc:
+      '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', "'" => '&#39;', '"' => '&quot;'
+    }.freeze
+    CLOSING_FILE_TAG = %r{</(file)}i # :nodoc:
+
     # File extensions recognized as document attachments when the MIME type
     # alone is inconclusive.
     DOCUMENT_EXTENSIONS = %w[
@@ -62,7 +74,7 @@ module RubyLLM
 
     def self.coerce(source, config:) # :nodoc:
       return if source.nil? || (source.is_a?(String) && source.strip.empty?)
-      return source if source.is_a?(Attachment)
+      return source.with_default_config(config) if source.is_a?(Attachment)
       return source.to_attachment if source.respond_to?(:to_attachment)
       return from_h(source, config:) if source.is_a?(Hash)
 
@@ -72,7 +84,9 @@ module RubyLLM
 
     def self.from_h(data, config: nil) # :nodoc:
       data = data.transform_keys(&:to_sym)
-      new(data.fetch(:source), filename: data[:filename], resolution: data[:resolution]&.to_sym, config:)
+      new(data.fetch(:source), filename: data[:filename], mime_type: data[:mime_type],
+                               resolution: data[:resolution]&.to_sym,
+                               processing: data[:processing]&.to_sym, config:)
     end
 
     # Creates an attachment from +source+: a file path, URL, IO-like object,
@@ -89,31 +103,53 @@ module RubyLLM
     #
     #   RubyLLM::Attachment.new("page-3.png", resolution: :ultra_high)
     #
-    # +config:+ is the Configuration a URL source is downloaded with, and
-    # defaults to the global one.
+    # +processing:+ chooses how the model reads a video. +:static+ samples
+    # frames across the whole video up front. +:agentic+ lets the model
+    # navigate a long video and load only the parts it needs. Providers
+    # without the setting ignore it.
+    #
+    #   RubyLLM::Attachment.new("lecture.mp4", processing: :agentic)
+    #
+    # +mime_type:+ states the file's type, for a source RubyLLM cannot tell
+    # it from, such as an IO, instead of detecting it. A <tt>charset</tt>
+    # says how to read binary text; #mime_type leaves parameters out. A
+    # Rails attachment's type comes from its blob, so set it there for one.
+    #
+    #   RubyLLM::Attachment.new(io, filename: "export.csv", mime_type: "text/csv")
+    #
+    # +config:+ is the Configuration a URL source is downloaded with. It
+    # defaults to that of the chat or operation the attachment is given to,
+    # then to the global one.
     #
     # Paths and URLs must be trusted and authorized by the application.
     # They can be read or fetched during construction to detect the MIME type.
     # Validate upload parameters before passing them here: an unchecked String
     # can access local files or internal network endpoints.
-    def initialize(source, filename: nil, resolution: nil, config: nil)
-      unless resolution.nil? || RESOLUTIONS.include?(resolution)
-        raise ArgumentError, "resolution must be one of #{RESOLUTIONS.join(', ')}, got #{resolution.inspect}"
-      end
+    def initialize(source, filename: nil, mime_type: nil, resolution: nil, processing: nil, config: nil)
+      check_option(:resolution, resolution, RESOLUTIONS)
+      check_option(:processing, processing, PROCESSING_MODES)
 
       @config = config
       @resolution = resolution
+      @processing = processing
       @source = source
       @source = source_type_cast
       @filename = filename || source_filename
 
-      determine_mime_type
+      @given_mime_type = mime_type
+      @mime_type = media_type(mime_type)
+      determine_mime_type unless @mime_type
     end
 
     def config # :nodoc:
       @config || RubyLLM.config
     end
 
+    def with_default_config(config) # :nodoc:
+      @config ||= config
+      self
+    end
+
     def url? # :nodoc:
       @source.is_a?(URI) || (@source.is_a?(String) && @source.match?(%r{\Ahttps?://}i))
     end
@@ -149,7 +185,7 @@ module RubyLLM
     end
 
     def io_like? # :nodoc:
-      @source.respond_to?(:read) && !path? && !active_storage? && !provider_file?
+      @source.respond_to?(:read) && !path? && !url? && !active_storage? && !provider_file?
     end
 
     def active_storage? # :nodoc:
@@ -178,7 +214,8 @@ module RubyLLM
     def for_llm # :nodoc:
       case type
       when :text
-        "<file name='#{filename}' mime_type='#{mime_type}'>#{content}</file>"
+        "<file name='#{escape_attribute(filename)}' mime_type='#{escape_attribute(mime_type)}'>" \
+        "#{content.to_s.gsub(CLOSING_FILE_TAG, '<\/\1')}</file>"
       else
         data_uri
       end
@@ -250,8 +287,23 @@ module RubyLLM
       RubyLLM::Files::MimeType.text? mime_type
     end
 
+    # Returns whether the attachment holds only the start of a text, the
+    # way a chat with a file store sends a file longer than its inline
+    # limit (see Chat#with_file_store). The whole file stays in the chat's
+    # files, and the text says where. An attachment you make is never
+    # partial.
+    def partial?
+      @partial == true
+    end
+
+    def mark_partial # :nodoc:
+      @partial = true
+      self
+    end
+
     def to_h # :nodoc:
-      { type: type, source: @source, filename: filename, resolution: resolution }.compact
+      { type: type, source: @source, filename: filename, mime_type: @given_mime_type, resolution: resolution,
+        processing: processing }.compact
     end
 
     def byte_size # :nodoc:
@@ -260,6 +312,16 @@ module RubyLLM
 
     private
 
+    def escape_attribute(value)
+      value.to_s.gsub(/[&<>'"]/, ATTRIBUTE_ESCAPES)
+    end
+
+    def check_option(name, value, allowed)
+      return if value.nil? || allowed.include?(value)
+
+      raise ArgumentError, "#{name} must be one of #{allowed.join(', ')}, got #{value.inspect}"
+    end
+
     def data_uri
       "data:#{mime_type};base64,#{encoded}"
     end
@@ -309,12 +371,26 @@ module RubyLLM
       end
     end
 
-    # Text content is loaded as binary; retag it so payloads serialize as UTF-8.
+    # Text content loaded as binary is retagged so payloads serialize as
+    # UTF-8. An IO can return text already tagged, with bytes its encoding
+    # does not allow.
     def normalize_text_encoding
-      return unless text? && @content.is_a?(String) && @content.encoding == Encoding::ASCII_8BIT
+      return unless text? && @content.is_a?(String)
 
-      text = @content.dup.force_encoding(Encoding::UTF_8)
-      @content = text.valid_encoding? ? text : text.scrub
+      @content = decoded_text(@content) if @content.encoding == Encoding::ASCII_8BIT
+      @content = @content.scrub unless @content.valid_encoding?
+    end
+
+    def decoded_text(bytes)
+      charset = @given_mime_type.to_s[/charset="?([^";\s]+)/i, 1] || Encoding::UTF_8
+      bytes.dup.force_encoding(charset).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    rescue ArgumentError, EncodingError
+      bytes.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def media_type(mime_type)
+      type = mime_type.to_s.split(';').first.to_s.strip.downcase
+      type unless type.empty?
     end
 
     def determine_mime_type
@@ -324,13 +400,18 @@ module RubyLLM
       return @mime_type = content_type unless content_type.to_s.empty?
 
       @mime_type = RubyLLM::Files::MimeType.for(url? ? nil : @source, name: @filename)
-      @mime_type = RubyLLM::Files::MimeType.for(content) if @mime_type == 'application/octet-stream'
+      @mime_type = content_mime_type if @mime_type == 'application/octet-stream'
       @mime_type = 'audio/wav' if @mime_type == 'audio/x-wav'
     end
 
+    # An IO's bytes were examined already, so it isn't read in full for a
+    # second look.
+    def content_mime_type
+      io_like? ? @mime_type : RubyLLM::Files::MimeType.for(content)
+    end
+
     def fetch_content
-      response = Transport::Connection.basic(config).get @source.to_s
-      @content = response.body
+      @content = Transport::Connection.download(@source, config)
     end
 
     def load_content_from_path
@@ -406,7 +487,7 @@ module RubyLLM
     end
 
     def inspect_attributes # :nodoc:
-      { filename: filename, mime_type: mime_type, resolution: resolution, source: @source }
+      { filename: filename, mime_type: mime_type, resolution: resolution, processing: processing, source: @source }
     end
   end
 end