What it does 

Ai3 Core is the shared core package of the Ai3 Suite. It is not a standalone user-facing extension; instead, it provides infrastructure that all other Ai3 packages depend on.

Core responsibilities:

• Authenticate against the Zak_ai REST API using credentials supplied via environment variables.
• Manage a Zak_ai registration lifecycle (API key request and confirm). the registration progress is persisted in the TYPO3 system registry.
• Maintain a generation task queue stored in tx_ai3_domain_model_generation_task. AI-generation requests can be processed asynchronously.
• Expose a capability registry that other Ai3 extensions use to register their own AI endpoints.
• Provide a TYPO3 backend module (Ai3) with a dashboard, the Zak_ai setup wizard, and view of the generation task queue.

Features 

• PSR-compliant HTTP client wrapper for the Zak_ai API
• Symfony DI compiler pass for tagged capability registration
• Extbase GenerationTask entity and repository
• Backend module
• AJAX endpoints for live Zak_ai credit and account info
• CLI: ai3_core:process_tasks
• ES module namespace @wegewerk/ai3core/

Requirements 

Installation via Composer 

Ai3 Core is installed as a dependency of other Ai3 Suite packages. It is not intended to be required directly in most projects. If you do need it explicitly, run:

composer require wegewerk/ai3_core

Environment variables 

The Zak_ai API client reads its credentials exclusively from environment variables. API_KEY and SECRET are obtained in the Backend Module.

ZAKAI_API_KEY=<your-api-key>
ZAKAI_SECRET=<your-secret>

The complete registration flow — including requesting and confirming the API key — is available through the backend module.

API base URL 

The Zak_ai API base URL is defined in Configuration/Services.yaml. To override it in a specific environment, rebind the service argument in your project's Services.yaml:

Wegewerk\Ai3Core\Api\ZakAiClient:
    arguments:
        $baseUrl: 'https://staging.zak-ai.com/api/v1/'

Or define to use another env-var:

Wegewerk\Ai3Core\Api\ZakAiClient:
    arguments:
        $baseUrl: '%env(ZAK_AI_BASE_URL)%'

Default model 

The default inference model is mistral-small3.2:latest, defined as the DEFAULT_MODEL constant in \Wegewerk\Ai3Core\Api\ZakAiClient. It is appended automatically to every POST payload.

It is not detemined yet if this should be user configurable in the future.

Dashboard 

Zak_ai management 

This Dashboard guides you through the Zak_ai registration process:

1. Generate a Secret and Provide an e-mail address.
2. Put this secret in the ``ZAKAI_SECRET'' environment variable.

3. Request API key — Sends a POST /accounts request to Zak_ai. The registration status changes to Requested. Zak_ai sends an email containing your api key.

4. Save API key After receiving the confirmation e-mail from Zak_ai, Put the API Key in the ``ZAKAI_API_KEY'' environment variable.
5. Activate API key Click Activate API key to call PUT /accounts. The status changes to Done.

The dashboard looks like this when the registration is complete.

Generation task overview 

This view lists all GenerationTask records stored in the database. Each row shows the capability, target record (table / field / UID), current status, prompt, and generated result.

This view is intended for developers to see what the queue status looks like

See Generation task for the full field reference.

ai3_core:credits 

Queries the Zak_ai credits endpoint and dumps the raw response.

vendor/bin/typo3 ai3_core:credits

Output: A var_dump() of the decoded JSON response from GET /credits. Useful for verifying that ZAKAI_API_KEY is set correctly and the API is reachable.

ai3_core:process_tasks 

Fetches up to 100 pending GenerationTask records (ordered by UID ascending) and processes each one by calling the registered capability endpoint.

vendor/bin/typo3 ai3_core:process_tasks

Processing logic per task:

1. Look up the capability identified by task.capability in the CapabilityRegistry.
2. Call capability->endpoint->generate(image, prompt, language).
3. If a result is returned, set task.result, mark the task as Done, and store task.generated_timestamp.
4. Persist all changes.

ZakAiEndpointInterface 

Every capability must implement \Wegewerk\Ai3Core\Api\ZakAiEndpointInterface:

interface ZakAiEndpointInterface
{
    public function generate(
        string $imagePath,
        string $description,
        string $language,
    ): string;
}

The generate() method receives the image path (may be empty), a text prompt, and a language code. It must return the generated text.

Registering a capability 

Tag your endpoint service with ai3.capability in your extension's Configuration/Services.yaml. The compiler pass picks up the $key, $title, and $endpoint constructor arguments automatically:

MyVendor\MyAiExt\Endpoint\SummaryEndpoint:
    tags:
        - name: ai3.capability
    arguments:
        $key: 'my_ext_summary'
        $title: 'Automatic summary'
        $endpoint: '@MyVendor\MyAiExt\Endpoint\SummaryEndpoint'

use Wegewerk\Ai3Core\Api\ZakAiEndpointInterface;

final class SummaryEndpoint implements ZakAiEndpointInterface
{
    public function generate(
        string $imagePath,
        string $description,
        string $language,
    ): string {
        // Call Zak_ai provider here.
        return 'Generated summary …';
    }
}

CapabilityRegistry 

At runtime, all registered capabilities are available via \Wegewerk\Ai3Core\Service\CapabilityRegistry. It is a SingletonInterface and can be injected via constructor:

use Wegewerk\Ai3Core\Service\CapabilityRegistry;

final class MyService
{
    public function __construct(
        private readonly CapabilityRegistry $capabilityRegistry,
    ) {}

    public function run(string $capabilityKey): string
    {
        $capability = $this->capabilityRegistry
            ->getCapability($capabilityKey);
        if ($capability === null) {
            throw new \RuntimeException(
                'Unknown capability: ' . $capabilityKey,
            );
        }
        return $capability->endpoint->generate('', 'Hello', 'en');
    }
}

TCA integration 

To expose capability selection in a FormEngine field, use the provided itemsProcFunc:

'capability' => [
    'label' => 'AI capability',
    'config' => [
        'type' => 'select',
        'renderType' => 'selectSingle',
        'itemsProcFunc' =>
            \Wegewerk\Ai3Core\FormEngine\CapabilityItemsProcFunc::class
            . '->itemsProcFunc',
    ],
],

The items list is populated dynamically from the CapabilityRegistry at render time.

Task lifecycle 

Every task moves through a set of states defined by \Wegewerk\Ai3Core\Enums\Status:

Field reference 

GenerationTaskService 

\Wegewerk\Ai3Core\Service\GenerationTaskService is the primary API for working with the task queue. Inject it via constructor:

use Wegewerk\Ai3Core\Domain\Model\Dto\AddGenerationTask;
use Wegewerk\Ai3Core\Service\GenerationTaskService;

$dto = new AddGenerationTask(
    status: 'Pending',
    prompt: 'Write a short product description.',
    image: '',
    capability: 'my_ext_summary',
    record_table: 'tt_content',
    record_field: 'bodytext',
    record_uid: 42,
    generateLanguage: 'en',
    parameters: '',
    result: '',
    result_meta: '',
    error_message: '',
);

$task = $this->generationTaskService->addTask($dto);

Useful query methods:

ZakAiClient 

ZakAiClient handles authentication and the raw HTTP layer. It reads credentials from the environment at construction time (see Environment variables). The base URL defaults to https://www.zak-ai.com/api/v1/.

Public methods:

All request methods accept optional $extraHeaders and a $requireAuth flag. When $requireAuth is true (default) and no API key is set, a \RuntimeException is thrown before the request is sent.

ZakAiAccount 

ZakAiAccount wraps the account-related endpoints:

0.9 — 2026-06-17 

• Initial version