anthropic-sdk-ruby

# Working in this repository

Context for contributors on how this SDK is put together, plus the things reviews most often come back to. Setup instructions live in [CONTRIBUTING.md](CONTRIBUTING.md).

## Overview

- The official Ruby SDK for the Claude API (the `anthropic` gem). Much of it is produced via code generation from the OpenAPI spec, with hand-written helpers (`lib/anthropic/helpers/**`: streaming, tools, input schemas, platform clients), credentials, middleware and examples layered on top.
- Generated files are safe to edit. New generator output is git-merged with custom changes rather than overwriting them, so fix things where they live; a collision is just a merge conflict.
- Fix things upstream first wherever you can, before reaching for custom code: a missing parameter, an out-of-date doc string, or a response the models can't represent (a missing required field, an unknown enum member, a nullability mismatch) belongs in the OpenAPI spec, and broken generated infrastructure (`lib/anthropic/internal/**`: transport, retries, SSE and multipart handling, coercion) belongs in the generator — fixing it there is preferred over a local patch.
- PRs target the default branch (`main` on the public repo). `next` belongs to release automation — don't open PRs against it or push to it; a commit that lands there outside the release flow breaks the sync. Rebase onto the current default branch before asking for review — a stale base shows up as unrelated "changed" files.
- `lib/anthropic/version.rb`, `.release-please-manifest.json`, the gem's own entry in `Gemfile.lock`, the `README.md` version block and `CHANGELOG.md` are written by release automation.

## Build, test, lint

- `./scripts/bootstrap` installs the bundle; `./scripts/test` starts the mock API server (`./scripts/mock`, needs Node) and runs the suite; run `./scripts/lint` before pushing (it is exactly what CI runs) and format only the files you touched, e.g. `bundle exec rubocop -a <files>` — a whole-tree `./scripts/format` also reflows long lines and restyles `rbi/`/`sig/` files you never opened, since CI doesn't check formatting. A single file runs with `bundle exec rake test TEST=test/anthropic/…_test.rb`.
- Lint is rubocop plus `steep check` (RBS) plus Sorbet, and the Sorbet step is `srb typecheck --dir examples` — the examples are type-checked in CI on top of `rbi/`. A bare `bundle exec srb tc` never looks at `examples/`, which is how "green locally, red in CI" has happened; use the `--dir examples` form after touching examples or any signature they use. Rubocop runs with `Layout/LineLength` excluded, so line length is never what fails CI; trailing whitespace (easy to pick up while resolving a sync conflict) and missing parentheses are.
- Only the generated `ResourceTest` suites under `test/anthropic/resources/**` need the mock server (port 4010, or `TEST_API_BASE_URL`); `APIConnectionError`s there mean the mock isn't running. Everything else runs offline against WebMock — helper, credentials, middleware and client tests, plus the hand-written `resources/messages/streaming_test.rb` and `resources/beta/messages/streaming_test.rb` that sit inside that directory. Live tests against real cloud providers only run with `ANTHROPIC_LIVE=1`, and the Bedrock/AWS unit tests read ambient AWS state (`AWS_*` variables and `~/.aws` profiles), so if they fail locally on region, profile or credential lookup, run them with `AWS_*` unset and `AWS_CONFIG_FILE=/dev/null AWS_SHARED_CREDENTIALS_FILE=/dev/null`.
- CI's `./scripts/detect-breaking-changes` restores the release base's generated tests and `client_test.rb` and re-runs `./scripts/lint` over them, but nothing in lint type-checks `test/`, so it will not notice a removed or renamed method or keyword — treat public-surface removals as a review item: deprecate first (a forwarding alias plus `warn(…, category: :deprecated)`) and remove later, in step with the other SDKs.
- The gem supports Ruby 3.2+, and users also run it on Ruby 4 (Prism) and JRuby, which CI doesn't cover; both have broken on load-time edge cases before (bytecode precompilation of unusual syntax, constant resolution during `require`), so keep load-time code boring and take reports from those runtimes seriously.
- Examples are executable scripts (`#!/usr/bin/env ruby`, `# frozen_string_literal: true`, a `# typed:` sigil, `require_relative "../lib/anthropic"`), linted and type-checked with everything else. Match the sigil of neighbouring examples of the same kind: client and streaming examples are `typed: strong`, while the `BaseModel`/`BaseTool` DSL examples (tools, tool runner, structured output, input schemas) can't type-check today and stay `typed: false` or unsigilled, where Sorbet checks little beyond syntax and constant names. New user-facing helpers usually come with an example and a `helpers.md` section, using a current public model id like the neighbouring examples; user documentation beyond `helpers.md` lives outside this repo (see CONTRIBUTING.md), so say in the PR what needs documenting.

## Types and signatures

- Generated code exists three times: Ruby with YARD docs in `lib/`, Sorbet in `rbi/`, RBS in `sig/`. Solargraph reads the YARD, Sorbet/Tapioca the `.rbi`, Steep and ruby-lsp the `.rbs`, and no tool compares either signature set with `lib/` (`steep check` validates `sig/` on its own; Sorbet reads `rbi/` and `examples/`), so agreement is kept by review — which regularly catches a keyword present in `lib/` but missing from a signature, or a documented block signature that doesn't match what the code yields. `.rbi` files repeat the YARD prose; `.rbs` files carry none. Not every hand-written helper has all three yet: update whichever surfaces exist for the thing you touch, and give new public helpers all three.
- Sorbet has no literal types, so API enums are branded `Symbol` aliases with constants (`Anthropic::StopReason::TOOL_USE`, `Anthropic::Models::AnthropicBeta::*`). In Sorbet-checked files — the typed examples — `message.stop_reason == :tool_use` is an error (an always-false comparison) and Sorbet never narrows through `case … in`, which it rejects outright as an untyped branch under `typed: strong`; narrow with `case … when Klass`, `content.grep(Anthropic::Models::ToolUseBlock)` or `is_a?`, or compare against the constants.
- Public value objects are plain classes with explicit readers declared in all three surfaces (`Anthropic::APIRequest`/`APIResponse`) rather than `Data.define`/`Struct`, whose synthesized members LSPs and both checkers can't see.
- Sorbet upgrades have turned previously valid `.rbi` output into errors for downstream Tapioca users before; if the lockfile's `sorbet` moves, run the full `rake typecheck` and fix `rbi/` in the same PR.

## Code organization

- `Anthropic::Helpers::*` holds the hand-written features, and the short public names are alias shims at the top of `lib/anthropic/` (`streaming.rb` → `Anthropic::Streaming`, `bedrock.rb` → `Anthropic::BedrockClient`, `vertex.rb`, `aws.rb`, `bedrock_mantle.rb`, `google_cloud.rb`, `input_schema.rb`, `mcp.rb`). A new public helper gets a shim, its rbi/rbs, and a `helpers.md` mention.
- `lib/anthropic.rb` is one explicit `require_relative` list — there is no autoload, and users `require "anthropic"` themselves — so new files go there in dependency order (and a newly used stdlib into `manifest.yaml`; the Steepfile loads each entry as an RBS library, so a stdlib without RBS signatures also goes in its exclusion list or `steep check` fails). When a codegen sync conflicts in that file, keep every hand-written `require_relative` and take the generated side as it is — its removals as well as its additions — then check that `bundle exec ruby -e 'require "./lib/anthropic"'` still loads.
- The runtime tier (`lib/anthropic/internal/**`) stays provider-agnostic and dependency-free: the gem ships its own Net::HTTP transport, multipart writer and SSE decoder so it can stream in both directions without pinning an HTTP stack on applications. Runtime dependencies are the four range-pinned gems in the gemspec (exercised across versions by `dependency-versions.yml`); optional integrations (`aws-sdk-bedrockruntime`/`aws-sdk-core`, `googleauth`, `mcp`) are required lazily inside the helper that needs them, with an error naming the gem to add; and provider-specific decoding such as Bedrock's binary event-stream lives in `helpers/bedrock/`, applied from that client's `provider_middleware`.
- A lot of logic exists twice, GA and beta (`resources/messages.rb`/`resources/beta/messages.rb`, the `Models::X | Models::BetaX` arms in `MessageStream`, the GA and beta `resources/**/streaming_test.rb` suites), some entry points come in fours (`create`/`stream`/`stream_raw`/`count_tokens`), and the platform clients (`helpers/{bedrock,aws,vertex,google_cloud}/` plus `bedrock/mantle_client.rb`) each derive their own base URL and attach per-attempt auth, with Bedrock and Vertex also rewriting the request in `adapt_request`. A fix usually needs applying to every twin — a streaming-header fix once landed in the generated `stream_raw` and missed the hand-written `stream` beside it — and a shared piece (`Helpers::Messages`, `AWSAuth`) beats parallel copies.
- For anything cross-SDK (environment variable and option names, header semantics, credential precedence, the non-streaming `max_tokens`/timeout guard, telemetry values, helper shapes such as the accumulated stream returning the non-streaming `Message`), matching the other SDKs is the default; mention a deliberate divergence in the PR.

## Errors

- Everything the SDK raises on its own behalf derives from `Anthropic::Errors::Error` (`lib/anthropic/errors.rb`), so callers can rescue the family in one clause:
  - `APIStatusError` — the service answered with an error; carries `url`, `status`, `headers`, `body` and the parsed `type` (the body's `error.type`), and `APIStatusError.for` picks the concrete subclass by status (`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError`, `InternalServerError`, otherwise plain `APIStatusError`). It is raised only once the retry policy is done (408/409/429/5xx, or whatever `x-should-retry` says, are retried first), and an `error` event inside an otherwise successful stream goes through the same factory off the already-open response, so `type` says more than `status` there.
  - `APIConnectionError`, with `APITimeoutError` beneath it — a transport failure with no status, which the client counts as retryable; it shares the `APIError` parent (`url`/`status`/`headers`/`body`) with `APIStatusError`.
  - `ConversionError` — a typed reader whose value didn't fit the model; the message points at `Model[:field]` for the raw value and `cause` carries the underlying error.
  - `RetryableError` — what middleware raises, or wraps anywhere in the `cause` chain, to opt a failure into the retry loop.
  - `ConfigurationError` for the credentials/config layer, and feature-specific subclasses next to their feature where a family of failures deserves its own type (`Credentials::WorkloadIdentityError`, `APIResponse::ConsumedBodyError`, the session accumulator's `AccumulationError`).
- Deliberately outside that family: bad arguments or option combinations at public entry points raise `ArgumentError`; a resource a platform client can't offer raises `NotImplementedError`; a missing optional gem raises a `RuntimeError`/`LoadError` naming the gem to install; and an exception from a tool inside the tool runner isn't an SDK failure — it becomes an `is_error: true` `tool_result` for the model.
- New code reuses these rather than adding types or raising bare `StandardError`/`RuntimeError` for SDK conditions, keeps the original exception as `cause`, and leaves HTTP-status mapping to `APIStatusError.for`.

## Common mistakes

- **Rewriting or second-guessing the request.** Don't validate, hoist, merge, reorder or drop parts of a request the caller built. Transform input only as far as the API spec specifies and pass the rest through verbatim (`extra_body`/`extra_headers`/`extra_query` exist so power users can always send what they need), letting the API return an actionable 400. (Protocol translation in `adapt_request` — `model` into the URL, `anthropic_version`/`anthropic_beta` into the body — is mapping, not rewriting.)
- **Inferring capabilities from model IDs.** Model-name lists go stale on the next launch and rarely cover the Bedrock/Vertex spellings; use an explicit option or just send the request. (The exact-match tables mirrored from the other SDKs — `Client::MODEL_NONSTREAMING_TOKENS` and `Resources::Messages::MODELS_TO_WARN_WITH_THINKING_ENABLED` — are the accepted precedents.)
- **Raising on data the SDK doesn't recognize.** Responses can carry enum values, block types and fields this version doesn't model, and the converters never raise on them: an unknown enum member comes through as the raw String, an unknown `type` inside a union of models is coerced best-effort into the nearest known variant class (whose `#type` is then that raw String, unknown fields still reachable through `#to_h`), and only wholly unmatched values stay Hashes — so a class match can receive unknown data, and code that cares checks `type` or the generated constants. Hand-written code should degrade the same way: handle what you recognize and pass the rest through — especially in `MessageStream`, the tool runner and middleware, where an exception tears down the caller's response — keeping fallback arms as no-ops unless the stream is genuinely malformed.
- **Losing wire data on the way back to the API.** When relaying API output into a new request, carry the model or a copy of its raw hash across (`to_h` is the model's live storage, so `dup` before changing it) rather than rebuilding from typed readers, which raise `ConversionError` for values that failed coercion (`model[:key]` still holds the raw value). Request bodies are symbol-keyed, so normalize a user hash's string keys once at the boundary (a stray `"model"` string key once duplicated the field on the wire); wire names come from `Converter.dump` (`format`, not `format_`); and `Time` goes out as RFC 3339 (`iso8601`), never `to_s`.
- **Sending `nil` where the key should be omitted.** `BaseModel#to_h` and request hashes keep a key if it was ever set, so an explicitly assigned `nil` serializes as `null`, which the API treats differently from an omitted key — build hashes without the keys you don't mean to send, and apply overrides delete-on-nil rather than with `Hash#merge`.
- **Streaming assumptions that don't hold** (each has bitten the accumulator at least once):
  - The accumulated message has to equal the non-streaming `Message`, GA and beta, so every field of `RawMessageDeltaEvent`/`MessageDeltaUsage` and their `Beta` twins gets folded, and both `resources/**/streaming_test.rb` suites test it.
  - Assigning `nil` through a generated setter poisons the field — even one declared `nil?: true` — so the next typed read raises; copy delta fields only when present.
  - An arm naming `Models::X` but not `Models::BetaX` silently no-ops on beta streams.
  - Not every block streams as text-style appends: some arrive complete at `content_block_start`, others as a placeholder plus one delta (compaction).
- **Clobbering headers.** `Util.normalized_headers` is last-wins by design (signed headers, a multipart `content-type` and a caller's `x-api-key` all rely on replacing), with `anthropic-beta` as the one comma-joined exception; beta flags arrive from the `betas:` param, generator-injected per-endpoint defaults and OAuth, and all of them have to survive (in hand-written code the generated `AnthropicBeta::*` constants age better than date literals). The helper-telemetry header is likewise a set — append and de-duplicate through the existing merge helper rather than overwriting it. Header names compare case-insensitively internally, but `Net::HTTP` re-canonicalizes their casing on the wire.
- **Transport slips.** SigV4 clients sign every attempt over the exact bytes sent (materialize enumerable/multipart bodies first; `encode_content` passes an already-encoded body through) — reusing a signature across retries has shipped twice as 403s. A body containing an `IO` makes the request non-retryable on purpose (`can_retry`), since pipes can't be rewound. Streaming requests send `accept-encoding: identity`, or every event arrives in one burst at the end. Leaving `Net::HTTP#read_body` early takes `throw`/`catch`, not `break`. Middleware runs per attempt inside the retry loop, receives an immutable `APIRequest` and an `APIResponse` for every status, and opts into retries with `Errors::RetryableError`.
- **Unverified claims about the API.** Check doc comments, error messages and PR text that say "the API rejects X" or "model Y requires Z" against the official Claude API docs, not a third-party page or a bug report.

## Style notes

- Type safety comes first. Downgrading a `# typed:` sigil, widening a signature to `T.anything`/`untyped`, or comparing enum values as bare strings is occasionally necessary but usually a sign to restructure — narrow by class, keep `@param`/`@return` and rbi/rbs types precise, and let the converters do coercion. `T.*` helpers are for `rbi/` only: the gem doesn't load `sorbet-runtime`, so `T.must`/`T.cast`/`T.let`/`T.unsafe` in `lib/`, `examples/` or `test/` type-check fine and then raise `NameError` when the code runs.
- Immutable things should actually be immutable: freeze constants and lookup tables, deep-freeze what you hand to user code (`Util.deep_frozen_copy`, as the middleware path does for `APIRequest`), `dup` caller-supplied arrays and hashes before storing them, and don't hand out references that let callers mutate state presented as fixed.
- Rubocop settles most formatting; the recurring manual points are double quotes unless the string contains them (`'{"a": 1}'` beats escapes, in YARD examples too), parentheses on calls with arguments inside methods and blocks, `alias_method`, bracketed symbol arrays, `_1`/`_2` block params, and fencing a deliberate `Type === value` with `rubocop:disable Style/CaseEquality` rather than letting autocorrect turn it into `is_a?`. Pattern matching is the house idiom in `lib/` and `test/`, which Sorbet doesn't read; typed examples use `case … when`.
- New siblings follow the existing shape: hash-or-model reads go through `Runner#read_field`, tool serialization and API names through `Helpers::Messages.distill_input_schema_models!`/`tool_api_name`, structured-output parsing through the `unwrap` step (`parse_input_schemas!`) that any new response path has to thread through, optional gems through the lazy `require` in the Vertex client. "How do we already do this elsewhere?" is usually the first review question, and new public surface (a `BaseTool` DSL keyword, a constructor option, an env-var name) is a maintainer call rather than something to slip into a fix.
- Comments and YARD in moderation: worth writing for the non-obvious (an invariant, a wire-format reason, the admission rule for a lookup table), not to restate what the code does or narrate its history — over-documenting the obvious is its own review finding. Param docs read "Defaults to `ENV["…"]`, otherwise …" and skip internal mechanics; product names in prose follow the public docs, while identifiers, env vars and error strings never change for a rebrand.

## Tests

- A behaviour change comes with a test that fails before and passes after (worth saying so in the PR), covering the beta twin when the code is shared. Watch for vacuous cases — a lookup table was once mostly deleted under a "covering" test that stayed green because its inputs took a default path — and remember `assert_pattern { actual => ^expected }` compares while `actual => expected` merely binds.
- `test_helper.rb` turns on `parallelize_me!` and `prove_it!`, so every test asserts something and classes run in parallel unless they `extend Minitest::Serial` — which hand-written classes touching `ENV`, WebMock or other process state do, alongside `include WebMock::API` with `enable!`/`disable!` in `before_all`/`after_all` and `reset!` in `teardown`. Restore any `ENV` you change; the few `i_suck_and_my_tests_are_order_dependent!` classes are debt, not precedent.
- Retry paths don't really sleep in tests: `Kernel#sleep`/`Time.now` honour the `:mock_sleep`/`:time_now` thread variables, so set `Thread.current.thread_variable_set(:mock_sleep, [])` in `setup` when a test can retry.
- For request-shaping code, asserting on the exact wire request is what makes the test meaningful — WebMock's `assert_requested(…) { |req| … }` paired with a real `assert_*` (plain `webmock` is loaded, so `assert_requested` alone doesn't count towards `prove_it!`), or a capturing `request_options: {middleware: ->(req, nxt) { … }}`; for streaming, serve literal SSE bytes and check `accumulated_message`. Generated resource tests only check shapes against the mock, so behaviour tests for patches in `resources/*` go in hand-written files such as `test/anthropic/resources/messages/streaming_test.rb` and its `beta/` twin.

## Commits and pull requests

- Conventional Commits drive release-please and the changelog (`feat(scope):`, `fix(scope):`, `chore`, `docs`; `test` and `ci` are hidden). A `!` or `BREAKING CHANGE:` footer cuts a major version, which is rare and a maintainer call — describe the compatibility impact in the PR instead.
- One logical change per PR, against the current default branch, with formatting-only churn in its own commit.
- A good PR description says what was wrong (a short before/after helps), what changed, and what gives confidence — the failing-then-passing test plus any manual verification, and what the sibling SDKs do when the change is visible on the wire — and calls out behaviour changes and anything left unverified (no mock server, no cloud credentials) rather than implying it passed.