ADR-014: AI-Powered Wizard System 

Status

Accepted

Date

2025-12

Authors

Netresearch DTT GmbH

Context 

Users need to configure LLM providers, models, configurations, and tasks -- a complex multi-step process involving endpoint URLs, API keys, model selection, system prompts, and temperature tuning. Manual CRUD via TYPO3 list module is error-prone and intimidating for non-technical users.

Problem statement 

  1. High barrier to entry: First-time setup requires knowledge of API endpoints, adapter types, model capabilities, and prompt engineering.
  2. Model discovery gap: Users don't know which models their provider offers.
  3. Configuration quality: Hand-written system prompts are often suboptimal.
  4. Task chain complexity: Creating a task requires a configuration, which requires a model, which requires a provider -- four entities in sequence.

Decision 

Implement an AI-powered wizard system with three wizard types:

  1. Setup Wizard -- Guided provider onboarding (connect, verify, discover, configure, save). Five-step flow driven by Resources/Public/JavaScript/Backend/SetupWizard.js.
  2. Configuration Wizard -- Takes a natural-language description and generates a structured LlmConfiguration via WizardGeneratorService::generateConfiguration().
  3. Task Wizard -- Takes a natural-language description and generates a complete task chain (task + configuration + model recommendation) via WizardGeneratorService::generateTaskWithChain().

Graceful fallback when no LLM is available:

Example: Fallback when LLM is unavailable 
// WizardGeneratorService::generateConfiguration()
$config ??= $this->getDefaultConfiguration();
if ($config === null) {
    return $this->fallbackConfiguration($description);
}
Copied!

Key architectural components:

  • SetupWizardController -- AJAX endpoints for detect, test, discover, generate, save.
  • WizardGeneratorService -- LLM-powered generation with JSON parsing and normalization.
  • ModelDiscovery / ModelDiscoveryInterface -- Provider-specific model listing.
  • ProviderDetector -- Endpoint URL pattern matching for adapter type detection.
  • ConfigurationGenerator -- LLM-powered configuration preset generation.
  • DTOs: DetectedProvider, DiscoveredModel, SuggestedConfiguration, WizardResult.

Consequences 

Positive:

  • ●● Self-service onboarding without requiring LLM expertise.
  • ●● AI-generated prompts are more effective than hand-crafted first attempts.
  • ● Model discovery removes guesswork about available models.
  • ● Fallback defaults ensure the wizard works even without a working LLM.
  • ◐ Five-step flow with progress bar reduces cognitive load.

Negative:

  • ◑ Requires one working LLM configuration to power the AI generation path.
  • ◑ Generated configurations may need manual tuning for specialized use cases.
  • ◑ Additional JavaScript adds bundle size.

Net Score: +5.5 (Strong positive)

Files changed 

Added:

  • Classes/Controller/Backend/SetupWizardController.php
  • Classes/Service/WizardGeneratorService.php
  • Classes/Service/SetupWizard/ModelDiscovery.php
  • Classes/Service/SetupWizard/ModelDiscoveryInterface.php
  • Classes/Service/SetupWizard/ProviderDetector.php
  • Classes/Service/SetupWizard/ConfigurationGenerator.php
  • Classes/Service/SetupWizard/DTO/DetectedProvider.php
  • Classes/Service/SetupWizard/DTO/DiscoveredModel.php
  • Classes/Service/SetupWizard/DTO/SuggestedConfiguration.php
  • Classes/Service/SetupWizard/DTO/WizardResult.php
  • Resources/Public/JavaScript/Backend/SetupWizard.js