sg_ai
Integrates AI into TYPO3 to streamline content creation and editorial workflows.

Table of Contents

1. Ext: sg_ai
2. SG AI for TYPO3: End-User Documentation
3. AI Watermark Overlay API

---

Ext: sg_ai

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

1. Install extension:

composer require sgalinski/sg_ai

2. Activate extension in Extension Manager.
3. Run database schema updates in TYPO3 Install Tool / Admin Tools.
4. 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:

1. Render your image markup (<img> or <picture>) in your own ViewHelper/renderer.
2. Create and dispatch AfterImageRenderingEvent with:
   • the rendered HTML
   • the resolved FileInterface
   • render context (width, height, accessibleText, isDecorative, optional override keys)
3. 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:

1. 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)
2. 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

---

SG AI for TYPO3: End-User Documentation

This guide explains how to use the sg_ai TYPO3 extension in daily editorial work.

It is focused on:

• real backend workflows for editors and SEO managers
• all user-facing buttons introduced by the extension
• setup and configuration that affects behavior
• practical benefits, limits, and troubleshooting

For extension-level setup and upgrade notes, also see:

• ../../README.md

1. Purpose of the Extension

sg_ai adds AI-assisted content and quality workflows directly into TYPO3 backend forms.

Main goals:

• speed up content production
• improve SEO and accessibility quality
• reduce repetitive manual work for editors
• standardize outputs across large teams

The extension currently covers:

1. Alt text generation for images
2. AI image generation for file fields
3. AI text generation for RTE content
4. SEO title and description generation for pages
5. AI-powered technical/content SEO recommendations
6. AI-powered accessibility recommendations
7. URL checks in the backend module
8. bulk processing through CLI commands

2. Target Users and Responsibilities

Editors

• generate text, images, and alt text
• refine generated output before publishing
• trigger page-level recommendation generation

SEO / Accessibility Managers

• review scores and recommendation tables
• prioritize fixes by impact
• re-run checks after content updates

TYPO3 Administrators / Integrators

• configure API access and defaults
• control field-level behavior in TCA
• automate bulk generation via commands

3. Prerequisites

Before users can work with the buttons:

1. The extension sg_ai must be installed and active.
2. Queue processing must be active by creating the TYPO3 scheduler task sg_ai:process-queue.
3. SG AI API credentials must be configured.
4. Editors need backend access to the affected records/tables.
5. For URL/page-based checks, the checked page must be reachable as rendered HTML.

3.1 Required queue activation (TYPO3 2.x)

Queue processing is mandatory in 2.x for asynchronous workflows (recommendations, history updates, remote background results).

Recommended setup path:

1. Open Web > AI Assistant > Dashboard.
2. If the warning Scheduler task inactive is shown, click Create scheduler task now for sg_ai:process-queue.
3. Add the additional recommended scheduler tasks from the dashboard:
   • 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; may consume many credits)

Recommended execution interval for sg_ai:process-queue: every 5 minutes (*/5 * * * *).

4. Global Configuration (Extension Configuration)

Open:

• Admin Tools > Settings > Extension Configuration > sg_ai

4.1 Required

• apiKey
  • SG AI API key.
  • Recommended: do not store in TYPO3 DB; use environment variable SG_AI_API_KEY.

4.2 Optional but Important

• useImageAnalysis (0/1)

  • 1: analyzes actual image content for alt text generation.
  • 0: metadata-only alt text generation.
  • Impact: quality vs. processing complexity.

• useBase64Encoding (0/1)

  • 1: sends image data as base64 to SG AI.
  • 0: sends image URL.
  • Recommended: keep 1 for private/staging/non-public environments.

• useContextForAltText (0/1)

  • 1: includes surrounding TYPO3 context when generating alt text.
  • 0: no contextual page data.
  • Impact: often better relevance, potentially higher token usage.

• language (e.g. en, de)

  • default language for recommendation output (SEO/a11y checks and module usage).

• watermarkEnabled (0/1)

  • global on/off switch for SG AI watermark logic on AI-flagged images (overlay decision + processing metadata hooks).

• watermarkOverlayEnabled (0/1)

  • enables/disables frontend HTML/CSS watermark overlay rendering.
  • default is 0 (disabled).

• watermarkPreserveMetadataOnProcessing (0/1)

  • adds SG AI provenance metadata in TYPO3's processing command when processed variants are created.
  • default is 1 (enabled).

• watermarkBadgeAssetPath

  • EXT: path or absolute path to the badge graphic (default circled AI icon).

• watermarkPosition, watermarkMargin, watermarkRelativeSize, watermarkOpacity

  • visual styling and placement controls.

• watermarkMaxWidth, watermarkMaxHeight

  • badge size caps in pixels (default 80/80, 0 = unlimited).

• watermarkMinWidth, watermarkMinHeight

  • minimum output dimensions for watermarking.

• watermarkScreenReaderLabelEnabled, watermarkScreenReaderSuffix

  • controls whether non-decorative AI images receive an accessibility suffix in alt and aria-label.

• watermarkOverlayAccessibilityLabel

  • localized label text used for the watermark badge image (alt / aria-label).

• per-call overrides

  • mode-only: sgAiWatermarkMode (on|off)
  • structured: sgAiWatermarkOverride supports mode / enabled and visual/accessibility settings.

HTML overlay behavior:

• the extension appends additional badge markup to rendered image HTML
• the badge is positioned with CSS on top of the image
• this does not alter image pixels or binary image data

4.3 Fixed Queue/Polling Defaults

Queue and remote background polling behavior uses fixed defaults in code and is not configurable via Extension Configuration:

• immediate local processing priorities: 20,30
• remote synchronous priorities: 20,30
• polling max retries: 120
• polling sleep seconds: 2

4.4 EU AI Act (Pragmatic Note)

sg_ai supports practical transparency measures for AI-assisted content:

• AI-image markers in TYPO3 metadata/reference records
• optional visual frontend overlay labeling
• optional accessibility suffixes for non-decorative AI images
• provenance metadata best effort during processing
• persisted AI text/recommendation outputs in TYPO3 records/history for editorial approval workflows

What must be shown to end users, in which channel, and at what workflow stage remains an integrator/editorial decision. This documentation does not provide legal advice.

5. Field-Level Configuration in TCA

Several features can be tuned per field using config.sg_ai.

5.1 Common controls

• disabled
  • hides SG AI controls for that field.
• promptProvider
  • custom provider class to generate prompts.
• promptTemplate
  • template with placeholders such as ###title###.

5.2 Image-field specific

• image_size
  • default generated image size preset or custom dimensions.
• output_format
  • png or jpeg.

6. Button-by-Button End-User Guide

This section lists all user-facing buttons introduced by sg_ai.

6.1 Generate Alt Text with AI

Where it appears

• On sys_file_reference.alternative
• On sys_file_metadata.alternative

Label / title behavior

• The control uses context-aware titles:
  • context active
  • context ignored

Workflow

1. Open a record that contains an image reference.
2. Locate the Alternative (alt text) field.
3. Click Generate Alt Text with AI.
4. Wait for the request to finish.
5. Review the generated text and adjust if needed.
6. Save the record.

Important notes

• If image is marked decorative, generation is skipped.
• If record/file is missing or inaccessible, generation fails with an error message.
• If API key is missing, users receive an explicit configuration error.

Benefits

• very fast accessibility baseline
• improved consistency in alt text style and length
• lower manual effort for media-heavy pages

6.2 Is Decorative (Toggle)

Where it appears

• Image overlay palette in sys_file_reference

Purpose

• Marks an image as decorative.
• Decorative images are intentionally excluded from alt text generation.

Workflow

1. Open image reference in backend form.
2. Enable Is decorative if image has no informative value.
3. Save.

Benefit

• prevents misleading or unnecessary alt text
• improves accessibility quality by using proper decorative-image handling

6.3 Generate Image with AI

Where it appears

• In inline file controls for image-capable fields (for matching image file types)
• Can be disabled per field via config.sg_ai.disabled

Modal actions

• Generate
• Reset to Default
• Cancel

Workflow

1. Open a saved record with an eligible image field.
2. Click Generate Image with AI.
3. In modal, edit or keep the prompt.
4. Optional: click Reset to Default to regenerate default prompt.
5. Click Generate.
6. Wait for processing notification.
7. Page reloads and new image reference is attached.

What happens technically (user-visible outcome)

• New file is generated and attached to record.
• Generated file is marked as AI-generated in file metadata.
• SG AI stores provenance metadata for generated images.
• Alt text generation is triggered for the new image.
• Last prompt is persisted per record/field, including the image settings comment block.
• File may be renamed to an SEO-friendly name derived from alt text.
• Generated filename length is capped to 60 characters (including suffix and extension).

EU AI Act transparency support is documented in extension metadata (ext_emconf.php and composer.json).

Benefits

• fast visual content creation without leaving TYPO3
• consistent style via prompt templates
• immediate integration into existing media fields

6.4 Generate Text with AI

Where it appears

• On eligible RTE text fields.
• The extension auto-injects this button for supported text fields.

Modal actions

• Generate Text
• Reset to Default
• Cancel
• Checkbox: Include page context

Workflow

1. Open a saved record with an RTE field.
2. Click Generate Text with AI.
3. Review/edit the generated prompt.
4. Choose whether to include page context.
5. Click Generate Text.
6. Generated content is inserted into CKEditor/textarea.
7. Review, edit, and save.

Page-context option

When enabled, context may include:

• TYPO3 version metadata
• page information
• nearby content data for richer relevance

Restrictions

• Unsaved records cannot generate text.
• Non-RTE fields are filtered/removed from this workflow.

Benefits

• faster drafting, rewriting, and expansion
• better context-aware results with one click
• reduced editor switching between tools

6.5 Generate SEO-Friendly Title

Where it appears

• pages.seo_title field control

Workflow

1. Open page properties.
2. Click Generate SEO-friendly title.
3. Wait for generation.
4. Value is written to seo_title.
5. Review and save.

Benefits

• faster meta optimization
• consistent and language-aware SEO title generation

6.6 Generate SEO-Friendly Description

Where it appears

• pages.description field control

Workflow

1. Open page properties.
2. Click Generate SEO-friendly description.
3. Wait for generation.
4. Value is written to description.
5. Review and save.

Benefits

• faster and more complete meta coverage
• reduced chance of missing or weak descriptions

6.7 Generate Technical SEO Recommendations

Where it appears

• In page-level SG AI recommendation area

Workflow

1. Open saved page record.
2. Click Generate Technical SEO Recommendations.
3. Wait for background processing notice.
4. Page reloads.
5. Review updated score and recommendation table.

Output shown to users

• score indicator (0-100)
• recommendation table with:
  • Priority, Where, What, How, Why
• generation timestamp

Benefit

• quick technical SEO issue discovery directly in page editing

6.8 Generate Content SEO Recommendations

Workflow

1. Open saved page record.
2. Click Generate Content SEO Recommendations.
3. Page reloads with updated score and recommendations.

Benefit

• content-quality and relevance guidance for editors and SEO teams

6.9 Generate Accessibility Recommendations

Workflow

1. Open saved page record.
2. Click Generate Accessibility Recommendations.
3. Page reloads with updated score and recommendation table.

Benefit

• faster identification of accessibility barriers and fixes

6.10 Backend Module Button: Get Recommendations

Use the dashboard first when setting up a fresh instance:

• Web > AI Assistant > Dashboard for onboarding and scheduler setup
• then switch to Web > AI Assistant > AI Page Insights for URL checks

Location

• Web > AI Assistant > AI Page Insights

Inputs

• URL (required)
• Type:
  • Technical SEO
  • Content SEO
  • Accessibility

Main action

• Get recommendations

Workflow

1. Open module.
2. Enter public URL.
3. Select analysis type.
4. Click Get recommendations.
5. Review score and structured recommendations in “Last result”.

Benefits

• quick quality check for arbitrary URLs
• usable for checks outside the currently edited page

6.11 AI History and Queue Status

Where it appears

• Web > AI Assistant > AI Page Insights (integrated Analysis + History tabs)
• Web > AI Assistant > Dashboard (scheduler overview and setup actions)

What users can do

1. Track queued and completed AI tasks.
2. Open View to inspect full generated result payloads.
3. Search, sort, and paginate through past results.
4. Reuse generated output where action buttons are available.
5. Identify remote queue runs by message state information in status/details.

Why this matters

• improves traceability of AI-generated changes
• supports editorial review before applying outputs
• helps teams verify that queue processing is healthy

7. Typical End-User Scenarios

7.1 New page creation

1. Create and save page/content.
2. Generate draft text in RTE fields.
3. Generate images where needed.
4. Generate image alt texts.
5. Generate SEO title and description.
6. Run content/technical/a11y recommendations.
7. Apply improvements and publish.

7.2 Existing page optimization

1. Run recommendation buttons.
2. Prioritize high-impact items from table.
3. Update content, structure, or media.
4. Re-run recommendation generation.
5. Track improved score and publish updates.

8. CLI Workflows for Large Sites

For admins/integrators:

• vendor/bin/typo3 sg_ai:generate-alt-texts
• vendor/bin/typo3 sg_ai:generate-seo-meta
• vendor/bin/typo3 sg_ai:generate-ai-recommendations
• vendor/bin/typo3 sg_ai:process-queue
• vendor/bin/typo3 sg_ai:list-queue
• vendor/bin/typo3 sg_ai:cleanup-queue

When to use:

• initial rollout on existing content
• scheduled quality maintenance jobs
• large-batch updates after migrations

9. Best Practices for Content Teams

1. Always review AI output before publishing.
2. Use “Is decorative” correctly for non-informative images.
3. Keep prompts concise and task-specific.
4. Use TCA templates for consistent tone across fields.
5. Re-run recommendations after meaningful content changes.
6. Keep API credentials in environment variables, not in VCS.

10. Troubleshooting Guide

“API key is not configured”

• Check SG_AI_API_KEY or sg_ai extension configuration.

Buttons are missing

• Check user permissions.
• Verify field-level config.sg_ai.disabled.
• Confirm field type supports that button workflow.

Unsaved record warning

• Save record first, then run generation.

Recommendation generation fails

• Ensure target page/URL is reachable and rendered.
• Check TYPO3/system logs for request details.

Queue tasks stay pending for too long

• Verify the scheduler task sg_ai:process-queue exists and is enabled.
• Execute a manual run: vendor/bin/typo3 sg_ai:process-queue --limit=5.
• If the backend shows Scheduler task inactive, create it in Web > AI Assistant > Dashboard.

Image generation works but no visible result

• Record reload may be required.
• Verify file field configuration and storage permissions.

History is empty even after generation

• Confirm queue processing is active and tasks reach status finished.
• Verify there are no API/permission errors in TYPO3 logs.

11. Governance and Quality Control

For team leads:

• define editorial rules for AI output acceptance
• set periodic accessibility/SEO review cadences
• document approved prompt patterns for each content type
• monitor changes in recommendations over time

12. Summary

sg_ai turns TYPO3 backend forms into AI-assisted workflows:

• generate faster
• improve quality continuously
• keep content, SEO, and accessibility work inside TYPO3

For extension-level setup and upgrade information, see:

• ../../README.md

---

AI Watermark Overlay API

sg_ai provides a reusable overlay API so extension-level ViewHelpers can render AI watermarks in a generic way.

SG AI watermark overlays are injected through PSR-14 image-rendering events:

• SGalinski\SgAi\Event\AfterImageRenderingEvent

Recommended integration for all setups: dispatch AfterImageRenderingEvent from your existing renderer right after building the final image HTML (<img>/<picture>). This avoids custom SG AI wrapper ViewHelpers and keeps one rendering path.

Implementation outline:

1. Render image HTML in your own renderer.
2. Resolve the corresponding TYPO3 FileInterface.
3. Dispatch SGalinski\SgAi\Event\AfterImageRenderingEvent with HTML, file, and render context.
4. Use the returned event HTML (getImageHtml()) as final output.

Services

SGalinski\SgAi\Service\AiImageWatermarkOverlayService

Main methods:

• buildPictureOverlayResult(FileInterface $file, array $renderContext = []): array

buildPictureOverlayResult() returns a consumer-ready payload for thin integrations:

• overlayMarkup (ready-to-append badge overlay markup)
• isWatermarkActive (final decision after global settings, AI flag, dimension limits, and optional per-call override)
• accessibleText (input accessible text with optional AI suffix applied for non-decorative images)
• shouldSyncAccessibleText (whether alt/aria-label should be rewritten from accessibleText)

The badge image accessibility label (alt/aria-label inside overlayMarkup) is configured through watermarkOverlayAccessibilityLabel and supports LLL references.

SGalinski\SgAi\Service\AiImageWatermarkService

Relevant integration method:

• resolvePerCallWatermarkContext(array $context, ?array $watermarkConfiguration = null): array

This method normalizes mode-only and structured overrides and is used by both processing and overlay integrations. Use it if your extension needs to apply SG AI-compatible watermark overrides in custom pipelines.

Render Context

Supported render-context keys:

• width, height (optional target dimensions used for threshold checks)
• accessibleText (optional source text for alt and aria-label synchronization)
• isDecorative (optional boolean to suppress suffixing for decorative images)
• sgAiWatermarkMode (optional on|off)
• sgAiWatermarkOverride (optional structured override array)

sgAiWatermarkOverride supports:

• mode (on|off) or enabled (true|false)
• badgeAssetPath
• position
• margin
• relativeSize
• maxWidth, maxHeight
• opacity
• minWidth, minHeight
• overlayAccessibilityLabel
• screenReaderSuffix
• screenReaderLabelEnabled

Global extension settings relevant to overlay behavior:

• watermarkEnabled (global watermark decision base)
• watermarkOverlayEnabled (frontend overlay rendering switch)

If watermarkOverlayEnabled is disabled, no overlay markup is injected even if image-level watermark conditions are met.

Overlay Markup and CSS Requirements

The overlay is rendered as additional HTML appended to the image/picture output:

<span class="sgai-watermark-overlay" style="--sgai-watermark-margin: ...; --sgai-watermark-size: ...; ...">
	<img class="sgai-watermark-overlay-badge sgai-watermark-overlay-badge--southeast" ... />
</span>

This markup requires CSS to be visually positioned as an overlay. Without CSS, the badge will be rendered as normal inline content.

Required CSS Integration

Import the SG AI stylesheet partial in your frontend build:

EXT:sg_ai/Resources/Public/Sass/Bootstrap5/_sg-ai.scss

If you do not use SASS imports, add equivalent CSS rules manually. The minimum required behavior is:

1. The image container must be position: relative.
2. .sgai-watermark-overlay must be position: absolute; inset: 0;.
3. .sgai-watermark-overlay-badge must be absolutely positioned via the --north/.../--southeast classes.

Plain CSS Fallback Example

.my-image-wrapper {
	position: relative;
}

.my-image-wrapper .sgai-watermark-overlay {
	position: absolute;
	inset: 0;
	pointer-events: none;
}

.my-image-wrapper .sgai-watermark-overlay-badge {
	position: absolute;
	width: var(--sgai-watermark-size, 12%);
	opacity: var(--sgai-watermark-opacity, 0.85);
}

.my-image-wrapper .sgai-watermark-overlay-badge--southeast {
	right: var(--sgai-watermark-margin, 24px);
	bottom: var(--sgai-watermark-margin, 24px);
}

Runtime CSS Variables

The overlay service writes these CSS variables inline:

• --sgai-watermark-margin
• --sgai-watermark-size
• --sgai-watermark-opacity
• --sgai-watermark-max-width
• --sgai-watermark-max-height

This allows integrators to keep global CSS generic while sizing and placement are still controlled by SG AI settings and per-call overrides.