adachsoft / model-pricing-contracts
Framework-independent contracts and value objects for AI model pricing and cost estimation.
Package info
gitlab.com/a.adach/model-pricing-contracts
pkg:composer/adachsoft/model-pricing-contracts
Requires
- php: ^8.3
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^12.5
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 19:08:26 UTC
README
Framework-independent PHP contracts and value objects for describing AI model price sheets and estimating usage costs.
Features
- Immutable price-sheet, pricing-condition, usage, and estimate DTOs.
- Catalog and cost-estimator interfaces for application and infrastructure integrations.
- Validated ordered collections and typed identifiers for price components and units.
- Decimal-string monetary amounts, avoiding floating-point price representation.
Requirements
PHP 8.3 or later.
Installation
composer require adachsoft/model-pricing-contracts
Usage
Use the catalog and estimator interfaces as integration boundaries, and implement them in your application or infrastructure layer. The package supplies the associated data contracts, not provider-specific storage or estimation implementations.
See usage examples for cost-estimation and provider price-source examples.
Price sources
Provider integrations implement PriceSourceInterface to supply validated price sheets for synchronization. A source reports its provider identifier and returns a PriceSheetDtoCollection for a requested fetch instant. Provider-specific retrieval and parsing remain outside this package; failures are represented by PriceSourceException.
Billed cost sources
Provider integrations can implement BilledCostSourceInterface to retrieve billed cost lines for a half-open time range. BilledCostLineDto represents an invoice line, and BilledCostLineDtoCollection provides an immutable ordered collection so consumers can compare billed charges with estimated costs. Retrieval or parsing failures use BilledCostSourceException.
Usage normalization
Provider integrations implement UsageNormalizerInterface to translate provider-specific response usage into NormalizedUsageDto; the package supplies the port and data contracts, not a provider adapter. A normalizer returns null when it cannot determine usage and throws UsageNormalizationException for internally inconsistent data. Its BillableUsageDto must contain disjoint usage items: every token is counted exactly once. contextInputTokens retains the total input count for context-based pricing. A non-empty warning list means usage may be incomplete, so consumers should mark the estimated cost as incomplete.
For APIs where input_tokens includes cached tokens, report uncached input as input_tokens - cached_tokens and represent cached input separately:
use AdachSoft\ModelPricingContracts\Estimation\BillableUsageDto;
use AdachSoft\ModelPricingContracts\Estimation\BillableUsageItemDto;
use AdachSoft\ModelPricingContracts\Estimation\BillableUsageItemDtoCollection;
use AdachSoft\ModelPricingContracts\Estimation\PricingContextDto;
use AdachSoft\ModelPricingContracts\Exception\UsageNormalizationException;
use AdachSoft\ModelPricingContracts\Normalization\NormalizedUsageDto;
use AdachSoft\ModelPricingContracts\Normalization\UsageNormalizationRequestDto;
use AdachSoft\ModelPricingContracts\Normalization\UsageNormalizerInterface;
final class ExampleUsageNormalizer implements UsageNormalizerInterface
{
public function normalize(UsageNormalizationRequestDto $request): ?NormalizedUsageDto
{
if ($request->inputTokens === null || $request->outputTokens === null) {
return null;
}
$inputDetails = $request->details['input_tokens_details'] ?? [];
if (!is_array($inputDetails)) {
throw new UsageNormalizationException('Input token details must be an array.');
}
$cachedTokens = $inputDetails['cached_tokens'] ?? 0;
if (!is_int($cachedTokens) || $cachedTokens < 0 || $cachedTokens > $request->inputTokens) {
throw new UsageNormalizationException('Cached tokens must not exceed total input tokens.');
}
$uncachedTokens = $request->inputTokens - $cachedTokens;
$items = [];
if ($uncachedTokens > 0) {
$items[] = new BillableUsageItemDto('input', $uncachedTokens);
}
if ($cachedTokens > 0) {
$items[] = new BillableUsageItemDto('cached_input', $cachedTokens);
}
if ($request->outputTokens > 0) {
$items[] = new BillableUsageItemDto('output', $request->outputTokens);
}
return new NormalizedUsageDto(
usage: new BillableUsageDto(
items: new BillableUsageItemDtoCollection($items),
contextInputTokens: $request->inputTokens,
),
context: PricingContextDto::createEmpty(),
warnings: [],
);
}
}