nr-llm
EN DE

ADR 011 · Accepted

Object-Only Options API

Status

Accepted (2024-12)

Supersedes: ADR-006

Context

ADR-006 introduced Option Objects with array backwards compatibility (union types ChatOptions|array). This dual-path approach created:

  • Unnecessary complexity in the codebase.

  • OptionsResolverTrait with 6 resolution methods.

  • fromArray() methods in all Option classes.

  • Cognitive load deciding which syntax to use.

  • Inconsistent usage patterns across the codebase.

Given that:

  • No external users exist yet (pre-release).

  • No breaking change impact on third parties.

  • Clean break is possible without migration burden.

Decision

Remove array support entirely. Use typed Option objects only:

Implementation:

  • Signatures: ?ChatOptions instead of ChatOptions|array.

  • Defaults: null creates default Options in method body.

  • Removed: OptionsResolverTrait, all fromArray() methods.

  • Preserved: Factory presets, fluent builders, validation.

Consequences

Positive:

  • ●● Type safety enforced at compile time.

  • ●● Single consistent API pattern.

  • ● Reduced codebase complexity (~250 lines removed).

  • ● No trait usage or resolution overhead.

  • ● Better IDE support without union types.

  • ◐ Cleaner method signatures.

Negative:

  • ◑ No array syntax for quick prototyping.

  • ◑ Slightly more verbose for simple cases.

Net Score: +6.0 (Strong positive - type safety and consistency outweigh minor verbosity increase)

Files changed

Deleted:

  • Classes/Service/Option/OptionsResolverTrait.php

Modified:

  • Classes/Service/Option/AbstractOptions.php - Removed fromArray() abstract.

  • Classes/Service/Option/ChatOptions.php - Removed fromArray().

  • Classes/Service/Option/EmbeddingOptions.php - Removed fromArray().

  • Classes/Service/Option/VisionOptions.php - Removed fromArray().

  • Classes/Service/Option/ToolOptions.php - Removed fromArray().

  • Classes/Service/Option/TranslationOptions.php - Removed fromArray().

  • Classes/Service/LlmServiceManager.php - Object-only signatures.

  • Classes/Service/LlmServiceManagerInterface.php - Object-only signatures.

  • Classes/Service/Feature/*Service.php - All feature services updated.

  • Classes/Specialized/Translation/LlmTranslator.php - Uses ChatOptions objects.

← All ADRs