---
title: "ADR-014: AI-Powered Wizard System"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-014@0.35"
source: "Adr/Adr014AiPoweredWizardSystem.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# 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.
1.  **Model discovery gap:** Users don't know which models their provider offers.
1.  **Configuration quality:** Hand-written system prompts are often suboptimal.
1.  **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`.
1.  **Configuration Wizard** -- Takes a natural-language
    description and generates a structured
    `LlmConfiguration` via
    `WizardGeneratorService::generateConfiguration()`.
1.  **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**

```php
// WizardGeneratorService::generateConfiguration()
$config ??= $this->getDefaultConfiguration();
if ($config === null) {
    return $this->fallbackConfiguration($description);
}
```

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`