README

Integration of Anthropic Claude (tool calling) with the adachsoft/ai-integration library.

Requirements

• PHP >= 8.3
• guzzlehttp/guzzle ^7.0 || ^8.0
• adachsoft/ai-integration ^0.7.0

Installation

composer require adachsoft/ai-integration-anthropic

Basic usage

Example of wiring the Anthropic SPI provider with the tool-calling facade from adachsoft/ai-integration:

use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegrationAnthropic\AnthropicToolCallingChatSpiFactory;

$apiKey = getenv('ANTHROPIC_KEY');

$factory = new AnthropicToolCallingChatSpiFactory();

$builder = new ToolCallingChatFacadeBuilder();
$builder->withSpiProvider('anthropic', $factory->create($apiKey));

$facade = $builder->build();

Anthropic cache configuration

This package exposes explicit cache configuration via ToolCallingChatSpiRequest::$parameters. All cache-related keys are prefixed with ai_integration-.

Supported cache sections:

• ai_integration-cache_system – cache for the system prompt (off, 5min, 1hour).
• ai_integration-cache_tools – cache for tool definitions (off, 5min, 1hour).
• ai_integration-cache_messages – cache for conversation messages (off, 5min, 1hour).
• ai_integration-cache_automatic – Anthropic automatic cache mode (off, 5min, 1hour).

When ai_integration-cache_messages is enabled (5min or 1hour), you can select strategy with:

• ai_integration-cache_messages_strategy – supported strategies:
  • off
  • first_user
  • last_user
  • threshold_tokens

Additional parameters for threshold_tokens strategy:

• ai_integration-cache_messages_threshold_tokens – positive integer threshold (default 5000).
• ai_integration-cache_messages_last_cached_message_id – optional last cached user message identifier.

The cache layer is opt-in and non-intrusive: if you do not provide any ai_integration-* keys, cache behaviour is disabled.

ai_integration-cache_automatic is mutually exclusive with explicit cache TTL keys (cache_system, cache_tools, cache_messages). If both modes are enabled, configuration validation fails before request execution.

Response metadata

Cache-aware responses may include these metadata keys:

• cache_creation_input_tokens
• cache_read_input_tokens
• cache_breakpoint_message_id

For full details (TTL semantics, beta headers, strategy behaviour and payload rules), see:

• docs/CACHE_STRATEGIES.md
• docs/architecture.md

Tests

The default phpunit.xml configuration defines two test suites:

• unit – standard tests.
• production – production/integration tests that require external credentials.

Example commands:

# All tests
vendor/bin/phpunit

# Unit tests only
vendor/bin/phpunit --testsuite unit

# Production tests only
ANTHROPIC_KEY=... vendor/bin/phpunit --testsuite production