---
title: "ADR-003: Typed Response Objects"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-003@0.35"
source: "Adr/Adr003TypedResponseObjects.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# ADR-003: Typed Response Objects

-   *Status:* Accepted
-   *Date:* 2024-01
-   *Authors:* Netresearch DTT GmbH

## Context

Provider APIs return different response structures. We needed to:

-   Provide consistent response format to consumers.
-   Enable IDE autocompletion and type checking.
-   Include relevant metadata (usage, model, finish reason).

## Decision

Use **immutable value objects** for responses:

**Example: CompletionResponse value object**

```php
final class CompletionResponse
{
    public function __construct(
        public readonly string $content,
        public readonly string $model,
        public readonly UsageStatistics $usage,
        public readonly string $finishReason,
        public readonly string $provider,
        public readonly ?array $toolCalls = null,
    ) {}
}
```

Key characteristics:

-   `final` classes prevent inheritance issues.
-   `readonly` properties ensure immutability.
-   Constructor promotion for concise definition.
-   Nullable for optional data.

## Consequences

**Positive:**

-   ●● Strong typing with IDE support.
-   ● Immutable objects are thread-safe.
-   ●● Clear API contract.
-   ● Easy testing and mocking.

**Negative:**

-   ◑ Cannot extend responses.
-   ✕ Breaking changes require new properties.
-   ◑ Slight memory overhead vs arrays.

**Net Score:** +5.5 (Strong positive impact - type
safety and immutability outweigh flexibility
limitations)