TYPO3 LLM extension 

Extension key

nr_llm

Package name

netresearch/nr-llm

Version

main

Language

en

Author

Netresearch DTT GmbH

License

This document is published under the CC BY 4.0 license.

Rendered

Fri, 01 May 2026 15:28:27 +0000

Shared AI foundation for TYPO3. Configure LLM providers once — every AI extension uses them. Supports OpenAI, Anthropic Claude, Google Gemini, Ollama, and more.

For developers 

Build your TYPO3 extension on nr-llm — three lines of dependency injection, no API key handling.

🚀 Integration guide 

Step-by-step tutorial: add AI capabilities to your extension in five minutes.

Read more

💻 Developer guide 

LlmServiceManager API, streaming, tool calling, and custom providers.

Read more

⚙️ Feature services 

Translation, vision, embeddings, and completion — ready to inject and use.

Read more

📚 API reference 

Complete class and method reference for all public services and response objects.

Read more

🏗️ Architecture 

Three-tier configuration hierarchy, provider abstraction, and design decisions.

Read more

✅ Testing 

Test infrastructure, mocking LLM services, and CI configuration.

Read more

---

[n] A Netresearch extension 

Professional TYPO3 development, AI integration, and enterprise consulting since 2002.

netresearch.de

---

Table of contents

• Introduction
• Installation
• Administration
  • Managing providers
  • Managing models
  • Managing configurations
  • Managing tasks
  • AI-powered wizards
  • Per-user AI budgets
• Configuration reference
  • Provider fields
  • Model fields
  • Configuration field reference
  • Task fields
  • Settings
• Developer guide
  • Streaming support
  • Tool/function calling
  • Creating custom providers
  • Registering a provider
  • Fallback chain
  • BE group permission checks
  • Build your extension on nr-llm
  • Feature services
• API reference
  • LlmServiceManager
  • CompletionService
  • EmbeddingService
  • VisionService
  • TranslationService
  • Response objects
  • Option classes
  • Provider interface
  • Exceptions
• Architecture
• Testing guide
  • Unit testing
  • Functional testing
  • E2E testing
  • CI configuration
• Architecture Decision Records
  • ADR-001: Provider Abstraction Layer
  • ADR-002: Feature Services Architecture
  • ADR-003: Typed Response Objects
  • ADR-004: PSR-14 Event System
  • ADR-005: TYPO3 Caching Framework Integration
  • ADR-006: Option Objects vs Arrays
  • ADR-007: Multi-Provider Strategy
  • ADR-008: Error Handling Strategy
  • ADR-009: Streaming Implementation
  • ADR-010: Tool/Function Calling Design
  • ADR-011: Object-Only Options API
  • ADR-012: API key encryption at application level
  • ADR-013: Three-level configuration architecture (Provider-Model-Configuration)
  • ADR-014: AI-Powered Wizard System
  • ADR-015: Type-Safe Domain Models via PHP 8.1+ Enums & Value Objects
  • ADR-016: Thinking/Reasoning Block Extraction
  • ADR-017: Safe Type Casting via SafeCastTrait
  • ADR-018: Multi-Provider Model Discovery
  • ADR-019: Internationalization Strategy
  • ADR-020: Backend Output Format Rendering
  • ADR-021: Provider Fallback Chain
  • ADR-022: Attribute-Based Provider Registration
  • ADR-023: Native Backend Capability Permissions
  • ADR-024: Dashboard Widgets
  • ADR-025: Per-User AI Budgets
  • ADR-026: Provider Middleware Pipeline
  • ADR-027: Split TaskController
  • ADR-028: Public services policy in Configuration/Services.yaml
• Changelog

Introduction 

// Use database configurations for consistent settings
$config = $configRepository->findByIdentifier('blog-summarizer');
$adapter = $adapterRegistry->createAdapterFromModel($config->getModel());
$response = $adapter->chatCompletion($messages, $config->toOptions());

// Or use inline provider selection
$response = $llmManager->chat($messages, ['provider' => 'openai']);
$response = $llmManager->chat($messages, ['provider' => 'claude']);

foreach ($llmManager->streamChat($messages) as $chunk) {
    echo $chunk;
    flush();
}

$response = $llmManager->chatWithTools($messages, $tools);
if ($response->hasToolCalls()) {
    // Process tool calls
}

Installation 

composer require netresearch/nr-llm

vendor/bin/typo3 extension:setup nr_llm

use TYPO3\CMS\Core\Cache\Backend\RedisBackend;

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nrllm_responses']
    ['backend'] = RedisBackend::class;

Administration 

This guide walks you through managing AI providers, models, configurations, and tasks in the TYPO3 backend. It also covers the AI-powered wizards that automate most of the setup.

The LLM backend module 

All AI management happens in Admin Tools > LLM. The dashboard shows your current setup status, quick links to each section, and AI wizard buttons.

The module has five sections accessible from the left-hand navigation:

• Dashboard — overview and wizards
• Providers — API connections
• Models — available LLM models
• Configurations — use-case presets
• Tasks — one-shot prompt templates

• Managing providers
  • Adding a provider
  • Testing a connection
  • Editing and deleting providers
• Managing models
  • Adding a model manually
  • Fetching models from a provider
• Managing configurations
  • Adding a configuration manually
  • Testing a configuration
  • Editing configurations
• Managing tasks
  • Adding a task manually
  • Executing a task
• AI-powered wizards
  • Setup wizard
  • Configuration wizard
  • Task wizard
  • Model discovery
  • Recommended workflow
• Per-user AI budgets
  • What a budget caps
  • Creating a budget
  • How the check runs
  • Budgets vs. configuration limits

Managing providers 

Providers represent connections to AI services. Each provider stores an API endpoint, encrypted credentials, and adapter-specific settings.

Testing a connection 

After saving a provider, click Test Connection to verify the setup. The test makes an HTTP request to the provider API and reports:

• Connection status (success or failure).
• Available models (if the provider supports listing).
• Error details on failure.

Managing models 

Models represent specific LLM models available through a provider (e.g., gpt-5, claude-sonnet-4-6, llama-3).

Managing configurations 

Configurations define use-case-specific presets that combine a model with a system prompt and generation parameters. Extension developers reference configurations by identifier in their code.

Testing a configuration 

Click Test Configuration on any row. The test sends a short prompt to the model and shows the response, model ID, and token usage.

Managing tasks 

Tasks are one-shot prompt templates that combine a configuration with a specific user prompt. They provide reusable AI operations that editors or extensions can execute with a single call.

Executing a task 

Click Run on any task to open the execution form. It shows the configuration, model, parameters, input field, and prompt template.

Example tasks:

• Summarize content — condense long articles.
• Generate meta descriptions — SEO optimization.
• Translate text — one-click translation.
• Extract keywords — pull key terms from content.

Tip

Use the Task wizard to generate a complete task (including a new configuration) from a plain-language description.

AI-powered wizards 

The extension includes AI-powered wizards that use your existing LLM providers to generate configurations and tasks automatically. This reduces manual setup to a minimum.

Setup wizard 

The setup wizard guides first-time configuration in five steps:

1. Connect — enter your provider endpoint and API key.
2. Verify — test the connection.
3. Models — fetch available models from the provider API.
4. Configure — create an initial configuration with system prompt and parameters.
5. Save — run a test prompt to confirm everything works.

Access it from the Dashboard when no providers are configured, or via the setup wizard link at any time.

Configuration wizard 

The configuration wizard generates a complete LLM configuration using AI. Instead of filling in each field manually, describe your use case in plain language and the wizard generates everything.

1. Navigate to Admin Tools > LLM > Configurations.
2. Click Create with AI.
3. Describe your use case (e.g., "summarize blog posts in three sentences").
4. The wizard generates: identifier, name, system prompt, temperature, and all other parameters.
5. Review and click Save.

Task wizard 

The task wizard creates a complete task setup — a task and a dedicated configuration — in one step.

1. Navigate to Admin Tools > LLM > Tasks.
2. Click Create with AI.
3. Describe the task (e.g., "extract the five most important keywords from an article").
4. The wizard generates: a task with prompt template, a configuration with system prompt and parameters, and a model recommendation.
5. Review and click Save.

Per-user AI budgets 

The tx_nrllm_user_budget table caps per-backend-user AI spend independently of the per-configuration daily limits on tx_nrllm_configuration. A user request must clear BOTH layers: any limit on the preset they chose AND any limit on their personal budget record.

Configuration reference 

This page is the field reference for all configurable entities. For step-by-step setup instructions, see the Administration guide.

Provider fields 

Providers represent API connections with credentials.

Model fields 

Models represent specific LLM models available through a provider.

Configuration field reference 

Configurations define use-case presets with model selection and parameters.

Task fields 

Tasks combine a configuration with a user prompt template for one-shot AI operations.

Each task references an LLM configuration and adds a user prompt template. The same configuration can power multiple tasks with different prompts.

Settings 

plugin.tx_nrllm {
    settings {
        # Default provider (openai, claude, gemini)
        defaultProvider = openai
        # Enable response caching
        enableCaching = 1
        # Cache lifetime in seconds
        cacheLifetime = 3600

        providers {
            openai {
                enabled = 1
                defaultModel = gpt-4o
                temperature = 0.7
                maxTokens = 4096
            }
            claude {
                enabled = 1
                defaultModel = claude-sonnet-4-20250514
                temperature = 0.7
                maxTokens = 4096
            }
            gemini {
                enabled = 1
                defaultModel = gemini-2.0-flash
                temperature = 0.7
                maxTokens = 4096
            }
        }
    }
}

# TYPO3 encryption key (used for API key encryption)
TYPO3_CONF_VARS__SYS__encryptionKey=your-key

# Optional: Override default timeout
TYPO3_NR_LLM_DEFAULT_TIMEOUT=60

use TYPO3\CMS\Core\Utility\GeneralUtility;

$sanitizedInput = GeneralUtility::removeXSS(
    $userInput
);

$response = $adapter->chatCompletion([
    ['role' => 'user', 'content' => $sanitizedInput],
]);

$response = $adapter->chatCompletion([
    ['role' => 'user', 'content' => $prompt],
]);

$safeOutput = htmlspecialchars(
    $response->content, ENT_QUOTES, 'UTF-8'
);

use Psr\Log\LogLevel;
use TYPO3\CMS\Core\Log\Writer\FileWriter;

$GLOBALS['TYPO3_CONF_VARS']['LOG']
    ['Netresearch']['NrLlm'] = [
    'writerConfiguration' => [
        LogLevel::DEBUG => [
            FileWriter::class => [
                'logFileInfix' => 'nr_llm',
            ],
        ],
    ],
];

use TYPO3\CMS\Core\Cache\Backend\RedisBackend;

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']
    ['cacheConfigurations']['nrllm_responses']
    ['backend'] = RedisBackend::class;

vendor/bin/typo3 cache:flush --group=nrllm

Developer guide 

This guide covers technical details for developers integrating the LLM extension into their TYPO3 projects.

┌─────────────────────────────────────────┐
│         Your Application Code           │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         Feature Services                │
│  (Completion, Embedding, Vision, etc.)  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         LlmServiceManager               │
│    (Provider selection & routing)       │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│           Providers                     │
│    (OpenAI, Claude, Gemini, etc.)       │
└─────────────────────────────────────────┘

use Netresearch\NrLlm\Service\LlmServiceManager;
use Netresearch\NrLlm\Service\Feature\CompletionService;
use Netresearch\NrLlm\Service\Feature\EmbeddingService;
use Netresearch\NrLlm\Service\Feature\VisionService;
use Netresearch\NrLlm\Service\Feature\TranslationService;

class MyController
{
    public function __construct(
        private readonly LlmServiceManager $llmManager,
        private readonly CompletionService $completionService,
        private readonly EmbeddingService $embeddingService,
        private readonly VisionService $visionService,
        private readonly TranslationService $translationService,
    ) {}
}

$messages = [
    ['role' => 'system', 'content' => 'You are a helpful assistant.'],
    ['role' => 'user', 'content' => 'What is TYPO3?'],
];

$response = $this->llmManager->chat($messages);

// Response properties
$content = $response->content;           // string
$model = $response->model;               // string
$finishReason = $response->finishReason; // string
$usage = $response->usage;               // UsageStatistics

use Netresearch\NrLlm\Service\Option\ChatOptions;

// Using ChatOptions object
$options = ChatOptions::creative()
    ->withMaxTokens(2000)
    ->withSystemPrompt('You are a creative writer.');

$response = $this->llmManager->chat($messages, $options);

// Or using array
$response = $this->llmManager->chat($messages, [
    'provider' => 'claude',
    'model' => 'claude-sonnet-4-6',
    'temperature' => 1.2,
    'max_tokens' => 2000,
]);

$response = $this->llmManager->complete('Explain recursion in programming');

// Single text
$response = $this->llmManager->embed('Hello, world!');
$vector = $response->getVector(); // array<float>

// Multiple texts
$response = $this->llmManager->embed(['Text 1', 'Text 2', 'Text 3']);
$vectors = $response->embeddings; // array<array<float>>

use Netresearch\NrLlm\Provider\Exception\ProviderException;
use Netresearch\NrLlm\Provider\Exception\ProviderConfigurationException;
use Netresearch\NrLlm\Provider\Exception\ProviderConnectionException;
use Netresearch\NrLlm\Provider\Exception\ProviderResponseException;
use Netresearch\NrLlm\Provider\Exception\UnsupportedFeatureException;
use Netresearch\NrLlm\Exception\InvalidArgumentException;

try {
    $response = $this->llmManager->chat($messages);
} catch (ProviderConfigurationException $e) {
    // Invalid or missing provider configuration
} catch (ProviderConnectionException $e) {
    // Connection to provider failed
} catch (ProviderResponseException $e) {
    // Provider returned an error response
} catch (UnsupportedFeatureException $e) {
    // Requested feature not supported by provider
} catch (ProviderException $e) {
    // General provider error
} catch (InvalidArgumentException $e) {
    // Invalid parameters
}

Streaming support 

Streaming allows you to receive LLM responses incrementally as they are generated, rather than waiting for the complete response. This improves perceived performance for long responses.

$stream = $this->llmManager->streamChat($messages);

foreach ($stream as $chunk) {
    echo $chunk;
    ob_flush();
    flush();
}

$provider = $this->llmManager->getProvider('openai');
if ($provider instanceof StreamingCapableInterface) {
    // Provider supports streaming
}

Tool/function calling 

Tool calling (also known as function calling) allows the LLM to request execution of functions you define. The model decides when to call a tool based on the conversation context.

$tools = [
    [
        'type' => 'function',
        'function' => [
            'name' => 'get_weather',
            'description' => 'Get current weather for a location',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'location' => [
                        'type' => 'string',
                        'description' => 'City name',
                    ],
                    'unit' => [
                        'type' => 'string',
                        'enum' => ['celsius', 'fahrenheit'],
                    ],
                ],
                'required' => ['location'],
            ],
        ],
    ],
];

$response = $this->llmManager->chatWithTools($messages, $tools);

if ($response->hasToolCalls()) {
    foreach ($response->toolCalls as $toolCall) {
        $functionName = $toolCall['function']['name'];
        $arguments = json_decode($toolCall['function']['arguments'], true);

        // Execute your function
        $result = match ($functionName) {
            'get_weather' => $this->getWeather($arguments['location']),
            default => throw new \RuntimeException("Unknown function: {$functionName}"),
        };

        // Continue conversation with result
        $messages[] = [
            'role' => 'assistant',
            'content' => null,
            'tool_calls' => [$toolCall],
        ];
        $messages[] = [
            'role' => 'tool',
            'tool_call_id' => $toolCall['id'],
            'content' => json_encode($result),
        ];

        $response = $this->llmManager->chat($messages);
    }
}

Creating custom providers 

Implement a custom provider by extending AbstractProvider:

<?php

namespace MyVendor\MyExtension\Provider;

use Netresearch\NrLlm\Provider\AbstractProvider;
use Netresearch\NrLlm\Provider\Contract\ProviderInterface;

class MyCustomProvider extends AbstractProvider implements ProviderInterface
{
    protected string $baseUrl = 'https://api.example.com/v1';

    public function getName(): string
    {
        return 'My Custom Provider';
    }

    public function getIdentifier(): string
    {
        return 'custom';
    }

    public function isConfigured(): bool
    {
        return !empty($this->apiKey);
    }

    public function chatCompletion(array $messages, array $options = []): CompletionResponse
    {
        $payload = $this->buildChatPayload($messages, $options);
        $response = $this->sendRequest('chat', $payload);

        return new CompletionResponse(
            content: $response['choices'][0]['message']['content'],
            model: $response['model'],
            usage: $this->parseUsage($response['usage']),
            finishReason: $response['choices'][0]['finish_reason'],
            provider: $this->getIdentifier(),
        );
    }

    // Implement other required methods...
}

MyVendor\MyExtension\Provider\MyCustomProvider:
  arguments:
    $httpClient: '@Psr\Http\Client\ClientInterface'
    $requestFactory: '@Psr\Http\Message\RequestFactoryInterface'
    $streamFactory: '@Psr\Http\Message\StreamFactoryInterface'
    $logger: '@Psr\Log\LoggerInterface'
  tags:
    - name: nr_llm.provider
      priority: 50

Registering a provider 

Two mechanisms pick up your provider class. Use the attribute when you can.

use Netresearch\NrLlm\Attribute\AsLlmProvider;
use Netresearch\NrLlm\Provider\AbstractProvider;

#[AsLlmProvider(priority: 85)]
final class MyProvider extends AbstractProvider
{
    public function getIdentifier(): string
    {
        return 'my-provider';
    }

    public function getName(): string
    {
        return 'My LLM Service';
    }

    // ... chatCompletion(), embeddings(), supportsFeature()
}

services:
  Acme\MyExt\Provider\AcmeProvider:
    public: true
    tags:
      - name: nr_llm.provider
        priority: 85

Fallback chain 

A LlmConfiguration can carry an ordered list of other configuration identifiers to fall back to on retryable provider failures. The lookup happens transparently inside NetresearchNrLlmServiceLlmServiceManager::chatWithConfiguration() and completeWithConfiguration(). Callers see a regular completion response or a typed exception; they never need to reach into retry mechanics.

{"configurationIdentifiers": ["claude-sonnet", "ollama-local"]}

use Netresearch\NrLlm\Domain\DTO\FallbackChain;

$chain = (new FallbackChain())
    ->withLink('claude-sonnet')
    ->withLink('ollama-local');

$configuration->setFallbackChainDTO($chain);

BE group permission checks 

Every ModelCapability enum value is registered as a native TYPO3 customPermOptions entry under the nrllm namespace. Administrators see a checkbox per capability (chat, completion, embeddings, vision, streaming, tools, json_mode, audio) on the Backend Users > Access Options tab when editing a BE group. Consumer code asks the NetresearchNrLlmServiceCapabilityPermissionService whether the capability is allowed for the current user.

use Netresearch\NrLlm\Domain\Enum\ModelCapability;
use Netresearch\NrLlm\Exception\AccessDeniedException;
use Netresearch\NrLlm\Service\CapabilityPermissionService;

final class Caption
{
    public function __construct(
        private readonly CapabilityPermissionService $permissions,
    ) {}

    public function describe(string $imageUrl): string
    {
        if (!$this->permissions->isAllowed(ModelCapability::VISION)) {
            throw new AccessDeniedException(
                'Vision capability not permitted for this user',
                1745712100,
            );
        }
        // ... dispatch to VisionService ...
    }
}

use Netresearch\NrLlm\Domain\Enum\ModelCapability;
use Netresearch\NrLlm\Service\CapabilityPermissionService;

$permString = CapabilityPermissionService::permissionString(
    ModelCapability::TOOLS,
);
// => "nrllm:capability_tools"

Build your extension on nr-llm 

This guide walks you through adding AI capabilities to a TYPO3 extension using nr-llm as a dependency. By the end, your extension will have working AI features without any provider-specific code.

composer require netresearch/nr-llm

'constraints' => [
    'depends' => [
        'typo3' => '13.4.0-14.99.99',
        'nr_llm' => '0.4.0-0.99.99',
    ],
],

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Netresearch\NrLlm\Service\LlmServiceManagerInterface;

final readonly class MyAiService
{
    public function __construct(
        private LlmServiceManagerInterface $llm,
    ) {}

    public function summarize(string $text): string
    {
        $response = $this->llm->complete(
            "Summarize the following text in 2-3 sentences:\n\n" . $text,
        );

        return $response->content;
    }
}

use Netresearch\NrLlm\Service\Feature\TranslationService;

final readonly class ContentTranslator
{
    public function __construct(
        private TranslationService $translator,
    ) {}

    public function translateToGerman(string $text): string
    {
        $result = $this->translator->translate($text, 'de');
        return $result->translation;
    }
}

use Netresearch\NrLlm\Service\Feature\VisionService;

final readonly class ImageMetadataGenerator
{
    public function __construct(
        private VisionService $vision,
    ) {}

    public function generateAltText(string $imageUrl): string
    {
        return $this->vision->generateAltText($imageUrl);
    }
}

use Netresearch\NrLlm\Service\Feature\EmbeddingService;

final readonly class ContentRecommender
{
    public function __construct(
        private EmbeddingService $embeddings,
    ) {}

    /**
     * @param list<array{id: int, text: string, vector: list<float>}> $candidates
     * @return list<int> Top 5 most similar content IDs
     */
    public function findSimilar(string $query, array $candidates): array
    {
        $queryVector = $this->embeddings->embed($query);
        $results = $this->embeddings->findMostSimilar(
            $queryVector,
            array_column($candidates, 'vector'),
            topK: 5,
        );

        return array_map(
            fn(int $index) => $candidates[$index]['id'],
            array_keys($results),
        );
    }
}

use Netresearch\NrLlm\Provider\Exception\ProviderConfigurationException;
use Netresearch\NrLlm\Provider\Exception\ProviderConnectionException;
use Netresearch\NrLlm\Provider\Exception\ProviderResponseException;

try {
    $response = $this->llm->complete($prompt);
} catch (ProviderConfigurationException) {
    // No provider configured — guide the admin
    return 'AI features require LLM configuration. '
         . 'An administrator can set this up in Admin Tools > LLM.';
} catch (ProviderConnectionException) {
    // Network issue — suggest retry
    return 'Could not reach the AI provider. Please try again.';
} catch (ProviderResponseException $e) {
    // Provider returned an error (rate limit, invalid input, etc.)
    $this->logger->warning('LLM provider error', ['exception' => $e]);
    return 'The AI service returned an error. Please try again later.';
}

use Netresearch\NrLlm\Domain\Repository\LlmConfigurationRepository;
use Netresearch\NrLlm\Service\LlmServiceManagerInterface;

final readonly class BlogSummarizer
{
    public function __construct(
        private LlmConfigurationRepository $configRepo,
        private LlmServiceManagerInterface $llm,
    ) {}

    public function summarize(string $article): string
    {
        // Uses the "blog-summarizer" configuration created by the admin
        // (specific model, temperature, system prompt, etc.)
        $config = $this->configRepo->findByIdentifier('blog-summarizer');

        $response = $this->llm->chat(
            [['role' => 'user', 'content' => "Summarize:\n\n" . $article]],
            $config->toChatOptions(),
        );

        return $response->content;
    }
}

use Netresearch\NrLlm\Domain\Model\CompletionResponse;
use Netresearch\NrLlm\Domain\Model\UsageStatistics;
use Netresearch\NrLlm\Service\LlmServiceManagerInterface;
use PHPUnit\Framework\TestCase;

final class MyAiServiceTest extends TestCase
{
    public function testSummarizeReturnsCompletionContent(): void
    {
        $llm = $this->createStub(LlmServiceManagerInterface::class);
        $llm->method('complete')->willReturn(
            new CompletionResponse(
                content: 'A short summary.',
                model: 'gpt-5.3-instant',
                usage: new UsageStatistics(50, 20, 70),
                finishReason: 'stop',
                provider: 'openai',
            ),
        );

        $service = new MyAiService($llm);
        self::assertSame('A short summary.', $service->summarize('Long text...'));
    }
}

Feature services 

High-level AI services for TYPO3 with prompt engineering and response parsing.

┌─────────────────────────────────────────────────────────┐
│            Consuming Extensions                          │
│  (rte-ckeditor-image, textdb, contexts)                 │
└──────────────────────┬──────────────────────────────────┘
                       │ Dependency Injection
┌──────────────────────▼──────────────────────────────────┐
│              Feature Services                            │
│  - CompletionService                                     │
│  - VisionService                                         │
│  - EmbeddingService                                      │
│  - TranslationService                                    │
│  - PromptTemplateService                                 │
└──────────────────────┬──────────────────────────────────┘
                       │ LLM abstraction
┌──────────────────────▼──────────────────────────────────┐
│              LlmServiceManager                           │
│  (Provider routing, caching, rate limiting)             │
└──────────────────────┬──────────────────────────────────┘
                       │ Provider calls
┌──────────────────────▼──────────────────────────────────┐
│            Provider Implementations                      │
│  (OpenAI, Anthropic, Gemini, etc.)                      │
└─────────────────────────────────────────────────────────┘

use Netresearch\NrLlm\Service\Feature\CompletionService;

$completion = $completionService->complete(
    prompt: 'Explain TYPO3 in simple terms',
    options: [
        'temperature' => 0.3,
        'max_tokens' => 200,
        'response_format' => 'markdown',
    ]
);

echo $completion->text;

// Standard completion
$response = $completionService->complete($prompt);

// JSON output
$data = $completionService->completeJson('List 5 colors as a JSON array');

// Markdown output
$markdown = $completionService->completeMarkdown('Write docs for this API');

// Factual (low creativity, high consistency)
$response = $completionService->completeFactual('What is the capital of France?');

// Creative (high creativity)
$response = $completionService->completeCreative('Write a haiku about coding');

use Netresearch\NrLlm\Service\Feature\VisionService;

// Single image
$altText = $visionService->generateAltText(
    'https://example.com/image.jpg'
);

// Batch processing
$altTexts = $visionService->generateAltText([
    'https://example.com/img1.jpg',
    'https://example.com/img2.jpg',
]);

// Generate WCAG-compliant alt text
$altText = $visionService->generateAltText('https://example.com/image.jpg');

// Generate SEO-optimized title
$title = $visionService->generateTitle('/path/to/local/image.png');

// Generate detailed description
$description = $visionService->generateDescription($imageUrl);

// Custom analysis
$analysis = $visionService->analyzeImage(
    $imageUrl,
    'What colors are prominent in this image?'
);

use Netresearch\NrLlm\Service\Feature\EmbeddingService;

// Generate embedding
$vector = $embeddingService->embed('Search query text');

// Find similar
$similar = $embeddingService->findMostSimilar(
    queryVector: $vector,
    candidateVectors: $allVectors,
    topK: 5
);

// Generate embedding (cached automatically)
$vector = $embeddingService->embed('Some text');

// Full response with metadata
$response = $embeddingService->embedFull('Some text');

// Batch embedding
$vectors = $embeddingService->embedBatch(['Text 1', 'Text 2']);

// Calculate cosine similarity
$similarity = $embeddingService->cosineSimilarity($vectorA, $vectorB);

// Find most similar vectors
$results = $embeddingService->findMostSimilar(
    $queryVector,
    $candidateVectors,
    topK: 5
);

// Normalize a vector
$normalized = $embeddingService->normalize($vector);

use Netresearch\NrLlm\Service\Feature\TranslationService;

$result = $translationService->translate(
    text: 'The TYPO3 extension is great',
    targetLanguage: 'de',
    options: [
        'glossary' => ['TYPO3' => 'TYPO3'],
        'formality' => 'formal',
        'domain' => 'technical',
    ]
);

echo $result->translation;
echo $result->confidence;

// Basic translation
$result = $translationService->translate('Hello, world!', 'de');

// With options
$result = $translationService->translate(
    $text,
    targetLanguage: 'de',
    sourceLanguage: 'en',
    options: [
        'formality' => 'formal',
        'domain' => 'technical',
        'glossary' => [
            'TYPO3' => 'TYPO3',
            'extension' => 'Erweiterung',
        ],
        'preserve_formatting' => true,
    ]
);

// TranslationResult properties
$translation = $result->translation;
$sourceLanguage = $result->sourceLanguage;
$confidence = $result->confidence;

// Batch translation
$results = $translationService->translateBatch($texts, 'de');

// Language detection
$language = $translationService->detectLanguage($text);

// Quality scoring
$score = $translationService->scoreTranslationQuality($source, $translation, 'de');

use Netresearch\NrLlm\Service\PromptTemplateService;

$prompt = $promptService->render(
    identifier: 'vision.alt_text',
    variables: ['image_url' => 'https://example.com/img.jpg']
);

// Use with completion service
$response = $completionService->complete(
    prompt: $prompt->getUserPrompt(),
    options: [
        'system_prompt' => $prompt->getSystemPrompt(),
        'temperature' => $prompt->getTemperature(),
    ]
);

services:
  Your\Extension\Service\YourService:
    public: true
    arguments:
      $visionService: '@Netresearch\NrLlm\Service\Feature\VisionService'
      $translationService: '@Netresearch\NrLlm\Service\Feature\TranslationService'
      $completionService: '@Netresearch\NrLlm\Service\Feature\CompletionService'
      $embeddingService: '@Netresearch\NrLlm\Service\Feature\EmbeddingService'

<?php

namespace Your\Extension\Service;

use Netresearch\NrLlm\Service\Feature\VisionService;

class YourService
{
    public function __construct(
        private readonly VisionService $visionService
    ) {}

    public function enhanceImage(string $imageUrl): array
    {
        return [
            'alt' => $this->visionService->generateAltText($imageUrl),
            'title' => $this->visionService->generateTitle($imageUrl),
            'description' => $this->visionService->generateDescription($imageUrl),
        ];
    }
}

# Run all unit tests
Build/Scripts/runTests.sh -s unit

# Alternative: Via Composer script
composer ci:test:php:unit

use Netresearch\NrLlm\Service\Feature\VisionService;
use PHPUnit\Framework\TestCase;

class YourServiceTest extends TestCase
{
    public function testImageEnhancement(): void
    {
        $visionMock = $this->createMock(VisionService::class);
        $visionMock->method('generateAltText')
            ->willReturn('Test alt text');

        $service = new YourService($visionMock);
        $result = $service->enhanceImage('test.jpg');

        $this->assertEquals('Test alt text', $result['alt']);
    }
}

// Good: Single request for multiple images
$altTexts = $visionService->generateAltText($imageUrls);

// Bad: Multiple individual requests
foreach ($imageUrls as $url) {
    $altText = $visionService->generateAltText($url);
}

INSERT INTO tx_nrllm_prompts (
    identifier,
    title,
    feature,
    system_prompt,
    user_prompt_template,
    temperature,
    max_tokens,
    is_active
) VALUES (
    'custom.vision.alt_text',
    'Custom Alt Text',
    'vision',
    'Custom system prompt...',
    'Custom user prompt with {{image_url}}',
    0.5,
    100,
    1
);

$result = $completionService->complete(
    prompt: 'Generate text',
    options: [
        'temperature' => 0.7,
        'max_tokens' => 1000,
        'top_p' => 0.9,
        'frequency_penalty' => 0.0,
        'presence_penalty' => 0.0,
        'response_format' => 'json',
        'system_prompt' => 'Custom instructions',
        'stop_sequences' => ['\n\n', 'END'],
    ]
);

use Netresearch\NrLlm\Service\Feature\VisionService;

class ImageAiService
{
    public function __construct(
        private readonly VisionService $visionService
    ) {}

    public function enhanceImage(FileReference $file): array
    {
        $url = $file->getPublicUrl();
        return [
            'alt' => $this->visionService->generateAltText($url),
            'title' => $this->visionService->generateTitle($url),
        ];
    }
}

use Netresearch\NrLlm\Service\Feature\TranslationService;
use Netresearch\NrLlm\Service\Feature\EmbeddingService;

class AiTranslationService
{
    public function __construct(
        private readonly TranslationService $translationService,
        private readonly EmbeddingService $embeddingService
    ) {}

    public function suggestTranslation(string $text, string $lang): array
    {
        return [
            'translation' => $this->translationService->translate($text, $lang),
            'similar' => $this->findSimilar($text),
        ];
    }
}

use Netresearch\NrLlm\Service\Feature\CompletionService;

class RuleGeneratorService
{
    public function __construct(
        private readonly CompletionService $completionService
    ) {}

    public function generateRule(string $description): ?array
    {
        return $this->completionService->completeJson(
            "Generate TYPO3 context rule: $description",
            ['temperature' => 0.2]
        );
    }
}

nr-llm/
├── Classes/
│   ├── Domain/
│   │   └── Model/
│   │       ├── CompletionResponse.php
│   │       ├── VisionResponse.php
│   │       ├── TranslationResult.php
│   │       ├── EmbeddingResponse.php
│   │       ├── UsageStatistics.php
│   │       ├── PromptTemplate.php
│   │       └── RenderedPrompt.php
│   ├── Service/
│   │   ├── Feature/
│   │   │   ├── CompletionService.php
│   │   │   ├── VisionService.php
│   │   │   ├── EmbeddingService.php
│   │   │   └── TranslationService.php
│   │   └── PromptTemplateService.php
│   └── Exception/
│       ├── InvalidArgumentException.php
│       └── PromptTemplateNotFoundException.php
├── Configuration/
│   └── Services.yaml
├── Resources/
│   └── Private/
│       └── Data/
│           └── DefaultPrompts.php
└── Tests/
    └── Unit/
        └── Service/
            └── Feature/
                ├── CompletionServiceTest.php
                ├── VisionServiceTest.php
                └── EmbeddingServiceTest.php

API reference 

Complete API reference for the TYPO3 LLM extension.

LlmServiceManager 

The central service for all LLM operations.

class LlmServiceManager

Fully qualified name

\Netresearch\NrLlm\Service\LlmServiceManager

Orchestrates LLM providers and provides unified API access.

chat ( array $messages, ?ChatOptions $options = null) : CompletionResponse

Execute a chat completion request.

param array $messages

Array of message objects with 'role' and 'content' keys

param ChatOptions|null $options

Optional config

Message Format:

Chat message format

$messages = [
    ['role' => 'system', 'content' => '...'],
    ['role' => 'user', 'content' => 'Hello!'],
    ['role' => 'assistant', 'content' => 'Hi!'],
    ['role' => 'user', 'content' => 'How are you?'],
];

Copied!

Returns

CompletionResponse

complete ( string $prompt, ?ChatOptions $options = null) : CompletionResponse

Simple completion from a single prompt.

param string $prompt

The prompt text

param ChatOptions|null $options

Optional config

Returns

CompletionResponse

embed ( string|array $input, ?EmbeddingOptions $options = null) : EmbeddingResponse

Generate embeddings for text.

param string|array $input

Single text or array of texts

param EmbeddingOptions|null $options

Optional configuration

Returns

EmbeddingResponse

vision ( array $content, ?VisionOptions $options = null) : VisionResponse

Analyze an image with vision capabilities.

param array $content

Array of content parts (text and image_url entries)

param VisionOptions|null $options

Optional configuration

Returns

VisionResponse

streamChat ( array $messages, ?ChatOptions $options = null) : Generator

Stream a chat completion response.

param array $messages

Array of message objects

param ChatOptions|null $options

Optional config

Returns

Generator yielding string chunks

chatWithTools ( array $messages, array $tools, ?ToolOptions $options = null) : CompletionResponse

Chat with tool/function calling capability.

param array $messages

Array of message objects

param array $tools

Array of tool definitions

param ToolOptions|null $options

Optional config

Returns

CompletionResponse with tool calls

getProvider ( ?string $identifier = null) : ProviderInterface

Get a specific provider by identifier.

param string|null $identifier

Provider identifier (openai, claude, gemini); null for default

throws

ProviderException

Returns

ProviderInterface

getAvailableProviders ( ) : array

Get all configured and available providers.

Returns

array<string, ProviderInterface>

CompletionService 

class CompletionService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\CompletionService

High-level text completion with format control.

complete ( string $prompt, ?ChatOptions $options = null) : CompletionResponse

Standard text completion.

param string $prompt

The prompt text

param ?ChatOptions $options

Optional configuration

Returns

CompletionResponse

completeJson ( string $prompt, ?ChatOptions $options = null) : array

Completion with JSON output parsing.

param string $prompt

The prompt text

param ?ChatOptions $options

Optional configuration

Returns

array Parsed JSON data

completeMarkdown ( string $prompt, ?ChatOptions $options = null) : string

Completion with markdown formatting.

param string $prompt

The prompt text

param ?ChatOptions $options

Optional configuration

Returns

string Markdown formatted text

completeFactual ( string $prompt, ?ChatOptions $options = null) : CompletionResponse

Low-creativity completion for factual responses.

param string $prompt

The prompt text

param ?ChatOptions $options

Optional configuration (temperature defaults to 0.1)

Returns

CompletionResponse

completeCreative ( string $prompt, ?ChatOptions $options = null) : CompletionResponse

High-creativity completion for creative content.

param string $prompt

The prompt text

param ?ChatOptions $options

Optional configuration (temperature defaults to 1.2)

Returns

CompletionResponse

EmbeddingService 

class EmbeddingService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\EmbeddingService

Text-to-vector conversion with caching and similarity operations.

embed ( string $text, ?EmbeddingOptions $options = null) : array

Generate embedding vector for text (cached).

param string $text

The text to embed

param ?EmbeddingOptions $options

Optional config

Returns

array<float> Vector representation

embedFull ( string $text, ?EmbeddingOptions $options = null) : EmbeddingResponse

Generate embedding with full response metadata.

param string $text

The text to embed

param ?EmbeddingOptions $options

Optional config

Returns

EmbeddingResponse

embedBatch ( array $texts, ?EmbeddingOptions $options = null) : array

Generate embeddings for multiple texts.

param array $texts

Array of texts

param ?EmbeddingOptions $options

Optional config

Returns

array<array<float>> Array of vectors

cosineSimilarity ( array $a, array $b) : float

Calculate cosine similarity between two vectors.

param array $a

First vector

param array $b

Second vector

Returns

float Similarity score (-1 to 1)

findMostSimilar ( array $queryVector, array $candidates, int $topK = 5) : array

Find most similar vectors from candidates.

param array $queryVector

The query vector

param array $candidates

Array of candidate vectors

param int $topK

Number of results to return

Returns

array Sorted by similarity (highest first)

pairwiseSimilarities ( array $vectors) : array

Calculate pairwise similarities between all vectors.

Returns a 2D matrix where each cell [i][j] contains the cosine similarity between vectors i and j. Diagonal values are always 1.0.

param array $vectors

Array of embedding vectors

Returns

array 2D array of similarity scores

normalize ( array $vector) : array

Normalize a vector to unit length.

param array $vector

The vector to normalize

Returns

array Normalized vector

VisionService 

class VisionService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\VisionService

Image analysis with specialized prompts.

generateAltText(string|array $imageUrl, ?VisionOptions $options = null): string|array ( )

Generate WCAG-compliant alt text.

Optimized for screen readers and WCAG 2.1 Level AA compliance. Output is concise (under 125 characters) and focuses on essential information.

param string|array $imageUrl

URL, local path, or array of URLs for batch processing

param VisionOptions|null $options

Vision options (defaults: maxTokens=100, temperature=0.5)

Returns

string|array Alt text or array of alt texts for batch input

generateTitle(string|array $imageUrl, ?VisionOptions $options = null): string|array ( )

Generate SEO-optimized image title.

Creates compelling, keyword-rich titles under 60 characters for improved search rankings.

param string|array $imageUrl

URL, local path, or array of URLs for batch processing

param VisionOptions|null $options

Vision options (defaults: maxTokens=50, temperature=0.7)

Returns

string|array Title or array of titles for batch input

generateDescription(string|array $imageUrl, ?VisionOptions $options = null): string|array ( )

Generate detailed image description.

Provides comprehensive analysis including subjects, setting, colors, mood, composition, and notable details.

param string|array $imageUrl

URL, local path, or array of URLs for batch processing

param VisionOptions|null $options

Vision options (defaults: maxTokens=500, temperature=0.7)

Returns

string|array Description or array of descriptions for batch input

analyzeImage(string|array $imageUrl, string $customPrompt, ?VisionOptions $options = null): string|array ( )

Custom image analysis with specific prompt.

param string|array $imageUrl

URL, local path, or array of URLs for batch processing

param string $customPrompt

Custom analysis prompt

param VisionOptions|null $options

Vision options

Returns

string|array Analysis result or array of results for batch input

analyzeImageFull ( string $imageUrl, string $prompt, ?VisionOptions $options = null) : VisionResponse

Full image analysis returning complete response with usage statistics.

Returns a VisionResponse with metadata and usage data, unlike the other methods which return plain text.

param string $imageUrl

Image URL or base64 data URI

param string $prompt

Analysis prompt

param VisionOptions|null $options

Vision options

throws

InvalidArgumentException If image URL is invalid

Returns

VisionResponse Complete response with usage data

TranslationService 

class TranslationService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\TranslationService

Language translation with quality control.

translate ( string $text, string $targetLanguage, ?string $sourceLanguage = null, ?TranslationOptions $options = null) : TranslationResult

Translate text to target language.

param string $text

Text to translate

param string $targetLanguage

Target language code (e.g., 'de', 'fr')

param string|null $sourceLanguage

Source language code (auto-detected if null)

param TranslationOptions|null $options

Translation options

TranslationOptions fields:

• formality: 'formal', 'informal', 'default'
• domain: 'technical', 'legal', 'medical', 'marketing', 'general'
• glossary: array of term translations
• preserve_formatting: bool

Returns

TranslationResult

translateBatch ( array $texts, string $targetLanguage, ?string $sourceLanguage = null, ?TranslationOptions $options = null) : array

Translate multiple texts.

param array $texts

Array of texts

param string $targetLanguage

Target language code

param string|null $sourceLanguage

Source language code (auto-detected if null)

param TranslationOptions|null $options

Translation options

Returns

array<TranslationResult>

detectLanguage ( string $text, ?TranslationOptions $options = null) : string

Detect the language of text.

param string $text

Text to analyze

param TranslationOptions|null $options

Translation options

Returns

string Language code (ISO 639-1)

scoreTranslationQuality ( string $sourceText, string $translatedText, string $targetLanguage, ?TranslationOptions $options = null) : float

Score translation quality.

param string $sourceText

Original text

param string $translatedText

Translated text

param string $targetLanguage

Target language code

param TranslationOptions|null $options

Translation options

Returns

float Quality score (0.0 to 1.0)

Response objects 

Option classes 

Provider interface 

interface ProviderInterface

Fully qualified name

\Netresearch\NrLlm\Provider\Contract\ProviderInterface

Contract for LLM providers.

getName ( ) : string

Get human-readable provider name.

getIdentifier ( ) : string

Get provider identifier for configuration.

configure ( array $config) : void

Configure the provider with API key and settings.

param array $config

Configuration key-value pairs

isAvailable ( ) : bool

Check if provider is available and configured.

supportsFeature ( string|ModelCapability $feature) : bool

Check if provider supports a specific feature.

chatCompletion ( array $messages, array $options = []) : CompletionResponse

Execute chat completion.

param array $messages

Messages with role and content. Content can be a string (plain text) or an array of content blocks for multimodal input (text, image_url, document).

complete ( string $prompt, array $options = []) : CompletionResponse

Execute simple completion from a prompt.

embeddings ( string|array $input, array $options = []) : EmbeddingResponse

Generate embeddings for text.

getAvailableModels ( ) : array

Get list of available models.

getDefaultModel ( ) : string

Get the default model identifier.

testConnection ( ) : array

Test the connection to the provider.

throws

ProviderConnectionException

Returns

array{success, message, models?}

interface VisionCapableInterface

Fully qualified name

\Netresearch\NrLlm\Provider\Contract\VisionCapableInterface

Contract for providers supporting vision/image analysis.

analyzeImage ( array $content, array $options = []) : VisionResponse

Analyze an image.

param array $content

Array of content parts (text and image_url entries)

param array $options

Optional configuration

Returns

VisionResponse

supportsVision ( ) : bool

Check if vision is supported.

getSupportedImageFormats ( ) : array

Get supported image formats.

getMaxImageSize ( ) : int

Get maximum image size in bytes.

interface StreamingCapableInterface

Fully qualified name

\Netresearch\NrLlm\Provider\Contract\StreamingCapableInterface

Contract for providers supporting streaming.

streamChatCompletion ( array $messages, array $options = []) : Generator

Stream chat completion.

supportsStreaming ( ) : bool

Check if streaming is supported.

interface ToolCapableInterface

Fully qualified name

\Netresearch\NrLlm\Provider\Contract\ToolCapableInterface

Contract for providers supporting tool/function calling.

chatCompletionWithTools ( array $messages, array $tools, array $options = []) : CompletionResponse

Chat with tool calling. Messages support multimodal content (string or array of content blocks).

supportsTools ( ) : bool

Check if tool calling is supported.

Exceptions 

class ProviderException

Fully qualified name

\Netresearch\NrLlm\Provider\Exception\ProviderException

Base exception for provider errors.

getProvider ( ) : string

Get the provider that threw the exception.

class ProviderConfigurationException

Fully qualified name

\Netresearch\NrLlm\Provider\Exception\ProviderConfigurationException

Thrown when a provider is incorrectly configured.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

class ProviderConnectionException

Fully qualified name

\Netresearch\NrLlm\Provider\Exception\ProviderConnectionException

Thrown when a connection to the provider fails.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

class ProviderResponseException

Fully qualified name

\Netresearch\NrLlm\Provider\Exception\ProviderResponseException

Thrown when the provider returns an unexpected or error response.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

class UnsupportedFeatureException

Fully qualified name

\Netresearch\NrLlm\Provider\Exception\UnsupportedFeatureException

Thrown when a requested feature is not supported by the provider.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

class InvalidArgumentException

Fully qualified name

\Netresearch\NrLlm\Exception\InvalidArgumentException

Thrown for invalid method arguments.

class ConfigurationNotFoundException

Fully qualified name

\Netresearch\NrLlm\Exception\ConfigurationNotFoundException

Thrown when a named configuration is not found.

Architecture 

This section describes the architectural design of the TYPO3 LLM extension.

┌─────────────────────────────────────────────────────────────────────────┐
│ CONFIGURATION (Use-Case Specific)                                        │
│ "blog-summarizer", "product-description", "support-translator"          │
│                                                                          │
│ Fields: system_prompt, temperature, max_tokens, use_case_type           │
│ References: model_uid → Model                                            │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   │ N:1
┌──────────────────────────────────▼──────────────────────────────────────┐
│ MODEL (Available Models)                                                 │
│ "gpt-5", "claude-sonnet-4-5", "llama-70b", "text-embedding-3-large"     │
│                                                                          │
│ Fields: model_id, context_length, capabilities, pricing                 │
│ References: provider_uid → Provider                                      │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   │ N:1
┌──────────────────────────────────▼──────────────────────────────────────┐
│ PROVIDER (API Connections)                                               │
│ "openai-prod", "openai-dev", "local-ollama", "azure-openai-eu"          │
│                                                                          │
│ Fields: endpoint_url, api_key (encrypted), adapter_type, timeout        │
└─────────────────────────────────────────────────────────────────────────┘

@startuml
skinparam rectangle {
    BackgroundColor<<config>> #E8F5E9
    BackgroundColor<<model>>  #E3F2FD
    BackgroundColor<<provider>> #FFF3E0
}

rectangle "**CONFIGURATION**\n(Use-Case Specific)" <<config>> as C {
    note right
        blog-summarizer
        product-description
        support-translator
    end note
}

rectangle "**MODEL**\n(Available Models)" <<model>> as M {
    note right
        gpt-5, claude-sonnet-4-5
        llama-70b
        text-embedding-3-large
    end note
}

rectangle "**PROVIDER**\n(API Connections)" <<provider>> as P {
    note right
        openai-prod, openai-dev
        local-ollama
        azure-openai-eu
    end note
}

C -down-> M : "N:1\nmodel_uid"
M -down-> P : "N:1\nprovider_uid"
@enduml

┌─────────────────────────────────────────┐
│         Your Application Code           │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         Feature Services                │
│  (Completion, Embedding, Vision, etc.)  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│         LlmServiceManager               │
│    (Provider selection & routing)       │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│       ProviderAdapterRegistry           │
│    (Maps adapters to database providers)│
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│       Provider Adapters                 │
│  (OpenAI, Claude, Gemini, Ollama, etc.) │
└─────────────────────────────────────────┘

Testing guide 

Comprehensive testing guide for the TYPO3 LLM extension.

Unit testing 

# Install dependencies (dev deps included by default)
composer install

# Recommended: Use runTests.sh (Docker-based, consistent environment)
Build/Scripts/runTests.sh -s unit

# With specific PHP version
Build/Scripts/runTests.sh -s unit -p 8.3

# Alternative: Via Composer script
composer ci:test:php:unit

# Run integration tests (requires API keys)
OPENAI_API_KEY=your-api-key-here \
    Build/Scripts/runTests.sh -s functional