anthropic 0.0.0 → 0.1.0.pre.beta.9

data/README.md

@@ -1,138 +1,379 @@
-# Anthropic (WIP)
+# 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.
 
-Use the [Anthropic API](https://anthropic.com/blog/anthropic-api/) with Ruby! 🤖❤️
+## Documentation
 
-This is very much a WIP and probably doesn't work as I don't have access to the Anthropic API as yet, but it will get a lot better once I do! Hopefully very soon :D
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/anthropic).
 
-[Ruby AI Builders Discord](https://discord.gg/k4Uc224xVD)
+The REST API documentation can be found on [docs.anthropic.com](https://docs.anthropic.com/claude/reference/).
 
-[Rails AI Guides](https://railsai.com)
+## Installation
 
-Follow me on [Twitter](https://twitter.com/alexrudall) for more Ruby / AI content!
+To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
 
-### Bundler
-
-Add this line to your application's Gemfile:
+<!-- x-release-please-start-version -->
 
 ```ruby
-gem "anthropic"
+gem "anthropic", "~> 0.1.0.pre.beta.9"
 ```
 
-And then execute:
-
-$ bundle install
+<!-- x-release-please-end -->
 
-### Gem install
+## Feedback
 
-Or install with:
+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!
 
-$ gem install anthropic
+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).
 
-and require with:
+## Usage
 
 ```ruby
+require "bundler/setup"
 require "anthropic"
+
+anthropic = Anthropic::Client.new(
+  api_key: ENV["ANTHROPIC_API_KEY"] # This is the default and can be omitted
+)
+
+message = anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [{role: "user", content: "Hello, Claude"}],
+  model: :"claude-3-7-sonnet-latest"
+)
+
+puts(message.content)
 ```
 
-## Usage
+### Streaming
 
-- Get your API key from [https://platform.anthropic.com/account/api-keys](https://platform.anthropic.com/account/api-keys)
-- If you belong to multiple organizations, you can get your Organization ID from [https://platform.anthropic.com/account/org-settings](https://platform.anthropic.com/account/org-settings)
+We provide support for streaming responses using Server-Sent Events (SSE).
 
-### Quickstart
+**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.
 
-For a quick test you can pass your token directly to a new client:
+```ruby
+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
+```
+
+### Pagination
+
+List methods in the Anthropic API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```ruby
+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
+```
+
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
 
 ```ruby
-client = Anthropic::Client.new(access_token: "access_token_goes_here")
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.data[0].id)
+end
 ```
 
-### With Config
+### Handling errors
 
-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.
+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:
 
 ```ruby
-Anthropic.configure do |config|
-    config.access_token = ENV.fetch("ANTHROPIC_API_KEY")
+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
 ```
 
-Then you can create a client like this:
+Error codes are as follows:
+
+| 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`       |
+
+### Retries
+
+Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+
+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.
+
+You can use the `max_retries` option to configure or disable this:
 
 ```ruby
-client = Anthropic::Client.new
+# 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}
+)
 ```
 
-#### Custom timeout or base URI
+### Timeouts
 
-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.
+By default, requests will time out after 600 seconds. You can use the timeout option to configure or disable this:
 
 ```ruby
-client = Anthropic::Client.new(
-    access_token: "access_token_goes_here",
-    request_timeout: 240
+# Configure the default for all requests:
+anthropic = Anthropic::Client.new(
+  timeout: nil # default is 600
+)
+
+# 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}
 )
 ```
 
-or when configuring the gem:
+On timeout, `Anthropic::Errors::APITimeoutError` is raised.
+
+Note that requests that time out are retried by default.
+
+## AWS Bedrock
+
+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).
 
 ```ruby
-Anthropic.configure do |config|
-    config.access_token = ENV.fetch("ANTHROPIC_API_KEY")
-    config.request_timeout = 240 # Optional
-    config.extra_headers = {
-        "X-Proxy-Refresh": "true"
-    } # Optional
-end
+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)
+```
+
+For more examples see [`examples/bedrock`](examples/bedrock).
+
+## Google Vertex
+
+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.
+
+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 "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"
+)
+
+puts(message)
 ```
 
-### Completions
+For more examples see [`examples/vertex`](examples/vertex).
+
+## Advanced concepts
+
+### BaseModel
+
+All parameter and response objects inherit from `Anthropic::Internal::Type::BaseModel`, which provides several conveniences, including:
+
+1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
+
+2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
+
+3. Both instances and the classes themselves can be pretty-printed.
+
+4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
 
-Hit the Anthropic API for a completion:
+### Making custom or undocumented requests
+
+#### Undocumented properties
+
+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
+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])
+```
+
+#### 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 examples above.
+
+#### 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
-response = client.completions(
-    parameters: {
-        model: "claude-2",
-        prompt: "Once upon a time",
-        max_tokens: 5
-    })
-puts response["choices"].map { |c| c["text"] }
-# => [", there lived a great"]
+response = client.request(
+  method: :post,
+  path: '/undocumented/endpoint',
+  query: {"dog": "woof"},
+  headers: {"useful-header": "interesting-value"},
+  body: {"hello": "world"}
+)
 ```
 
-## Development
+### Concurrency & connection pooling
+
+The `Anthropic::Client` instances are threadsafe, but only are fork-safe when there are no in-flight HTTP requests.
 
-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.
+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.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+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.
 
-### Warning
+Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
 
-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.
+## Sorbet
 
-## Release
+This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
 
-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:
+You can provide typesafe request parameters like so:
 
+```ruby
+anthropic.messages.create(
+  max_tokens: 1024,
+  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
+  model: :"claude-3-7-sonnet-latest"
+)
 ```
-ANTHROPIC_API_KEY=123abc bundle exec rspec
+
+Or, equivalently:
+
+```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"
+)
+
+# 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)
 ```
 
-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).
+### Enums
 
-## Contributing
+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:
+
+```ruby
+# :"image/jpeg"
+puts(Anthropic::Base64ImageSource::MediaType::IMAGE_JPEG)
+
+# Revealed type: `T.all(Anthropic::Base64ImageSource::MediaType, Symbol)`
+T.reveal_type(Anthropic::Base64ImageSource::MediaType::IMAGE_JPEG)
+```
 
-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).
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
-## License
+```ruby
+Anthropic::Base64ImageSource.new(
+  media_type: Anthropic::Base64ImageSource::MediaType::IMAGE_JPEG,
+  # …
+)
+
+Anthropic::Base64ImageSource.new(
+  media_type: :"image/jpeg",
+  # …
+)
+```
+
+## Versioning
+
+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.
+
+This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
+
+## Requirements
+
+Ruby 3.2.0 or higher.
+
+## 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.

data/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting Security Issues
+
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+
+To report a security issue, please contact the Stainless team at security@stainless.com.
+
+## Responsible Disclosure
+
+We appreciate the efforts of security researchers and individuals who help us maintain the security of
+SDKs we generate. If you believe you have found a security vulnerability, please adhere to responsible
+disclosure practices by allowing us a reasonable amount of time to investigate and address the issue
+before making any information public.
+
+## Reporting Non-SDK Related Security Issues
+
+If you encounter security issues that are not directly related to SDKs but pertain to the services
+or products provided by Anthropic please follow the respective company's security reporting guidelines.
+
+### Anthropic Terms and Policies
+
+Please contact support@anthropic.com for any questions or concerns regarding security of our services.
+
+---
+
+Thank you for helping us keep the SDKs and systems they interact with secure.

data/lib/anthropic/bedrock.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Anthropic
+  BedrockClient = Anthropic::Helpers::Bedrock::Client
+end

data/lib/anthropic/client.rb

@@ -1,18 +1,108 @@
+# frozen_string_literal: true
+
 module Anthropic
-  class Client
-    extend Anthropic::HTTP
-
-    def initialize(access_token: nil, organization_id: nil, uri_base: nil, request_timeout: nil,
-                   extra_headers: {})
-      Anthropic.configuration.access_token = access_token if access_token
-      Anthropic.configuration.organization_id = organization_id if organization_id
-      Anthropic.configuration.uri_base = uri_base if uri_base
-      Anthropic.configuration.request_timeout = request_timeout if request_timeout
-      Anthropic.configuration.extra_headers = extra_headers
+  class Client < Anthropic::Internal::Transport::BaseClient
+    # Default max number of retries to attempt after a failed retryable request.
+    DEFAULT_MAX_RETRIES = 2
+
+    # Default per-request timeout.
+    DEFAULT_TIMEOUT_IN_SECONDS = 600.0
+
+    # Default initial retry delay in seconds.
+    # Overall delay is calculated using exponential backoff + jitter.
+    DEFAULT_INITIAL_RETRY_DELAY = 0.5
+
+    # Default max retry delay in seconds.
+    DEFAULT_MAX_RETRY_DELAY = 8.0
+
+    # @return [String, nil]
+    attr_reader :api_key
+
+    # @return [String, nil]
+    attr_reader :auth_token
+
+    # @return [Anthropic::Resources::Completions]
+    attr_reader :completions
+
+    # @return [Anthropic::Resources::Messages]
+    attr_reader :messages
+
+    # @return [Anthropic::Resources::Models]
+    attr_reader :models
+
+    # @return [Anthropic::Resources::Beta]
+    attr_reader :beta
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_headers
+      {**api_key_auth, **bearer_auth}
+    end
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def api_key_auth
+      {"x-api-key" => @api_key}
+    end
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def bearer_auth
+      return {} if @auth_token.nil?
+
+      {"authorization" => "Bearer #{@auth_token}"}
     end
 
-    def completions(parameters: {})
-      Anthropic::Client.json_post(path: "/completions", parameters: parameters)
+    # Creates and returns a new client for interacting with the API.
+    #
+    # @param api_key [String, nil] Defaults to `ENV["ANTHROPIC_API_KEY"]`
+    #
+    # @param auth_token [String, nil] Defaults to `ENV["ANTHROPIC_AUTH_TOKEN"]`
+    #
+    # @param base_url [String, nil] Override the default base URL for the API, e.g.,
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["ANTHROPIC_BASE_URL"]`
+    #
+    # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
+    #
+    # @param timeout [Float]
+    #
+    # @param initial_retry_delay [Float]
+    #
+    # @param max_retry_delay [Float]
+    def initialize(
+      api_key: ENV["ANTHROPIC_API_KEY"],
+      auth_token: ENV["ANTHROPIC_AUTH_TOKEN"],
+      base_url: ENV["ANTHROPIC_BASE_URL"],
+      max_retries: self.class::DEFAULT_MAX_RETRIES,
+      timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
+    )
+      base_url ||= "https://api.anthropic.com"
+
+      headers = {
+        "anthropic-version" => "2023-06-01"
+      }
+
+      @api_key = api_key&.to_s
+      @auth_token = auth_token&.to_s
+
+      super(
+        base_url: base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        initial_retry_delay: initial_retry_delay,
+        max_retry_delay: max_retry_delay,
+        headers: headers
+      )
+
+      @completions = Anthropic::Resources::Completions.new(client: self)
+      @messages = Anthropic::Resources::Messages.new(client: self)
+      @models = Anthropic::Resources::Models.new(client: self)
+      @beta = Anthropic::Resources::Beta.new(client: self)
     end
   end
 end