anthropic 0.4.1 → 1.1.0

data/README.md

@@ -1,413 +1,403 @@
-# Anthropic
+# Anthropic Ruby API library
 
-[![Gem Version](https://badge.fury.io/rb/anthropic.svg)](https://badge.fury.io/rb/anthropic)
-[![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)
+The Anthropic Ruby library provides convenient access to the Anthropic REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/anthropics/anthropic-sdk-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
 
-> [!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.
+## Documentation
 
-Use the [Anthropic API](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) with Ruby! 🤖🌌
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/anthropic).
 
-You can get access to the API [here](https://docs.anthropic.com/claude/docs/getting-access-to-claude).
+The REST API documentation can be found on [docs.anthropic.com](https://docs.anthropic.com/claude/reference/).
 
-[🎮 Ruby AI Builders Discord](https://discord.gg/k4Uc224xVD) | [🐦 Twitter](https://twitter.com/alexrudall) | [🤖 OpenAI Gem](https://github.com/alexrudall/ruby-openai) | [🚂 Midjourney Gem](https://github.com/alexrudall/midjourney)
+## Installation
 
-### Bundler
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
 
-Add this line to your application's Gemfile:
+<!-- x-release-please-start-version -->
 
 ```ruby
-gem "anthropic"
+gem "anthropic", "~> 1.1.0"
 ```
 
-And then execute:
+<!-- x-release-please-end -->
 
-$ bundle install
+## Feedback
 
-### Gem install
+If you have recommendations, notice bugs, find things confusing, or anything else, create a github issue. Don't be shy -- we're very open to hearing any thoughts and musings you have!
 
-Or install with:
+Feel free to make an issue for more substantial issues. For smaller issues or stream-of-thought, you can use the [pinned issue here](https://github.com/anthropics/anthropic-sdk-ruby/issues/85).
 
-$ gem install anthropic
-
-and require with:
+## Usage
 
 ```ruby
+require "bundler/setup"
 require "anthropic"
-```
 
-## Usage
+anthropic = Anthropic::Client.new(
+  api_key: ENV["ANTHROPIC_API_KEY"] # This is the default and can be omitted
+)
 
-- Get your API key from [https://console.anthropic.com/account/keys](https://console.anthropic.com/account/keys)
+message = anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest"
+)
+
+puts(message.content)
+```
+
+### Streaming
 
-### Quickstart
+We provide support for streaming responses using Server-Sent Events (SSE).
 
-For a quick test you can pass your token directly to a new client:
+**coming soon**: `anthropic.messages.stream` will have [Python SDK](https://github.com/anthropics/anthropic-sdk-python?tab=readme-ov-file#streaming-helpers) style streaming response helpers.
 
 ```ruby
-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.
+stream = anthropic.messages.stream_raw(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest"
 )
+
+stream.each do |message|
+  puts(message.type)
+end
 ```
 
-### With Config
+### Pagination
+
+List methods in the Anthropic API are paginated.
 
-For a more robust setup, you can configure the gem with your API keys, for example in an `anthropic.rb` initializer file. Never hardcode secrets into your codebase - instead use something like [dotenv](https://github.com/motdotla/dotenv) to pass the keys safely into your environments or rails credentials if you are using this in a rails project.
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
 
 ```ruby
-Anthropic.configure do |config|
-  # With dotenv
-  config.access_token = ENV.fetch("ANTHROPIC_API_KEY"),
-  # OR
-  # With Rails credentials
-  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.
+page = anthropic.beta.messages.batches.list(limit: 20)
+
+# Fetch single item from page.
+batch = page.data[0]
+puts(batch.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |batch|
+  puts(batch.id)
 end
 ```
 
-Then you can create a client like this:
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
 
 ```ruby
-client = Anthropic::Client.new
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.data[0].id)
+end
 ```
 
-#### Change version or timeout
-
-You can change to a different dated version (different from the URL version which is just `v1`) of Anthropic's API by passing `anthropic_version` when initializing the client. If you don't the default latest will be used, which is "2023-06-01". [More info](https://docs.anthropic.com/claude/reference/versioning)
+### File uploads
 
-The default timeout for any request using this library is 120 seconds. You can change that by passing a number of seconds to the `request_timeout` when initializing the client.
+Request parameters that correspond to file uploads can be passed as raw contents, a [`Pathname`](https://rubyapi.org/3.2/o/pathname) instance, [`StringIO`](https://rubyapi.org/3.2/o/stringio), or more.
 
 ```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
-)
-```
+require "pathname"
 
-You can also set these keys when configuring the gem:
+# Use `Pathname` to send the filename and/or avoid paging a large file into memory:
+file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))
 
-```ruby
-Anthropic.configure do |config|
-  config.access_token = ENV.fetch("ANTHROPIC_API_KEY")
-  config.anthropic_version = "2023-01-01" # Optional
-  config.request_timeout = 240 # Optional
-end
+# Alternatively, pass file contents or a `StringIO` directly:
+file_metadata = anthropic.beta.files.upload(file: File.read("/path/to/file"))
+
+# Or, to control the filename and/or content type:
+file = Anthropic::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "…")
+file_metadata = anthropic.beta.files.upload(file: file)
+
+puts(file_metadata.id)
 ```
 
-#### Logging
+Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
+
+### Handling errors
 
-##### 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).
+When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Anthropic::Errors::APIError` will be thrown:
 
-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)
+begin
+  message = anthropic.messages.create(
+    max_tokens: 1024,
+    messages: [{role: "user", content: "Hello, Claude"}],
+    model: :"claude-3-7-sonnet-latest"
+  )
+rescue Anthropic::Errors::APIConnectionError => e
+  puts("The server could not be reached")
+  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
+rescue Anthropic::Errors::RateLimitError => e
+  puts("A 429 status code was received; we should back off a bit.")
+rescue Anthropic::Errors::APIStatusError => e
+  puts("Another non-200-range status code was received")
+  puts(e.status)
+end
 ```
 
-### Models
-
-Available Models:
+Error codes are as follows:
 
-| Name            | API Name                 |
-| --------------- | ------------------------ |
-| Claude 3 Opus   | claude-3-opus-20240229   |
-| Claude 3 Sonnet | claude-3-sonnet-20240229 |
-| Claude 3 Haiku  | claude-3-haiku-20240307  |
+| Cause            | Error Type                 |
+| ---------------- | -------------------------- |
+| HTTP 400         | `BadRequestError`          |
+| HTTP 401         | `AuthenticationError`      |
+| HTTP 403         | `PermissionDeniedError`    |
+| HTTP 404         | `NotFoundError`            |
+| HTTP 409         | `ConflictError`            |
+| HTTP 422         | `UnprocessableEntityError` |
+| HTTP 429         | `RateLimitError`           |
+| HTTP >= 500      | `InternalServerError`      |
+| Other HTTP error | `APIStatusError`           |
+| Timeout          | `APITimeoutError`          |
+| Network error    | `APIConnectionError`       |
 
-You can find the latest model names in the [Anthropic API documentation](https://docs.anthropic.com/claude/docs/models-overview#model-recommendations).
+### Retries
 
-### Messages
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-```
-POST https://api.anthropic.com/v1/messages
-```
+Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
 
-Send a sequence of messages (user or assistant) to the API and receive a message in response.
+You can use the `max_retries` option to configure or disable this:
 
 ```ruby
-response = client.messages(
-  parameters: {
-    model: "claude-3-haiku-20240307", # claude-3-opus-20240229, claude-3-sonnet-20240229
-    system: "Respond only in Spanish.",
-    messages: [
-      {"role": "user", "content": "Hello, Claude!"}
-    ],
-    max_tokens: 1000
-  }
+# Configure the default for all requests:
+anthropic = Anthropic::Client.new(
+  max_retries: 0 # default is 2
+)
+
+# Or, configure per-request:
+anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest",
+  request_options: {max_retries: 5}
 )
-# => {
-# =>   "id" => "msg_0123MiRVCgSG2PaQZwCGbgmV",
-# =>   "type" => "message",
-# =>   "role" => "assistant",
-# =>   "content" => [{"type"=>"text", "text"=>"¡Hola! Es un gusto saludarte. ¿En qué puedo ayudarte hoy?"}],
-# =>   "model" => "claude-3-haiku-20240307",
-# =>   "stop_reason" => "end_turn",
-# =>   "stop_sequence" => nil,
-# =>   "usage" => {"input_tokens"=>17, "output_tokens"=>32}
-# => }
 ```
 
-### 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.
+### Timeouts
 
-Batches can contain up to 100,000 requests or 256 MB in total size, whichever limit is reached first.
+By default, requests will time out after 600 seconds. You can use the timeout option to configure or disable this:
 
-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" }
-          ]
-        }
-      }
-    ]
-  }
+# Configure the default for all requests:
+anthropic = Anthropic::Client.new(
+  timeout: nil # default is 600
 )
-batch_id = response["id"]
-```
 
-You can retrieve information about a specific batch:
-```ruby
-batch = client.messages.batches.get(id: batch_id)
+# Or, configure per-request:
+anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest",
+  request_options: {timeout: 5}
+)
 ```
 
-To cancel a batch that is in progress:
-```ruby
-client.messages.batches.cancel(id: batch_id)
-```
+On timeout, `Anthropic::Errors::APITimeoutError` is raised.
 
-List all batches:
-```ruby
-client.messages.batches.list
-```
+Note that requests that time out are retried by default.
 
-#### Notes (as of 31 March 2025)
+## AWS Bedrock
 
-- 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.
+This library also provides support for the [Anthropic Bedrock API](https://aws.amazon.com/bedrock/claude/) if you install this library with the `aws-sdk-bedrockruntime` gem.
+
+You can then instantiate a separate `Anthropic::BedrockClient` class, and use AWS's standard guide for configuring credentials (see [the aws-sdk-ruby gem README](https://github.com/aws/aws-sdk-ruby?tab=readme-ov-file#configuration) or [AWS Documentation](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html#credchain)). It has the same API as the base `Anthropic::Client` class.
+
+Note that the model ID required is different for Bedrock models, and, depending on the model you want to use, you will need to use either the AWS's model ID for Anthropic models -- which can be found in [AWS's Bedrock model catalog](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) -- or an inference profile id (e.g. `us.anthropic.claude-3-5-haiku-20241022-v1:0` for Claude 3.5 Haiku).
 
-Once processing ends, you can fetch the results:
 ```ruby
-results = client.messages.batches.results(id: batch_id)
+require "bundler/setup"
+require "anthropic"
+
+anthropic = Anthropic::BedrockClient.new
+
+message = anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [
+    {
+      role: "user",
+      content: "Hello, Claude"
+    }
+  ],
+  model: "anthropic.claude-3-5-sonnet-20241022-v2:0"
+)
+
+puts(message)
 ```
 
-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.
+For more examples see [`examples/bedrock`](examples/bedrock).
 
-### Vision
+## Google Vertex
 
-Claude 3 family of models comes with vision capabilities that allow Claude to understand and analyze images.
+This library also provides support for the [Anthropic Vertex API](https://cloud.google.com/vertex-ai?hl=en) if you install this library with the `googleauth` gem.
 
-Transform an image to base64 and send to the API.
+You can then import and instantiate a separate `Anthropic::VertexClient` class, and use Google's guide for configuring [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc). It has the same API as the base `Anthropic::Client` class.
 
 ```ruby
-require 'base64'
-
-image = File.open(FILE_PATH, 'rb') { |file| file.read }
-
-imgbase64 = Base64.strict_encode64(image)
-
-response = client.messages(
-  parameters: {
-    model: "claude-3-haiku-20240307", # claude-3-opus-20240229, claude-3-sonnet-20240229
-    system: "Respond only in Spanish.",
-    messages: [
-      {"role": "user", "content": [
-        {
-          "type":"image","source":
-          {"type":"base64","media_type":"image/png", imgbase64 }
-        },
-        {"type":"text","text":"What is this"}
-        ]
-      }
-    ],
-    max_tokens: 1000
-  }
+require "bundler/setup"
+require "anthropic"
+
+anthropic = Anthropic::VertexClient.new(region: "us-east5", project_id: "my-project-id")
+
+message = anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [
+    {
+      role: "user",
+      content: "Hello, Claude"
+    }
+  ],
+  model: "claude-3-7-sonnet@20250219"
 )
 
-# => {
-# =>   "id" => "msg_0123MiRVCgSG2PaQZwCGbgmV",
-# =>   "type" => "message",
-# =>   "role" => "assistant",
-# =>   "content" => [{"type"=>"text", "text"=>"This
-# =>    image depicts a person, presumably a student or young adult, holding a tablet
-# =>    device. "}],
-# =>   "model" => "claude-3-haiku-20240307",
-# =>   "stop_reason" => "end_turn",
-# =>   "stop_sequence" => nil,
-# =>   "usage" => {"input_tokens"=>17, "output_tokens"=>32}
-# => }
+puts(message)
 ```
 
+For more examples see [`examples/vertex`](examples/vertex).
 
-### Additional parameters
+## Advanced concepts
 
-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).
+### BaseModel
 
-There are two special parameters, though, to do with... streaming. Keep reading to find out more.
+All parameter and response objects inherit from `Anthropic::Internal::Type::BaseModel`, which provides several conveniences, including:
 
-### JSON
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
 
-If you want your output to be json, it is recommended to provide an additional message like this:
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
 
-```ruby
-[{ role: "user", content: "Give me the heights of the 3 tallest mountains. Answer in the provided JSON format. Only include JSON." },
-{ role: "assistant", content: '[{"name": "Mountain Name", "height": "height in km"}]' }]
-```
+3. Both instances and the classes themselves can be pretty-printed.
 
-Then Claude v3, even Haiku, might respond with:
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-```ruby
-[{"name"=>"Mount Everest", "height"=>"8.85 km"}, {"name"=>"K2", "height"=>"8.61 km"}, {"name"=>"Kangchenjunga", "height"=>"8.58 km"}]
-```
+### Making custom or undocumented requests
 
-### Streaming
+#### Undocumented properties
 
-There are two modes of streaming: raw and preprocessed. The default is raw. You can call it like this:
+You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+
+> [!WARNING]
+>
+> The `extra_` parameters of the same name overrides the documented parameters. For security reasons, ensure these methods are only used with trusted input data.
 
 ```ruby
-client.messages(
-  parameters: {
-    model: "claude-3-haiku-20240307",
-    messages: [{ role: "user", content: "How high is the sky?" }],
-    max_tokens: 50,
-    stream: Proc.new { |chunk| print chunk }
-  }
-)
+message =
+  anthropic.messages.create(
+    max_tokens: 1024,
+    messages: [{role: "user", content: "Hello, Claude"}],
+    model: :"claude-3-7-sonnet-latest",
+    request_options: {
+      extra_query: {my_query_parameter: value},
+      extra_body: {my_body_parameter: value},
+      extra_headers: {"my-header": value}
+    }
+  )
+
+puts(message[:my_undocumented_property])
 ```
 
-This still returns a regular response at the end, but also gives you direct access to every single chunk returned by Anthropic as they come in. Even if you don't want to
-use the streaming, you may find this useful to avoid timeouts, which can happen if you send Opus a large input context, and expect a long response... It has been known to take
-several minutes to compile the full response - which is longer than our 120 second default timeout. But when streaming, the connection does not time out.
+#### Undocumented request params
+
+If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
 
-Here is an example of a stream you might get back:
+#### Undocumented endpoints
+
+To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
 
 ```ruby
-{"type"=>"message_start", "message"=>{"id"=>"msg_01WMWvcZq5JEMLf6Jja4Bven", "type"=>"message", "role"=>"assistant", "model"=>"claude-3-haiku-20240307", "stop_sequence"=>nil, "usage"=>{"input_tokens"=>13, "output_tokens"=>1}, "content"=>[], "stop_reason"=>nil}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>"There"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" is"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" no"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" single"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" defin"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>"itive"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" \""}}
-...
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>"'s"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" atmosphere"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" extends"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" up"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" to"}}
-{"type"=>"content_block_delta", "index"=>0, "delta"=>{"type"=>"text_delta", "text"=>" about"}}
-{"type"=>"content_block_stop", "index"=>0}
-{"type"=>"message_delta", "delta"=>{"stop_reason"=>"max_tokens", "stop_sequence"=>nil}, "usage"=>{"output_tokens"=>50}}
-{"type"=>"message_stop"}
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
+)
 ```
 
-Now, you may find this... somewhat less than practical. Surely, the vast majority of developers will not want to deal with so much
-boilerplate json.
+### Concurrency & connection pooling
 
-Luckily, you can ask the anthropic gem to preprocess things for you!
+The `Anthropic::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
 
-First, if you expect simple text output, you can receive it delta by delta:
+Each instance of `Anthropic::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
-```ruby
-client.messages(
-  parameters: {
-    model: "claude-3-haiku-20240307",
-    messages: [{ role: "user", content: "How high is the sky?" }],
-    max_tokens: 50,
-    stream: Proc.new { |incremental_response, delta| process_your(incremental_response, delta) },
-    preprocess_stream: :text
-  }
-)
-```
+When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
 
-The first block argument, `incremental_response`, accrues everything that's been returned so far, so you don't have to. If you just want the last bit,
-then use the second, `delta` argument.
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-But what if you want to stream JSON?
+## Sorbet
 
-Partial JSON is not very useful. But it is common enough to request a collection of JSON objects as a response, as in our earlier example of asking for the heights of the 3 tallest mountains.
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-If you ask it to, this gem will also do its best to sort this out for you:
+You can provide typesafe request parameters like so:
 
 ```ruby
-client.messages(
-  parameters: {
-    model: "claude-3-haiku-20240307",
-    messages: [{ role: "user", content: "How high is the sky?" }],
-    max_tokens: 50,
-    stream: Proc.new { |json_object| process_your(json_object) },
-    preprocess_stream: :json
-  }
+anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
+  model: :"claude-3-7-sonnet-latest"
 )
 ```
 
-Each time a `}` is reached in the stream, the preprocessor will take what it has in the preprocessing stack, pick out whatever's between the widest `{` and `}`, and try to parse it into a JSON object.
-If it succeeds, it will pass you the json object, reset its preprocessing stack, and carry on.
+Or, equivalently:
 
-If the parsing fails despite reaching a `}`, currently, it will catch the Error, log it to `$stdout`, ignore the malformed object, reset the preprocessing stack and carry on. This does mean that it is possible,
-if the AI is sending some malformed JSON (which can happen, albeit rarely), that some objects will be lost.
+```ruby
+# Hashes work, but are not typesafe:
+anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest"
+)
 
-## Development
+# You can also splat a full Params class:
+params = Anthropic::MessageCreateParams.new(
+  max_tokens: 1024,
+  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
+  model: :"claude-3-7-sonnet-latest"
+)
+anthropic.messages.create(**params)
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. You can run `bin/console` for an interactive prompt that will allow you to experiment.
+### Enums
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
-To run all tests, execute the command `bundle exec rake`, which will also run the linter (Rubocop). This repository uses [VCR](https://github.com/vcr/vcr) to log API requests.
+```ruby
+# :auto
+puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)
 
-> [!WARNING]
-> If you have an `ANTHROPIC_API_KEY` in your `ENV`, running the specs will use this to run the specs against the actual API, which will be slow and cost you money - 2 cents or more! Remove it from your environment with `unset` or similar if you just want to run the specs against the stored VCR responses.
+# Revealed type: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
+T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)
+```
 
-### Warning
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
-If you have an `ANTHROPIC_API_KEY` in your `ENV`, running the specs will use this to run the specs against the actual API, which will be slow and cost you money - 2 cents or more! Remove it from your environment with `unset` or similar if you just want to run the specs against the stored VCR responses.
+```ruby
+# Using the enum constants preserves the tagged type information:
+anthropic.messages.create(
+  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
+  # …
+)
 
-## Release
+# Literal values are also permissible:
+anthropic.messages.create(
+  service_tier: :auto,
+  # …
+)
+```
 
-First run the specs without VCR so they actually hit the API. This will cost 2 cents or more. Set ANTHROPIC_API_KEY in your environment or pass it in like this:
+## Versioning
 
-```
-ANTHROPIC_API_KEY=123abc bundle exec rspec
-```
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
 
-Then update the version number in `version.rb`, update `CHANGELOG.md`, run `bundle install` to update Gemfile.lock, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
 
-## Contributing
+## Requirements
 
-Bug reports and pull requests are welcome on GitHub at <https://github.com/alexrudall/anthropic>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/alexrudall/anthropic/blob/main/CODE_OF_CONDUCT.md).
+Ruby 3.2.0 or higher.
 
-## License
+## Contributing
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+See [the contributing documentation](https://github.com/anthropics/anthropic-sdk-ruby/tree/main/CONTRIBUTING.md).
 
-## Code of Conduct
+## Acknowledgements
 
-Everyone interacting in the Ruby Anthropic project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/alexrudall/anthropic/blob/main/CODE_OF_CONDUCT.md).
+Thank you [@alexrudall](https://github.com/alexrudall) for giving feedback, donating the `anthropic` Ruby Gem name, and paving the way by building the first Anthropic Ruby SDK.