README

License: GNU GPL, Version 3

Repository: https://gitlab.sgalinski.de/sg-ai/sg_ai

Please report bugs here: https://gitlab.sgalinski.de/sg-ai/sg_ai/-/work_items

Overview

sg_ai brings AI-assisted editorial workflows directly into TYPO3 backend forms and modules.

The extension covers:

Alt text generation for images (sys_file_reference and sys_file_metadata)
AI image generation in file fields (including automatic file reference creation)
AI text generation in configured text fields
SEO title/description generation for pages and social meta fields
Technical SEO, content SEO, and accessibility recommendations
Queue-based background processing for long-running operations
Backend history views for queued/generated AI results
Prompt persistence for image generation (including image settings block)
Automatic SEO-friendly image filename generation based on alt text

For end-user focused documentation, see:

Docs/End-User/README.md

Requirements

TYPO3 v13 LTS (13.4)
PHP >= 8.3
Valid SG AI API key

Installation

Install extension:

composer require sgalinski/sg_ai

Activate extension in Extension Manager.
Run database schema updates in TYPO3 Install Tool / Admin Tools.
Configure extension settings (see next section).

Configuration

Open:

Admin Tools > Settings > Extension Configuration > sg_ai

Available extension settings (ext_conf_template.txt):

apiKey
useImageAnalysis
useBase64Encoding
useContextForAltText
language
watermarkEnabled
watermarkOverlayEnabled
watermarkPreserveMetadataOnProcessing
watermarkBadgeAssetPath
watermarkPosition
watermarkMargin
watermarkRelativeSize
watermarkMaxWidth
watermarkMaxHeight
watermarkOpacity
watermarkMinWidth
watermarkMinHeight
watermarkScreenReaderLabelEnabled
watermarkScreenReaderSuffix
watermarkOverlayAccessibilityLabel

Recommended API key setup:

Preferred: provide SG_AI_API_KEY as environment variable (for example in .env.local)
Alternative: set apiKey directly in extension configuration

AI Image Watermarking

Watermark overlays are applied via PSR-14 image-rendering events.
sg_ai provides a frontend SASS partial for overlay positioning at Resources/Public/Sass/Bootstrap5/_sg-ai.scss.
Theme integrations (for example project-theme) should import this partial.
watermarkEnabled=1 means watermark logic is active for images marked as AI-generated (tx_sgai_is_ai_generated in metadata or file references).
watermarkOverlayEnabled=1 enables frontend HTML/CSS overlay badge rendering (default: 0, disabled).
watermarkPreserveMetadataOnProcessing=1 sets SG AI provenance metadata during TYPO3 processing in the same ImageMagick call.
Mode-only override is available via sgAiWatermarkMode (on|off).
Structured per-call override is available via sgAiWatermarkOverride and supports: mode|enabled (on|off|true|false|1|0), badgeAssetPath, position, margin, relativeSize, maxWidth, maxHeight, opacity, minWidth, minHeight, overlayAccessibilityLabel, screenReaderSuffix, screenReaderLabelEnabled.
Default badge asset is a high-resolution PNG (Resources/Public/Icons/ai-watermark-badge.png).
Watermark badge sizing uses watermarkRelativeSize and is capped by default via watermarkMaxWidth / watermarkMaxHeight (80/80); set either to 0 for no cap.
Accessibility suffix behavior is configurable through watermarkScreenReaderLabelEnabled and watermarkScreenReaderSuffix and keeps alt and aria-label synchronized for non-decorative images.
Watermark badge accessibility text (alt/aria-label) is configurable through watermarkOverlayAccessibilityLabel and supports LLL translation references.
watermarkScreenReaderSuffix and watermarkOverlayAccessibilityLabel both support LLL translation references.
Optional overlay API integration for custom ViewHelpers is documented in Docs/Developer/WatermarkOverlayApi.md.

What the HTML overlay does:

It appends additional markup (<span class="sgai-watermark-overlay">...) to the rendered image/picture HTML.
CSS positions this badge absolutely on top of the image.
No image pixels are changed in this mode.
The required CSS contract and fallback examples are documented in Docs/Developer/WatermarkOverlayApi.md.

Integrator Example (Event-Based Integration)

After generating image markup, dispatch AfterImageRenderingEvent:

$event = new \SGalinski\SgAi\Event\AfterImageRenderingEvent(
	$imageHtml,
	$file,
	[
		'width' => $width,
		'height' => $height,
		'accessibleText' => $alternative,
		'isDecorative' => $alternative === '',
		'sgAiWatermarkOverride' => [
			'mode' => 'on',
			'badgeAssetPath' => 'EXT:site_package/Resources/Public/Icons/custom-ai-badge.svg',
			'maxWidth' => 40,
			'maxHeight' => 40,
		],
	]
);
$event = $eventDispatcher->dispatch($event);
$imageHtml = $event->getImageHtml();

Integrating Into Any Renderer (Recommended)

Use your existing image rendering pipeline and dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent after generating image HTML. SG AI listens to this event and applies overlay/accessibility updates.

This keeps image rendering in one place and avoids duplicate integration paths.

Implementation outline:

Render your image markup (<img> or <picture>) in your own ViewHelper/renderer.
Create and dispatch AfterImageRenderingEvent with:
- the rendered HTML
- the resolved FileInterface
- render context (width, height, accessibleText, isDecorative, optional override keys)
Return getImageHtml() from the dispatched event object.

Integrator Example (Direct Overlay API)

For rendering pipelines without events, use:

$overlayService = GeneralUtility::makeInstance(\SGalinski\SgAi\Service\AiImageWatermarkOverlayService::class);
$overlayResult = $overlayService->buildPictureOverlayResult($file, [
	'width' => $width,
	'height' => $height,
	'accessibleText' => $alternative,
	'isDecorative' => $alternative === '',
	'sgAiWatermarkOverride' => [
		'mode' => 'on',
	],
]);

$overlayMarkup = (string) ($overlayResult['overlayMarkup'] ?? '');
if ($overlayMarkup !== '') {
	$imageHtml .= $overlayMarkup;
}

Why this pattern is recommended:

It avoids full-page HTML middleware scanning.
It keeps SG AI decision logic centralized and reusable.
It supports per-render overrides without custom data attributes.

Required Queue Setup (2.x)

Queue processing must be active for asynchronous tasks.

Required scheduler command:

vendor/bin/typo3 sg_ai:process-queue

Recommended execution interval:

every 5 minutes (*/5 * * * *)

Setup options:

Backend shortcut:
- Open module group AI Assistant > Dashboard
- Click Create scheduler task now if inactive warning is shown for the queue worker
- Optionally create additional tasks directly there:
  - sg_ai:cleanup-queue (daily)
  - sg_ai:generate-seo-meta (nightly)
  - sg_ai:generate-alt-texts (early morning)
  - sg_ai:generate-ai-recommendations --limit=25 (weekly, can consume many credits)
Manual scheduler setup:
- Open TYPO3 Scheduler module and create Execute console commands tasks in group SGAI
- Use the same command/interval recommendations as shown in the dashboard cards

Backend Usage

Modules

AI Assistant (/module/web/ai-assistant)
- Backend module group for SG AI workflows
Dashboard (/module/web/sg-ai-dashboard)
- Overview for all SG AI modules, onboarding checklist, scheduler status/setup
AI Page Insights (/module/web/sg-ai)
- Unified workspace for analysis and history (tabs in one module)
- Run URL checks, trigger recommendation tasks, monitor active queue work, and inspect/reuse past results
Legacy AI History URL (/module/web/sg-ai-history)
- Redirects to the unified AI Page Insights history tab for backward compatibility

Field Controls

Depending on TCA configuration and field type, backend forms can show:

Generate alt text button
Generate image button
Generate text button
Generate SEO title/description buttons
Generate technical/content/a11y recommendation buttons

Generated images are marked as AI-generated in TYPO3 metadata/reference flags (tx_sgai_is_ai_generated) and receive automatic alt text handling. If the SG AI image response provides provenance/generation metadata, sg_ai preserves it for generated originals by mapping values into sys_file_metadata (for example creator, creator_tool, source, copyright, description, title). Additionally, sg_ai writes AI provenance markers for generated originals:

IPTC/XMP Digital Source Type (trainedAlgorithmicMedia URI)
AI system fields (system name/version and model name) when provided by the API response
A normalized provenance summary in TYPO3 sys_file_metadata.note

For processed image variants, SG AI can add this provenance metadata within TYPO3's processing command (watermarkPreserveMetadataOnProcessing, default 1). Metadata persistence in image binaries depends on file format and ImageMagick/GraphicsMagick capabilities. In practice, PNG/JPEG usually keep more metadata than WEBP in many environments. SG AI still attempts metadata embedding for all processed target formats as best effort.

EU AI Act transparency support is declared at extension metadata level (ext_emconf.php and composer.json), not as an image-embedded compliance statement.

EU AI Act (Pragmatic Note)

This extension provides technical support for transparency workflows:

AI-generated image marking (tx_sgai_is_ai_generated)
Optional visual watermark overlays in frontend output
Accessible label suffixes for non-decorative AI images
Provenance metadata best effort during image processing
Prompt/result traces in TYPO3 data structures for editorial review
AI-generated text/recommendation outputs are persisted in TYPO3 records and queue/history tables for review before publication

Integrators are responsible for deciding where and when labels/disclosures are shown, based on their legal and organizational requirements. This extension does not provide legal advice.

Not Yet Added: C2PA Manifest Signing

sg_ai does not yet add a C2PA manifest to generated images.

What this would provide:

A cryptographically signed provenance manifest embedded in or bound to the image
Verifiable claim of origin and transformation chain (tamper-evident)
Stronger interoperability with Content Credentials / C2PA-aware verification tools

Why this is separate from ordinary metadata:

XMP/IPTC fields are editable metadata and are not cryptographically protected by default
C2PA requires a signing pipeline (private key management, certificates, manifest generation, and signature validation strategy)
Operationally this introduces trust infrastructure and key-rotation requirements that must be configured per environment

Planned scope for a future implementation:

Optional C2PA signer integration (disabled by default)
Configurable key/certificate handling and signer identity
Fail-safe behavior (image generation still succeeds if signing is unavailable, with explicit logging)

Queue and History Behavior

Long-running tasks are enqueued and processed asynchronously.
Queue records are persisted in tx_sgai_queue.
Results/history are persisted in tx_sgai_url_check.
Remote background processing (HTTP 202/message ID) is supported and finalized via queue polling.
Queue entries store cloud tracking metadata (remote_message_id, remote_status) for remote runs.
History views support search, sorting, pagination, and result preview via View action.
If the cloud API rate limits (HTTP 429), processing is deferred and retried safely.

Image Generation Behavior

The last image prompt is persisted and reused per record/field (tx_sgai_last_image_prompt).
Prompt persistence keeps the image settings comment block, including image_size and output_format.
Generated images are automatically marked as AI-generated (tx_sgai_is_ai_generated).
AI-generated images can be watermarked automatically during rendering based on extension configuration.
Generated images can be renamed from alt text to SEO-friendly slugs.
Renamed files are capped at 60 characters total (including hash suffix and extension).

TCA Configuration Example (AI Image Generation)

'images' => [
	'config' => [
		'sg_ai' => [
			'promptProvider' => 'Vendor\\Extension\\PromptProvider\\CustomPromptProvider',
			'promptTemplate' => 'Generate an image for ###title### with ###category### theme',
			'disabled' => true,
			'image_size' => 'landscape_16_9',
			'output_format' => 'png',
		],
		'type' => 'file',
	],
],

Supported image size presets:

square_hd
square
portrait_4_3
portrait_16_9
landscape_4_3
landscape_16_9

You can also pass custom dimensions:

['width' => 1280, 'height' => 720]

CLI Commands

Alt text generation

vendor/bin/typo3 sg_ai:generate-alt-texts

Options:

--limit
--dry-run

SEO meta generation

vendor/bin/typo3 sg_ai:generate-seo-meta [page-uid]

Options include:

--force
--title-only
--description-only
--limit
--exclude-hidden
--exclude-deleted

AI recommendations generation

vendor/bin/typo3 sg_ai:generate-ai-recommendations [page-uid]

Options include:

--force
--accessibility-only
--content-seo-only
--technical-seo-only
--limit
--exclude-hidden
--exclude-deleted

Queue operations

Process queue:

vendor/bin/typo3 sg_ai:process-queue

List queue:

vendor/bin/typo3 sg_ai:list-queue

Cleanup queue/results:

vendor/bin/typo3 sg_ai:cleanup-queue

Troubleshooting

Tasks stay pending:
- verify scheduler task exists and is enabled
- run one manual queue cycle: vendor/bin/typo3 sg_ai:process-queue --limit=5
API key error:
- check SG_AI_API_KEY / extension configuration
URL/page checks fail:
- ensure target pages are publicly reachable for checks that require rendered output

Testing

Run extension checks from the project root:

composer phpunit vendor/sgalinski/sg-ai
composer phpstan vendor/sgalinski/sg-ai
composer ecs vendor/sgalinski/sg-ai

sgalinski / sg-ai

Maintainers

Package info

Statistics

Security