AGENTS.md — Classes

<!-- SPDX-License-Identifier: GPL-2.0-or-later -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
<!-- Managed by agent: keep sections and order; edit content, not structure. Last updated: 2026-08-19 -->

# AGENTS.md — Classes

<!-- AGENTS-GENERATED:START overview -->
## Overview
PHP 8.2+ source code with strict typing, PSR-12, PHPStan level 10. Three-tier domain: Providers -> Models -> Configurations.
<!-- AGENTS-GENERATED:END overview -->

<!-- AGENTS-GENERATED:START setup -->
## Setup
```bash
./Build/Scripts/runTests.sh -s phpstan      # Static analysis (level 10)
./Build/Scripts/runTests.sh -s cgl -n       # PHP-CS-Fixer dry-run
./Build/Scripts/runTests.sh -s cgl          # Apply fixes
./Build/Scripts/runTests.sh -s rector -n    # Rector dry-run
```
<!-- AGENTS-GENERATED:END setup -->

<!-- AGENTS-GENERATED:START tests -->
## Build/Tests
```bash
./Build/Scripts/runTests.sh -s unit         # Unit tests for Classes/
./Build/Scripts/runTests.sh -s functional   # Functional tests (DB)
```
Full test matrix in root `AGENTS.md` Commands section.
<!-- AGENTS-GENERATED:END tests -->

<!-- AGENTS-GENERATED:START filemap -->
## Key Files

| Directory | Purpose |
|-----------|---------|
| `Attribute/` | `#[AsLlmProvider]` and `#[AsTranslator]` auto-registration attributes |
| `Command/` | CLI commands (purge/reap/eval/agent-run maintenance, `SetProviderApiKeyCommand`) |
| `Controller/Backend/` | Backend module controllers, request DTOs, Response objects |
| `DependencyInjection/` | ProviderCompilerPass, TranslatorCompilerPass |
| `Domain/DTO/` | BudgetCheckResult, CapabilitySet, FallbackChain, ModelSelectionCriteria, ProviderOptions |
| `Domain/Enum/` | Backed enums for capabilities, task shape, agent-run state, tool data class / effect / egress, trust zone, governance |
| `Domain/Model/` | Extbase entities (Provider, Model, LlmConfiguration, Task, UserBudget, Skill, SkillSource, PromptSnippet, Glossary, BackendUserGroup) and the response/result types |
| `Domain/Repository/` | Glossary, LlmConfiguration, Model, PromptSnippet, Provider, Skill, SkillSource, Task, UserBudget |
| `Domain/ValueObject/` | Immutable payloads across the runtime — `ChatMessage` is the central one (constructed via `::system()` / `::user()` / `::toolResult()`) |
| `Exception/` | Core domain exceptions (access, configuration, budget, guardrail, context) — all implement `NrLlmExceptionInterface` |
| `Form/` | ModelIdElement (TCA element), ModelConstraintsWizard (field wizard), and the GuardrailItems / SiteItems / SnippetTagItems / ToolGroupItems item providers |
| `Provider/` | Chat adapters (OpenAI, Claude, Gemini, Groq, Mistral, Ollama, OpenRouter, …) and the decision adapters TypeSafe and the local decision sidecar on `AbstractDecisionProvider` (ADR-211) |
| `Provider/Contract/` | ProviderInterface, Streaming/Tool/Vision/Document/DecisionCapableInterface |
| `Provider/Exception/` | Typed provider exceptions (authentication, configuration, connection, rate limit, response, unsupported feature, circuit open, fallback exhausted) |
| `Service/` | LlmServiceManager, CacheManager, ModelSelectionService, WizardGeneratorService, BudgetService |
| `Provider/Middleware/` | Middleware pipeline (Fallback, Budget, Usage, Cache) — see ADR-026 |
| `Service/Feature/` | CompletionService, ConversationService, EmbeddingService, ToolCallingService, TranslationService, VisionService — each with its interface |
| `Service/Decision/` | DecisionService: typed decisions by a consumer-declared profile (DI tag `nr_llm.decision_profile`) on a configuration's model — natively through `LlmServiceManager::decideForConfiguration()` for a model that declares `decision`, through structured output (`StructuredDecisionAsker`) for a chat model — ADR-211 |
| `Service/Glossary/` | GlossaryResolver: the site glossary for a language pair, read by TranslationService (ADR-208) |
| `Service/Option/` | ChatOptions, DecisionOptions, EmbeddingOptions, ToolOptions, TranslationOptions, VisionOptions on `AbstractOptions`, plus the budget-aware trait and interface |
| `Service/SetupWizard/` | ProviderDetector, ModelDiscovery (facade), ConfigurationGenerator + DTOs; `Discovery/` holds one model discoverer per provider |
| `Specialized/` | Image (DALL-E, FAL), Speech (Whisper, TTS), Translation (DeepL, LLM, DeepL glossary sync) |
| `Hook/` | ProviderEndpointNormalizationHook |
| `Testing/` | Fake service doubles (`FakeCompletionService`, …) for consumers' tests |
| `Updates/` | Upgrade wizards |
| `Utility/` | SafeCastTrait, ErrorMessageSanitizerTrait |
| `Widgets/DataProvider/` | Backend dashboard widgets (MonthlyCost, RequestsByProvider) |
<!-- AGENTS-GENERATED:END filemap -->

<!-- AGENTS-GENERATED:START code-style -->
## Code Style
- `declare(strict_types=1);` required in ALL files
- All properties MUST be typed, all methods MUST have return types
- PSR-12 via PHP-CS-Fixer
- DTOs: `final readonly class` with typed constructor properties
- Domain models: extend `AbstractEntity` for Extbase persistence
<!-- AGENTS-GENERATED:END code-style -->

<!-- AGENTS-GENERATED:START architecture -->
## Architecture Rules (PHPat enforced)
1. Controllers must NOT depend on Repositories directly
2. Domain\Model must NOT depend on Domain\Repository
3. Domain\Model must NOT depend on Controller
4. DTOs must be readonly with typed properties only
5. Domain models excluded from mutation testing

See `Tests/Architecture/` for enforcement tests.
<!-- AGENTS-GENERATED:END architecture -->

<!-- AGENTS-GENERATED:START patterns -->
## Patterns

### New Provider
1. Create in `Provider/` extending `AbstractProvider`
2. Implement capability interfaces from `Provider/Contract/` and add the `#[AsLlmProvider(priority: ...)]` attribute (auto-registers via `ProviderCompilerPass`); return the identifier from `ProviderInterface::getIdentifier()`
3. Add to `AdapterType` enum (`Domain/Model/AdapterType.php`)
4. Add the provider icon to `Resources/Public/Icons/provider-<identifier>.svg`
5. Add unit tests in `Tests/Unit/Provider/`
6. Add integration tests in `Tests/Integration/Provider/`

### New Feature Service
1. Create in `Service/Feature/`
2. Accept option object from `Service/Option/`
3. Return typed response from `Domain/Model/`
4. Add to `LlmServiceManager` public API

### Touching the public surface (`@api`)
- Add an ADR under `Documentation/Adr/` (format `Adr<N>Description.rst`) — it lands **before** the implementation PR, not inside it. `AdrReferenceIntegrityTest` refuses a reference to a record that does not exist; that the record arrived first is not machine-checked.
- `Tests/Unit/Api/api-surface.txt` freezes every `@api` signature, constructors included — the class's own, or one inherited from a base inside `Netresearch\NrLlm` (bases from TYPO3 core or the SPL are left out because they differ across the version matrix). The failure says whether the diff is additive (regenerate + `### Added`) or breaking (decide first).
- Removals follow `Documentation/Api/Deprecation.rst`, whose inventory is asserted against the `@deprecated` docblocks in both directions.

### Linking between backend controllers
Use the full Extbase alias `Backend\<Name>` (e.g. `'controller' => 'Backend\\TaskWizard'`), not the short name — `resolveControllerAliasFromControllerClassName()` keeps the segment after `Controller\`, so a short alias yields an empty URL / `InvalidControllerNameException`. Namespaced backend arguments are OFF here, so use bare `controller`/`action` keys (NOT `tx_nrllm_task[...]`). Introduced by ADR-027's TaskController split.
<!-- AGENTS-GENERATED:END patterns -->

<!-- AGENTS-GENERATED:START utilities -->
## Shared Utilities — Don't Reinvent

- **Type coercion**: `Utility/SafeCastTrait` exposes private helpers (`toStr`, `toInt`, `toFloat`) for internal coercion when raw values come from untrusted sources. Use them inside the trait consumer; do not invent `safeIntCast`-style public methods.
- **Error-message sanitizing**: `Utility/ErrorMessageSanitizerTrait::sanitizeErrorMessage()` strips secret-bearing query parameters (`?key=`, `?token=`, …) before a message is logged or surfaced. Use the trait; do not copy the regex.
- **Provider invocation**: `Domain/DTO/FallbackChain.php` defines fallback chains; `Provider/Middleware/FallbackMiddleware.php` enforces them at runtime. Always go through the middleware pipeline rather than calling provider classes directly — it handles retries, fallback ordering, and error mapping.
- **Cost tracking**: `Provider/Middleware/UsageMiddleware.php` records usage after each successful provider call via `UsageTrackerServiceInterface::trackUsage()`. Don't write to the usage table directly.
- **Cache config**: `Configuration/Caching.php` declares the `nrllm_responses` cache. Add new caches there (no hardcoded backend — let the host instance configure Redis/Valkey/Memcached).
<!-- AGENTS-GENERATED:END utilities -->

<!-- AGENTS-GENERATED:START security -->
## Security
- API keys stored as nr-vault UUID identifiers (envelope encryption via nr-vault extension)
- Input validation via typed DTOs
- Output treated as untrusted content
- Provider exceptions never expose API keys
<!-- AGENTS-GENERATED:END security -->

<!-- AGENTS-GENERATED:START checklist -->
## PR Checklist
- [ ] `declare(strict_types=1);` present
- [ ] All properties and return types declared
- [ ] PHPStan level 10 passes
- [ ] PHP-CS-Fixer passes
- [ ] Architecture tests pass
- [ ] Unit tests cover new code
<!-- AGENTS-GENERATED:END checklist -->

<!-- AGENTS-GENERATED:START examples -->
## Examples
> **Look at real code, not these stubs.**
> - Provider: `Provider/OpenAiProvider.php`
> - DTO: `Controller/Backend/DTO/ExecuteTaskRequest.php`
> - Feature service: `Service/Feature/CompletionService.php`
> - Option: `Service/Option/ChatOptions.php`
> - Wizard: `Service/SetupWizard/ProviderDetector.php`
<!-- AGENTS-GENERATED:END examples -->

<!-- AGENTS-GENERATED:START help -->
## When Stuck
- Architecture decisions: `Documentation/Adr/`
- API reference: `Documentation/Api/`
- Run `./Build/Scripts/runTests.sh -s phpstan` to check types
<!-- AGENTS-GENERATED:END help -->