Anthropic Driver

Introduction

The Anthropic Driver provides a configured Anthropic PHP SDK client for Kipchak applications. It supports multiple named connections and automatically injects a configured default model so you don't have to repeat it on every call.

Key features include:

• Multiple Connections: Configure separate API keys and defaults per use case.
• Default Model Injection: Set default_model once in config; override per call when needed.
• Messages API: Full support for single messages, multi-turn conversations, and streaming.
• Tool Use: Pass tool definitions to enable Claude's function-calling capabilities.
• Raw Client Access: Escape the wrapper at any time for direct SDK access.

Installation

composer require kipchak/driver-anthropic

Initialise the Driver

Add the following line to your drivers/drivers.php file:

\Kipchak\Driver\Anthropic\Anthropic::initialise($container);

Configuration

Create a config file named kipchak.anthropic.php in your project's config/ directory.

Connection Settings

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    'connections' => [
        'default' => [
            'api_key'       => env('ANTHROPIC_API_KEY', ''),
            'default_model' => env('ANTHROPIC_DEFAULT_MODEL', 'claude-sonnet-4-6'),
        ],
        // Additional connections for different API keys or model defaults:
        // 'fast' => [
        //     'api_key'       => env('ANTHROPIC_API_KEY', ''),
        //     'default_model' => 'claude-haiku-4-5-20251001',
        // ],
    ],
];

Environment Variables

ANTHROPIC_API_KEY=sk-ant-your-key-here
ANTHROPIC_DEFAULT_MODEL=claude-sonnet-4-6

Usage

Retrieve a connection by name. If no name is given, default is used.

use Kipchak\Driver\Anthropic\Anthropic;

$anthropic = Anthropic::get();            // 'default' connection
$anthropic = Anthropic::get('fast');      // named connection

Creating a Message

The configured default_model is injected automatically:

$response = $anthropic->messages()->create(
    messages: [
        ['role' => 'user', 'content' => 'What is the capital of France?'],
    ],
);

echo $response->content[0]->text;

Override the model or any other parameter per call:

$response = $anthropic->messages()->create(
    messages:  [['role' => 'user', 'content' => 'Summarise this in one sentence.']],
    model:     'claude-haiku-4-5-20251001',
    maxTokens: 256,
    system:    'You are a concise assistant.',
);

Multi-Turn Conversations

Pass the full conversation history in the messages array:

$response = $anthropic->messages()->create(
    messages: [
        ['role' => 'user',      'content' => 'My name is Alice.'],
        ['role' => 'assistant', 'content' => 'Hello Alice, how can I help you today?'],
        ['role' => 'user',      'content' => 'What is my name?'],
    ],
);

Streaming

$stream = $anthropic->messages()->createStream(
    messages: [['role' => 'user', 'content' => 'Tell me a short story.']],
);

foreach ($stream as $event) {
    // handle streaming events
}

Tool Use

Define tools and handle Claude's tool-use responses:

$tools = [
    [
        'name'         => 'get_weather',
        'description'  => 'Get the current weather for a location.',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'location' => ['type' => 'string', 'description' => 'City and country'],
            ],
            'required' => ['location'],
        ],
    ],
];

$response = $anthropic->messages()->create(
    messages: [['role' => 'user', 'content' => 'What is the weather in Dubai?']],
    tools:    $tools,
);

foreach ($response->content as $block) {
    if ($block->type === 'tool_use') {
        $result = myGetWeatherFunction($block->input->location);

        $followup = $anthropic->messages()->create(
            messages: [
                ['role' => 'user', 'content' => 'What is the weather in Dubai?'],
                ['role' => 'assistant', 'content' => $response->content],
                ['role' => 'user', 'content' => [
                    [
                        'type'        => 'tool_result',
                        'tool_use_id' => $block->id,
                        'content'     => $result,
                    ],
                ]],
            ],
            tools: $tools,
        );
    }
}

Raw SDK Access

For anything not covered by the driver wrapper, use raw() to access the full Anthropic SDK client:

$client = $anthropic->raw(); // returns \Anthropic\Client

Method Reference

messages()->create()

messages()->createStream()

Accepts the same parameters as create() and returns a stream for incremental output.

Error Handling

An InvalidArgumentException is thrown when api_key is missing from the connection config, or when no model is specified and no default_model is configured:

Anthropic api_key is required.
A model must be specified or default_model must be configured for this connection.

The Anthropic SDK automatically retries on transient errors (connection errors, rate limits, and 5xx responses) with exponential backoff. The default retry count of 2 can be overridden via the max_retries config key.

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/drivers/anthropic.