Supported providers 

Unified provider API 

All providers implement a common interface, allowing you to:

• Switch between providers with a single configuration change.
• Test with different models without modifying application code.
• Implement provider fallbacks for increased reliability.

// 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']);

Specialized feature services 

High-level services for common AI tasks:

CompletionService

Text generation with format control (JSON, Markdown) and creativity presets.

EmbeddingService

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

VisionService

Image analysis with specialized prompts for alt-text, titles, descriptions.

TranslationService

Language translation with formality control, domain-specific terminology, and glossaries.

PromptTemplateService

Centralized prompt management with variable substitution and versioning.

Streaming support 

Real-time response streaming for better user experience:

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

Tool/function calling 

Execute custom functions based on AI decisions:

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

Intelligent caching 

• Automatic response caching using TYPO3's caching framework.
• Deterministic embedding caching (24-hour default TTL).
• Configurable cache lifetimes per operation type.

Content generation 

• Generate product descriptions.
• Create meta descriptions and SEO content.
• Draft blog posts and articles.
• Summarize long-form content.

Translation 

• Translate website content.
• Maintain consistent terminology with glossaries.
• Preserve formatting in technical documents.

Image processing 

• Generate accessibility-compliant alt-text.
• Create SEO-optimized image titles.
• Analyze and categorize image content.

Search and discovery 

• Semantic search using embeddings.
• Content similarity detection.
• Recommendation systems.

Chatbots and assistants 

• Customer support chatbots.
• FAQ answering systems.
• Guided navigation assistants.

Provider requirements 

To use specific providers, you need:

• OpenAI: API key from https://platform.openai.com.
• Anthropic Claude: API key from https://console.anthropic.com.
• Google Gemini: API key from https://aistudio.google.com.
• Ollama: Local installation from https://ollama.ai (no API key required).
• OpenRouter: API key from https://openrouter.ai.
• Mistral: API key from https://console.mistral.ai.
• Groq: API key from https://console.groq.com.

Requirements 

Ensure your system meets these requirements:

• PHP 8.2 or higher.
• TYPO3 v13.4 or higher.
• Composer 2.x.
• netresearch/nr-vault ^0.4.0 (required for API key encryption; installed automatically via Composer).

Installation steps 

1. Add the package

   Install via Composer

   composer require netresearch/nr-llm

   Copied!

2. Activate the extension

   Navigate to Admin Tools > Extension Manager and activate EXT:nr_llm.

3. Configure API keys

   See Configuration for detailed setup instructions.

4. Clear caches

   Flush all caches

   vendor/bin/typo3 cache:flush

   Copied!

From previous versions 

1. Backup your database before upgrading.

2. Run Composer update:

   Update the extension

   composer update netresearch/nr-llm

   Copied!

3. Run database migrations:

   Update database schema

   vendor/bin/typo3 database:updateschema

   Copied!

4. Clear all caches:

   Flush all caches

   vendor/bin/typo3 cache:flush

   Copied!

Breaking changes 

Check the Changelog for breaking changes between versions.

Required fields 

Optional fields 

Testing provider connections 

Use the Test Connection button to verify provider configuration. The test makes an actual HTTP request to the provider's API and returns:

• Connection status (success/failure).
• Available models (if supported by the provider).
• Error details (on failure).

Required fields 

Optional fields 

Fetching models from providers 

Use the Fetch Models action to automatically retrieve available models from the provider's API. This populates the model list with the provider's current offerings.

Required fields 

Optional fields 

Constants 

plugin.tx_nrllm {
    settings {
        # Default LLM provider (openai, claude, gemini)
        defaultProvider = openai

        # Enable/disable response caching
        enableCaching = 1

        # Cache lifetime in seconds
        cacheLifetime = 3600

        # Per-provider settings
        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
            }
        }
    }
}

API key protection 

1. Encrypted storage: API keys are encrypted using sodium_crypto_secretbox.
2. Database security: Ensure database backups are encrypted.
3. Backend access: Restrict backend module access to authorized users.
4. Key rotation: Changing the TYPO3 encryptionKey requires re-encryption.

Input sanitization 

Always sanitize user input before sending to LLM providers:

use TYPO3\CMS\Core\Utility\GeneralUtility;

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

Output handling 

Treat LLM responses as untrusted content:

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

Benefits 

• Multiple API keys per provider type: Separate production and development accounts.
• Custom endpoints: Azure OpenAI, Ollama, vLLM, local models.
• Reusable model definitions: Centralized capabilities and pricing.
• Clear separation of concerns: Connection vs capability vs use-case.

Provider layer 

Represents a specific API connection with credentials.

Database table: tx_nrllm_provider

Key design points:

• One provider = one API key = one billing relationship.
• Same adapter type can have multiple providers (prod/dev accounts).
• Adapter type determines the protocol/client class used.
• API keys are encrypted at rest using sodium.

Model layer 

Represents a specific model available through a provider.

Database table: tx_nrllm_model

Key design points:

• Models belong to exactly one provider.
• Capabilities define what the model can do.
• Pricing stored as integers (cents/1M tokens) to avoid float issues.
• Same logical model can exist multiple times (different providers).

Configuration layer 

Represents a specific use case with model and prompt settings.

Database table: tx_nrllm_configuration

Key design points:

• Configurations reference models, not providers directly.
• All LLM parameters are tunable per use case.
• Same model can be used by multiple configurations.

Feature services 

High-level services for common AI tasks:

• CompletionService: Text generation with format control (JSON, Markdown).
• EmbeddingService: Text-to-vector conversion with caching.
• VisionService: Image analysis for alt-text, titles, descriptions.
• TranslationService: Language translation with glossaries.

Provider adapters 

The extension includes adapters for multiple LLM providers:

• OpenAI (OpenAiProvider): GPT-5.x series, o-series reasoning models.
• Anthropic (ClaudeProvider): Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5.
• Google (GeminiProvider): Gemini 3 Pro, Gemini 3 Flash, Gemini 2.5 series.
• Ollama (OllamaProvider): Local model deployment.
• OpenRouter (OpenRouterProvider): Multi-model routing.
• Mistral (MistralProvider): Mistral models.
• Groq (GroqProvider): Fast inference.

API key encryption 

API keys are encrypted at rest in the database using sodium_crypto_secretbox (XSalsa20-Poly1305).

• Keys are derived from TYPO3's encryptionKey with domain separation.
• Nonce is randomly generated per encryption (24 bytes).
• Encrypted values are prefixed with enc: for detection.
• Legacy plaintext values are automatically encrypted on first access.

For details, see ADR-012: API key encryption at application level.

Supported adapter types 

Architecture overview 

The extension follows a layered architecture:

1. Providers - Handle direct API communication.
2. LlmServiceManager - Orchestrates providers and provides unified API.
3. Feature services - High-level services for specific tasks.
4. Domain models - Response objects and value types.

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

Dependency injection 

All services are available via dependency injection:

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,
    ) {}
}

Basic chat 

$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

// UsageStatistics
$promptTokens = $usage->promptTokens;
$completionTokens = $usage->completionTokens;
$totalTokens = $usage->totalTokens;

Chat with options 

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-opus-4-5-20251101',
    'temperature' => 1.2,
    'max_tokens' => 2000,
    'top_p' => 0.9,
    'frequency_penalty' => 0.5,
    'presence_penalty' => 0.5,
]);

Simple completion 

// Quick completion from a prompt
$response = $this->llmManager->complete('Explain recursion in programming');

Embeddings 

// 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>>

Streaming 

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

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

Tool/function calling 

$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);
    }
}

CompletionResponse 

namespace Netresearch\NrLlm\Domain\Model;

final class CompletionResponse
{
    public readonly string $content;
    public readonly string $model;
    public readonly UsageStatistics $usage;
    public readonly string $finishReason;
    public readonly string $provider;
    public readonly ?array $toolCalls;

    public function isComplete(): bool;      // finished normally
    public function wasTruncated(): bool;    // hit max_tokens
    public function wasFiltered(): bool;     // content filtered
    public function hasToolCalls(): bool;    // has tool calls
    public function getText(): string;       // alias for content
}

EmbeddingResponse 

namespace Netresearch\NrLlm\Domain\Model;

final class EmbeddingResponse
{
    /** @var array<int, array<int, float>> */
    public readonly array $embeddings;
    public readonly string $model;
    public readonly UsageStatistics $usage;
    public readonly string $provider;

    public function getVector(): array;   // First embedding
    public static function cosineSimilarity(array $a, array $b): float;
}

UsageStatistics 

namespace Netresearch\NrLlm\Domain\Model;

final readonly class UsageStatistics
{
    public int $promptTokens;
    public int $completionTokens;
    public int $totalTokens;
    public ?float $estimatedCost;
}

Use cases 

• Content generation.
• Rule generation (contexts extension).
• Content summarization.
• SEO meta generation.

Key features 

• JSON response formatting.
• Markdown generation.
• Factual mode (low creativity).
• Creative mode (high creativity).
• System prompt support.

Example 

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;

Methods 

// 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 cases 

• Alt text generation (rte-ckeditor-image).
• SEO title generation.
• Detailed descriptions.
• Custom image analysis.

Key features 

• WCAG 2.1 compliant alt text.
• SEO-optimized titles.
• Batch processing.
• Base64 and URL support.

Example 

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',
]);

Methods 

// 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 cases 

• Semantic translation memory (textdb).
• Content similarity.
• Duplicate detection.
• Semantic search.

Key features 

• Aggressive caching (deterministic).
• Batch processing.
• Cosine similarity calculations.
• Top-K similarity search.

Example 

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
);

Methods 

// 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 cases 

• Translation suggestions (textdb).
• Content localization.
• Glossary-aware translation.

Key features 

• Language detection.
• Glossary support.
• Formality levels.
• Domain specialization.
• Quality scoring.

Example 

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;

Methods 

// 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');

Key features 

• Database-driven templates.
• Variable substitution.
• Conditional rendering.
• Version control.
• A/B testing.
• Performance tracking.

Example 

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(),
    ]
);

Dependency injection 

Add to your extension's Configuration/Services.yaml:

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'

Usage in your extension 

<?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),
        ];
    }
}

Vision 

• vision.alt_text - WCAG 2.1 compliant alt text.
• vision.seo_title - SEO-optimized titles.
• vision.description - Detailed descriptions.

Translation 

• translation.general - General purpose translation.
• translation.technical - Technical documentation.
• translation.marketing - Marketing copy.

Completion 

• completion.rule_generation - TYPO3 contexts rules.
• completion.content_summary - Content summarization.
• completion.seo_meta - SEO meta descriptions.

Embedding 

• embedding.semantic_search - Semantic search configuration.

Unit tests 

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

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

Mocking services 

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']);
    }
}

Caching 

• Embeddings: 24h cache (deterministic).
• Vision: Short cache (subjective).
• Translation: Medium cache (context-dependent).
• Completion: Case-by-case basis.

Batch processing 

Use batch methods for better performance:

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

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

Custom prompts 

Override default prompts via database or configuration:

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
);

Service options 

All services accept configuration options:

$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'],
    ]
);

rte-ckeditor-image 

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),
        ];
    }
}

textdb 

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),
        ];
    }
}

contexts 

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]
        );
    }
}

CompletionService 

class CompletionService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\CompletionService

High-level text completion with format control.

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

Standard text completion.

param string $prompt

The prompt text

param array $options

Optional configuration

Returns

CompletionResponse

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

Completion with JSON output parsing.

param string $prompt

The prompt text

param array $options

Optional configuration

Returns

array Parsed JSON data

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

Completion with markdown formatting.

param string $prompt

The prompt text

param array $options

Optional configuration

Returns

string Markdown formatted text

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

Low-creativity completion for factual responses.

param string $prompt

The prompt text

param array $options

Optional configuration (temperature defaults to 0.1)

Returns

CompletionResponse

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

High-creativity completion for creative content.

param string $prompt

The prompt text

param array $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) : array

Generate embedding vector for text (cached).

param string $text

The text to embed

Returns

array<float> Vector representation

embedFull ( string $text) : EmbeddingResponse

Generate embedding with full response metadata.

param string $text

The text to embed

Returns

EmbeddingResponse

embedBatch ( array $texts) : array

Generate embeddings for multiple texts.

param array $texts

Array of texts

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)

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 $imageUrl) : string

Generate WCAG-compliant alt text.

param string $imageUrl

URL or local path to image

Returns

string Accessibility-optimized alt text

generateTitle ( string $imageUrl) : string

Generate SEO-optimized image title.

param string $imageUrl

URL or local path to image

Returns

string SEO-friendly title

generateDescription ( string $imageUrl) : string

Generate detailed image description.

param string $imageUrl

URL or local path to image

Returns

string Detailed description

analyzeImage ( string $imageUrl, string $prompt) : string

Custom image analysis with specific prompt.

param string $imageUrl

URL or local path to image

param string $prompt

Analysis prompt

Returns

string Analysis result

TranslationService 

class TranslationService

Fully qualified name

\Netresearch\NrLlm\Service\Feature\TranslationService

Language translation with quality control.

translate ( string $text, string $targetLanguage, ?string $sourceLanguage = null, array $options = []) : 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 array $options

Translation options

Options:

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

Returns

TranslationResult

translateBatch ( array $texts, string $targetLanguage, array $options = []) : array

Translate multiple texts.

param array $texts

Array of texts

param string $targetLanguage

Target language code

param array $options

Translation options

Returns

array<TranslationResult>

detectLanguage ( string $text) : string

Detect the language of text.

param string $text

Text to analyze

Returns

string Language code

scoreTranslationQuality ( string $source, string $translation, string $targetLanguage) : float

Score translation quality.

param string $source

Original text

param string $translation

Translated text

param string $targetLanguage

Target language code

Returns

float Quality score (0.0 to 1.0)

CompletionResponse 

class CompletionResponse

Fully qualified name

\Netresearch\NrLlm\Domain\Model\CompletionResponse

Response from chat/completion operations.

string content

The generated text content.

string model

The model used for generation.

UsageStatistics usage

Token usage statistics.

string finishReason

Why generation stopped: 'stop', 'length', 'content_filter', 'tool_calls'

string provider

The provider identifier.

array|null toolCalls

Tool calls if any were made.

isComplete ( ) : bool

Check if response finished normally.

wasTruncated ( ) : bool

Check if response hit max_tokens limit.

wasFiltered ( ) : bool

Check if content was filtered.

hasToolCalls ( ) : bool

Check if response contains tool calls.

getText ( ) : string

Alias for content property.

EmbeddingResponse 

class EmbeddingResponse

Fully qualified name

\Netresearch\NrLlm\Domain\Model\EmbeddingResponse

Response from embedding operations.

array embeddings

Array of embedding vectors.

string model

The model used for embedding.

UsageStatistics usage

Token usage statistics.

string provider

The provider identifier.

getVector ( ) : array

Get the first embedding vector.

static cosineSimilarity ( array $a, array $b)

Calculate cosine similarity between vectors.

returns

float

TranslationResult 

class TranslationResult

Fully qualified name

\Netresearch\NrLlm\Domain\Model\TranslationResult

Response from translation operations.

string translation

The translated text.

string sourceLanguage

Detected or provided source language.

string targetLanguage

The target language.

float confidence

Confidence score (0.0 to 1.0).

UsageStatistics 

class UsageStatistics

Fully qualified name

\Netresearch\NrLlm\Domain\Model\UsageStatistics

Token usage and cost tracking.

int promptTokens

Tokens in the prompt/input.

int completionTokens

Tokens in the completion/output.

int totalTokens

Total tokens used.

float|null estimatedCost

Estimated cost in USD (if available).

ChatOptions 

class ChatOptions

Fully qualified name

\Netresearch\NrLlm\Service\Option\ChatOptions

Typed options for chat operations.

static factual ( )

Create options optimized for factual responses (temperature: 0.1).

returns

ChatOptions

static creative ( )

Create options for creative content (temperature: 1.2).

returns

ChatOptions

static balanced ( )

Create balanced options (temperature: 0.7).

returns

ChatOptions

static json ( )

Create options for JSON output format.

returns

ChatOptions

static code ( )

Create options optimized for code generation.

returns

ChatOptions

withTemperature ( float $temperature) : self

Set temperature (0.0 - 2.0).

withMaxTokens ( int $maxTokens) : self

Set maximum output tokens.

withTopP ( float $topP) : self

Set nucleus sampling parameter.

withFrequencyPenalty ( float $penalty) : self

Set frequency penalty (-2.0 to 2.0).

withPresencePenalty ( float $penalty) : self

Set presence penalty (-2.0 to 2.0).

withSystemPrompt ( string $prompt) : self

Set system prompt.

withProvider ( string $provider) : self

Set provider (openai, claude, gemini).

withModel ( string $model) : self

Set specific model.

toArray ( ) : array

Convert to array format.

Prerequisites 

# Install development dependencies
composer install --dev

Unit tests 

# 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

Integration tests 

# Run integration tests (requires mock server or API keys)
composer ci:test:php:integration

# With real API (set environment variables first)
OPENAI_API_KEY=sk-... Build/Scripts/runTests.sh -s unit

Functional tests 

# Run TYPO3 functional tests
Build/Scripts/runTests.sh -s functional

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

All tests 

# Run all test suites via runTests.sh
Build/Scripts/runTests.sh -s unit
Build/Scripts/runTests.sh -s functional

# Run code quality checks
Build/Scripts/runTests.sh -s cgl
Build/Scripts/runTests.sh -s phpstan

Unit test example 

<?php

namespace Netresearch\NrLlm\Tests\Unit\Service;

use Netresearch\NrLlm\Domain\Model\CompletionResponse;
use Netresearch\NrLlm\Domain\Model\UsageStatistics;
use Netresearch\NrLlm\Provider\Contract\ProviderInterface;
use Netresearch\NrLlm\Service\LlmServiceManager;
use PHPUnit\Framework\TestCase;

class LlmServiceManagerTest extends TestCase
{
    private LlmServiceManager $subject;

    protected function setUp(): void
    {
        parent::setUp();

        $mockProvider = $this->createMock(ProviderInterface::class);
        $mockProvider->method('getIdentifier')->willReturn('test');
        $mockProvider->method('isConfigured')->willReturn(true);

        $this->subject = new LlmServiceManager(
            providers: [$mockProvider],
            defaultProvider: 'test'
        );
    }

    public function testChatReturnsCompletionResponse(): void
    {
        $provider = $this->createMock(ProviderInterface::class);
        $provider->method('chatCompletion')->willReturn(
            new CompletionResponse(
                content: 'Hello!',
                model: 'test-model',
                usage: new UsageStatistics(10, 5, 15),
                finishReason: 'stop',
                provider: 'test'
            )
        );

        // ... test implementation
    }

    /**
     * @dataProvider invalidMessagesProvider
     */
    public function testChatThrowsOnInvalidMessages(array $messages): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->subject->chat($messages);
    }

    public static function invalidMessagesProvider(): array
    {
        return [
            'empty messages' => [[]],
            'missing role' => [[['content' => 'test']]],
            'missing content' => [[['role' => 'user']]],
            'invalid role' => [[['role' => 'invalid', 'content' => 'test']]],
        ];
    }
}

Integration test example 

<?php

namespace Netresearch\NrLlm\Tests\Integration\Provider;

use Netresearch\NrLlm\Provider\OpenAiProvider;
use PHPUnit\Framework\TestCase;

class OpenAiProviderIntegrationTest extends TestCase
{
    private ?OpenAiProvider $provider = null;

    protected function setUp(): void
    {
        $apiKey = getenv('OPENAI_API_KEY');
        if (!$apiKey) {
            $this->markTestSkipped('OPENAI_API_KEY not set');
        }

        $this->provider = new OpenAiProvider(
            httpClient: new \GuzzleHttp\Client(),
            requestFactory: new \GuzzleHttp\Psr7\HttpFactory(),
            streamFactory: new \GuzzleHttp\Psr7\HttpFactory(),
            apiKey: $apiKey
        );
    }

    public function testChatCompletionWithRealApi(): void
    {
        $response = $this->provider->chatCompletion([
            ['role' => 'user', 'content' => 'Say "test" and nothing else.'],
        ], [
            'max_tokens' => 10,
        ]);

        $this->assertStringContainsStringIgnoringCase('test', $response->content);
        $this->assertGreaterThan(0, $response->usage->totalTokens);
    }
}

Functional test example 

<?php

namespace Netresearch\NrLlm\Tests\Functional\Repository;

use Netresearch\NrLlm\Domain\Model\PromptTemplate;
use Netresearch\NrLlm\Domain\Repository\PromptTemplateRepository;
use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;

class PromptTemplateRepositoryTest extends FunctionalTestCase
{
    protected array $testExtensionsToLoad = [
        'netresearch/nr-llm',
    ];

    private PromptTemplateRepository $repository;

    protected function setUp(): void
    {
        parent::setUp();
        $this->repository = $this->get(PromptTemplateRepository::class);
    }

    public function testFindByIdentifierReturnsTemplate(): void
    {
        $this->importCSVDataSet(__DIR__ . '/Fixtures/prompt_templates.csv');

        $template = $this->repository->findByIdentifier('test-template');

        $this->assertInstanceOf(PromptTemplate::class, $template);
        $this->assertEquals('Test Template', $template->getName());
    }
}

Using mock provider 

<?php

use Netresearch\NrLlm\Domain\Model\CompletionResponse;
use Netresearch\NrLlm\Domain\Model\UsageStatistics;
use Netresearch\NrLlm\Provider\Contract\ProviderInterface;

$mockProvider = $this->createMock(ProviderInterface::class);

$mockProvider
    ->method('chatCompletion')
    ->willReturn(new CompletionResponse(
        content: 'Mocked response',
        model: 'mock-model',
        usage: new UsageStatistics(100, 50, 150),
        finishReason: 'stop',
        provider: 'mock'
    ));

$mockProvider
    ->method('isConfigured')
    ->willReturn(true);

Using HTTP mock 

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

$mock = new MockHandler([
    new Response(200, [], json_encode([
        'choices' => [
            [
                'message' => ['content' => 'Test response'],
                'finish_reason' => 'stop',
            ],
        ],
        'model' => 'gpt-5',
        'usage' => [
            'prompt_tokens' => 10,
            'completion_tokens' => 5,
            'total_tokens' => 15,
        ],
    ])),
]);

$handlerStack = HandlerStack::create($mock);
$client = new Client(['handler' => $handlerStack]);

$provider = new OpenAiProvider(
    httpClient: $client,
    // ...
);

CSV fixtures 

"tx_nrllm_prompt_template"
"uid","pid","identifier","name","template","variables"
1,0,"test-template","Test Template","Hello {name}!","name"

JSON response fixtures 

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Test response"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15
  }
}

Running mutation tests 

# Run mutation tests via runTests.sh
Build/Scripts/runTests.sh -s mutation

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

Interpreting results 

• MSI (Mutation Score Indicator): Percentage of mutations killed.
• Target: >60% MSI indicates good test quality.
• Current: 58% MSI (459 tests).

Mutation Score Indicator (MSI): 58%
Mutation Code Coverage: 85%
Covered Code MSI: 68%

GitHub Actions 

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        php: ['8.2', '8.3', '8.4', '8.5']
        typo3: ['13.4', '14.0']

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          coverage: xdebug

      - name: Install dependencies
        run: composer install --prefer-dist

      - name: Run tests
        run: composer test

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: coverage/clover.xml

GitLab CI/CD 

test:
  image: php:8.2
  script:
    - composer install
    - composer test
  coverage: '/^\s*Lines:\s*\d+.\d+\%/'

Problem statement 

TYPO3's TCA type=password field has two modes:

1. Hashed mode (default): Uses bcrypt/argon2 - irreversible, suitable for user passwords
2. Unhashed mode (hashed => false): Stores plaintext - required for API keys that must be retrieved

API keys must be retrievable to authenticate with external services, so hashing is not an option. However, storing them in plaintext exposes them to:

• Database dumps/backups
• SQL injection attacks
• Unauthorized database access
• Accidental exposure in logs

Requirements 

1. API keys must be retrievable (not hashed).
2. Keys must be encrypted at rest in the database.
3. Encryption must be transparent to the application.
4. Solution must work without external dependencies (self-contained).
5. Must support key rotation.
6. Backwards compatible with existing plaintext values.

Architecture 

┌─────────────────────────────────────────────────────────────────┐
│                        Backend Form                              │
│                    (user enters API key)                         │
└─────────────────────────────┬───────────────────────────────────┘
                              │ plaintext
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Provider::setApiKey()                         │
│              ProviderEncryptionService::encrypt()                │
│                                                                  │
│  1. Generate random nonce (24 bytes)                             │
│  2. Derive key from TYPO3 encryptionKey via SHA-256              │
│  3. Encrypt with XSalsa20-Poly1305                               │
│  4. Prefix with "enc:" marker                                    │
│  5. Base64 encode for storage                                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │ "enc:base64(nonce+ciphertext+tag)"
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Database                                 │
│                   tx_nrllm_provider.api_key                      │
└─────────────────────────────────────────────────────────────────┘

Key derivation 

// Domain-separated key derivation
$key = hash('sha256', $typo3EncryptionKey . ':nr_llm_provider_encryption', true);

The domain separator :nr_llm_provider_encryption ensures:

• Keys are unique to this use case.
• Same encryptionKey produces different keys for different purposes.
• No collision with other extensions using similar patterns.

Encryption format 

enc:{base64(nonce || ciphertext || auth_tag)}

Where:
- "enc:" = 4-byte prefix marker
- nonce = 24 bytes (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES)
- ciphertext = variable length
- auth_tag = 16 bytes (Poly1305 MAC, included by sodium)

Files created/modified 

Key methods 

// ProviderEncryptionService
public function encrypt(string $plaintext): string;
public function decrypt(string $ciphertext): string;
public function isEncrypted(string $value): bool;

// Provider Model
public function setApiKey(string $apiKey): void;      // Encrypts before storage
public function getApiKey(): string;                   // Returns raw (encrypted)
public function getDecryptedApiKey(): string;          // Returns decrypted
public function toAdapterConfig(): array;              // Uses decrypted key

Positive 

◐ Encryption at rest: Database dumps no longer expose plaintext credentials.

◐ Transparent operation: Encryption/decryption handled automatically.

◐ No external dependencies: Uses PHP's built-in sodium extension.