Search by

adachsoft / ai-3d-generation-contracts

Arkadiusz Adach

Provider-agnostic PHP contracts and value objects for asynchronous text- and image-to-3D model generation.

Package info

gitlab.com/a.adach/ai-3d-generation-contracts

Issues

pkg:composer/adachsoft/ai-3d-generation-contracts

Statistics

Installs: 9

Dependents: 1

Suggesters: 0

Stars: 0

v0.2.0 2026-11-20 07:15 UTC

This package is auto-updated.

Last update: 2026-11-20 06:15:58 UTC


README

A provider-agnostic PHP contract for asynchronous text-to-3D and image-to-3D generation. It defines interfaces, immutable request and result DTOs, value objects, collections, and standard exceptions without coupling consumers to any provider or deployment topology. An implementation may call one provider, proxy requests, or fan out to several providers.

Requirements

  • PHP 8.3 or higher
  • adachsoft/collection

Installation

composer require adachsoft/ai-3d-generation-contracts

Contract and usage

Implement ModelGeneratorInterface to estimate costs, create generation tasks, and poll their status. A GenerationRequestDto accepts either a TextPromptVo or an ImageInputVo. The image input value object identifies HTTP(S) URLs, valid Base64 image data URIs, and implementation-specific file paths; implementations decide whether a path exists or is supported.

use AdachSoft\Ai3dGenerationContracts\Contracts\ModelGeneratorInterface;
use AdachSoft\Ai3dGenerationContracts\Models\GenerationRequestDto;
use AdachSoft\Ai3dGenerationContracts\ValueObjects\TextPromptVo;

/** @var ModelGeneratorInterface $generator */
$generator = ...;
$request = new GenerationRequestDto(new TextPromptVo('A small red ceramic fox'));

$estimate = $generator->estimateCost($request);
$task = $generator->createTask($request);
$reference = $task->reference; // Includes the estimate computed before submission.

// Poll when appropriate for the implementation.
$task = $generator->getTask($reference);

foreach ($task->models as $model) {
    echo "Generated model: {$model->url->value}\n";
}

if ($task->reportedCost !== null) {
    foreach ($task->reportedCost as $costItem) {
        printf("Reported usage: %s %s\n", $costItem->amount->value, $costItem->unit->value);
    }
}

Cost items retain their individual units and optional source labels. Units are not interchangeable: consumers are responsible for grouping or converting amounts and must not sum items expressed in different units. reportedCost contains only usage reported by an API; it is null when no reported usage is available and never substitutes for the estimate on the task reference.

Task identifiers are opaque to the contract. An implementation can use a provider ID, a composite ID, or any other non-empty value without control characters.

Plugins (auto-discovery)

A provider package can expose a generator plugin by implementing ModelGeneratorPluginInterface. Plugin implementations must have no required constructor arguments so a consumer can instantiate them during discovery.

Declare plugins in the provider package's composer.json under the discovery key:

{
  "extra": {
    "adachsoft/ai-3d-generation-contracts": {
      "plugins": {
        "tripo": "AdachSoft\\Ai3dGenerationTripo\\TripoPlugin"
      }
    }
  }
}

Plugin IDs must match ^[a-z0-9]+(?:[._-][a-z0-9]+)*$, be no longer than 64 characters, and be unique across the installation. Provider packages should document the parameter names accepted by each plugin, such as api_key.

The contract defines the discovery key and plugin interface, but does not provide a discovery implementation. Consumers are responsible for reading Composer metadata, validating plugin IDs, and instantiating declared plugins.

Pass provider-specific string parameters using PluginParametersDto:

use AdachSoft\Ai3dGenerationContracts\Plugins\PluginParametersDto;
use AdachSoft\Ai3dGenerationTripo\TripoPlugin;

$plugin = new TripoPlugin();
$generator = $plugin->create(new PluginParametersDto(['api_key' => '...']));

Upgrade from 0.1 to 0.2

Version 0.2 is a breaking change. The public API no longer identifies a single provider or stores provider-specific task identifiers and costs. Update imports and adapt integrations as follows; no compatibility aliases are provided.

Previous APINew API
ModelGenerationProviderInterfaceContracts\ModelGeneratorInterface
ModelGenerationRequestDtoModels\GenerationRequestDto
ModelGenerationTaskReferenceDtoModels\TaskReferenceDto
ModelGenerationTaskDtoModels\GenerationTaskDto
ModelGenerationCostDtoModels\CostItemDto (one amount and unit per item)
ModelUrlCollectionCollections\GeneratedModelCollection (contains GeneratedModelDto values)
ModelGenerationProviderIdVo and ProviderTaskIdVoValueObjects\TaskIdVo for an opaque task cursor; provider identity is not part of the contract
ModelGenerationCostUnitEnumValueObjects\CostUnitVo
GenerationInputTypeEnum and ImageUrlVoValueObjects\TextPromptVo or ValueObjects\ImageInputVo; the latter exposes Models\Enums\ImageSourceTypeEnum
Provider-specific Invalid* exceptionsExceptions\InvalidInputException

Generated model URLs and formats are now separate ModelUrlVo and optional ModelFormatVo values. Estimates are represented as CostItemCollection values on TaskReferenceDto; API-reported usage is a separate nullable CostItemCollection on GenerationTaskDto.

Exceptions

All library-specific exceptions implement Ai3dGenerationExceptionInterface:

  • InvalidInputException for invalid value objects or inputs unsupported by an implementation
  • GenerationFailedException for non-retryable generation failures, with optional error and request identifiers
  • RetryableException for temporary failures, with a suggested refreshTime delay
  • MissingPluginParameterException and InvalidPluginParametersException for plugin configuration errors

Testing

Run the PHPUnit suite with:

vendor/bin/phpunit

License

The MIT License (MIT).