Developer guide 

Core services 

AiRequestService

Sends provider requests, handles response parsing, and logs request outcomes.

BaseClient

Builds provider-specific request payloads and extracts provider-specific responses.

AiStatisticsService

Fetches OpenAI usage data, transforms result sets, and prepares chart-ready data.

AiEngineConfiguration

Exposes configured engines and filters engines based on available API keys.

HttpAuthUtility

Adds basic auth headers and provides protected URL fetch utility behavior.

AiUniverseUtilityHelper

Utility methods for extension configuration, TYPO3 version data, and page/language helpers.

Dependency injection 

Services are autowired through Configuration/Services.yaml.

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  NITSAN\NsAiUniverse\:
    resource: '../Classes/*'

Request flow 

1. Consumer calls AiRequestService::sendRequest().
2. Service merges defaults and incoming options.
3. BaseClient::getRequestData() builds provider-specific endpoint + body.
4. TYPO3 RequestFactory sends request.
5. BaseClient::getResponseData() extracts generated text.
6. AiLogService stores status log entry.

Example integration 

use NITSAN\NsAiUniverse\Service\AiRequestService;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$ai = GeneralUtility::makeInstance(AiRequestService::class);

$text = $ai->sendRequest(
    'openai',
    [['role' => 'user', 'content' => 'Summarize this page in 3 bullets.']],
    'gpt-4o',
    ['temperature' => 0.3, 'max_tokens' => 300],
    true,
    'my_extension',
    'summary'
);

Embeddings 

Use BaseClient::getEmbeddingRequestData() and BaseClient::parseEmbeddingResponse() for embedding workflows.

Supported embedding request handlers in code:

• OpenAI
• Gemini
• Mistral

Statistics and caching 

AiStatisticsService:

• fetches OpenAI usage API data
• paginates if needed
• transforms data via AiUniverseChartHelper
• stores processed results in nsaiuniverse_statistics cache
• default cache TTL is 24 hours for statistics snapshots

Logging 

Request outcomes are written to sys_log via AiLogService. Use this for operational tracing and debugging.

Implementation notes 

• Provider capabilities and models evolve quickly; keep defaults reviewed.
• Error handling should be explicit around network failures and provider API errors.
• For security-sensitive environments, review how extension configuration is managed.