API reference

Complete API reference for the TYPO3 LLM extension.

LlmServiceManager

The central service for all LLM operations.

class LlmServiceManager

Fully qualified name: \Netresearch\NrLlm\Service\LlmServiceManager

Orchestrates LLM providers and provides unified API access.

chat ( array $messages, array|ChatOptions $options = []) : CompletionResponse

Execute a chat completion request.

param array $messages: Array of message objects with 'role' and 'content' keys
param array|ChatOptions $options: Optional configuration

Message Format:

$messages = [
    ['role' => 'system', 'content' => 'You are a helpful assistant.'],
    ['role' => 'user', 'content' => 'Hello!'],
    ['role' => 'assistant', 'content' => 'Hi there!'],
    ['role' => 'user', 'content' => 'How are you?'],
];

Returns: CompletionResponse

complete ( string $prompt, array|ChatOptions $options = []) : CompletionResponse

Simple completion from a single prompt.

param string $prompt: The prompt text
param array|ChatOptions $options: Optional configuration

Returns: CompletionResponse

embed ( string|array $text, array $options = []) : EmbeddingResponse

Generate embeddings for text.

param string|array $text: Single text or array of texts
param array $options: Optional configuration

Returns: EmbeddingResponse

streamChat ( array $messages, array $options = []) : Generator

Stream a chat completion response.

param array $messages: Array of message objects
param array $options: Optional configuration

Returns: Generator yielding string chunks

chatWithTools ( array $messages, array $tools, array $options = []) : CompletionResponse

Chat with tool/function calling capability.

param array $messages: Array of message objects
param array $tools: Array of tool definitions
param array $options: Optional configuration

Returns: CompletionResponse with potential tool calls

getProvider ( string $identifier) : ProviderInterface

Get a specific provider by identifier.

param string $identifier: Provider identifier (openai, claude, gemini)
throws: ProviderNotFoundException

Returns: ProviderInterface

getAvailableProviders ( ) : array

Get all configured and available providers.

Returns: array<string, ProviderInterface>

Feature services

CompletionService

class CompletionService

Fully qualified name: \Netresearch\NrLlm\Service\Feature\CompletionService

High-level text completion with format control.

complete ( string $prompt, array $options = []) : CompletionResponse

Standard text completion.

param string $prompt: The prompt text
param array $options: Optional configuration

Returns: CompletionResponse

completeJson ( string $prompt, array $options = []) : array

Completion with JSON output parsing.

param string $prompt: The prompt text
param array $options: Optional configuration

Returns: array Parsed JSON data

completeMarkdown ( string $prompt, array $options = []) : string

Completion with markdown formatting.

param string $prompt: The prompt text
param array $options: Optional configuration

Returns: string Markdown formatted text

completeFactual ( string $prompt, array $options = []) : CompletionResponse

Low-creativity completion for factual responses.

param string $prompt: The prompt text
param array $options: Optional configuration (temperature defaults to 0.1)

Returns: CompletionResponse

completeCreative ( string $prompt, array $options = []) : CompletionResponse

High-creativity completion for creative content.

param string $prompt: The prompt text
param array $options: Optional configuration (temperature defaults to 1.2)

Returns: CompletionResponse

EmbeddingService

class EmbeddingService

Fully qualified name: \Netresearch\NrLlm\Service\Feature\EmbeddingService

Text-to-vector conversion with caching and similarity operations.

embed ( string $text) : array

Generate embedding vector for text (cached).

param string $text: The text to embed

Returns: array<float> Vector representation

embedFull ( string $text) : EmbeddingResponse

Generate embedding with full response metadata.

param string $text: The text to embed

Returns: EmbeddingResponse

embedBatch ( array $texts) : array

Generate embeddings for multiple texts.

param array $texts: Array of texts

Returns: array<array<float>> Array of vectors

cosineSimilarity ( array $a, array $b) : float

Calculate cosine similarity between two vectors.

param array $a: First vector
param array $b: Second vector

Returns: float Similarity score (-1 to 1)

findMostSimilar ( array $queryVector, array $candidates, int $topK = 5) : array

Find most similar vectors from candidates.

param array $queryVector: The query vector
param array $candidates: Array of candidate vectors
param int $topK: Number of results to return

Returns: array Sorted by similarity (highest first)

normalize ( array $vector) : array

Normalize a vector to unit length.

param array $vector: The vector to normalize

Returns: array Normalized vector

VisionService

class VisionService

Fully qualified name: \Netresearch\NrLlm\Service\Feature\VisionService

Image analysis with specialized prompts.

generateAltText ( string $imageUrl) : string

Generate WCAG-compliant alt text.

param string $imageUrl: URL or local path to image

Returns: string Accessibility-optimized alt text

generateTitle ( string $imageUrl) : string

Generate SEO-optimized image title.

param string $imageUrl: URL or local path to image

Returns: string SEO-friendly title

generateDescription ( string $imageUrl) : string

Generate detailed image description.

param string $imageUrl: URL or local path to image

Returns: string Detailed description

analyzeImage ( string $imageUrl, string $prompt) : string

Custom image analysis with specific prompt.

param string $imageUrl: URL or local path to image
param string $prompt: Analysis prompt

Returns: string Analysis result

TranslationService

class TranslationService

Fully qualified name: \Netresearch\NrLlm\Service\Feature\TranslationService

Language translation with quality control.

translate ( string $text, string $targetLanguage, ?string $sourceLanguage = null, array $options = []) : TranslationResult

Translate text to target language.

param string $text: Text to translate
param string $targetLanguage: Target language code (e.g., 'de', 'fr')
param string|null $sourceLanguage: Source language code (auto-detected if null)
param array $options: Translation options

Options:

formality: 'formal', 'informal', 'default'
domain: 'technical', 'legal', 'medical', 'general'
glossary: array of term translations
preserve_formatting: bool

Returns: TranslationResult

translateBatch ( array $texts, string $targetLanguage, array $options = []) : array

Translate multiple texts.

param array $texts: Array of texts
param string $targetLanguage: Target language code
param array $options: Translation options

Returns: array<TranslationResult>

detectLanguage ( string $text) : string

Detect the language of text.

param string $text: Text to analyze

Returns: string Language code

scoreTranslationQuality ( string $source, string $translation, string $targetLanguage) : float

Score translation quality.

param string $source: Original text
param string $translation: Translated text
param string $targetLanguage: Target language code

Returns: float Quality score (0.0 to 1.0)

Domain models

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.

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.

getText ( ) : string: Alias for content property.

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

Option classes

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.

Provider interface

interface ProviderInterface

Fully qualified name: \Netresearch\NrLlm\Provider\Contract\ProviderInterface

Contract for LLM providers.

getName ( ) : string: Get human-readable provider name.

getIdentifier ( ) : string: Get provider identifier for configuration.

isConfigured ( ) : bool: Check if provider has required configuration.

chatCompletion ( array $messages, array $options = []) : CompletionResponse: Execute chat completion.

getAvailableModels ( ) : array: Get list of available models.

interface EmbeddingCapableInterface

Fully qualified name: \Netresearch\NrLlm\Provider\Contract\EmbeddingCapableInterface

Contract for providers supporting embeddings.

embeddings ( string|array $input, array $options = []) : EmbeddingResponse: Generate embeddings.

interface VisionCapableInterface

Fully qualified name: \Netresearch\NrLlm\Provider\Contract\VisionCapableInterface

Contract for providers supporting vision/image analysis.

analyzeImage ( string $imageUrl, string $prompt, array $options = []) : CompletionResponse: Analyze an image.

interface StreamingCapableInterface

Fully qualified name: \Netresearch\NrLlm\Provider\Contract\StreamingCapableInterface

Contract for providers supporting streaming.

streamChatCompletion ( array $messages, array $options = []) : Generator: Stream chat completion.

interface ToolCapableInterface

Fully qualified name: \Netresearch\NrLlm\Provider\Contract\ToolCapableInterface

Contract for providers supporting tool/function calling.

chatWithTools ( array $messages, array $tools, array $options = []) : CompletionResponse: Chat with tool calling.

Exceptions

class ProviderException

Fully qualified name: \Netresearch\NrLlm\Provider\Exception\ProviderException

Base exception for provider errors.

getProvider ( ) : string: Get the provider that threw the exception.

class AuthenticationException

Fully qualified name: \Netresearch\NrLlm\Provider\Exception\AuthenticationException

Thrown when API authentication fails.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

class RateLimitException

Fully qualified name: \Netresearch\NrLlm\Provider\Exception\RateLimitException

Thrown when rate limits are exceeded.

Extends \Netresearch\NrLlm\Provider\Exception\ProviderException

getRetryAfter ( ) : int: Get seconds to wait before retry.

class InvalidArgumentException

Fully qualified name: \Netresearch\NrLlm\Exception\InvalidArgumentException

Thrown for invalid method arguments.

class ConfigurationNotFoundException

Fully qualified name: \Netresearch\NrLlm\Exception\ConfigurationNotFoundException

Thrown when a named configuration is not found.

Events

class BeforeRequestEvent

Fully qualified name: \Netresearch\NrLlm\Event\BeforeRequestEvent

Dispatched before sending request to provider.

getMessages ( ) : array: Get the messages being sent.

getOptions ( ) : array: Get the request options.

setOptions ( array $options) : void: Modify request options.

getProvider ( ) : string: Get the target provider.

class AfterResponseEvent

Fully qualified name: \Netresearch\NrLlm\Event\AfterResponseEvent

Dispatched after receiving response from provider.

getResponse ( )

Get the response object.

Returns: CompletionResponse or EmbeddingResponse

getProvider ( ) : string: Get the provider that responded.

getDuration ( ) : float: Get request duration in seconds.