anthropic 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b7437e17231234859a48749dd8da3cdbd5a809df002cb2654a78b6d91edbff5
-  data.tar.gz: 38b2a62cc793013345b9eeef31d152f3fcd1a704515a45640132ff8ceccfd24c
+  metadata.gz: e9def8893a5bf773385f2acf8cab126f65fcaf8c14c0aa30809ce20150221da8
+  data.tar.gz: eb2fd9b075ff306205857c4ecd926c9a1d0e82d20a5c91c1d03711c7947090f2
 SHA512:
-  metadata.gz: 53e3400a7f4a752a981e788dac7b83c286732dd18216ad0314a7a84d703f582930b5dcaeae19ebcd8c8ab3ace746dbe277e096fe5604c5b3edc9163acf1b16fd
-  data.tar.gz: 94ea524fb3e4b6a1e7b8f3277315b7a001488bbb7d345240cf6120820af405be212f6a8e6a30f480e2c14110cc03cd71545cf022538d6ce1c8936f7631cef41e
+  metadata.gz: 5a4c4015f3b2416adbe94b7a2170eb61dcecc7e87f71e6f26f7006006bd15801c9a28197af6892cf0f0393f8e6c9901a625419ebf9d5bee425c2de4ef514bc9d
+  data.tar.gz: 2e2ab2e3e71affe935a42e54e8e38eea23ec31a37495d8c1e9004aff96fd24163e802efe64de7b32e3e4304743525788a0a0337c9a90d0f79e478471c330f2c4

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2025-04-10
+
+### Changed
+
+- Add deprecation warning - this gem will be renamed to ruby-anthropic in the next release, to make way for the new official Anthropic SDK (currently at https://github.com/anthropics/anthropic-sdk-ruby).
+- The gem name 'anthropic' will soon refer to the official Anthropic SDK. You'll need to update your Gemfile to 'ruby-anthropic' if you want to keep using this gem.
+
+## [0.4.0] - 2025-03-25
+
+### Added
+
+- Add Batches API! Thanks to [@ignacio-chiazzo](https://github.com/ignacio-chiazzo) for previous work on this.
+- Thanks to [@seuros](https://github.com/seuros) for helpful README notes on Batch usage.
+
 ## [0.3.2] - 2024-10-09
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    anthropic (0.3.2)
+    anthropic (0.4.1)
       event_stream_parser (>= 0.3.0, < 2.0.0)
       faraday (>= 1)
       faraday-multipart (>= 1)

data/README.md

@@ -4,6 +4,10 @@
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alexrudall/anthropic/blob/main/LICENSE.txt)
 [![CircleCI Build Status](https://circleci.com/gh/alexrudall/anthropic.svg?style=shield)](https://circleci.com/gh/alexrudall/anthropic)
 
+> [!IMPORTANT]
+> This gem has been renamed from `anthropic` to `ruby-anthropic`, to make way for the new [official Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) 🎉
+> If you wish to keep using this gem, you just need to update your Gemfile from `anthropic` to `ruby-anthropic` and version `0.4.2` or greater. No other changes are needed and it will continue to work as normal.
+
 Use the [Anthropic API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) with Ruby! 🤖🌌
 
 You can get access to the API [here](https://docs.anthropic.com/claude/docs/getting-access-to-claude).
@@ -43,7 +47,10 @@ require "anthropic"
 For a quick test you can pass your token directly to a new client:
 
 ```ruby
-client = Anthropic::Client.new(access_token: "access_token_goes_here")
+client = Anthropic::Client.new(
+  access_token: "access_token_goes_here",
+  log_errors: true # Highly recommended in development, so you can see what errors Anthropic is returning. Not recommended in production because it could leak private data to your logs.
+)
 ```
 
 ### With Config
@@ -53,10 +60,11 @@ For a more robust setup, you can configure the gem with your API keys, for examp
 ```ruby
 Anthropic.configure do |config|
   # With dotenv
-  config.access_token = ENV.fetch("ANTHROPIC_API_KEY")
+  config.access_token = ENV.fetch("ANTHROPIC_API_KEY"),
   # OR
   # With Rails credentials
-  config.access_token = Rails.application.credentials.dig(:anthropic, :api_key)
+  config.access_token = Rails.application.credentials.dig(:anthropic, :api_key),
+  config.log_errors = true # Highly recommended in development, so you can see what errors Anthropic is returning. Not recommended in production because it could leak private data to your logs.
 end
 ```
 
@@ -75,6 +83,7 @@ The default timeout for any request using this library is 120 seconds. You can c
 ```ruby
 client = Anthropic::Client.new(
   access_token: "access_token_goes_here",
+  log_errors: true, # Optional
   anthropic_version: "2023-01-01", # Optional
   request_timeout: 240 # Optional
 )
@@ -90,6 +99,16 @@ Anthropic.configure do |config|
 end
 ```
 
+#### Logging
+
+##### Errors
+By default, the `anthropic` gem does not log any `Faraday::Error`s encountered while executing a network request to avoid leaking data (e.g. 400s, 500s, SSL errors and more - see [here](https://www.rubydoc.info/github/lostisland/faraday/Faraday/Error) for a complete list of subclasses of `Faraday::Error` and what can cause them).
+
+If you would like to enable this functionality, you can set `log_errors` to `true` when configuring the client:
+```ruby
+client = Anthropic::Client.new(log_errors: true)
+```
+
 ### Models
 
 Available Models:
@@ -133,7 +152,74 @@ response = client.messages(
 # => }
 ```
 
-#### Vision
+### Batches
+The Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing a soon as possible.
+
+Batches can contain up to 100,000 requests or 256 MB in total size, whichever limit is reached first.
+
+Create a batch of message requests:
+```ruby
+response = client.messages.batches.create(
+  parameters: {
+    requests: [
+      {
+        custom_id: "my-first-request",
+        params: {
+          model: "claude-3-haiku-20240307",
+          max_tokens: 1024,
+          messages: [
+            { role: "user", content: "Hello, world" }
+          ]
+        }
+      },
+      {
+        custom_id: "my-second-request",
+        params: {
+          model: "claude-3-haiku-20240307",
+          max_tokens: 1024,
+          messages: [
+            { role: "user", content: "Hi again, friend" }
+          ]
+        }
+      }
+    ]
+  }
+)
+batch_id = response["id"]
+```
+
+You can retrieve information about a specific batch:
+```ruby
+batch = client.messages.batches.get(id: batch_id)
+```
+
+To cancel a batch that is in progress:
+```ruby
+client.messages.batches.cancel(id: batch_id)
+```
+
+List all batches:
+```ruby
+client.messages.batches.list
+```
+
+#### Notes (as of 31 March 2025)
+
+- If individual batch items have errors, you will not be billed for those specific items.
+- Batches will be listed in the account indefinitely.
+- Results are fetchable only within 29 days after batch creation.
+- When you cancel a batch, any unprocessed items will not be billed.
+- Batches in other workspaces are not accessible with API keys from a different workspace.
+- If a batch item takes more than 24 hours to process, it will expire and not be billed.
+
+Once processing ends, you can fetch the results:
+```ruby
+results = client.messages.batches.results(id: batch_id)
+```
+
+Results are returned as a .jsonl file, with each line containing the result of a single request. Results may be in any order - use the custom_id field to match results to requests.
+
+### Vision
 
 Claude 3 family of models comes with vision capabilities that allow Claude to understand and analyze images.
 
@@ -179,14 +265,14 @@ response = client.messages(
 ```
 
 
-#### Additional parameters
+### Additional parameters
 
 You can add other parameters to the parameters hash, like `temperature` and even `top_k` or `top_p`. They will just be passed to the Anthropic server. You
 can read more about the supported parameters [here](https://docs.anthropic.com/claude/reference/messages_post).
 
 There are two special parameters, though, to do with... streaming. Keep reading to find out more.
 
-#### JSON
+### JSON
 
 If you want your output to be json, it is recommended to provide an additional message like this:
 

data/lib/anthropic/client.rb

@@ -1,3 +1,6 @@
+require_relative "messages/batches"
+require_relative "messages/client"
+
 module Anthropic
   class Client
     include Anthropic::HTTP
@@ -6,10 +9,12 @@ module Anthropic
       access_token
       anthropic_version
       api_version
+      log_errors
       uri_base
       request_timeout
       extra_headers
     ].freeze
+    attr_reader(*CONFIG_KEYS)
 
     def initialize(config = {}, &faraday_middleware)
       CONFIG_KEYS.each do |key|
@@ -21,6 +26,8 @@ module Anthropic
         )
       end
       @faraday_middleware = faraday_middleware
+      log "[WARNING] Gem `anthropic` was renamed to `ruby-anthropic`.
+        Please update your Gemfile to use `ruby-anthropic` version 0.4.2 or later."
     end
 
     # @deprecated (but still works while Anthropic API responds to it)
@@ -30,7 +37,10 @@ module Anthropic
     end
 
     # Anthropic API Parameters as of 2024-05-07:
-    #   @see https://docs.anthropic.com/claude/reference/messages_post
+    # @see https://docs.anthropic.com/claude/reference/messages_post
+    #
+    # When called without parameters, returns a Messages::Batches instance for batch operations.
+    # When called with parameters, creates a single message.
     #
     # @param [Hash] parameters
     # @option parameters [Array] :messages - Required. An array of messages to send to the API. Each
@@ -51,20 +61,44 @@ module Anthropic
     #   arguments: the first will be the text accrued so far, and the second will be the delta
     #   just received in the current chunk.
     #
-    # @returns [Hash] the response from the API (after the streaming is done, if streaming)
-    #   @example:
-    # {
-    #   "id" => "msg_013xVudG9xjSvLGwPKMeVXzG",
-    #   "type" => "message",
-    #   "role" => "assistant",
-    #   "content" => [{"type" => "text", "text" => "The sky has no distinct"}],
-    #   "model" => "claude-2.1",
-    #   "stop_reason" => "max_tokens",
-    #   "stop_sequence" => nil,
-    #   "usage" => {"input_tokens" => 15, "output_tokens" => 5}
-    # }
-    def messages(parameters: {})
-      json_post(path: "/messages", parameters: parameters)
+    # @returns [Hash, Messages::Client] Returns a Hash response from the API when creating a message
+    # with parameters, or a Messages::Client instance when called without parameters
+    # @example Creating a message:
+    #   {
+    #     "id" => "msg_013xVudG9xjSvLGwPKMeVXzG",
+    #     "type" => "message",
+    #     "role" => "assistant",
+    #     "content" => [{"type" => "text", "text" => "The sky has no distinct"}],
+    #     "model" => "claude-2.1",
+    #     "stop_reason" => "max_tokens",
+    #     "stop_sequence" => nil,
+    #     "usage" => {"input_tokens" => 15, "output_tokens" => 5}
+    #   }
+    # @example Accessing batches:
+    #   client.messages.batches.create(requests: [...])
+    #   client.messages.batches.get(id: "batch_123")
+    def messages(**args)
+      return @messages ||= Messages::Client.new(self) unless args && args[:parameters]
+
+      json_post(path: "/messages", parameters: args[:parameters])
+    end
+
+    # Adds Anthropic beta features to API requests. Can be used in two ways:
+    #
+    # 1. Multiple betas in one call with comma-separated string:
+    #    client.beta("feature1,feature2").messages
+    #
+    # 2. Chaining multiple beta calls:
+    #    client.beta("feature1").beta("feature2").messages
+    #
+    # @param version [String] The beta version(s) to enable
+    # @return [Client] A new client instance with the beta header(s)
+    def beta(version)
+      dup.tap do |client|
+        existing_beta = client.extra_headers["anthropic-beta"]
+        combined_beta = [existing_beta, version].compact.join(",")
+        client.add_headers("anthropic-beta" => combined_beta)
+      end
     end
 
     private

data/lib/anthropic/compatibility.rb

@@ -5,5 +5,6 @@ module Ruby
     Error = ::Anthropic::Error
     ConfigurationError = ::Anthropic::ConfigurationError
     Configuration = ::Anthropic::Configuration
+    MiddlewareErrors = ::Anthropic::MiddlewareErrors
   end
 end

data/lib/anthropic/http.rb

@@ -7,19 +7,19 @@ module Anthropic
   module HTTP
     include HTTPHeaders
 
-    # Unused?
-    def get(path:)
-      to_json(conn.get(uri(path: path)) do |req|
+    def get(path:, parameters: nil)
+      response = conn.get(uri(path: path), parameters) do |req|
         req.headers = headers
-      end&.body)
+      end
+      response&.body
     end
 
-    # This is currently the workhorse for all API calls.
     # rubocop:disable Metrics/MethodLength
-    def json_post(path:, parameters:)
+    # rubocop:disable Metrics/AbcSize
+    def json_post(path:, parameters: {})
       str_resp = {}
       response = conn.post(uri(path: path)) do |req|
-        if parameters[:stream].is_a?(Proc)
+        if parameters.respond_to?(:key?) && parameters[:stream].is_a?(Proc)
           req.options.on_data = to_json_stream(user_proc: parameters[:stream], response: str_resp,
                                                preprocess: parameters[:preprocess_stream])
           parameters[:stream] = true # Necessary to tell Anthropic to stream.
@@ -33,8 +33,9 @@ module Anthropic
       str_resp.empty? ? response.body : str_resp
     end
     # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
 
-    # Unused?
+    # Unused - leave in until v1 since someone might be using it.
     def multipart_post(path:, parameters: nil)
       to_json(conn(multipart: true).post(uri(path: path)) do |req|
         req.headers = headers.merge({ "Content-Type" => "multipart/form-data" })
@@ -42,7 +43,7 @@ module Anthropic
       end&.body)
     end
 
-    # Unused?
+    # Unused - leave in until v1 since someone might be using it.
     def delete(path:)
       to_json(conn.delete(uri(path: path)) do |req|
         req.headers = headers
@@ -51,7 +52,7 @@ module Anthropic
 
     private
 
-    # Used only by unused methods?
+    # Used only in unused methods - leave in until v1 since someone might be using it.
     def to_json(string)
       return unless string
 
@@ -63,7 +64,7 @@ module Anthropic
 
     # Given a proc, returns an outer proc that can be used to iterate over a JSON stream of chunks.
     # For each chunk, the inner user_proc is called giving it the JSON object. The JSON object could
-    # be a data object or an error object as described in the OpenAI API documentation.
+    # be a data object or an error object as described in the Anthropic API documentation.
     #
     # @param user_proc [Proc] The inner proc to call for each JSON object in the chunk.
     # @return [Proc] An outer proc that iterates over a raw stream, converting it to JSON.
@@ -147,7 +148,7 @@ module Anthropic
     def log(error)
       logger = Logger.new($stdout)
       logger.formatter = proc do |_severity, _datetime, _progname, msg|
-        "\033[31mAnthropic JSON Error (spotted in ruby-anthropic #{VERSION}): #{msg}\n\033[0m"
+        "\033[31mAnthropic Error (spotted in anthropic #{VERSION}): #{msg}\n\033[0m"
       end
       logger.error(error)
     end

data/lib/anthropic/http_headers.rb

@@ -11,7 +11,7 @@ module Anthropic
       # if azure?
       #   azure_headers
       # else
-      #   openai_headers
+      #   anthropic_headers
       # end.merge(extra_headers)
       anthropic_headers.merge(extra_headers)
     end

data/lib/anthropic/messages/batches.rb

@@ -0,0 +1,112 @@
+module Anthropic
+  module Messages
+    class Batches
+      BETA_VERSION = "message-batches-2024-09-24".freeze
+
+      def initialize(client)
+        @client = client.beta(BETA_VERSION)
+      end
+
+      # Anthropic API Parameters as of 2024-10-09:
+      # @see https://docs.anthropic.com/en/api/creating-message-batches
+      #
+      # @param [Array] :parameters - List of requests for prompt completion.
+      # Each is an individual request to create a Message.
+      # Parameters are an array of hashes, each with the following keys:
+      # - :custom_id (required): Developer-provided ID created for each request in a Message Batch.
+      # Useful for matching results to requests, as results may be given out of request order.
+      # Must be unique for each request within the Message Batch.
+      # - :params (required): Messages API creation parameters for the individual request.
+      # See the Messages API reference for full documentation on available parameters.
+      #
+      # @returns [Hash] the response from the API (after the streaming is done, if streaming)
+      # @example:
+      #
+      # > messages.batches.create(parameters: [message1, message2])
+      # {
+      #   "id"=>"msgbatch_01668jySCZeCpMLsxFcroNnN",
+      #   "type"=>"message_batch",
+      #   "processing_status"=>"in_progress",
+      #   "request_counts"=>{
+      #     "processing"=>2,
+      #     "succeeded"=>0,
+      #     "errored"=>0,
+      #     "canceled"=>0,
+      #     "expired"=>0
+      #   },
+      #   "ended_at"=>nil,
+      #   "created_at"=>"2024-10-09T20:18:11.480471+00:00",
+      #   "expires_at"=>"2024-10-10T20:18:11.480471+00:00",
+      #   "cancel_initiated_at"=>nil,
+      #   "results_url"=>nil
+      # }
+      def create(parameters: {})
+        @client.json_post(
+          path: "/messages/batches",
+          parameters: parameters
+        )
+      end
+
+      # Anthropic API Parameters as of 2024-10-09:
+      # @see https://docs.anthropic.com/en/api/creating-message-batches
+      #
+      # @param [String] :id - ID of the Message Batch.
+      #
+      # @returns [Hash] the same response shape as #create method.
+      def get(id:)
+        @client.get(path: "/messages/batches/#{id}")
+      end
+
+      # Anthropic API Parameters as of 2024-10-09:
+      # @see https://docs.anthropic.com/en/api/creating-message-batches
+      #
+      # @param [String] :id - ID of the Message Batch.
+      #
+      # Returns the results of a Message Batch as a .jsonl file.
+      # Each line in the file is a JSON object containing the result of a
+      # single request in the Message Batch.
+      # Results are not guaranteed to be in the same order as requests.
+      # Use the custom_id field to match results to requests.
+      def results(id:)
+        @client.get(path: "/messages/batches/#{id}/results")
+      end
+
+      # Anthropic API Parameters as of 2024-10-09:
+      # @see https://docs.anthropic.com/en/api/listing-message-batches
+      #
+      # List all Message Batches within a Workspace. Most recently created batches returned first.
+      # @param [String] :before_id - ID of the object to use as a cursor for pagination.
+      # When provided, returns the page of results immediately before this object.
+      #
+      # @param [String] :after_id - ID of the object to use as a cursor for pagination.
+      # When provided, returns the page of results immediately after this object.
+      #
+      # @param [Integer] :limit - Number of items to return per page.
+      # Defaults to 20. Ranges from 1 to 100.
+      #
+      # @returns [Hash] the response from the API
+      def list(parameters: {})
+        @client.get(path: "/messages/batches", parameters: parameters)
+      end
+
+      # Anthropic API Parameters as of 2024-10-09:
+      # @see https://docs.anthropic.com/en/api/creating-message-batches
+      #
+      # @param [String] :id - ID of the Message Batch.
+      #
+      # @returns [Hash] the response from the API
+      #
+      # Cancel a Message Batch.
+      # Batches may be canceled any time before processing ends. Once cancellation is initiated,
+      # the batch enters a canceling state, at which time the system may complete any in-progress,
+      # non-interruptible requests before finalizing cancellation.
+      #
+      # The number of canceled requests is specified in request_counts.
+      # To determine which requests were canceled, check the individual results within the batch.
+      # Note that cancellation may not cancel any requests if they were non-interruptible.
+      def cancel(id:)
+        @client.json_post(path: "/messages/batches/#{id}/cancel")
+      end
+    end
+  end
+end

data/lib/anthropic/messages/client.rb

@@ -0,0 +1,13 @@
+module Anthropic
+  module Messages
+    class Client
+      def initialize(client)
+        @client = client
+      end
+
+      def batches
+        @batches ||= Batches.new(@client)
+      end
+    end
+  end
+end

data/lib/anthropic/version.rb

@@ -1,3 +1,3 @@
 module Anthropic
-  VERSION = "0.3.2".freeze
+  VERSION = "0.4.1".freeze
 end

data/lib/anthropic.rb

@@ -17,7 +17,7 @@ module Anthropic
 
       logger = Logger.new($stdout)
       logger.formatter = proc do |_severity, _datetime, _progname, msg|
-        "\033[31mAnthropic HTTP Error (spotted in ruby-anthropic #{VERSION}): #{msg}\n\033[0m"
+        "\033[31mAnthropic HTTP Error (spotted in anthropic #{VERSION}): #{msg}\n\033[0m"
       end
       logger.error(e.response[:body])
 
@@ -27,11 +27,16 @@ module Anthropic
 
   class Configuration
     attr_writer :access_token
-    attr_accessor :anthropic_version, :api_version, :extra_headers,
-                  :request_timeout, :uri_base
+    attr_accessor :anthropic_version,
+                  :api_version,
+                  :extra_headers,
+                  :log_errors,
+                  :request_timeout,
+                  :uri_base
 
     DEFAULT_API_VERSION = "v1".freeze
     DEFAULT_ANTHROPIC_VERSION = "2023-06-01".freeze
+    DEFAULT_LOG_ERRORS = false
     DEFAULT_URI_BASE = "https://api.anthropic.com/".freeze
     DEFAULT_REQUEST_TIMEOUT = 120
 
@@ -39,6 +44,7 @@ module Anthropic
       @access_token = nil
       @api_version = DEFAULT_API_VERSION
       @anthropic_version = DEFAULT_ANTHROPIC_VERSION
+      @log_errors = DEFAULT_LOG_ERRORS
       @uri_base = DEFAULT_URI_BASE
       @request_timeout = DEFAULT_REQUEST_TIMEOUT
       @extra_headers = {}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anthropic
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Alex
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-09 00:00:00.000000000 Z
+date: 2025-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: event_stream_parser
@@ -88,6 +88,8 @@ files:
 - lib/anthropic/compatibility.rb
 - lib/anthropic/http.rb
 - lib/anthropic/http_headers.rb
+- lib/anthropic/messages/batches.rb
+- lib/anthropic/messages/client.rb
 - lib/anthropic/version.rb
 - lib/ruby/anthropic.rb
 - pull_request_template.md