Use structured responses with the AiFoundation module

// Request AI to extract product attributes
$productDataTransfer = new ProductDataTransfer();
$response = $aiFoundationClient->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent($rawProductDescription)
        )
        ->setStructuredMessage($productDataTransfer)
);

/** @var \Generated\Shared\Transfer\ProductDataTransfer $extractedData */
$extractedData = $response->getStructuredMessage();
$sku = $extractedData->getSku();
$price = $extractedData->getPrice();

// Request AI to categorize customer message
$categoryTransfer = new CustomerIntentTransfer();
$response = $aiFoundationClient->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent($customerMessage)
        )
        ->setStructuredMessage($categoryTransfer)
);

/** @var \Generated\Shared\Transfer\CustomerIntentTransfer $intent */
$intent = $response->getStructuredMessage();
$category = $intent->getCategory(); // 'support', 'sales', 'feedback'
$priority = $intent->getPriority(); // 'high', 'medium', 'low'

// Request AI to generate content with SEO metadata
$contentTransfer = new ContentWithMetadataTransfer();
$response = $aiFoundationClient->prompt(
    (new PromptRequestTransfer())
        ->setPromptMessage(
            (new PromptMessageTransfer())->setContent('Write a product description for ' . $productName)
        )
        ->setStructuredMessage($contentTransfer)
);

/** @var \Generated\Shared\Transfer\ContentWithMetadataTransfer $content */
$content = $response->getStructuredMessage();
$description = $content->getDescription();
$keywords = $content->getKeywords(); // array of strings
$metaDescription = $content->getMetaDescription();

<?php

namespace Pyz\Zed\YourModule\Business\Analyzer;

use Generated\Shared\Transfer\ProductAnalysisTransfer;
use Generated\Shared\Transfer\PromptMessageTransfer;
use Generated\Shared\Transfer\PromptRequestTransfer;
use Spryker\Client\AiFoundation\AiFoundationClientInterface;

class ProductAnalyzer
{
    public function __construct(
        protected AiFoundationClientInterface $aiFoundationClient
    ) {
    }

    public function analyzeProduct(string $productDescription): ProductAnalysisTransfer
    {
        $promptRequest = (new PromptRequestTransfer())
            ->setAiConfigurationName('openai')
            ->setPromptMessage(
                (new PromptMessageTransfer())->setContent(
                    sprintf('Analyze this product: %s', $productDescription)
                )
            )
            ->setStructuredMessage(new ProductAnalysisTransfer())
            ->setMaxRetries(2);

        $promptResponse = $this->aiFoundationClient->prompt($promptRequest);

        if ($promptResponse->getIsSuccessful() !== true) {
            // Handle errors
            $errors = $promptResponse->getErrors();
            throw new AnalysisFailedException('Failed to analyze product');
        }

        /** @var \Generated\Shared\Transfer\ProductAnalysisTransfer $analysis */
        $analysis = $promptResponse->getStructuredMessage();

        return $analysis;
    }
}

$promptResponse = $this->aiFoundationClient->prompt($promptRequest);

if ($promptResponse->getIsSuccessful() === true) {
    /** @var \Generated\Shared\Transfer\ProductAnalysisTransfer $analysis */
    $analysis = $promptResponse->getStructuredMessage();

    // The type matches the Transfer you provided in the request
    // Access properties with full type safety
    $productName = $analysis->getProductName(); // string
    $features = $analysis->getFeatures(); // array
    $sentiment = $analysis->getSentiment(); // ProductSentimentTransfer|null

    // Work with nested Transfer objects
    if ($sentiment !== null) {
        $sentimentScore = $sentiment->getScore(); // float
        $sentimentLabel = $sentiment->getLabel(); // string
    }
}

$promptRequest = (new PromptRequestTransfer())
    ->setPromptMessage($message)
    ->setStructuredMessage($transfer)
    ->setMaxRetries(3); // Retry up to 3 times on failure

/** @var \Generated\Shared\Transfer\AnalysisResultTransfer $result */
$result = $promptResponse->getStructuredMessage();

foreach ($result->getProducts() as $product) {
    echo $product->getName(); // Each element is ProductDataTransfer
}

if ($promptResponse->getIsSuccessful() !== true) {
    return $this->handleFailure($promptResponse->getErrors());
}

/** @var \Generated\Shared\Transfer\ProductAnalysisTransfer $analysis */
$analysis = $promptResponse->getStructuredMessage();

// Validate critical fields
if ($analysis->getPrice() === null || $analysis->getPrice() <= 0) {
    throw new InvalidPriceException('AI returned invalid price');
}

// Critical business logic: more retries
$promptRequest->setMaxRetries(3);

// Non-critical features: fewer retries
$promptRequest->setMaxRetries(1);