dAi – Manual

From installation to a running chatbot – in eight steps

This manual describes the free TYPO3 extension dAi. If you work through everything in sequence, the result will be a chatbot that answers questions about your TYPO3 pages.

Allow around an hour for the first run – most of that is spent on the database.

1. Check the prerequisites

TYPO3 12.4, 13.4 or 14, installed via Composer.
PHP 8.2 or newer, with the pdo_pgsql extension.
PostgreSQL with pgvector. A separate database per project has proven effective.
An API key with Mistral, OpenAI, Google Gemini or Anthropic.

Whether pdo_pgsql is present can be checked from the command line:

Terminal bash

php -m | grep pdo_pgsql

2. Install the extension

dAi is installed via Composer. Installing through the Extension Manager does not work, because the extension comes with four runtime dependencies.

Terminal bash

composer require dreistein/d-ai

3. Set up the vector database

The semantic search requires a vector index. Create a PostgreSQL database for this and enable the vector extension in it once – this requires superuser rights:

psql sql

CREATE DATABASE typo3_dai OWNER typo3_dai;
\c typo3_dai
CREATE EXTENSION vector;

Then enter the connection in TYPO3 and assign the five dAi tables to this connection. All other tables remain where they are:

config/system/additional.php php

<?php

$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['pgvector'] = [
    'driver'   => 'pdo_pgsql',
    'host'     => '127.0.0.1',
    'port'     => 5432,
    'dbname'   => 'typo3_dai',
    'user'     => 'typo3_dai',
    'password' => 'ihr-passwort',
    'charset'  => 'utf8',
];

foreach ([
    'tx_dai_domain_model_project',
    'tx_dai_llm_config',
    'tx_dai_data_source',
    'tx_dai_ingest_job',
    'tx_dai_domain_model_document',
] as $table) {
    $GLOBALS['TYPO3_CONF_VARS']['DB']['TableMapping'][$table] = 'pgvector';
}

The order matters: first enter the assignment, then run the database comparison. Otherwise TYPO3 creates the tables on the default connection, and they will then exist twice.

Then configure the extension:

Terminal bash

vendor/bin/typo3 extension:setup --extension=d_ai

As long as something is still missing from the setup, the dAi backend module displays a setup check instead of the collections: there you will see, across six stages, where the problem lies – from the missing PHP extension to the not yet enabled vector extension – and what needs to be done in each case.

4. Configure the language model

Open the dAi module in the backend and go to LLM configurations. Create one configuration per provider: select the provider type, enter the API key, confirm the model. The interface address fills in automatically when you change the provider type.

You need two capabilities: a chat model that writes the answers, and an embedding model that translates the content into vectors for the search. Mistral, OpenAI and Gemini can do both. Anthropic (Claude) offers no embedding interface – if you want to answer with Claude, you additionally create one of the three other configurations for the embedding.

dAi backend module, LLM configurations page: list with Mistral, OpenAI and Anthropic including chat and embedding model, as well as the form for adding a further configuration. — LLM configurations: one entry per provider

5. Create a collection

A collection is a self-contained knowledge base: its own content, its own language models, its own languages, its own usage account. Each collection receives its own schema in the PostgreSQL database.

As a rule, one collection per website is sufficient. Multiple collections are worthwhile if you serve different target audiences – for example a public collection for visitors and an internal one for staff.

Overview of the collections in the dAi backend module with title, Postgres schema, language model used and modification date. — Overview of all collections

Settings of a collection in dAi: title, chat model and embedding model, languages, and the prompt fields. — Settings of a collection

6. Read in TYPO3 pages

Each collection draws its content from Data sources. The free version has exactly one type – and it covers the most common case: TYPO3 pages.

A source is configured with three settings:

Root pages. The IDs of the pages from which reading starts – comma-separated if there are several.
Depth. How many levels below are included.
Language. The language IDs to be read in. Enter multiple languages as a list (for example 0,1); dAi turns each language into a separate run.

After Synchronise now, the pages found appear as documents in the list.

The Data sources page of a collection with the configured source TYPO3 pages and the selection field for adding a further source. — Data sources of a collection

Form for editing the TYPO3 pages data source with the fields for root pages, depth and language. — Setting up the "TYPO3 pages" source

7. Processing documents

Read in does not yet mean searchable. Select the desired documents and click Process: dAi breaks the texts down into meaningful sections and has the embedding model translate them into vectors. The status thereby changes from crawled to indexed.

Using the tick in the Active column, you can control on a per-document basis what the chatbot knows. A deactivated document is retained but is no longer drawn on for any answer – handy for outdated pages that you do not yet wish to delete.

Detailed view of a collection in dAi, showing the CAG bundle, the TYPO3 Pages data source, the jobs and the list of synchronised content with status and token count per document. — Collection view with document list

8. Embedding the chatbot on a page

On the desired page, create a dAi: Chatbot (AI search) content element and select the collection and the language in the tab. Two further fields are optional:

Prompt. Additional instructions for this one element – for example a form of address or a thematic focus.
Threshold for topic distance. The distance from which a question is deemed ‘off topic’. 0 leaves the decision to dAi.

Save, open the page, ask. Nothing more is required.

The finished chatbot in the frontend: greeting, visitor question and the answer from the indexed content with an expandable list of sources. — The finished chatbot in the frontend

Let it work in the background

Processing larger stocks runs via a queue, so that no browser request has to wait for it. It is processed either via cron …

crontab bash

* * * * * cd /var/www/example.com && vendor/bin/typo3 dai:ingest:work >/dev/null 2>&1

… or via the Scheduler: there you will find the task dAi: Process ingest queue. Either one is sufficient – do not set up both at the same time.

If content changes, simply repeat Synchronise and Process. dAi recognises what has stayed the same and processes only the changes.

Usage and costs

Every call to the language model is logged. Under Usage you can see, for each collection, how many tokens were used on which day and for what purpose. If you enter your models' list prices under Configure prices, dAi converts usage into euros – exportable as an Excel or CSV file.

Usage page of a collection in dAi with month selection, price settings and export as an Excel or CSV file. — Usage per collection, exportable

Multilingual websites

A collection can hold multiple languages. The knowledge base is kept separately per language, as are prompts and help texts. On the website, you place one chatbot element per language version with the appropriate language – questions are then asked and answered wherever your visitors are.

The user interface itself is available in English, German, Dutch, French, Italian, Polish and Ukrainian; it follows the language of the backend user.

If something goes wrong

The module shows a setup check instead of the collections: In that case, a building block of the setup is still missing. The setup check goes through six stages – PHP extension, connection, database, vector extension, table assignment, schema – and identifies exactly where the problem lies. dAi can repair much of it on its own at the click of a button.
Nothing is being indexed even though documents are present: Check whether the collection really has its own LLM configuration linked. If it says ‘Default’ there, the global fallback applies – and if no key is stored for it, the processing runs into nothing without any error message.
The chatbot responds but does not cite any sources: Sources only appear for pages that are actually in the index. If the bot responds from a CAG bundle that still stems from an older state, rebuild it in the collection view.
The chatbot does not yet know a changed page: Synchronise triggers re-reading, Process generates the vectors. If the queue runs via cron, the second step happens automatically – otherwise a click on Process is sufficient.

Prefer to set it up together?

We built dAi and run it ourselves. If you would like to hand over the setup or tailor the result to your content, do get in touch – with no sales pressure and an honest assessment of whether the effort is worthwhile for your project.

Arrange an initial consultation