Feature services 

// Standard completion
$response = $completionService->complete($prompt);

// JSON output
$data = $completionService->completeJson('List 5 colors as a JSON array');

// Markdown output
$markdown = $completionService->completeMarkdown('Write docs for this API');

// Factual (low creativity, high consistency)
$response = $completionService->completeFactual('What is the capital of France?');

// Creative (high creativity)
$response = $completionService->completeCreative('Write a haiku about coding');

// Structured: schema-validated JSON (strict subset, ADR-126); ->data is
// the payload, ->response the answering call, ->usage every attempt
$data = $completionService->completeStructured('Rate this text', [
    'type'       => 'object',
    'required'   => ['score', 'reason'],
    'properties' => [
        'score'  => ['type' => 'number'],
        'reason' => ['type' => 'string'],
    ],
])->data;

use Netresearch\NrLlm\Service\Feature\VisionService;

// Single image
$altText = $visionService->generateAltText(
    'https://example.com/image.jpg'
);

// Batch processing
$altTexts = $visionService->generateAltText([
    'https://example.com/img1.jpg',
    'https://example.com/img2.jpg',
]);

// Generate an alt-text suggestion for review
$altText = $visionService->generateAltText('https://example.com/image.jpg');

// Request a concise title
$title = $visionService->generateTitle('https://example.com/image.png');

// Generate detailed description
$description = $visionService->generateDescription($imageUrl);

// Custom analysis
$analysis = $visionService->analyzeImage(
    $imageUrl,
    'What colors are prominent in this image?'
);

use Netresearch\NrLlm\Service\Feature\EmbeddingService;

// Generate embedding
$vector = $embeddingService->embed('Search query text');

// Find similar
$similar = $embeddingService->findMostSimilar(
    queryVector: $vector,
    candidateVectors: $allVectors,
    topK: 5
);

// Generate embedding (cached automatically)
$vector = $embeddingService->embed('Some text');

// Full response with metadata
$response = $embeddingService->embedFull('Some text');

// Batch embedding
$vectors = $embeddingService->embedBatch(['Text 1', 'Text 2']);

// Calculate cosine similarity
$similarity = $embeddingService->cosineSimilarity($vectorA, $vectorB);

// Find most similar vectors
$results = $embeddingService->findMostSimilar(
    $queryVector,
    $candidateVectors,
    topK: 5
);

// Normalize a vector
$normalized = $embeddingService->normalize($vector);

use Netresearch\NrLlm\Service\Option\TranslationOptions;

// Basic translation
$result = $translationService->translate('Hello, world!', 'de');

// With options
$result = $translationService->translate(
    $text,
    targetLanguage: 'de',
    sourceLanguage: 'en',
    options: new TranslationOptions(
        formality: 'formal',
        domain: 'technical',
        glossary: [
            'TYPO3' => 'TYPO3',
            'extension' => 'Erweiterung',
        ],
        preserveFormatting: true,
    ),
);

// TranslationResult properties
$translation = $result->translation;
$sourceLanguage = $result->sourceLanguage;
$confidence = $result->confidence;

// Batch translation
$results = $translationService->translateBatch($texts, 'de');

// Language detection
$language = $translationService->detectLanguage($text);

// Quality scoring
$score = $translationService->scoreTranslationQuality($source, $translation, 'de');

services:
  Your\Extension\Service\YourService:
    public: true
    arguments:
      $visionService: '@Netresearch\NrLlm\Service\Feature\VisionService'
      $translationService: '@Netresearch\NrLlm\Service\Feature\TranslationService'
      $completionService: '@Netresearch\NrLlm\Service\Feature\CompletionService'
      $embeddingService: '@Netresearch\NrLlm\Service\Feature\EmbeddingService'

# Run all unit tests
Build/Scripts/runTests.sh -s unit

# Alternative: Via Composer script
composer ci:test:php:unit

// One provider request per image, with results in the same order
$altTexts = $visionService->generateAltText($imageUrls);

$analysis = $visionService->analyzeImage(
    $imageUrl,
    'Describe the visible objects for this product catalog.',
);

use Netresearch\NrLlm\Service\Option\ChatOptions;

$result = $completionService->complete(
    prompt: 'Generate text',
    options: new ChatOptions(
        temperature: 0.7,
        maxTokens: 1000,
        topP: 0.9,
        frequencyPenalty: 0.0,
        presencePenalty: 0.0,
        responseFormat: 'json',
        systemPrompt: 'Custom instructions',
        stopSequences: ["\n\n", 'END'],
    ),
);

use Netresearch\NrLlm\Service\Feature\VisionService;

class ImageAiService
{
    public function __construct(
        private readonly VisionService $visionService
    ) {}

    public function enhanceImage(string $absoluteImageUrl): array
    {
        return [
            'alt' => $this->visionService->generateAltText($absoluteImageUrl),
            'title' => $this->visionService->generateTitle($absoluteImageUrl),
        ];
    }
}