adachsoft / ai-3d-generation-contracts
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
pkg:composer/adachsoft/ai-3d-generation-contracts
Requires
- php: ^8.3
- adachsoft/collection: ^3.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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 API | New API |
|---|---|
ModelGenerationProviderInterface | Contracts\ModelGeneratorInterface |
ModelGenerationRequestDto | Models\GenerationRequestDto |
ModelGenerationTaskReferenceDto | Models\TaskReferenceDto |
ModelGenerationTaskDto | Models\GenerationTaskDto |
ModelGenerationCostDto | Models\CostItemDto (one amount and unit per item) |
ModelUrlCollection | Collections\GeneratedModelCollection (contains GeneratedModelDto values) |
ModelGenerationProviderIdVo and ProviderTaskIdVo | ValueObjects\TaskIdVo for an opaque task cursor; provider identity is not part of the contract |
ModelGenerationCostUnitEnum | ValueObjects\CostUnitVo |
GenerationInputTypeEnum and ImageUrlVo | ValueObjects\TextPromptVo or ValueObjects\ImageInputVo; the latter exposes Models\Enums\ImageSourceTypeEnum |
Provider-specific Invalid* exceptions | Exceptions\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:
InvalidInputExceptionfor invalid value objects or inputs unsupported by an implementationGenerationFailedExceptionfor non-retryable generation failures, with optional error and request identifiersRetryableExceptionfor temporary failures, with a suggestedrefreshTimedelayMissingPluginParameterExceptionandInvalidPluginParametersExceptionfor plugin configuration errors
Testing
Run the PHPUnit suite with:
vendor/bin/phpunit
License
The MIT License (MIT).