Add anthropic-ai/sdk dependency and native client service

Foundation: Native SDK client and hybrid chat() routing

Branch 3572139-add-anthropic-aisdk-dependency adds the anthropic-ai/sdk PHP package and creates the plumbing for native API features in future issues.

Changes

• composer.json: Added anthropic-ai/sdk: ^0.5 and php-http/guzzle7-adapter: ^1.0
• AnthropicNativeClient service: SDK wrapper using $client->request() escape hatch for untyped params (effort, thinking not yet typed in SDK v0.5)
• AnthropicProvider: chat() override with requiresNativeApi() gate, nativeChat(), buildNativePayload(),
  parseNativeResponse()
• handleApiException(): Anthropic-specific credit balance check, delegates to parent for rate-limit handling
• Token usage: parseNativeResponse() maps input_tokens, output_tokens, and cache_read_input_tokens to TokenUsageDto
• 18 unit tests (36 assertions): routing logic, payload building, response parsing, native client wiring

Design

• requiresNativeApi() currently returns FALSE — no native-only features are wired yet
• All basic chat continues through the OpenAI compat layer via parent::chat()
• Phase 1 (effort, thinking) will add config checks to requiresNativeApi() AND wire them in buildNativePayload() together
• No phpunit.xml shipped — CI uses core's phpunit.xml.dist via GitLab templates

Verification

• phpcs (Drupal + DrupalPractice): clean
• phpstan level 1: clean
• PHPUnit: 18 tests, 36 assertions passing

How native API routing works

The routing decision is config-driven via requiresNativeApi().

In this Foundation MR, it always returns FALSE — no native-only features are wired yet, so all requests continue through the OpenAI compat layer with zero change in behavior.

Phase 1 will change it to check configuration keys:

  protected function requiresNativeApi(): bool {
      $config = $this->configuration;
      return !empty($config['effort'])
          || !empty($config['thinking_mode']);
  }
  

These config keys come from getModelSettings(), which adds UI fields (effort dropdown, thinking mode selector) to the per-model settings form. The Drupal AI framework passes them back as
$this->configuration on each request.

Request flow

• No native features configured → parent::chat() via OpenAI compat (proven path, no regression)
• Effort or thinking enabled → nativeChat() via Anthropic SDK

This means the site admin controls the routing per model. If they don't enable any native-only features, everything stays on the compat path. The native SDK path only activates when explicitly
needed.

Each Phase 1 feature added must update both requiresNativeApi() (the check) and buildNativePayload() (the implementation) to prevent mismatches.

Symfony AI forward compatibility

This work is designed with the Drupal AI → Symfony AI migration in mind (AI 2.0 Autumn 2026, AI 3.0 Early 2027).

The Symfony AI Anthropic bridge already uses the native Messages API (not OpenAI compat), making our approach
directionally aligned.

How our code maps to Symfony AI

• buildNativePayload() → Contract::createRequestPayload() + MessageBagNormalizer
• parseNativeResponse() → ResultConverter::convert() + TokenUsageExtractor::extract()
• AnthropicNativeClient::requestRaw() → ModelClient::request()

Portability of Phase 1 features

Symfony AI merges arbitrary options into the API payload via array_merge($options, $payload). This means:

• Effort — passes through as $options['output_config']['effort'] with zero Symfony AI changes
• Adaptive thinking — passes through as $options['thinking'] with zero Symfony AI changes
• Thinking response parsing — requires ResultConverter update (upstream contribution opportunity)
• Thinking token usage — requires TokenUsageExtractor update (upstream contribution opportunity)

Design choices for portability

• Plain arrays for payloads and responses (no SDK-specific type abstractions)
• Each feature in buildNativePayload() is a clearly-delimited block, easy to extract into Symfony AI options
• Token extraction separated from text parsing, mirroring Symfony AI's split architecture

Phase 1–2 features provide immediate value for the current module and inform upstream contributions to symfony/ai-anthropic-platform when the migration happens.

Thanks for the review, Michael!

1. Version constraint (^0.5): Keeping as-is. For pre-1.0 packages, Composer's caret already constrains to >=0.5.0, <0.6.0 — only patch updates are allowed. This follows standard Drupal contrib practice and
avoids the maintenance burden of exact pins on downstream consumers.

2. Constructor: The grandparent AiProviderClientBase::__construct() is final, so we can't override it. The create() factory + property assignment is the only available DI pattern here.

3. Readonly: Good call — applying protected readonly to nativeClient. It works with the create() pattern since PHP allows readonly initialization from the declaring class scope.