Getting started 

For administrators 

Set up and manage AI providers, models, and configurations through the TYPO3 backend module.

For developers 

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

[n] A Netresearch extension 

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

netresearch.de

Table of contents

What does it do? 

nr-llm is the shared AI foundation for TYPO3. It lets administrators configure LLM providers once in the backend — and every AI-powered extension on the site uses them automatically.

For extension developers, it eliminates the need to build provider integrations, manage API keys, or implement caching and streaming. Add AI capabilities to your extension with three lines of dependency injection.

For administrators, it provides a single backend module to manage all AI connections, encrypted API keys, and provider configurations. Switch from OpenAI to Anthropic without touching any extension code.

For agencies, it means consistent AI architecture across client projects, no vendor lock-in, and a local-first option via Ollama for data-sensitive environments.

The extension enables developers to:

• Access multiple AI providers through a single, consistent API.
• Switch providers transparently without code changes.
• Leverage specialized services for common AI tasks (translation, vision, embeddings).
• Cache responses to reduce API costs and improve performance.
• Stream responses for real-time user experiences.
• Store API keys securely as nr-vault identifiers (envelope encryption).

Key features 

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

Use cases 

Requirements 

• PHP: 8.2 or higher.
• TYPO3: v13.4 LTS or v14.3 LTS.
• HTTP client: PSR-18 compatible (e.g., guzzlehttp/guzzle ).

Credits 

This extension is developed and maintained by:

Netresearch DTT GmbH

https://www.netresearch.de

Built with the assistance of modern AI development tools and following TYPO3 coding standards and best practices.

Quick start 

The recommended way to install this extension is via Composer:

composer require netresearch/nr-llm

After installation:

1. Activate the extension in Admin Tools > Extension Manager.
2. Configure providers and API keys in Admin Tools > LLM > Providers.
3. Define available models in Admin Tools > LLM > Models.
4. Create configurations in Admin Tools > LLM > Configurations.
5. Clear caches.

Composer installation 

Manual installation 

If you cannot use Composer:

1. Download the extension from the TYPO3 Extension Repository (TER).
2. Extract to typo3conf/ext/nr_llm.
3. Activate in Admin Tools > Extension Manager.
4. Configure API keys and settings.

Database setup 

The extension creates the following database tables automatically:

Run the database compare tool after installation:

vendor/bin/typo3 extension:setup nr_llm

Cache configuration 

The extension uses TYPO3's caching framework. Cache configuration is set up automatically — no backend is hardcoded. TYPO3 uses your instance's default cache backend, so Redis, Valkey, or Memcached work transparently if configured.

To override the cache backend specifically for nr-llm:

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

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

Upgrading 

Uninstallation 

To remove the extension:

1. Deactivate in Admin Tools > Extension Manager.

2. Remove via Composer:

   Remove the extension

   composer remove netresearch/nr-llm

   Copied!

3. Clean up database tables if desired:

   Drop extension database tables

   DROP TABLE IF EXISTS tx_nrllm_provider;
   DROP TABLE IF EXISTS tx_nrllm_model;
   DROP TABLE IF EXISTS tx_nrllm_configuration;
   DROP TABLE IF EXISTS tx_nrllm_configuration_begroups_mm;
   DROP TABLE IF EXISTS tx_nrllm_task;
   DROP TABLE IF EXISTS tx_nrllm_prompttemplate;
   DROP TABLE IF EXISTS tx_nrllm_service_usage;

   Copied!
4. Remove any TypoScript includes referencing the extension.

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 eight 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
• Snippets — tagged reusable prompt fragments
• Skills — GitHub-hosted SKILL.md sources (admin-only)
• Tools — enable or disable the agent tools (admin-only)
• Playground — run the agent tool loop interactively (admin-only)

Adding a provider 

1. Navigate to Admin Tools > LLM > Providers.
2. Click Add Provider.

3. Fill in the required fields:

   Identifier

   A unique slug for programmatic access (e.g., openai-prod, ollama-local).

   Name

   A display name for the backend (e.g., OpenAI Production).

   Adapter Type

   Select the provider protocol. Available adapters: openai, anthropic, gemini, ollama, openrouter, mistral, groq, azure_openai, custom.

   API Key

   Your API key. Stored securely via nr-vault envelope encryption. Leave empty for local providers like Ollama.

4. Optionally set the endpoint URL, organization ID, timeout, and retry count.
5. Click Save.

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.

$GLOBALS['TYPO3_CONF_VARS']['HTTP']['allowed_hosts'][] = 'ollama';

Editing and deleting providers 

• Click a provider row to edit its settings.
• Use the Delete action to remove a provider. Models linked to a deleted provider become inactive.

Adding a model manually 

1. Navigate to Admin Tools > LLM > Models.
2. Click Add Model.

3. Fill in the required fields:

   Identifier

   Unique slug (e.g., gpt-5, claude-sonnet).

   Name

   Display name (e.g., GPT-5 (128K)).

   Provider

   Select the parent provider.

   Model ID

   The API model identifier as the provider expects it (e.g., gpt-5.3-instant, claude-sonnet-4-6).

4. Optionally set capabilities (chat, completion, embeddings, vision, streaming, tools), context length, max output tokens, and pricing.
5. Click Save.

Fetching models from a provider 

Instead of adding models manually, use the Fetch Models action to query the provider API and auto-populate the model list:

1. Ensure the provider is saved and the connection test passes.
2. On the model list or model edit form, click Fetch Models.
3. The extension queries the provider API and creates model records with capabilities and metadata pre-filled.

This is the recommended approach — it ensures model IDs match the provider exactly and keeps your catalogue current as providers release new models.

Adding a configuration manually 

1. Navigate to Admin Tools > LLM > Configurations.
2. Click Add Configuration.

3. Fill in the required fields:

   Identifier

   Unique slug for programmatic access (e.g., blog-summarizer).

   Name

   Display name (e.g., Blog Post Summarizer).

   Model

   Select the model to use.

   System Prompt

   The system message that sets the AI's behavior and context.

4. Optionally adjust temperature (0.0-2.0), top_p, frequency/presence penalty, max tokens, and use-case type (chat, completion, embedding, translation).
5. Click Save.

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.

Editing configurations 

Click a configuration row to edit. Changes take effect immediately for any extension code that references this configuration's identifier — no code deployment needed.

Adding a task manually 

1. Navigate to Admin Tools > LLM > Tasks.
2. Click Add Task.

3. Fill in the required fields:

   Name

   Display name (e.g., Summarize Article).

   Configuration

   Select the LLM configuration to use.

   User Prompt

   The prompt template. Use {placeholders} for dynamic values.

4. Add a description so other admins understand what the task does.
5. Click Save.

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.

Adding a snippet 

1. Navigate to Admin Tools > LLM > Snippets.
2. Click New Snippet.

3. Fill in the fields:

   Identifier

   Unique technical identifier (e.g., persona-friendly-expert).

   Name

   Display name (e.g., Friendly Expert).

   Tags

   Comma-separated tags consuming extensions search for (see below).

   Snippet text

   The prompt fragment itself.

   Metadata (JSON)

   Optional JSON object with extra settings.

4. Click Save.

Tag convention 

Tags are free-form, comma-separated strings. There is no fixed vocabulary — consuming extensions agree on tags with the editors. Matching is exact per tag and case-insensitive: the tag style does not match a snippet tagged lifestyle.

Established tags so far:

Persona snippets may carry a voice hint in their metadata so speech features can pick a matching text-to-speech voice:

{"voice": "nova"}

Using snippets from an extension 

Query snippets by tag through the public PromptSnippetRepository and compose the selected fragments with the PromptSnippetComposer:

$audiences = $this->promptSnippetRepository
    ->findActiveByTag('audience');
$tones = $this->promptSnippetRepository
    ->findActiveByTag('tone_of_voice');

$sections = $this->promptSnippetComposer->composeSections([
    'TARGET AUDIENCE' => $audiences[0] ?? null,
    'TONE OF VOICE' => $tones[0] ?? null,
]);

composeSections() renders each non-null snippet as a LABEL: block followed by the snippet text, joined by blank lines. Null entries and empty snippets are skipped.

See ADR-031 for the design rationale.

Source types 

A source has one of three types:

single_file

One SKILL.md at a fixed path in a repository. A single, explicit admin act — its skill may default to enabled.

repo

A whole repository. Every SKILL.md under the repo root, skills/<name>/, .claude/skills/<name>/ or <plugin>/skills/<name>/ is discovered. Discovered skills arrive disabled for review.

marketplace

An Anthropic marketplace.json index that lists plugins pointing at further repositories. Each entry is expanded with the repo flow. All discovered skills arrive disabled.

Adding a source 

1. Navigate to Admin Tools > LLM > Skills.
2. Click New Skill Source.

3. Fill in the fields:

   Title

   Display name for the source list.

   Type

   single_file, repo or marketplace (see above).

   URL

   The GitHub URL the type expects (the SKILL.md URL, the repository URL, or the marketplace.json URL).

   Ref

   A branch or tag (for example main or v1.2.0). It is resolved once to an immutable commit SHA at sync time; all bodies are then fetched by that SHA, never by the moving branch.

4. Click Save.

The pinned_sha, sync_status, sync_error and last_synced fields are managed by the sync run and shown read-only.

GitHub token and rate limits 

Unauthenticated GitHub API access is limited to 60 requests per hour, which is quickly exhausted by a repo or marketplace sync. Add a personal access token (a read-only, public-repo token is enough) to raise the limit and to read private repositories.

• The token is set through the Set token action on a source, not typed into a FormEngine field. It is stored as an nr-vault UUID (envelope-encrypted), mirroring provider API-key storage — never as plaintext in TCA, YAML or the database.
• When a sync hits the rate limit (HTTP 403 with no remaining quota), the source is set to sync_status = error carrying the reset time; state is not partially corrupted. Add a token and re-sync.

Host-allowlist prerequisite 

nr-llm enforces an app-level GitHub allowlist on every skill request: the scheme must be https and the host must be one of github.com, raw.githubusercontent.com, api.github.com or codeload.github.com. This is separate from, and in addition to, the nr-vault SSRF guard.

On hardened instances that restrict outbound HTTP through the global HTTP/allowed_hosts SSRF setting, those four GitHub hosts must be on that list, otherwise every sync fails closed. This is a deliberate prerequisite — nr-llm never silently bypasses the SSRF guard.

Syncing and the review flow 

1. On a source, click Sync. The source moves through never_synced → syncing → ok / partial / error. The syncing state also acts as a lock: a second concurrent sync on the same source is refused.
2. partial means the per-sync file-count or wall-time bound was reached (large marketplaces); the skills fetched so far are stored.
3. Discovered skills from repo and marketplace sources are created disabled by default. Review each one, then toggle it on with Enable.
4. Re-sync never silently changes an enabled skill. If a re-sync recomputes a different body_checksum for an enabled skill, nr-llm auto-disables it and surfaces a diff (Review changes) so you re-confirm before it is used again. Accepting the diff re-pins the SHA atomically.
5. A skill that disappeared upstream is marked orphaned and disabled, never silently dropped, so attachments (Plan 1b) do not vanish.

Deleting a source cascade-deletes its skills.

The partial support badge 

Each skill carries a support badge:

full

The skill is plain front-matter and prose.

partial

The body or front-matter references scripts, references/, assets/ or an allowed-tools declaration.

See ADR-035 for the full design and security rationale.

Attaching skills and injecting them into prompts 

Enabled, non-orphaned skills can be attached to a Task and/or an LLM configuration via the Skills field on those records (only enabled skills are offered). At execution time, for text-generation operations only — completion, translation and task execution; never embeddings, vision or speech — nr-llm composes the attached skills into a delimited block and prepends it to the user prompt. The configuration system_prompt is never modified.

Composition rules:

• Precedence. Configuration skills are the baseline, task skills are additive; the set is the union deduped by source + identifier (the configuration wins on a duplicate). The configuration block renders first.
• Budget. The block is bounded by a conservative character budget; when it is exceeded, task-additive skills are dropped before configuration-baseline skills and each drop is logged.
• Integrity. Each skill's body checksum is re-verified at injection time; a mismatch (tampering or a stale row) drops that skill — it is never injected.
• Untrusted output. Skill prose is third-party text; output produced under its influence is treated as untrusted and escaped/sanitized where it is stored or rendered. Message role is defense-in-depth, not a trust boundary.

See ADR-036 for the injection design.

The built-in example tools 

Two read-only example tools ship enabled. They are reference implementations of the security contract, not a general capability:

fetch_logs

Returns the most recent sys_log entries, newest first, with an optional PSR level filter and a limit (default 20, hard-capped at 50). Personally-identifying fields — the client IP, the backend user id and the serialized payload — are redacted by omission, because the result egresses to the external provider.

read_fal_asset_meta

Returns read-only metadata (file name, MIME type, size, title, alternative text) for a single managed file (sys_file) by its uid. The uid is model-chosen and therefore injection-steerable, so the lookup is storage-scoped (default: the default storage). A uid in a non-permitted storage returns the same neutral "not found or not permitted" string as a missing uid — the model cannot enumerate arbitrary files.

Registering a tool 

A tool is a PHP class that implements Netresearch\NrLlm\Service\Tool\ToolInterface:

getSpec(): ToolSpec

Returns the declaration the model receives — a name, a description, and a JSON-Schema parameters block. Build it with ToolSpec::function($name, $description, $parameters).

execute(array $arguments): string

Runs the tool with the model-provided arguments and returns a plain string that is fed back into the conversation as a tool turn.

The interface carries #[AutoconfigureTag('nr_llm.tool')], so a class is auto-registered simply by implementing it — no central registration file to edit. ToolRegistry collects every tagged tool through a DI iterator and indexes it by spec name; two tools with the same name is a developer error and fails fast at container build.

When you write a tool, honour the security contract: treat $arguments as attacker-influenced (the model is steerable by injected skill prose), validate and scope every input (cap volumes, scope identifier lookups), and never return secrets — the result leaves the instance.

Managing tools 

The Admin Tools > LLM > Tools module lists every registered tool with its global enable state and lets an admin toggle it. A disabled tool is refused on every run, everywhere — the runtime gate is fail-closed, so a disabled tool can never be offered to the model regardless of a skill's allowed-tools or the per-run selection in the playground. Some built-in tools (for example get_env_raw and get_php_info_raw) ship disabled by default because they return unredacted, secret-bearing output; enable them only deliberately.

Using the Tool Playground 

The playground lives in Admin Tools > LLM > Playground and is admin-only. It is a sibling of the Tools management module: the playground runs the loop, while the Tools module governs which tools exist and are enabled.

1. Pick an LLM configuration from the dropdown. Its vault-stored API key, model, temperature and system prompt are what the loop actually runs on — the playground never falls back to a default model.
2. Type a prompt and click Run.
3. Read the trace. Each tool the model called is shown in order with its name, the arguments the model chose, and the tool's result (errors are badged). The model's final answer follows the trace.

The Tools available to this run list lets you narrow a single run to a subset of the globally-enabled tools (the full list and the global enable/disable controls live in the Tools module). Every displayed string — tool arguments, tool results (which may include sys_log content), and the final answer — is rendered escaped; HTML is only ever shown inside a sandboxed preview, never injected into the page.

Each run is bounded by the iteration cap (default 5) and, when the configuration's backend user has a budget, by the per-iteration budget pre-flight. If the cap is hit with tools still pending, a final tool-free completion synthesises a closing answer and the run is marked truncated. The aggregated token usage is reported; the monetary cost is recorded in the usage table by the middleware pipeline.

Ollama model-capability dependency 

Tool calling depends on the model, not just the provider. For Ollama, only function-calling-capable models — for example llama3.1, mistral, qwen2.5 — return tool calls. A model without function-calling support simply answers the prompt directly and never calls a tool; the loop ends gracefully on the first plain answer. If a configured Ollama model never seems to use the available tools, verify it is one of the function-calling models for your Ollama version.

Gating tools with allowed-tools in a skill 

A skill's SKILL.md front-matter may carry an allowed-tools key that gates which tools the skills attached to a configuration (or task) grant for a run. The resolution is fail-closed on declaration, computed over the configuration's effective skills (enabled, non-orphaned — exactly the set that is injected into the prompt):

• Absent (no skill declares allowed-tools) — no opinion; all registered tools are offered.
• Declared list — the union of the declared lists across the effective skills; only those tools are offered (intersected with what is actually registered, so an unknown name is dropped).
• Declared empty (allowed-tools: []) — declares zero tools; if no other effective skill widens the set, the run gets no tools and is a single plain completion.

A disabled or orphaned skill never grants tools. The allow-list is enforced both when the tools are offered to the model and again when a tool call is executed, so a prompt injection cannot reach a tool the skills did not grant.

See ADR-038 for the runtime design and security rationale.

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.

Model discovery 

On the model edit form, use the Fetch Models button to query the provider API. This auto-populates available models with their capabilities, context length, and pricing metadata.

Recommended workflow 

For a fresh installation:

1. Run the Setup wizard from the dashboard to create your first provider, fetch models, and test a configuration.
2. Use the Configuration wizard to create additional use-case configurations (one per use case in your extensions).
3. Use the Task wizard to create reusable prompt templates for editors.
4. Share configuration identifiers with your extension developers — they reference them in code via $configRepository->findByIdentifier('...').

For ongoing maintenance:

• Add providers when you need additional AI services or separate prod/dev keys.
• Fetch models periodically to pick up new models from providers.
• Edit configurations to tune prompts and parameters — changes take effect immediately without code deployment.

What a budget caps 

Each row in tx_nrllm_user_budget binds to exactly one be_user and defines six independent ceilings. 0 on any axis means "unlimited on this axis".

Usage is aggregated on demand from tx_nrllm_service_usage — the same table the UsageTracker already writes to per request — so there is no second write per request and no way for a separate counter to drift away from the source of truth.

Creating a budget 

Budget records have rootLevel = -1, so admins can create them at the TYPO3 root (pid = 0) or on any regular page. Keeping them at the root is the convention because budgets are site-wide admin concerns, not page-scoped content; the recipe below follows that convention.

1. Open Web > List in the root (page UID 0) — or on the page where you keep other cross-site configuration records.
2. Click Create new record.
3. Choose LLM User Budget.
4. Pick the backend user, set the ceilings, toggle Enforce this budget on.
5. Save.

How the check runs 

Before dispatching a request the consuming extension calls NetresearchNrLlmServiceBudgetService::check(). The service:

1. Returns allowed when the user has no budget record, when Enforce this budget is off, or when every ceiling is 0.
2. Aggregates today's usage and this month's usage in a single database roundtrip.
3. Evaluates the daily window first; the monthly window only if the daily window passes.
4. Adds +1 request and +plannedCost to the usage figures before comparing, so a user at exactly the limit is still allowed one more call.

The returned BudgetCheckResult names which bucket was tripped (exceededLimit as a stable machine key, plus a human-friendly reason string suitable for log output or caller-side wrapping).

Budgets vs. configuration limits 

Both layers persist but cap different things:

See ADR-025: Per-User AI Budgets for the full design rationale, including the alternatives (counter table, group-level budgets, auto-throttling) we considered and why they were rejected.

Opening the module 

Open Admin Tools > LLM > Analytics. The submodule sits next to the other LLM sections in the left-hand navigation and is admin-only, like the rest of the module.

Choosing a date range 

A range switcher at the top of the page selects the reporting window. The range is a plain ?range= link, so changing it is an ordinary page reload — there is no AJAX. Four presets are available:

KPI tiles 

A row of tiles summarises the selected range:

• Total cost — the summed estimated cost across the window.
• Total requests — the number of AI requests recorded.
• Total tokens — prompt plus completion tokens consumed.
• Providers — how many distinct providers were used.
• Models — how many distinct models were used.

These are totals for the chosen range, not all-time figures.

Cost and requests trend 

A line chart plots daily estimated cost and daily request count across the range. Days with no usage are filled in as zero so the line is continuous rather than skipping gaps.

Breakdown charts 

Three bar charts split the window's usage along different axes:

• By provider — cost and requests per service_provider (OpenAI, Anthropic, Ollama, …).
• By model — cost and requests per model. This dimension is new: it relies on the model_uid / model_id columns added to the usage table, so it only reflects usage recorded after that change.
• By service — cost and requests per service type (chat, vision, translation, speech, image).

Per-user table 

A table lists usage grouped by backend user, ordered by cost. Each row shows the user's request count, token total, and estimated cost for the selected range, plus a monthly-budget bar that visualises how much of their per-user budget (see Per-user AI budgets) they have consumed.

Requests made without an authenticated backend user (CLI, scheduler, be_user = 0) are grouped under a system row.

A note on cost 

All cost figures are estimated. They are computed from the model pricing you configured (cents per 1M tokens, applied to the recorded prompt/completion token split), not billed back from the provider. Treat them as a planning and trend signal, not as an invoice. Costs are captured at call time, so they reflect the pricing in effect when each request ran. See ADR-029: Usage Analytics Dashboard for the design rationale.

Specialized services (DALL·E, text-to-speech, Whisper, DeepL) still record their requests and units, but their cost is currently shown as 0 — token-based pricing does not apply to them yet. Streaming responses are not recorded at all, because chunked output has no single terminal token count to price.

Usage columns in the list views 

The Providers, Models, Configurations, and Tasks list views each carry three extra columns — Cost (30d), Requests (30d) and Tokens (30d) — summarising the last 30 days of usage for that row, so you can spot the heavy hitters without leaving the list.

Two attribution notes:

• The Providers column aggregates by adapter type (the value stored on each usage row), not by individual provider record — two providers that share an adapter therefore show the same figures.
• The Tasks column relies on per-task tracking: each task execution records its task_uid so usage rolls up to the task that triggered it. Calls made outside a task (direct API/service use) are not attributed to any task row.

Demo data for local development 

To populate the module with something to look at during local development, run the dev-only DDEV command:

ddev seed-usage

It generates roughly 90 days of realistic historic usage across providers, models, services, and users so the trend line, breakdown charts, and per-user table all have content. This command is for local DDEV environments only — do not run it against production data.

Required 

Optional 

Required 

Optional 

Required 

Optional 

Provider configuration 

Providers, models and configurations are database-backed and managed in the LLM backend module — not via TypoScript. nr-llm does not read plugin.tx_nrllm TypoScript settings; any such constants/setup have no effect (this is true for both classic TypoScript templates and site sets).

To make the generic chat() / complete() entry points work without pinning a provider per call, set up a default configuration:

1. Open the LLM backend module.
2. Create a Provider (e.g. OpenAI) and store its API key as an nr-vault identifier — see API key protection.
3. Create a Model for that provider.
4. Create a Configuration bundling the model, then mark it active and default.

The Setup Wizard in the module walks through these steps.

Without an active default configuration, generic calls throw "No provider specified and no default provider configured".

Environment variables 

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

Security 

// Strip markup and control characters from free-text input before it is
// sent to a provider. (GeneralUtility::removeXSS() was removed from the
// TYPO3 core and must not be used.)
$sanitizedInput = trim(strip_tags($userInput));

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

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

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

Logging 

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

Log files: var/log/typo3_nr_llm_*.log

Caching 

The extension uses TYPO3's caching framework with cache identifier nrllm_responses.

No cache backend is specified — TYPO3 automatically uses the instance's default cache backend. If your instance has Redis, Valkey, or Memcached configured, nr-llm uses it transparently with zero configuration.

• Cache identifier: nrllm_responses
• Cache group: nrllm
• Default TTL: 3600 seconds (1 hour)
• Embeddings TTL: 86400 seconds (24 hours)

To override the backend for this cache specifically:

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

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

Clear cache:

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

Core concepts 

┌─────────────────────────────────────────┐
│         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,
    ) {}
}

Using LlmServiceManager 

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

Response objects 

See the API reference for the complete response object documentation. Key classes:

• CompletionResponse — content, model, usage, finishReason, toolCalls
• EmbeddingResponse — embeddings, model, usage
• UsageStatistics — promptTokens, completionTokens, totalTokens

Error handling 

The extension throws specific exceptions:

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
}

Events 

Best practices 

1. Use feature services for common tasks instead of raw LlmServiceManager.
2. Enable caching for deterministic operations like embeddings.
3. Handle errors gracefully with proper try-catch blocks.
4. Sanitize input before sending to LLM providers.
5. Validate output and treat LLM responses as untrusted.
6. Use streaming for long responses to improve UX.
7. Set reasonable timeouts based on expected response times.
8. Monitor usage to control costs and prevent abuse.

Usage 

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

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

The streamChat method returns a Generator that yields string chunks as the provider generates them. Each chunk contains a portion of the response text.

Providers that implement streamingcapableinterface support streaming. Check provider capabilities before using:

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

Defining tools 

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

Executing tool calls 

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

Providers that implement toolcapableinterface support tool calling.

Registering your provider 

Register your provider in Services.yaml:

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

Preferred: the #[AsLlmProvider] attribute 

Add the attribute to any provider class that lives under the Netresearch\NrLlm\ namespace. The compiler pass auto-tags the service, sets it public (so backend diagnostics can resolve it by class name), and registers it with LlmServiceManager in priority order:

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()
}

Priority is an ordering hint only. Providers are still resolved by their getIdentifier() at runtime. Higher priority wins when two providers otherwise tie.

Third-party fallback: yaml tagging 

Extensions that sit outside the Netresearch\NrLlm\ namespace still work via the original mechanism — declare a service with the nr_llm.provider tag:

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

When both yaml tagging AND the attribute are present on the same service, the yaml wins (the attribute pass skips already-tagged services). Treat this as an override hook rather than an additive mechanism.

Capability interfaces 

Priority governs registration order only; it says nothing about what a provider can do. Capabilities are advertised by implementing the relevant interface from NetresearchNrLlmProviderContract:

• VisionCapableInterface — image analysis
• StreamingCapableInterface — SSE streaming
• ToolCapableInterface — function / tool calling
• DocumentCapableInterface — PDF / structured document input

LlmServiceManager dispatches to a provider only when the caller's requested operation matches a capability the provider actually advertises. A provider that doesn't implement VisionCapableInterface can never be asked to describe an image, regardless of priority. See ADR-022: Attribute-Based Provider Registration for the attribute-discovery design decision and the Symfony registerAttributeForAutoconfiguration alternative we evaluated.

Configuring a chain 

The tx_nrllm_configuration.fallback_chain column stores a JSON object with a single key, configurationIdentifiers, whose value is the ordered array of target configuration identifiers:

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

Editors paste that JSON into the Fallback Chain tab in the backend form. The order is the retry order. Identifiers are matched case-insensitively against tx_nrllm_configuration.identifier. Using an object (rather than a bare top-level array) leaves room for future sibling fields — e.g. per-link retry policy — without a schema break.

Retryable vs. non-retryable errors 

Fallback only triggers for errors the next provider might actually recover from:

When every configuration in the chain trips a retryable error, NetresearchNrLlmProviderExceptionFallbackChainExhaustedException is thrown. It carries the per-attempt errors so consumers can surface the full failure sequence.

Scope limits 

v1 is deliberately narrow:

• No streaming. streamChatWithConfiguration() does not wrap the call. Once the first chunk has been yielded to the caller, mid-stream provider-switching would be detectable and surprising.
• No recursion. A fallback configuration's own chain is ignored. This avoids cycles (a -> b -> a) and unbounded attempt trees.
• Single primary-only chain is a no-op. If the configured chain contains only the primary's own identifier, the primary's original exception is rethrown verbatim rather than wrapped in FallbackChainExhaustedException.

Using the DTO directly 

For programmatic construction — e.g. a wizard that generates a configuration and also sets up fallback — use the NetresearchNrLlmDomainDTOFallbackChain value object:

use Netresearch\NrLlm\Domain\DTO\FallbackChain;

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

$configuration->setFallbackChainDTO($chain);

The DTO trims and lowercases identifiers on entry, deduplicates them, and silently rejects empty strings and non-string entries read from malformed JSON. See ADR-021: Provider Fallback Chain for the full design rationale and the alternatives we ruled out.

Running a check 

Inject the service and call isAllowed() before dispatching. The method accepts an optional BackendUserAuthentication for tests; when omitted it reads $GLOBALS['BE_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 ...
    }
}

Resolution order 

The check resolves in this order:

1. No BE user in context (CLI, scheduler, frontend) → allowed. Capability gating is a backend-editor concern; background jobs and frontend rendering are not subject to it.
2. User is admin → allowed. Admins bypass the native TYPO3 permission machinery by convention.
3. Delegates to $backendUser->check('custom_options', 'nrllm:capability_X') — the native TYPO3 permission check. Returns what it returns.

Complementary to configuration ACL 

The allowed_groups MM relation on tx_nrllm_configuration gates access to a specific preset (API keys, system prompt, etc.). Capability permissions gate which operations a user may invoke against any preset they can already reach. The two are orthogonal and both checks must pass.

• Configuration ACL: "Can this editor use the 'creative-writing' configuration at all?"
• Capability permission: "Can this editor invoke vision against any configuration?"

Stable keys 

CapabilityPermissionService::permissionString() returns the TYPO3 permission string (e.g. nrllm:capability_vision) for any enum case. Use it when you need to check directly without going through the service, for example in a Fluid ViewHelper or a TCA display condition:

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

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

See ADR-023: Native Backend Capability Permissions for the full design rationale and the alternatives (per-configuration flags, bespoke MM table, inline enforcement) we ruled out.

Why build on nr-llm? 

When your extension calls an LLM API directly, it takes on responsibility for:

• HTTP client setup, authentication, and error handling per provider
• Secure API key storage (not in ext_conf_template.txt or $GLOBALS)
• Response caching to control costs
• Streaming implementation for real-time UX
• A configuration UI for administrators

nr-llm handles all of this. Your extension focuses on what to ask the AI, not how to reach it.

Step 1: Add the dependency 

composer require netresearch/nr-llm

Add the dependency to your ext_emconf.php:

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

Step 2: Inject the service 

All nr-llm services are available via TYPO3's dependency injection. Pick the service that matches your use case:

<?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;
    }
}

No Services.yaml configuration needed — TYPO3's autowiring handles it.

Step 3: Use feature services for specialized tasks 

For common AI tasks, use the specialized feature services instead of raw chat:

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

Step 4: Handle errors gracefully 

nr-llm throws typed exceptions so you can provide meaningful feedback:

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.';
}

Step 5: Use database configurations (optional) 

For advanced use cases, reference named configurations that admins create in the backend module:

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

Testing your integration 

Mock the nr-llm interfaces in your unit tests:

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

Integration checklist 

1. composer.json — Added netresearch/nr-llm to require
2. ext_emconf.php — Added nr_llm to depends constraints
3. Services — Inject LlmServiceManagerInterface or feature services via DI
4. Error handling — Catch typed exceptions and show user-friendly messages
5. Testing — Mock LlmServiceManagerInterface in unit tests
6. Documentation — Tell your users they need to configure a provider in Admin Tools > LLM

Overview 

The feature services layer provides domain-specific AI capabilities for TYPO3 extensions. Each service wraps the core LlmServiceManager with specialized prompts, response parsing, and configuration optimized for specific use cases.

Architecture 

┌─────────────────────────────────────────────────────────┐
│            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.)                      │
└─────────────────────────────────────────────────────────┘

CompletionService 

Purpose: Text generation and completion.

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

VisionService 

Purpose: Image analysis and metadata generation.

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

EmbeddingService 

Purpose: Text-to-vector conversion and similarity search.

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

TranslationService 

Purpose: Language translation with quality control.

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

PromptTemplateService 

Purpose: Centralized prompt management.

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

Installation 

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

Default prompts 

The extension includes 10 default prompts optimized for common use cases:

Testing 

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

Performance 

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

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

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

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

Extension integration examples 

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

File structure 

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

Requirements 

• TYPO3 v13.4+.
• PHP 8.2+.
• nr-llm core extension (LlmServiceManager).

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.

array|null metadata

Provider-specific metadata. Structure varies by provider.

string|null thinking

Thinking/reasoning content from models that support extended thinking (e.g., Claude with thinking enabled).

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.

hasThinking ( ) : bool

Check if response contains thinking/reasoning content.

getText ( ) : string

Alias for content property.

VisionResponse 

class VisionResponse

Fully qualified name

\Netresearch\NrLlm\Domain\Model\VisionResponse

Response from vision/image analysis operations.

string description

The generated image analysis text.

string model

The model used for analysis.

UsageStatistics usage

Token usage statistics.

string provider

The provider identifier.

float|null confidence

Confidence score for the analysis (if available).

array|null detectedObjects

Detected objects in the image (if available).

array|null metadata

Provider-specific metadata.

getText ( ) : string

Get the analysis text. Alias for description property.

getDescription ( ) : string

Alias for description property.

meetsConfidence ( float $threshold) : bool

Check if confidence score meets or exceeds a threshold.

param float $threshold

Minimum confidence value

Returns

bool True if confidence is not null and meets threshold

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.