---
title: "Developer guide"
manual: "AI Universe"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:developer@1.0"
source: "Developer/Index.rst"
rendered: "2026-10-19T14:06:07+00:00"
---

# Developer guide {#developer}

Technical integration guide for extension developers.

-   [Core services](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:core-services@1.0)
-   [Dependency injection](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:dependency-injection@1.0)
-   [Request flow](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:request-flow@1.0)
-   [Example integration](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:example-integration@1.0)
-   [Embeddings](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:embeddings@1.0)
-   [Statistics and caching](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:statistics-and-caching@1.0)
-   [Logging](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:logging@1.0)
-   [Implementation notes](https://docs.typo3.org/permalink/nitsan/ns-aiuniverse:implementation-notes@1.0)

## Core services {#developer-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 {#developer-di}

Services are autowired through [`Configuration/Services.yaml`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Configuration/ServicesYaml.html#file-extension-configuration-services-yaml).

**Service registration overview**

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

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

## Request flow {#developer-request-flow}

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

## Example integration {#developer-example}

**Example use in custom service**

```php
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 {#developer-embeddings}

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

Supported embedding request handlers in code:

-   OpenAI
-   Gemini
-   Mistral

## Statistics and caching {#developer-statistics}

`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 {#developer-logging}

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

## Implementation notes {#developer-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.