llm.rb 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd935a4ccd3b911e92b5ff54335cfc143247cbb5fe55214fd563551f7349da4
-  data.tar.gz: c76b36f2877c0cec7fdde54471a81ae19a4ec044158077742eba9acd26cd1483
+  metadata.gz: 587a0b7425102e44f79107bd5f0471ba2cb8f88d95fe28af5e1d334093a539e3
+  data.tar.gz: 73242cb4daa8890a1f16d578c0e6ff50d54651162d11132ce06d9fb571fec062
 SHA512:
-  metadata.gz: f654d042a6f44cba15b2dc0049d3933aa442f631293be446486e524773ff01bfc0f13f89ecbf09659a175c3ff9f7c6512ae8bde5716f6935c8d3d05528d3e4e9
-  data.tar.gz: 73945113e01d89188301a1a7db921c8c07ac19a847fa71528bc2e62eb5162ac656aca02a5f17e02bc4918dc973c298f0021afbb14a4cb38e7f81705950c4ed5b
+  metadata.gz: 1f62948774f2cc389ec8b1d53886785667c95d4bd98d3f648307c07342b004c080feb40ae8baa9bda0cb6cf0d3cbeec33f084e9cd5a0a22622a07519a772c0b4
+  data.tar.gz: 92ce35a290004371ed6ac8ef11d4a41344d85170f398d69ebf2d5251a1a73fc9db79e3065ab5e8d32945070854362f415276a00ac56a4d4e916cd5752f12b5d4

data/README.md

@@ -3,14 +3,18 @@
 llm.rb is a zero-dependency Ruby toolkit for Large Language Models that
 includes OpenAI, Gemini, Anthropic, xAI (grok), DeepSeek, Ollama, and
 LlamaCpp. The toolkit includes full support for chat, streaming, tool calling,
-audio, images, files, and JSON Schema generation.
+audio, images, files, and structured outputs (JSON Schema).
+
+The library provides a common, uniform interface for all the providers and
+features it supports, in addition to provider-specific features as well. Keep
+reading to find out more.
 
 ## Features
 
 #### General
 - ✅ A single unified interface for multiple providers
 - 📦 Zero dependencies outside Ruby's standard library
-- 🚀 Efficient API design that minimizes the number of requests made
+- 🚀 Smart API design that minimizes the number of requests made
 
 #### Chat, Agents
 - 🧠 Stateless and stateful chat via completions and responses API
@@ -22,7 +26,7 @@ audio, images, files, and JSON Schema generation.
 - 🗣️ Text-to-speech, transcription, and translation
 - 🖼️ Image generation, editing, and variation support
 - 📎 File uploads and prompt-aware file interaction
-- 💡 Multimodal prompts (text, images, PDFs, URLs, files)
+- 💡 Multimodal prompts (text, documents, audio, images, videos, URLs, etc)
 
 #### Embeddings
 - 🧮 Text embeddings and vector support
@@ -44,12 +48,12 @@ breaks things down by provider, so you can see exactly what’s supported where.
 | **Streaming**                        | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
 | **Tool Calling**                     | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
 | **JSON Schema / Structured Output**  | ✅     | ❌        | ✅     | ❌       | ✅         | ✅*    | ✅*      |
+| **Embeddings**                       | ✅     | ✅        | ✅     | ✅       | ❌         | ✅     | ✅       |
+| **Multimodal Prompts** *(text, documents, audio, images, videos, URLs, etc)* | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
+| **Files API**                        | ✅     | ✅        | ✅     | ❌       | ❌         | ❌     | ❌       |
+| **Models API**                       | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
 | **Audio (TTS / Transcribe / Translate)** | ✅  | ❌        | ✅     | ❌       | ❌         | ❌     | ❌       |
 | **Image Generation & Editing**       | ✅     | ❌        | ✅     | ❌       | ✅         | ❌     | ❌       |
-| **File Uploads**                     | ✅     | ❌        | ✅     | ❌       | ❌         | ❌     | ❌       |
-| **Multimodal Prompts** *(text+image)* | ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
-| **Embeddings**                       | ✅     | ✅        | ✅     | ✅       | ❌         | ✅     | ✅       |
-| **Models API**                       g| ✅     | ✅        | ✅     | ✅       | ✅         | ✅     | ✅       |
 | **Local Model Support**              | ❌     | ❌        | ❌     | ❌       | ❌         | ✅     | ✅       |
 | **Vector Stores (RAG)**               | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
 | **Responses**                        | ✅     | ❌        | ❌     | ❌       | ❌         | ❌     | ❌       |
@@ -110,12 +114,12 @@ require "llm"
 
 llm  = LLM.openai(key: ENV["KEY"])
 bot  = LLM::Bot.new(llm)
-url  = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Cognac_glass.jpg/500px-Cognac_glass.jpg"
+url  = "https://en.wikipedia.org/wiki/Special:FilePath/Cognac_glass.jpg"
 msgs = bot.chat do |prompt|
   prompt.system "Your task is to answer all user queries"
   prompt.user ["Tell me about this URL", URI(url)]
-  prompt.user ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "rb")]
-  prompt.user "Is the URL and PDF similar to each other?"
+  prompt.user ["Tell me about this PDF", File.open("handbook.pdf", "rb")]
+  prompt.user "Are the URL and PDF similar to each other?"
 end
 
 # At this point, we execute a single request
@@ -142,12 +146,12 @@ require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm)
-url = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Cognac_glass.jpg/500px-Cognac_glass.jpg"
+url = "https://en.wikipedia.org/wiki/Special:FilePath/Cognac_glass.jpg"
 bot.chat(stream: $stdout) do |prompt|
   prompt.system "Your task is to answer all user queries"
   prompt.user ["Tell me about this URL", URI(url)]
-  prompt.user ["Tell me about this pdf", File.open("spec/fixtures/documents/freebsd.sysctl.pdf", "rb")]
-  prompt.user "Is the URL and PDF similar to each other?"
+  prompt.user ["Tell me about this PDF", File.open("handbook.pdf", "rb")]
+  prompt.user "Are the URL and PDF similar to each other?"
 end.to_a
 ```
 
@@ -167,10 +171,10 @@ require "llm"
 ##
 # Objects
 llm = LLM.openai(key: ENV["KEY"])
-schema = llm.schema.object(probability: llm.schema.integer.required)
+schema = llm.schema.object(probability: llm.schema.number.required)
 bot = LLM::Bot.new(llm, schema:)
 bot.chat "Does the earth orbit the sun?", role: :user
-bot.messages.find(&:assistant?).content! # => {probability: 1}
+bot.messages.find(&:assistant?).content! # => {probability: 1.0}
 
 ##
 # Enums
@@ -259,7 +263,7 @@ require "llm"
 llm = LLM.openai(key: ENV["KEY"])
 bot = LLM::Bot.new(llm)
 file = llm.files.create(file: "/books/goodread.pdf")
-bot.chat(["Tell me about this file", file])
+bot.chat ["Tell me about this file", file]
 bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
 ```
 
@@ -477,7 +481,7 @@ end
 ##
 # Select a model
 model = llm.models.all.find { |m| m.id == "gpt-3.5-turbo" }
-bot = LLM::Bot.new(llm, model:)
+bot = LLM::Bot.new(llm, model: model.id)
 bot.chat "Hello #{model.id} :)"
 bot.messages.select(&:assistant?).each { print "[#{_1.role}] ", _1.content, "\n" }
 ```
@@ -493,8 +497,12 @@ over or doesn't cover at all. The API reference is available at
 
 ### Guides
 
-* [An introduction to RAG with llm.rb](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/) –
-  a blog post that implements the RAG pattern in 32 lines of Ruby code
+* [An introduction to RAG](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/) –
+  a blog post that implements the RAG pattern
+* [How to estimate the age of a person in a photo](https://0x1eef.github.io/posts/age-estimation-with-llm.rb/) –
+  a blog post that implements an age estimation tool
+* [How to edit an image with Gemini](https://0x1eef.github.io/posts/how-to-edit-images-with-gemini/) –
+  a blog post that implements image editing with Gemini
 * [docs/](docs/) – the docs directory contains additional guides
 
 

data/lib/llm/bot/conversable.rb

@@ -12,8 +12,12 @@ class LLM::Bot
     # @param [Hash] params
     # @return [void]
     def async_response(prompt, params = {})
-      role = params.delete(:role)
-      @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
+      if Array === prompt and prompt.empty?
+        @messages
+      else
+        role = params.delete(:role)
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :respond]
+      end
     end
 
     ##
@@ -22,8 +26,12 @@ class LLM::Bot
     # @param [Hash] params
     # @return [void]
     def async_completion(prompt, params = {})
-      role = params.delete(:role)
-      @messages.push [LLM::Message.new(role, prompt), @params.merge(params), :complete]
+      if Array === prompt and prompt.empty?
+        @messages
+      else
+        role = params.delete(:role)
+        @messages << [LLM::Message.new(role, prompt), @params.merge(params), :complete]
+      end
     end
   end
 end

data/lib/llm/bot/prompt/completion.rb

@@ -27,5 +27,23 @@ module LLM::Bot::Prompt
       params = defaults.merge(params)
       bot.chat prompt, params.merge(role: :user)
     end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def assistant(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :assistant)
+    end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def model(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :model)
+    end
   end
 end

data/lib/llm/bot/prompt/respond.rb

@@ -36,5 +36,14 @@ module LLM::Bot::Prompt
       params = defaults.merge(params)
       bot.respond prompt, params.merge(role: :user)
     end
+
+    ##
+    # @param [String] prompt
+    # @param [Hash] params (see LLM::Provider#complete)
+    # @return [LLM::Bot]
+    def assistant(prompt, params = {})
+      params = defaults.merge(params)
+      bot.chat prompt, params.merge(role: :assistant)
+    end
   end
 end

data/lib/llm/bot.rb

@@ -13,12 +13,12 @@ module LLM
   #
   #   llm  = LLM.openai(key: ENV["KEY"])
   #   bot  = LLM::Bot.new(llm)
-  #   url  = "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/Cognac_glass.jpg/500px-Cognac_glass.jpg"
+  #   url  = "https://en.wikipedia.org/wiki/Special:FilePath/Cognac_glass.jpg"
   #   msgs = bot.chat do |prompt|
   #     prompt.system "Your task is to answer all user queries"
   #     prompt.user ["Tell me about this URL", URI(url)]
-  #     prompt.user ["Tell me about this pdf", File.open("freebsd_book.pdf", "rb")]
-  #     prompt.user "Is the URL and PDF similar to each other?"
+  #     prompt.user ["Tell me about this PDF", File.open("handbook.pdf", "rb")]
+  #     prompt.user "Are the URL and PDF similar to each other?"
   #   end
   #
   #   # At this point, we execute a single request

data/lib/llm/buffer.rb

@@ -55,7 +55,7 @@ module LLM
     end
 
     ##
-    # @param [[LLM::Message, Hash]] item
+    # @param [[LLM::Message, Hash, Symbol]] item
     #  A message and its parameters
     # @return [void]
     def <<(item)
@@ -80,6 +80,27 @@ module LLM
       "completed_count=#{@completed.size} pending_count=#{@pending.size}>"
     end
 
+    ##
+    # Returns true when the buffer is empty
+    # @return [Boolean]
+    def empty?
+      @pending.empty? and @completed.empty?
+    end
+
+    ##
+    # @example
+    #   llm = LLM.openai(key: ENV["KEY"])
+    #   bot = LLM::Bot.new(llm, stream: $stdout)
+    #   bot.chat "Hello", role: :user
+    #   bot.messages.drain
+    # @note
+    #   This method is especially useful when using the streaming API.
+    # Drains the buffer and returns all messages as an array
+    # @return [Array<LLM::Message>]
+    def drain
+      to_a
+    end
+
     private
 
     def empty!
@@ -94,23 +115,26 @@ module LLM
     end
 
     def complete!(message, params)
-      pendings = @pending.map { _1[0] }
-      messages = [*@completed, *pendings]
+      oldparams = @pending.map { _1[1] }
+      pendings  = @pending.map { _1[0] }
+      messages  = [*@completed, *pendings]
       role = message.role
       completion = @provider.complete(
         message.content,
-        params.merge(role:, messages:)
+        [*oldparams, params.merge(role:, messages:)].inject({}, &:merge!)
       )
       @completed.concat([*pendings, message, *completion.choices[0]])
       @pending.clear
     end
 
     def respond!(message, params)
-      pendings = @pending.map { _1[0] }
-      input = [*pendings]
+      oldparams = @pending.map { _1[1] }
+      pendings  = @pending.map { _1[0] }
+      messages  = [*pendings]
       role = message.role
       params = [
-        params.merge(input:),
+        *oldparams,
+        params.merge(input: messages),
         @response ? {previous_response_id: @response.id} : {}
       ].inject({}, &:merge!)
       @response = @provider.responses.create(message.content, params.merge(role:))

data/lib/llm/error.rb

@@ -31,6 +31,10 @@ module LLM
   # HTTPTooManyRequests
   RateLimitError = Class.new(ResponseError)
 
+  ##
+  # HTTPServerError
+  ServerError = Class.new(ResponseError)
+
   ##
   # When an given an input object that is not understood
   FormatError = Class.new(Error)

data/lib/llm/file.rb

@@ -26,7 +26,7 @@ class LLM::File
   # @return [String]
   #  Returns the MIME type of the file
   def mime_type
-    LLM::Mime[File.extname(path)]
+    LLM::Mime[path]
   end
 
   ##

data/lib/llm/function.rb

@@ -53,7 +53,7 @@ class LLM::Function
   # @yieldparam [LLM::Function] self The function object
   def initialize(name, &b)
     @name = name
-    @schema = JSON::Schema.new
+    @schema = LLM::Schema.new
     @called = false
     @cancelled = false
     yield(self)
@@ -72,7 +72,7 @@ class LLM::Function
   end
 
   ##
-  # @yieldparam [JSON::Schema] schema The schema object
+  # @yieldparam [LLM::Schema] schema The schema object
   # @return [void]
   def params
     @params = yield(@schema)

data/lib/llm/mime.rb

@@ -3,15 +3,16 @@
 ##
 # @private
 class LLM::Mime
+  EXTNAME = /\A\.[a-zA-Z0-9]+\z/
+  private_constant :EXTNAME
+
   ##
   # Lookup a mime type
   # @return [String, nil]
   def self.[](key)
-    if key.respond_to?(:path)
-      types[File.extname(key.path)]
-    else
-      types[key]
-    end
+    key = key.respond_to?(:path) ? key.path : key
+    extname = (key =~ EXTNAME) ? key : File.extname(key)
+    types[extname] || "application/octet-stream"
   end
 
   ##
@@ -24,6 +25,15 @@ class LLM::Mime
       ".jpg" => "image/jpeg",
       ".jpeg" => "image/jpeg",
       ".webp" => "image/webp",
+      ".gif" => "image/gif",
+      ".bmp" => "image/bmp",
+      ".tif" => "image/tiff",
+      ".tiff" => "image/tiff",
+      ".svg" => "image/svg+xml",
+      ".ico" => "image/x-icon",
+      ".apng" => "image/apng",
+      ".jfif" => "image/jpeg",
+      ".heic" => "image/heic",
 
       # Videos
       ".flv" => "video/x-flv",
@@ -34,6 +44,12 @@ class LLM::Mime
       ".webm" => "video/webm",
       ".wmv" => "video/x-ms-wmv",
       ".3gp" => "video/3gpp",
+      ".avi" => "video/x-msvideo",
+      ".mkv" => "video/x-matroska",
+      ".ogv" => "video/ogg",
+      ".m4v" => "video/x-m4v",
+      ".m2ts" => "video/mp2t",
+      ".mts" => "video/mp2t",
 
       # Audio
       ".aac" => "audio/aac",
@@ -45,10 +61,80 @@ class LLM::Mime
       ".pcm" => "audio/L16",
       ".wav" => "audio/wav",
       ".weba" => "audio/webm",
+      ".oga" => "audio/ogg",
+      ".ogg" => "audio/ogg",
+      ".mid" => "audio/midi",
+      ".midi" => "audio/midi",
+      ".aiff" => "audio/aiff",
+      ".aif" => "audio/aiff",
+      ".amr" => "audio/amr",
+      ".mka" => "audio/x-matroska",
+      ".caf" => "audio/x-caf",
 
       # Documents
       ".pdf" => "application/pdf",
-      ".txt" => "text/plain"
+      ".txt" => "text/plain",
+      ".md" => "text/markdown",
+      ".markdown" => "text/markdown",
+      ".mkd" => "text/markdown",
+      ".doc" => "application/msword",
+      ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".xls" => "application/vnd.ms-excel",
+      ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      ".ppt" => "application/vnd.ms-powerpoint",
+      ".pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      ".csv" => "text/csv",
+      ".json" => "application/json",
+      ".xml" => "application/xml",
+      ".html" => "text/html",
+      ".htm" => "text/html",
+      ".odt" => "application/vnd.oasis.opendocument.text",
+      ".odp" => "application/vnd.oasis.opendocument.presentation",
+      ".ods" => "application/vnd.oasis.opendocument.spreadsheet",
+      ".rtf" => "application/rtf",
+      ".epub" => "application/epub+zip",
+
+      # Code
+      ".js" => "application/javascript",
+      ".jsx" => "text/jsx",
+      ".ts" => "application/typescript",
+      ".tsx" => "text/tsx",
+      ".css" => "text/css",
+      ".c" => "text/x-c",
+      ".cpp" => "text/x-c++",
+      ".h" => "text/x-c",
+      ".rb" => "text/x-ruby",
+      ".py" => "text/x-python",
+      ".java" => "text/x-java-source",
+      ".sh" => "application/x-sh",
+      ".php" => "application/x-httpd-php",
+      ".yml" => "text/yaml",
+      ".yaml" => "text/yaml",
+      ".go" => "text/x-go",
+      ".rs" => "text/rust",
+
+      # Fonts
+      ".woff" => "font/woff",
+      ".woff2" => "font/woff2",
+      ".ttf" => "font/ttf",
+      ".otf" => "font/otf",
+
+      # Archives
+      ".zip" => "application/zip",
+      ".tar" => "application/x-tar",
+      ".gz" => "application/gzip",
+      ".bz2" => "application/x-bzip2",
+      ".xz" => "application/x-xz",
+      ".rar" => "application/vnd.rar",
+      ".7z" => "application/x-7z-compressed",
+      ".tar.gz" => "application/gzip",
+      ".tar.bz2" => "application/x-bzip2",
+      ".apk" => "application/vnd.android.package-archive",
+      ".exe" => "application/x-msdownload",
+
+      # Others
+      ".ics" => "text/calendar",
+      ".vcf" => "text/vcard"
     }
   end
 end

data/lib/llm/provider.rb

@@ -198,9 +198,9 @@ class LLM::Provider
 
   ##
   # Returns an object that can generate a JSON schema
-  # @return [JSON::Schema]
+  # @return [LLM::Schema]
   def schema
-    @schema ||= JSON::Schema.new
+    @schema ||= LLM::Schema.new
   end
 
   ##
@@ -284,7 +284,8 @@ class LLM::Provider
         parser&.free
       end
     else
-      client.request(request, &b)
+      b ? client.request(request) { (Net::HTTPSuccess === _1) ? b.call(_1) : _1 } :
+          client.request(request)
     end
     handle_response(res)
   end

data/lib/llm/providers/anthropic/error_handler.rb

@@ -22,6 +22,8 @@ class LLM::Anthropic
     #  Raises a subclass of {LLM::Error LLM::Error}
     def raise_error!
       case res
+      when Net::HTTPServerError
+        raise LLM::ServerError.new { _1.response = res }, "Server error"
       when Net::HTTPUnauthorized
         raise LLM::UnauthorizedError.new { _1.response = res }, "Authentication error"
       when Net::HTTPTooManyRequests

data/lib/llm/providers/anthropic/files.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+class LLM::Anthropic
+  ##
+  # The {LLM::Anthropic::Files LLM::Anthropic::Files} class provides a files
+  # object for interacting with [Anthropic's Files API](https://docs.anthropic.com/en/docs/build-with-claude/files).
+  #
+  # @example
+  #   #!/usr/bin/env ruby
+  #   require "llm"
+  #
+  #   llm = LLM.anthropic(key: ENV["KEY"])
+  #   bot = LLM::Bot.new(llm)
+  #   file = llm.files.create file: "/books/goodread.pdf"
+  #   bot.chat ["Tell me about this PDF", file]
+  #   bot.messages.select(&:assistant?).each { print "[#{_1.role}]", _1.content, "\n" }
+  class Files
+    require_relative "response/file"
+    ##
+    # Returns a new Files object
+    # @param provider [LLM::Provider]
+    # @return [LLM::Anthropic::Files]
+    def initialize(provider)
+      @provider = provider
+    end
+
+    ##
+    # List all files
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.all
+    #   res.each do |file|
+    #     print "id: ", file.id, "\n"
+    #   end
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @param [Hash] params Other parameters (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def all(**params)
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/files?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Anthropic::Response::Enumerable)
+    end
+
+    ##
+    # Create a file
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.create file: "/documents/haiku.txt"
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @param [File, LLM::File, String] file The file
+    # @param [Hash] params Other parameters (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def create(file:, **params)
+      multi = LLM::Multipart.new(params.merge!(file: LLM.File(file)))
+      req = Net::HTTP::Post.new("/v1/files", headers)
+      req["content-type"] = multi.content_type
+      set_body_stream(req, multi.body)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Anthropic::Response::File)
+    end
+
+    ##
+    # Get a file
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.get(file: "file-1234567890")
+    #   print "id: ", res.id, "\n"
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @param [#id, #to_s] file The file ID
+    # @param [Hash] params Other parameters - if any (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def get(file:, **params)
+      file_id = file.respond_to?(:id) ? file.id : file
+      query = URI.encode_www_form(params)
+      req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Anthropic::Response::File)
+    end
+
+    ##
+    # Retrieve file metadata
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.get_metadata(file: "file-1234567890")
+    #   print "id: ", res.id, "\n"
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files
+    # @param [#id, #to_s] file The file ID
+    # @param [Hash] params Other parameters - if any (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def get_metadata(file:, **params)
+      query = URI.encode_www_form(params)
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Get.new("/v1/files/#{file_id}?#{query}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res).extend(LLM::Anthropic::Response::File)
+    end
+    alias_method :retrieve_metadata, :get_metadata
+
+    ##
+    # Delete a file
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.delete(file: "file-1234567890")
+    #   print res.deleted, "\n"
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @param [#id, #to_s] file The file ID
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def delete(file:)
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Delete.new("/v1/files/#{file_id}", headers)
+      res = execute(request: req)
+      LLM::Response.new(res)
+    end
+
+    ##
+    # Download the contents of a file
+    # @note
+    #   You can only download files that were created by the code
+    #   execution tool. Files that you uploaded cannot be downloaded.
+    # @example
+    #   llm = LLM.anthropic(key: ENV["KEY"])
+    #   res = llm.files.download(file: "file-1234567890")
+    #   File.binwrite "program.c", res.file.read
+    #   print res.file.read, "\n"
+    # @see https://docs.anthropic.com/en/docs/build-with-claude/files Anthropic docs
+    # @param [#id, #to_s] file The file ID
+    # @param [Hash] params Other parameters (see Anthropic docs)
+    # @raise (see LLM::Provider#request)
+    # @return [LLM::Response]
+    def download(file:, **params)
+      query = URI.encode_www_form(params)
+      file_id = file.respond_to?(:id) ? file.id : file
+      req = Net::HTTP::Get.new("/v1/files/#{file_id}/content?#{query}", headers)
+      io = StringIO.new("".b)
+      res = execute(request: req) { |res| res.read_body { |chunk| io << chunk } }
+      LLM::Response.new(res).tap { _1.define_singleton_method(:file) { io } }
+    end
+
+    private
+
+    def key
+      @provider.instance_variable_get(:@key)
+    end
+
+    [:headers, :execute, :set_body_stream].each do |m|
+      define_method(m) { |*args, **kwargs, &b| @provider.send(m, *args, **kwargs, &b) }
+    end
+  end
+end