Add a knowledge document source EARLY ACCESS

Edit on GitHub

By default, Storefront Assistant searches only the product attachments, with the source type product_attachment. If your project has other documents that answer customer questions, such as the transcripts of product videos, you can add them as a new document source. The assistant then finds them with the same product_knowledge_search tool.

You change no core module. You add two plugins, register them, and add one configuration entry. The example in this document adds the source type product_video for product video transcripts.

Prerequisites

Install Storefront Assistant document semantic search.

How a document source fits in

One knowledge base holds the documents of all source types. The core handles the events, the queue, the content hash, the retries, the status, and the deletion of removed sources. A document source adds only the parts that are specific to its documents:

PART CORE, NO CHANGE YOUR DOCUMENT SOURCE
Events and tracking KnowledgeDocumentWritePublisherPlugin, the spy_knowledge_document table, the knowledge_document.index queue The event names and the source identifiers: the Zed source plugin
Content The content hash, the retries, the status, the deletion of removed sources The list of sources and the raw content: the Zed source plugin
Storage BedrockKnowledgeBaseKnowledgeStorePlugin The data source ID of the source type: the configuration
Search KnowledgeDocumentSearcher, BedrockKnowledgeBaseKnowledgeSearchPlugin The document keys that the customer can see: the Client scope resolver plugin
Assistant The product_knowledge_search tool Nothing, when the documents belong to products

The document key is {sourceType}:{sourceIdentifier}, for example product_video:42. It must be unique in the knowledge base.

1) Define the source type

Define the source type in one constant and use this constant in all plugins and in the configuration:

<?php

namespace Pyz\Shared\ProductVideo;

class ProductVideoConfig
{
    public const string KNOWLEDGE_DOCUMENT_SOURCE_TYPE_PRODUCT_VIDEO = 'product_video';
}

The entity of the source must send entity events. Add the event behavior to its Propel schema. A script that changes the data outside a console command or a Zed request must also send the events.

2) Implement the Zed source plugin

The source plugin tells the core which documents exist and how to read them. Implement SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentSourcePluginInterface. Put the plugin in the module that owns the entity.

The core calls the methods of the source plugin in these cases:

METHOD CALLED BY MUST DO
getSourceType() All parts Return the source type, for example product_video.
getSubscribedEvents() KnowledgeDocumentWritePublisherPlugin Return the entity events that create, change, or delete a source. The publisher subscribes to them automatically.
extractSourceIdentifiers() The publisher Return the source identifiers of the event entities.
getDocumentSourceCollection() The publisher, the index queue, knowledge-document:reindex With sourceIdentifiers, return the sources that exist. A missing identifier means that the source was deleted, and the core deletes the document. Without sourceIdentifiers, return one page of all sources by pagination.
readDocumentContent() The index queue Return the raw content and the MIME type. On failure, return isSuccessful = false with errors, and set isTemporaryFailure = true when a retry can succeed.

Set these fields on each KnowledgeDocumentSourceTransfer:

FIELD VALUE
sourceType The source type.
sourceIdentifier The ID of the source as a string.
documentName The name that the assistant shows as the source, for example the video title.
localeName The locale of the document, or null for all locales.
url The URL of the content, when the content is a file on a server.
metadata Optional scalar values. The knowledge store adds them as metadata, up to a total of 50 attributes.

src/Pyz/Zed/ProductVideo/Communication/Plugin/AiCommerce/ProductVideoKnowledgeDocumentSourcePlugin.php

<?php

namespace Pyz\Zed\ProductVideo\Communication\Plugin\AiCommerce;

use Generated\Shared\Transfer\KnowledgeDocumentContentTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentSourceCollectionTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentSourceCriteriaTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentSourceTransfer;
use Pyz\Shared\ProductVideo\ProductVideoConfig;
use Pyz\Shared\ProductVideo\ProductVideoEvents;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentSourcePluginInterface;

/**
 * @method \Pyz\Zed\ProductVideo\Business\ProductVideoFacadeInterface getFacade()
 */
class ProductVideoKnowledgeDocumentSourcePlugin extends AbstractPlugin implements KnowledgeDocumentSourcePluginInterface
{
    public function getSourceType(): string
    {
        return ProductVideoConfig::KNOWLEDGE_DOCUMENT_SOURCE_TYPE_PRODUCT_VIDEO;
    }

    /**
     * @return list<string>
     */
    public function getSubscribedEvents(): array
    {
        return [
            ProductVideoEvents::ENTITY_PYZ_PRODUCT_VIDEO_CREATE,
            ProductVideoEvents::ENTITY_PYZ_PRODUCT_VIDEO_UPDATE,
            ProductVideoEvents::ENTITY_PYZ_PRODUCT_VIDEO_DELETE,
        ];
    }

    /**
     * @param list<\Generated\Shared\Transfer\EventEntityTransfer> $eventEntityTransfers
     *
     * @return list<string>
     */
    public function extractSourceIdentifiers(array $eventEntityTransfers, string $eventName): array
    {
        return $this->getFacade()->extractProductVideoIds($eventEntityTransfers);
    }

    public function getDocumentSourceCollection(
        KnowledgeDocumentSourceCriteriaTransfer $knowledgeDocumentSourceCriteriaTransfer
    ): KnowledgeDocumentSourceCollectionTransfer {
        return $this->getFacade()->getProductVideoDocumentSourceCollection($knowledgeDocumentSourceCriteriaTransfer);
    }

    public function readDocumentContent(
        KnowledgeDocumentSourceTransfer $knowledgeDocumentSourceTransfer
    ): KnowledgeDocumentContentTransfer {
        return $this->getFacade()->readProductVideoTranscript($knowledgeDocumentSourceTransfer);
    }
}

The facade methods in the example belong to your module. The core needs only the five plugin methods.

Consider the following rules for the content:

  • The core compares the content hash. When the content did not change, the core does not send the document to the knowledge store again.
  • The Bedrock knowledge base parses PDF, Office, HTML, Markdown, CSV, text, and image files. Send text with a text MIME type: text/plain, text/markdown, or text/csv.
  • A document can have a maximum of 5 MB. A larger document gets the status failed.
  • If your content is a file on a server, you can reuse the download of the product attachments. The URL reader downloads only from public addresses and follows no redirect.

3) Implement the Client scope resolver plugin

The search sends to the knowledge store only the document keys that the scope resolver plugins return. Without document keys, the search returns no documents. The scope resolver is therefore also the access check: return only the documents that the customer can see in the store and locale of the request. Implement SprykerFeature\Client\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentScopeResolverPluginInterface.

The scope comes from KnowledgeDocumentScopeRequestTransfer:

FIELD CONTENT
scopeReferences Lists of entity references, keyed by scope reference type.
sourceIdentifiers Optional: keep only these source identifiers.
localeName, storeName The locale and the store of the customer. The search sets them.

The scope reference types of products are the constants KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_PRODUCT_ABSTRACT_ID, KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_ABSTRACT_SKU, and KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_CONCRETE_SKU of SprykerFeature\Shared\AiCommerce\AiCommerceConfig. Their values are product_abstract_id, abstract_sku, and concrete_sku.

METHOD MUST DO
isApplicable() Return true when scopeReferences has values of a reference type that the plugin reads.
resolveDocumentScope() Check that the customer can see each entity in the store and locale. Return the document keys of its documents. For each entity that you skip, add a message that is safe to show to the customer. When sourceIdentifiers is not empty, keep only these documents.

src/Pyz/Client/ProductVideo/Plugin/AiCommerce/ProductVideoKnowledgeDocumentScopeResolverPlugin.php

<?php

namespace Pyz\Client\ProductVideo\Plugin\AiCommerce;

use Generated\Shared\Transfer\KnowledgeDocumentScopeRequestTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentScopeTransfer;
use Spryker\Client\Kernel\AbstractPlugin;
use SprykerFeature\Client\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentScopeResolverPluginInterface;
use SprykerFeature\Shared\AiCommerce\AiCommerceConfig as SharedAiCommerceConfig;

/**
 * @method \Pyz\Client\ProductVideo\ProductVideoFactory getFactory()
 */
class ProductVideoKnowledgeDocumentScopeResolverPlugin extends AbstractPlugin implements KnowledgeDocumentScopeResolverPluginInterface
{
    protected const array SCOPE_REFERENCE_TYPES = [
        SharedAiCommerceConfig::KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_PRODUCT_ABSTRACT_ID,
        SharedAiCommerceConfig::KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_ABSTRACT_SKU,
        SharedAiCommerceConfig::KNOWLEDGE_DOCUMENT_SCOPE_REFERENCE_TYPE_CONCRETE_SKU,
    ];

    public function isApplicable(KnowledgeDocumentScopeRequestTransfer $knowledgeDocumentScopeRequestTransfer): bool
    {
        foreach (static::SCOPE_REFERENCE_TYPES as $scopeReferenceType) {
            if (($knowledgeDocumentScopeRequestTransfer->getScopeReferences()[$scopeReferenceType] ?? []) !== []) {
                return true;
            }
        }

        return false;
    }

    public function resolveDocumentScope(
        KnowledgeDocumentScopeRequestTransfer $knowledgeDocumentScopeRequestTransfer
    ): KnowledgeDocumentScopeTransfer {
        return $this->getFactory()
            ->createProductVideoDocumentScopeResolver()
            ->resolveDocumentScope($knowledgeDocumentScopeRequestTransfer);
    }
}

Read the entities from the key-value storage, not from Zed: the search runs in Yves and Glue on each tool call. Use SprykerFeature\Client\AiCommerce\ProductAttachmentKnowledgeDocument\ProductAttachmentDocumentScopeResolver as the reference for the product checks and the messages.

Which tool finds the new documents

SCOPE OF THE NEW SOURCE TOOL
Products: the plugin reads the product reference types product_knowledge_search finds the new documents without changes. Its source_types argument selects the source types. An empty value means all source types.
Another entity, such as a merchant or a Self-Service Portal asset A new tool is necessary. It builds KnowledgeDocumentScopeRequestTransfer.scopeReferences with your reference types. The AiCommerce Client has no public search method yet, so this case is not supported.

Documents that belong to no entity, such as an FAQ or a return policy, are not supported, because the search needs document keys.

4) Register the plugins

Add the source plugin to the Zed AiCommerceDependencyProvider:

src/Pyz/Zed/AiCommerce/AiCommerceDependencyProvider.php

<?php

namespace Pyz\Zed\AiCommerce;

use Pyz\Zed\ProductVideo\Communication\Plugin\AiCommerce\ProductVideoKnowledgeDocumentSourcePlugin;
use SprykerFeature\Zed\AiCommerce\AiCommerceDependencyProvider as SprykerFeatureAiCommerceDependencyProvider;
use SprykerFeature\Zed\AiCommerce\Communication\Plugin\KnowledgeDocument\ProductAttachmentKnowledgeDocumentSourcePlugin;

class AiCommerceDependencyProvider extends SprykerFeatureAiCommerceDependencyProvider
{
    /**
     * @return list<\SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentSourcePluginInterface>
     */
    protected function getKnowledgeDocumentSourcePlugins(): array
    {
        return [
            new ProductAttachmentKnowledgeDocumentSourcePlugin(),
            new ProductVideoKnowledgeDocumentSourcePlugin(),
        ];
    }
}

Add the scope resolver plugin to the Client AiCommerceDependencyProvider:

src/Pyz/Client/AiCommerce/AiCommerceDependencyProvider.php

<?php

namespace Pyz\Client\AiCommerce;

use Pyz\Client\ProductVideo\Plugin\AiCommerce\ProductVideoKnowledgeDocumentScopeResolverPlugin;
use SprykerFeature\Client\AiCommerce\AiCommerceDependencyProvider as SprykerFeatureAiCommerceDependencyProvider;
use SprykerFeature\Client\AiCommerce\Plugin\KnowledgeDocument\ProductAttachmentKnowledgeDocumentScopeResolverPlugin;

class AiCommerceDependencyProvider extends SprykerFeatureAiCommerceDependencyProvider
{
    /**
     * @return list<\SprykerFeature\Client\AiCommerce\Dependency\KnowledgeDocument\KnowledgeDocumentScopeResolverPluginInterface>
     */
    protected function getKnowledgeDocumentScopeResolverPlugins(): array
    {
        return [
            new ProductAttachmentKnowledgeDocumentScopeResolverPlugin(),
            new ProductVideoKnowledgeDocumentScopeResolverPlugin(),
        ];
    }
}

You do not need to register the events. KnowledgeDocumentWritePublisherPlugin subscribes to the events of all registered source plugins. Clear the caches after you change a dependency provider:

console cache:class-resolver:build
console cache:empty-all

5) Configure the data source

Each source type writes its documents to a custom data source of the knowledge base. Add the source type to BEDROCK_KNOWLEDGE_BASE_DATA_SOURCE_IDS:

config/Shared/config_ai.php

$config[AiCommerceConstants::BEDROCK_KNOWLEDGE_BASE_DATA_SOURCE_IDS] = [
    AiCommerceConfig::KNOWLEDGE_DOCUMENT_SOURCE_TYPE_PRODUCT_ATTACHMENT => getenv('SPRYKER_AI_KNOWLEDGE_BASE_DATA_SOURCE_ID') ?: '',
    ProductVideoConfig::KNOWLEDGE_DOCUMENT_SOURCE_TYPE_PRODUCT_VIDEO => getenv('SPRYKER_AI_KNOWLEDGE_BASE_PRODUCT_VIDEO_DATA_SOURCE_ID') ?: '',
];

Select the data source:

OPTION WHEN TO USE
The data source of another source type Default. Use the same ID as for product_attachment when the same ingestion settings are correct for the new documents. One data source can hold the documents of several source types, because the document key keeps them apart.
A new custom data source The new documents need other ingestion settings, such as no image extraction, or you must be able to delete all of them at one time. Create the data source as described in Create the AWS resources, step 3, and set its ID in the environment variable.

The search does not use the data source. It searches the whole knowledge base and filters by document key, source type, and locale.

Changing the data source of a source type

Do not change the data source of a source type that has indexed documents. The old documents stay in the old data source, and the search still finds them. Delete them from the old data source first, then run a forced re-index of the source type.

6) Set up and index the documents

  1. Check the knowledge base. The command reads the source types of all registered source plugins:

    console knowledge-document:setup -v
    

    When the configuration has no data source for the new source type, the command fails with Add the source type product_video to BEDROCK_KNOWLEDGE_BASE_DATA_SOURCE_IDS and sends no request to AWS.

  2. Queue the documents of the new source type only:

    console knowledge-document:reindex --source-type=product_video -v
    
  3. Process the queue:

    console queue:worker:start --stop-when-empty
    
  4. Some minutes later, save the result. The scheduler job also runs this command every five minutes:

    console knowledge-document:status:refresh
    
Verification
  1. Make sure that the documents of the new source type are indexed:

    SELECT status, COUNT(*) FROM spy_knowledge_document WHERE source_type = 'product_video' GROUP BY status;
    
  2. On a product page, ask the assistant a question that only the new document answers. The answer names the new document as the source.

7) Test the plugins

TEST WHAT TO CHECK
Functional test of the source plugin The events give the source identifiers. A deleted entity is missing in getDocumentSourceCollection(). The content and the MIME type are correct.
Functional test of the scope resolver plugin A visible entity gives the document keys product_video:{id}. An entity that is not visible in the store or the locale gives no keys and a message. sourceIdentifiers keeps only the requested documents.

The tests of the product attachment plugins in the spryker-feature/ai-commerce module are the reference: ProductAttachmentKnowledgeDocumentScopeResolverPluginTest and ProductAttachmentKnowledgeDocumentSourcePluginTest.