Search by

adachsoft / ai-integration-open-ai-responses

Arkadiusz Adach

OpenAI responses integration for adachsoft/ai-integration.

Package info

gitlab.com/a.adach/ai-integration-open-ai-responses

Issues

pkg:composer/adachsoft/ai-integration-open-ai-responses

Statistics

Installs: 77

Dependents: 1

Suggesters: 0

Stars: 0

v0.2.4 2026-11-16 21:19 UTC

This package is auto-updated.

Last update: 2026-11-16 20:19:20 UTC


README

OpenAI Responses API integration for the adachsoft/ai-integration tool-calling API.

Requirements

  • PHP ^8.3
  • adachsoft/ai-integration ^0.10
  • adachsoft/ai-conversation-model ^0.2
  • adachsoft/model-pricing-contracts ^0.2

Installation

composer require adachsoft/ai-integration-open-ai-responses

Usage

use AdachSoft\AiIntegration\PublicApi\Builder\ToolCallingChatFacadeBuilder;
use AdachSoft\AiIntegrationOpenAiResponses\OpenAiResponsesToolCallingChatSpi;

$apiKey = getenv('OPENAI_API_KEY');

if (!is_string($apiKey) || $apiKey === '') {
    throw new RuntimeException('OPENAI_API_KEY must be configured.');
}

$builder = ToolCallingChatFacadeBuilder::create();
$builder->withSpiProvider(
    'openai/responses',
    new OpenAiResponsesToolCallingChatSpi(apiKey: $apiKey),
);

$facade = $builder->build();

The provider sends requests to https://api.openai.com/v1/responses. Specify a model ID in each tool-calling chat request.

Conversation model and choices

Requests and responses use the shared conversation model, including ChatCompletionDto. Each response contains one choice. Requests that set n are rejected because multiple choices are not supported.

Multimodal content

Image and file content is sent using the Responses API input_image and input_file items. Content can be supplied as Base64 data, a URL, or an OpenAI File ID. PDF input is supported, and media in tool results is forwarded to the Responses API.

Reasoning and storage

Requests set store to false and request reasoning.encrypted_content. Returned encrypted reasoning items are stored in the choice metadata and carried forward with the conversation history for subsequent requests.

Token usage

Input, output, and total token counts are mapped to the shared token-usage model. Other raw Responses API usage fields are preserved in the usage details.

Cost calculation

OpenAiResponsesUsageNormalizer converts Responses API token details into disjoint billable usage components for the model-pricing contracts. Cached input and cache writes are separated by TTL; reasoning tokens remain included in output tokens and are not counted twice. Non-empty normalization warnings indicate that usage, and therefore its estimated cost, may be incomplete.

ResponsesResponseParser adds service_tier and model to ChatCompletionDto::metadata alongside raw_id. Both metadata values are null when absent from the response.

Pass the parsed usage and metadata to the normalizer, then submit the normalized usage and pricing context to a CostEstimatorInterface implementation. The estimator determines the cost from its configured catalog; no prices are embedded in this integration.

use AdachSoft\AiIntegration\Contract\ToolCalling\Dto\ChatCompletionDto;
use AdachSoft\AiIntegrationOpenAiResponses\Cost\OpenAiResponsesUsageNormalizer;
use AdachSoft\ModelPricingContracts\Estimation\CostEstimateDto;
use AdachSoft\ModelPricingContracts\Estimation\CostEstimateRequestDto;
use AdachSoft\ModelPricingContracts\Estimation\CostEstimatorInterface;
use AdachSoft\ModelPricingContracts\Normalization\UsageNormalizationRequestDto;

function estimateOpenAiResponseCost(
    ChatCompletionDto $completion,
    CostEstimatorInterface $estimator,
): ?CostEstimateDto {
    $tokenUsage = $completion->tokenUsage;
    $modelId = $completion->metadata['model'] ?? null;

    if ($tokenUsage === null || !is_string($modelId) || $modelId === '') {
        return null;
    }

    $normalizedUsage = (new OpenAiResponsesUsageNormalizer())->normalize(new UsageNormalizationRequestDto(
        providerId: 'openai/responses',
        modelId: $modelId,
        inputTokens: $tokenUsage->inputTokens,
        outputTokens: $tokenUsage->outputTokens,
        details: $tokenUsage->details,
        responseMetadata: $completion->metadata,
    ));

    if ($normalizedUsage === null) {
        return null;
    }

    return $estimator->estimate(new CostEstimateRequestDto(
        providerId: 'openai/responses',
        modelId: $modelId,
        usage: $normalizedUsage->usage,
        context: $normalizedUsage->context,
    ));
}

Limitations

The integration does not support audio, image generation, or multiple choices. The n parameter is rejected, and every response has a single choice.

Testing

The default PHPUnit suite is unit and does not call the paid OpenAI API:

vendor/bin/phpunit

The separate production suite runs conformance scenarios with adachsoft/ai-integration-tester ^0.5.1 and makes billable API requests. Do not run it without a valid API key and an explicit decision to incur API costs. Set OPENAI_API_KEY to authenticate. Set OPENAI_RESPONSES_MODEL to override the model; the default is gpt-4o-mini. The tester maps / in provider IDs to _ when deriving environment variable names.

export OPENAI_API_KEY=your_api_key_here
# Optional; defaults to gpt-4o-mini.
export OPENAI_RESPONSES_MODEL=gpt-4o-mini
vendor/bin/phpunit --testsuite production

Migrating from 0.1.x

This is a breaking change: the legacy 0.8-era conversation types have been replaced by the shared conversation model, including ChatCompletionDto and its related types. Update request and response type imports and construction to use the shared model, and use the dependency versions listed above. Register the provider with its canonical ID, openai/responses.