README

Русская версия

Simple PHP 7.4+ client for the OpenAI Responses API.

The package provides:

• a transport layer based on guzzlehttp/guzzle;
• retry handling for retryable HTTP errors;
• a high-level AiClient;
• prompt objects via PromptInterface;
• response objects via ResponseInterface.

Quick Start

<?php

use AlexTikhomirova\Ai\AiClient;
use AlexTikhomirova\Ai\Transport\GuzzleTransport;

$client = new AiClient(new GuzzleTransport('sk-...'));

$text = $client->textFromPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Write a short product description.',
]);

Requirements

• PHP 7.4+
• guzzlehttp/guzzle

Installation

As a local package in the current project

If the package lives inside external/packages/ai-client, add it to the root Composer project as a path repository.

composer require alex-tikhomirova/ai-client

In the current project setup the package is already connected through a Composer path repository and symlink.

Main classes

• AlexTikhomirova\Ai\Transport\GuzzleTransport — low-level HTTP transport
• AlexTikhomirova\Ai\AiClient — high-level client
• AlexTikhomirova\Ai\Prompt\PromptInterface — prompt contract
• AlexTikhomirova\Ai\Prompt\UniversalPrompt — generic prompt implementation
• AlexTikhomirova\Ai\Response\AiResponse — default response object

Quick start

1. Create transport and client

<?php

use AlexTikhomirova\Ai\AiClient;
use AlexTikhomirova\Ai\Transport\GuzzleTransport;

$transport = new GuzzleTransport('sk-...');
$client = new AiClient($transport);

2. Send a raw payload and get text

<?php

$text = $client->textFromPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Write a short product description.',
]);

3. Send a raw payload and get JSON

<?php

$data = $client->jsonFromPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Return JSON with fields title and description.',
    'text' => [
        'format' => [
            'type' => 'json_object',
        ],
    ],
]);

Using UniversalPrompt

UniversalPrompt is useful when you want to keep request building outside of the client.

<?php

use AlexTikhomirova\Ai\Prompt\UniversalPrompt;

$prompt = new UniversalPrompt(
    'gpt-4o-mini',
    'You normalize product data and return strict JSON.',
    [
        'raw_description' => 'Small kettle, black, 1.2kg',
        'raw_attributes' => [
            'Weight: 1.2 kg',
            'Color: black',
            'Has light: yes',
        ],
    ],
    'json',
    0.2
);

$result = $client->jsonFromPrompt($prompt);

AiClient methods

respondPayload(array $payload): AiResponse

Returns the default response object.

<?php

$response = $client->respondPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Hello',
]);

$raw = $response->toArray();

textFromPayload(array $payload): string

Returns text directly.

<?php

$text = $client->textFromPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Return one short sentence.',
]);

jsonFromPayload(array $payload): array

Returns decoded JSON directly.

<?php

$data = $client->jsonFromPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Return JSON with keys name and price.',
    'text' => [
        'format' => [
            'type' => 'json_object',
        ],
    ],
]);

respondPrompt(PromptInterface $prompt): ResponseInterface

Uses a prompt object and returns either the prompt-specific response class or the default AiResponse.

<?php

$response = $client->respondPrompt($prompt);

AiResponse

Default response wrapper supports:

• toArray()
• getText()
• getJson()
• getId()
• getModel()
• getUsage()

Example:

<?php

$response = $client->respondPayload([
    'model' => 'gpt-4o-mini',
    'input' => 'Return JSON with title.',
    'text' => [
        'format' => [
            'type' => 'json_object',
        ],
    ],
]);

$id = $response->getId();
$model = $response->getModel();
$data = $response->getJson();
$usage = $response->getUsage();

Retry and errors

Retryable errors

GuzzleTransport throws RetryableRequestException for:

• network errors;
• HTTP 429;
• HTTP 5xx.

If the API returns Retry-After, the exception stores the recommended delay in milliseconds.

Non-retryable errors

AiRequestException is used for:

• invalid payload;
• invalid JSON in the API response;
• unsupported HTTP method;
• response mapping errors.

Custom prompts

To create a custom prompt, implement PromptInterface:

<?php

use AlexTikhomirova\Ai\Prompt\PromptInterface;

final class MyPrompt implements PromptInterface
{
    public function toPayload(): array
    {
        return [
            'model' => 'gpt-4o-mini',
            'input' => 'Hello',
        ];
    }

    public function outputType(): string
    {
        return 'text';
    }

    public function responseClass(): ?string
    {
        return null;
    }
}

Custom response classes

If a prompt needs a custom response object, return its class name from responseClass().

The class must implement AlexTikhomirova\Ai\Response\ResponseInterface and accept array $data in the constructor.

Running tests

In the current project the tests are executed from the root external environment.

Example command used in Docker:

php /app/external/vendor/phpunit/phpunit/phpunit --bootstrap tests/bootstrap.php --no-configuration /app/external/packages/ai-client/tests

Current package status:

• unit tests for responses, prompts, retry, exceptions, client and transport;
• all tests are green in the current Docker setup.

License

MIT