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();

Transport modes

AnthropicToolCallingChatSpiFactory::create() supports two transport modes:

non_streaming (default) - legacy buffered mode using classic non-streaming HTTP response read.
streaming - request is sent as SSE stream and reconstructed back to the Anthropic JSON response format.

Factory parameters (transportMode, streamingPerChunkTimeoutSeconds) define application-level defaults. Per-request parameters have higher priority and can override these defaults:

ai_integration-transport_mode (non_streaming or streaming)
ai_integration-streaming_per_chunk_timeout_seconds (positive integer, only for effective streaming mode)

Example request-level override:

$request = new ToolCallingChatSpiRequest(
    model: 'claude-sonnet-4-20250514',
    messages: $messages,
    tools: $tools,
    parameters: [
        'ai_integration-transport_mode' => 'streaming',
        'ai_integration-streaming_per_chunk_timeout_seconds' => 45,
    ],
);

ToolCallingContext::$timeoutSeconds keeps the same SPI meaning in both modes: it is the total request timeout. In streaming mode, idle timeout between chunks is configured separately via ai_integration-streaming_per_chunk_timeout_seconds (or factory default).

Streaming mode requires allow_url_fopen=1. If it is disabled, the adapter throws a fail-fast SpiException with guidance to enable allow_url_fopen or switch to non_streaming.

With default non_streaming, long-running generations may again be exposed to idle connection drops in some environments. When this matters, enable streaming explicitly per request.

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

adachsoft / ai-integration-anthropic

Maintainers

Package info

Statistics

Security