Search by

adachsoft / ai-integration-cost

Arkadiusz Adach

Universal bridge between adachsoft/ai-integration cost SPI and adachsoft/llm-cost-calculator engine.

Package info

gitlab.com/a.adach/ai-integration-cost

Issues

pkg:composer/adachsoft/ai-integration-cost

Statistics

Installs: 27

Dependents: 0

Suggesters: 0

Stars: 0

v0.4.1 2026-11-17 06:30 UTC

This package is auto-updated.

Last update: 2026-11-17 07:32:30 UTC


README

A universal bridge between the adachsoft/ai-integration cost SPI and the adachsoft/model-pricing-contracts normalization and estimation contracts.

Provider-specific usage normalizers turn raw token usage and response metadata into billable usage and pricing context. A cost estimator then applies the current price sheet and returns a provider-neutral cost result to adachsoft/ai-integration.

Requirements

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

Installation

composer require adachsoft/ai-integration-cost

Usage

Provide a UsageNormalizerInterface implementation for each integration provider ID and any CostEstimatorInterface implementation. The registry constructor uses each integration provider ID as its pricing provider ID by default. Use with() when those IDs differ: the OpenAI Responses integration provider ID openai/responses can map to the pricing provider ID openai. The OpenAI chat-completions normalizer is provided by adachsoft/ai-integration, while the OpenAI Responses API normalizer is provided by adachsoft/ai-integration-openai-responses. An estimator can be supplied by any implementation of the contracts, such as adachsoft/model-pricing-lib.

<?php

declare(strict_types=1);

use AdachSoft\AiIntegration\PublicApi\Cost\OpenAiChatCompletionsUsageNormalizer;
use AdachSoft\AiIntegrationCost\PublicApi\Factory\SpiCostCalculatorFactory;
use AdachSoft\AiIntegrationCost\PublicApi\Registry\UsageNormalizerRegistry;
use AdachSoft\AiIntegrationOpenAiResponses\Cost\OpenAiResponsesUsageNormalizer;
use AdachSoft\ModelPricingContracts\Estimation\CostEstimatorInterface;

/** @var CostEstimatorInterface $estimator An estimator supplied by the application. */
$estimator = $pricingService;

$normalizers = (new UsageNormalizerRegistry([
    'openai' => new OpenAiChatCompletionsUsageNormalizer(),
]))->with(
    'openai/responses',
    new OpenAiResponsesUsageNormalizer(),
    'openai',
);

$calculator = SpiCostCalculatorFactory::create($estimator, $normalizers);

Pass the resulting calculator to the adachsoft/ai-integration cost SPI wherever a CostCalculatorInterface is required. The registry is immutable: use with($providerId, $normalizer) to create a new registry with an additional or replacement normalizer.

The adapter returns null when token usage or the model ID is unavailable, no normalizer is registered, normalization cannot produce usage, or no estimate is available. ModelPricingException and InvalidPricingDataException from adachsoft/model-pricing-contracts are also converted to null; cost calculation failures therefore do not interrupt a conversation with the model.

Cost details

The returned CostDto contains the estimate total and currency. Its details map contains:

  • is_complete: true only when both normalization and estimation are complete.
  • unpriced_kinds: usage kinds that have no matching price.
  • warnings: normalization warnings followed by estimation warnings.
  • lines: priced lines, each with kind, quantity, unit (the unit enum's string value), unit_price, amount, and applied_conditions as a condition-name-to-value map.
  • price_sheet_effective_from: the selected price sheet's effective time in ISO 8601 ATOM format.
  • pricing_context: normalized pricing conditions as a condition-name-to-value map.

Migration from 0.2 (BREAKING)

This release replaces the adachsoft/llm-cost-calculator and adachsoft/ai-model-list integration with adachsoft/model-pricing-contracts. The previous pricing-provider port, usage-kind map, and factory configuration methods have been removed.

Migrate consumers by:

  1. Supplying a CostEstimatorInterface implementation instead of a ModelPricingProviderInterface and an LLM calculator engine.
  2. Registering one UsageNormalizerInterface per provider ID instead of configuring UsageKindMapVo mappings.
  3. Calling SpiCostCalculatorFactory::create($estimator, $registry).

Provider normalizers are responsible for converting provider-specific usage details into disjoint billable usage and pricing context. The estimator owns price-sheet selection and cost calculation.

Development

Install development dependencies and run the unit tests and quality checks:

composer install
composer test
composer stan
composer cs:fix

composer test runs the default PHPUnit unit suite.

License

This package is released under the MIT License.