Introduction

The OpenAI driver provides a simple way to access OpenAI APIs from within Kipchak.

It exposes a configured OpenAI client so you can create responses, generate embeddings, and run other OpenAI operations without wiring credentials in every call.

Installation

Install the driver via composer by running:

composer require kipchak/driver-openai

Initialise the Driver

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

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

Configuration

The configuration in kipchak.openai.php can be used to configure one or more OpenAI connections:

<?php

use function Kipchak\Core\env;

return [
    'connections' => [
        'default' => [
            'api_key' => env('OPENAI_API_KEY', ''),
            'organization' => env('OPENAI_ORG', ''),
            'project' => env('OPENAI_PROJECT', ''),
            'base_uri' => env('OPENAI_BASE_URI', 'https://api.openai.com/v1'),
            'default_model' => env('OPENAI_DEFAULT_MODEL', 'gpt-4o-mini'),
            // Optional: a psr18 client from config/kipchak.http.php (see HTTP client below)
            // 'http_client' => 'ai',
            // Optional: add extra headers to every request
            // 'headers' => [
            //     'OpenAI-Beta' => 'responses=v1',
            // ],
            // Optional: customize the client factory or return a custom client
            // 'client_builder' => function (\OpenAI\Factory $factory, array $connection) {
            //     return $factory->withHttpHeader('X-App', 'kipchak')->make();
            // },
        ],
        'analysis' => [
            'api_key' => env('OPENAI_API_KEY', ''),
            'organization' => env('OPENAI_ORG', ''),
            'project' => env('OPENAI_PROJECT', ''),
            'base_uri' => env('OPENAI_BASE_URI', 'https://api.openai.com/v1'),
            'default_model' => env('OPENAI_ANALYSIS_MODEL', 'gpt-4o-mini'),
        ],
    ],
];

HTTP client

Requests are sent with Guzzle, which comes with the Kipchak HTTP driver. By default each connection has a client of its own: a 10-second connect timeout, no limit on the whole request so that long streamed responses are not cut off, and a request is abandoned after 600 seconds without receiving data.

To use other settings, such as a proxy or different timeouts, define a psr18 client in config/kipchak.http.php and name it with http_client:

// config/kipchak.http.php
'ai' => [
    'type' => 'psr18',
    'options' => ['connect_timeout' => 5, 'proxy' => env('HTTPS_PROXY', '')],
],

// config/kipchak.openai.php, in a connection
'http_client' => 'ai',

Streaming works with either.

Usage

use Kipchak\Driver\OpenAI\OpenAI;

$client = OpenAI::get('default');

$response = $client->chat()->create([
    'messages' => [
        ['role' => 'system', 'content' => 'You are a concise assistant.'],
        ['role' => 'user', 'content' => 'Summarize Kipchak in one sentence.'],
    ],
]);

$text = $response->choices[0]->message->content;

Multiple connections are supported:

use Kipchak\Driver\OpenAI\OpenAI;

$default = OpenAI::get('default');
$analysis = OpenAI::get('analysis');

$response = $analysis->responses()->create([
    'input' => 'Explain caching strategies in one paragraph.',
]);

The driver wraps the OpenAI PHP client. If a default_model is configured, it is applied automatically to resources that accept a model parameter (chat, responses, embeddings, images, audio, and more). You can also pass headers for custom request headers or a client_builder callable to customize the factory/client per connection.

For more details on the client methods and response shapes, see the OpenAI PHP client documentation.

Git Repository

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