Custom Context Providers

Every generation request carries context that grounds the AI output in your actual content. By default, the bundle provides the document's template data. Context providers are the extension point to enrich these requests with your own data: a company glossary, product information, brand voice guidelines, target audience descriptions, or data from external systems.

How it works

When an expert request is built, all registered context providers for that expert are asked to contribute. Each provider yields key/value pairs that are merged into the request context sent to the sulu.ai platform. The default DocumentContentContextProvider for example contributes the document content:

yield 'content' => $content->getTemplateData();

Your providers add additional keys alongside it.

Available interfaces

Expert	Interface	Service tag
SEO Generator	Expert\SeoGenerator\SeoContextProviderInterface	sulu_ai.seo_context_provider
Excerpt Generator	Expert\ExcerptGenerator\ExcerptContextProviderInterface	sulu_ai.excerpt_context_provider
Media Metadata Generator	Expert\MediaMetadataGenerator\MediaMetadataContextProviderInterface	sulu_ai.media_metadata_context_provider

(All interfaces live under the Sulu\Bundle\AiPlatformBundle\ namespace.)

Example: SEO context provider

Implement the interface and yield your additional context:

<?php

namespace App\Ai;

use Sulu\Bundle\AiPlatformBundle\Compatibility\ContentPersister\ContentAdapterInterface;
use Sulu\Bundle\AiPlatformBundle\Expert\SeoGenerator\SeoContextProviderInterface;
use Sulu\Bundle\AiPlatformBundle\Expert\SeoGenerator\SeoGeneratorContext;

final readonly class BrandVoiceContextProvider implements SeoContextProviderInterface
{
    public function __construct(
        private BrandGuidelineRepository $brandGuidelines,
    ) {
    }

    public function generateContext(
        ContentAdapterInterface $content,
        string $expertUuid,
        SeoGeneratorContext $seoContext,
    ): iterable {
        yield 'brand_voice' => $this->brandGuidelines->getVoiceDescription();
        yield 'target_audience' => $this->brandGuidelines->getAudience($seoContext->webspaceKey);
    }
}

SeoGeneratorContext (and its excerpt counterpart) carries the request scope — locale, resourceKey, and webspaceKey — so providers can tailor their context per webspace or content type.

Register the service with the tag — implementing the interface alone is not enough for services defined in your application:

# config/services.yaml
services:
    App\Ai\BrandVoiceContextProvider:
        tags: ['sulu_ai.seo_context_provider']

Media metadata providers

The media interface receives the media entity and the raw file content instead of a document:

public function generateContext(
    MediaInterface $media,
    string $fileContent,
    string $locale,
    string $expertUuid,
): iterable;

Use it, for example, to pass the media's collection, existing tags, or licensing information as additional context.

Tips

• Yield stable keys — the keys become part of the request context; pick descriptive names (brand_voice, product_data) and keep them consistent so platform-side expert instructions can refer to them.
• Use the expert UUID — providers receive the expertUuid, so a single provider can serve different variants with different context.
• Keep it lean — context counts against the model's input; send what helps the generation, not entire databases.