---
title: "Developer guide"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:developer@0.35"
source: "Developer/Index.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# Developer guide

This guide covers technical details for developers integrating the LLM extension
into their TYPO3 projects.

## Core concepts

### Architecture overview

The extension follows a layered architecture:

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

**Architecture overview**

```text
┌─────────────────────────────────────────┐
│         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:

**Example: Injecting LLM services**

```php
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

### Basic chat

**Example: Basic chat request**

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

### Chat with options

**Example: Chat with configuration options**

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

### Simple completion

**Example: Quick completion from a prompt**

```php
$response = $this->llmManager->complete('Explain recursion in programming');
```

### Embeddings

**Example: Generating embeddings**

```php
// 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](https://docs.typo3.org/permalink/netresearch/nr-llm:api-domain-models@0.35) 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:

**Example: Error handling**

```php
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

> [!NOTE]
> PSR-14 events (`BeforeRequestEvent`, `AfterResponseEvent`) are planned
> for a future release.

## Best practices

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