AiM is the central AI layer for TYPO3. Extensions describe what they need. AiM decides which provider and model to use, routes through a middleware pipeline, and returns the result. Built for TYPO3 v12, v13, and v14.
New to AiM? Read the Introduction for a non-technical overview of what AiM does, why it exists, and how it works for administrators and extension developers.
Alpha state. AiM is under active development. The API is functional but may change before 1.0. We'd love your feedback: open an issue or reach out at b13.com.
use B13\Aim\Ai;
public function __construct(private readonly Ai $ai) {}
$response = $this->ai->vision(
imageData: base64_encode($fileContent),
mimeType: 'image/jpeg',
prompt: 'Generate alt text for this image',
extensionKey: 'my_extension',
);
echo $response->content; // "A golden retriever playing fetch in a sunny park"A few lines to add AI to any TYPO3 extension. No API keys in your code, no provider lock-in, full logging and cost tracking out of the box.
For extension developers:
- Simple proxy API (
$ai->vision(),$ai->text(),$ai->translate(),$ai->embed()) - Fluent builder for advanced parameters
- Direct pipeline access for full control
- Structured output (JSON Schema), tool calling, streaming
For administrators:
- Backend modules for provider management and request monitoring
- Disable specific models per provider via clickable badges
- Budget limits and rate limiting per user (including admins as a safety net)
- Privacy levels (standard / reduced / none) per provider
- Provider group restrictions and capability permissions via native TYPO3 mechanisms
- LLM grading: score response quality with a second model acting as a judge
Under the hood:
- Zero provider dependencies. Install Symfony AI bridge packages as needed.
- Auto-discovery of installed bridges (OpenAI, Anthropic, Gemini, Mistral, Ollama, etc.)
- Capability-based routing with model-level awareness
- Auto model switch: one config covers all capabilities
- Smart routing: routes simple prompts to cheaper models based on historical cost, reliability, and (with grading) quality data
- Fallback chains: automatic retry with alternative providers on failure
- 9-layer middleware pipeline: retry, access control, smart routing, capability validation, grading, logging, cost tracking, events, dispatch
composer require b13/aimAiM has zero AI provider dependencies. Install provider bridges as needed:
# For OpenAI
composer require symfony/ai-open-ai-platform
# For local models via Ollama
composer require symfony/ai-ollama-platform
# For Anthropic, Gemini, Mistral, etc.
composer require symfony/ai-anthropic-platform
composer require symfony/ai-gemini-platform
composer require symfony/ai-mistral-platformAny installed symfony/ai-*-platform package is auto-discovered at container compile time. Models, capabilities, and features are read from the bridge's ModelCatalog automatically.
After installation, create a provider configuration in the backend (Admin Tools > AiM > Providers) with your API key and preferred model.
Local providers (Ollama, LM Studio): The API Key field doubles as the endpoint URL. Enter
http://localhost:11434(Ollama) orhttp://localhost:1234(LM Studio) instead of a key. The available models are then fetched live from that endpoint.
Once a provider configuration exists, you can fire requests without writing an extension first. The aim:test command sends a one-off request through the full pipeline and reports the response, model used, token usage, cost, timing, and whether a request-log row was written:
# Text generation (default capability)
vendor/bin/typo3 aim:test text --prompt "Write a haiku about TYPO3"
# Conversation, against a specific provider
vendor/bin/typo3 aim:test conversation -p "anthropic:*" --prompt "Explain dependency injection"
# Translation
vendor/bin/typo3 aim:test translate --prompt "Hello world" --from English --to German
# Embeddings
vendor/bin/typo3 aim:test embed --prompt "TYPO3 is an open-source CMS"The capability is a positional argument (text, conversation, translate, or embed; defaults to text). Options:
| Option | Purpose |
|---|---|
--prompt |
The prompt / text to send |
--provider / -p |
Provider notation (openai:gpt-4o, anthropic:*); defaults to the configured default |
--site |
Resolve the provider from a site's settings.yaml instead of the database; takes precedence over --provider |
--system-prompt |
Optional system prompt |
--max-tokens |
Token limit for the response |
--from / --to |
Source / target language (translate only) |
Because it runs through the real pipeline, every call also lands in the request log. A quick way to see logging, cost tracking, smart routing, and grading in action before integrating the API into your own code.
The simplest way. Extensions never see providers, configurations, or API keys:
use B13\Aim\Ai;
public function __construct(
private readonly Ai $ai,
) {}
// Vision (e.g. alt text generation)
$response = $this->ai->vision(
imageData: base64_encode($fileContent),
mimeType: 'image/jpeg',
prompt: 'Generate alt text for this image',
extensionKey: 'my_extension',
);
echo $response->content;
// Text generation
$response = $this->ai->text(
prompt: 'Write a meta description for a bakery website.',
maxTokens: 160,
extensionKey: 'my_extension',
);
// Translation
$response = $this->ai->translate(
text: 'Hello world',
sourceLanguage: 'English',
targetLanguage: 'German',
extensionKey: 'my_extension',
);
// Conversation
$response = $this->ai->conversation(
messages: [new UserMessage('What is TYPO3?')],
systemPrompt: 'You are a CMS expert.',
extensionKey: 'my_extension',
);
// Embeddings
$response = $this->ai->embed(
input: 'TYPO3 is an open-source CMS',
dimensions: 256,
extensionKey: 'my_extension',
);Extensions can request a specific provider without hardcoding configuration UIDs:
// Use OpenAI, admin picks the model
$response = $this->ai->text(
prompt: 'Summarize this.',
provider: 'openai:*',
extensionKey: 'my_extension',
);
// Use a specific model
$response = $this->ai->vision(
imageData: $data,
mimeType: 'image/jpeg',
prompt: 'Describe this image',
provider: 'openai:gpt-4.1',
extensionKey: 'my_extension',
);If the requested provider is unavailable, AiM falls back to the default with a logged warning.
More control over parameters, still provider-agnostic:
$response = $this->ai->request()
->vision($imageData, 'image/jpeg')
->prompt('Generate alt text for this image')
->systemPrompt('You are an accessibility expert.')
->maxTokens(100)
->temperature(0.3)
->provider('openai:*')
->from('my_extension')
->send();Full control. You choose the provider, build the request, and dispatch through the pipeline:
use B13\Aim\Capability\TextGenerationCapableInterface;
use B13\Aim\Middleware\AiMiddlewarePipeline;
use B13\Aim\Provider\ProviderResolver;
use B13\Aim\Request\TextGenerationRequest;
$resolvedProvider = $this->providerResolver->resolveForCapability(
TextGenerationCapableInterface::class
);
$request = new TextGenerationRequest(
configuration: $resolvedProvider->configuration,
prompt: 'Write a meta description for a bakery website.',
maxTokens: 160,
metadata: ['extension' => 'my_extension'],
);
$response = $this->pipeline->dispatch($request, $resolvedProvider);All three tiers flow through the same middleware chain: Logging, governance, cost tracking, and events always fire regardless of how the request was initiated.
use B13\Aim\Request\ResponseFormat;
$response = $this->ai->text(
prompt: 'Extract the product name and price from: "The MacBook Pro costs $2449.99"',
responseFormat: ResponseFormat::jsonSchema('product', [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string'],
'price' => ['type' => 'number'],
],
'required' => ['name', 'price'],
'additionalProperties' => false,
]),
extensionKey: 'my_extension',
);
$data = json_decode($response->content, true);use B13\Aim\Request\ToolCallingRequest;
use B13\Aim\Request\ToolDefinition;
use B13\Aim\Request\Message\UserMessage;
$request = new ToolCallingRequest(
configuration: $resolvedProvider->configuration,
messages: [new UserMessage('What is the weather in Berlin?')],
tools: [
new ToolDefinition(
name: 'get_weather',
description: 'Get current weather for a city',
parameters: [
'type' => 'object',
'properties' => [
'city' => ['type' => 'string', 'description' => 'City name'],
],
'required' => ['city'],
'additionalProperties' => false,
],
strict: true,
),
],
);
$response = $this->pipeline->dispatch($request, $resolvedProvider);
if ($response->requiresToolExecution()) {
foreach ($response->toolCalls as $toolCall) {
// $toolCall->name, $toolCall->getDecodedArguments()
}
}Each provider implements one or more capability interfaces:
| Interface | Request | Response | Use Case |
|---|---|---|---|
VisionCapableInterface |
VisionRequest |
TextResponse |
Image analysis, alt text generation |
ConversationCapableInterface |
ConversationRequest |
ConversationResponse |
Conversations, chatbots, multi-turn dialogs |
TextGenerationCapableInterface |
TextGenerationRequest |
TextResponse |
Content generation, summaries |
TranslationCapableInterface |
TranslationRequest |
TextResponse |
Text translation |
ToolCallingCapableInterface |
ToolCallingRequest |
ToolCallingResponse |
Agentic workflows, function calling |
EmbeddingCapableInterface |
EmbeddingRequest |
EmbeddingResponse |
Vector embeddings, semantic search, RAG |
Providers can declare per-model capabilities via modelCapabilities. Models listed get only the specified capabilities. Unlisted models inherit all provider capabilities except specialized ones (e.g. embedding-only models).
#[AsAiProvider(
identifier: 'openai',
supportedModels: ['gpt-4o' => 'GPT-4o', 'text-embedding-3-small' => 'Embeddings'],
modelCapabilities: [
'text-embedding-3-small' => [EmbeddingCapableInterface::class],
// gpt-4o inherits all capabilities EXCEPT embedding
],
)]When a provider config has gpt-4o but an embedding request comes in, AiM automatically switches to the cheapest capable model (e.g. text-embedding-3-small) using the same API key. The selection is data-driven: if historical cost data exists in the request log, AiM picks the cheapest model with a good success rate. Otherwise it falls back to the most specialized model.
The switch is:
- Logged with
model_requested,model_used, and reroute reason - Controllable at three levels:
| Level | Setting | Default |
|---|---|---|
| Per config | auto_model_switch toggle in TCA |
On |
| Per user/group | aim.autoModelSwitch = 0 in TSconfig |
On |
| Admin | Always allowed | - |
Any extension can add AI providers. Create a class implementing AiProviderInterface plus any capability interfaces, and annotate it with #[AsAiProvider]:
use B13\Aim\Attribute\AsAiProvider;
use B13\Aim\Capability\TextGenerationCapableInterface;
use B13\Aim\Capability\VisionCapableInterface;
use B13\Aim\Provider\AiProviderInterface;
#[AsAiProvider(
identifier: 'my-provider',
name: 'My AI Provider',
description: 'Custom provider for my use case',
supportedModels: [
'my-model-v1' => 'My Model v1',
'my-model-v2' => 'My Model v2',
],
features: [
'supportsStructuredOutput' => true,
'supportsStreaming' => true,
'maxContextWindow' => 128000,
],
)]
class MyProvider implements AiProviderInterface, TextGenerationCapableInterface, VisionCapableInterface
{
public function processTextGenerationRequest(TextGenerationRequest $request): TextResponse { ... }
public function processVisionRequest(VisionRequest $request): TextResponse { ... }
}The provider is auto-discovered via the PHP attribute. No manual registration needed.
AiM auto-discovers any installed Symfony AI bridge package (symfony/ai-*-platform). For each bridge:
- Reads the PSR-4 namespace from the package's
composer.json - Instantiates the bridge's
ModelCatalogto read models and per-model capabilities - Maps Symfony AI
Capabilityenums to AiM capability interfaces - Sanitizes model names for TCA compatibility (no colons)
- Detects the factory authentication parameter via reflection (
apiKeyvsendpoint) - Registers a
SymfonyAiPlatformAdapteras an AiM provider
Install a bridge, flush caches. The provider appears automatically in the backend module with all its models.
AiM provides a complete governance system for AI usage, built on native TYPO3 mechanisms.
Provider API keys stored in tx_aim_configuration.api_key are encrypted using a key derived from $GLOBALS['TYPO3_CONF_VARS']['SYS']['encryptionKey'].
| TYPO3 version | Cipher | Implementation |
|---|---|---|
| v14+ | XChaCha20-Poly1305 AEAD | Core \TYPO3\CMS\Core\Crypto\Cipher\CipherService |
| v12 / v13 | XSalsa20-Poly1305 secretbox | Local libsodium implementation (CipherService not yet available) |
Stored values carry a version prefix (aim:enc:v1: for the v12/v13 path, aim:enc:v2: for the v14 path) so decryption auto-selects the right routine even after an upgrade. Encryption is transparent: a DataHandler hook encrypts on save, a FormDataProvider decrypts for the backend edit form, and the repository decrypts on read. Legacy plaintext rows from earlier AiM versions are migrated via the "[AiM] Encrypt stored provider API keys" upgrade wizard in the Install Tool.
For providers that put an endpoint URL in the api_key field instead of a real secret (Ollama, LM Studio, self-hosted OpenAI-compatible proxies), AiM detects the http:// / https:// prefix and skips encryption — the URL stays plaintext both in the column and in DB exports.
If SYS/encryptionKey is rotated, existing API keys can no longer be decrypted with the new key. Run the rotation command before the rotation takes effect, or right after with the old value still in hand:
vendor/bin/typo3 aim:rotateApiKeys --old-key='<previous SYS/encryptionKey value>'The command decrypts each stored key with the supplied old value, re-encrypts with the current one, and reports the result. It is idempotent (re-running with the same old key is a no-op) and aborts without writes if any row cannot be decrypted with the supplied value. Add --dry-run to preview.
Without the previous key value, encrypted API keys cannot be recovered. This is by design. Save the old SYS/encryptionKey somewhere safe before rotating.
Restrict provider configurations to specific backend user groups via the be_groups field on each configuration record. Only members of the listed groups (or admins) can use that configuration.
Register AiM capability permissions in backend user groups (Access > Custom Options):
aim:capability_text: Text generationaim:capability_vision: Vision requestsaim:capability_translation: Translationsaim:capability_conversation: Conversationsaim:capability_embedding: Embeddingsaim:capability_toolcalling: Tool calling
Permissive by default: if no AiM permissions are configured in any group, all capabilities are allowed. Once any aim: permission is set, only explicitly granted capabilities are allowed.
aim {
budget {
period = monthly
maxCost = 50.00
maxTokens = 500000
maxRequests = 1000
}
rateLimit {
requestsPerMinute = 10
}
}
Budgets are tracked per user in rolling periods (daily/weekly/monthly) in tx_aim_usage_budget. When exceeded, requests are blocked with a clear error message.
Budgets and rate limits apply to all users, including admins. Admins skip provider group restrictions and capability permissions, but budgets and rate limits act as a safety net against accidental cost overruns. An admin can set their own limits via UserTSconfig and will be blocked when exceeded.
Each provider configuration has a privacy level:
| Level | Behavior |
|---|---|
standard |
Full logging: prompt, response, tokens, cost |
reduced |
Metadata only: tokens, cost, model, duration. No prompt/response content |
none |
No logging at all |
Users can escalate (but never downgrade) the privacy level via TSconfig:
aim.privacyLevel = reduced
The strictest level between the config and the user always wins.
Set rerouting_allowed = 0 on a provider configuration to prevent the smart router from rerouting requests away from or to that configuration. Combined with be_groups, this ensures confidential data (e.g. HR data on a local Ollama) stays on the designated model.
The SmartRoutingMiddleware classifies prompt complexity using language-agnostic structural heuristics:
- Character/sentence/line count
- Question marks, enumerations, code presence
- URLs, structural delimiters
- Multi-language keyword signals (extensible per extension)
Classification is logged per request (complexity_score, complexity_label, complexity_reason). When a cheaper model has proven reliable for simple prompts (based on historical request log data with minimum 10 requests and 90%+ success rate), the middleware automatically downgrades.
"Reliable" on its own only means the API call didn't error. A cheap model can succeed every time while producing weak answers. When LLM grading is enabled, smart routing also consults the recorded grade_score: a cheaper model is only chosen if its graded responses for that request type average at least 0.65 (the "good" boundary) across at least 10 graded requests.
The gate is a one-way veto, not a tie-breaker. The cheapest cost-and-success-eligible model is still the one picked; a poor average grade simply removes a candidate. Crucially, too few graded requests means "no signal", not "bad": a model with fewer than 10 graded samples is judged on cost and success rate exactly as before, so installs without grading enabled see no change in routing behavior.
The downgrade decision is logged with the candidate's graded quality, e.g. ... (avg grade: 0.82 over 14 graded) or ... (ungraded).
Ship a Configuration/SmartRouting/ComplexitySignals.php in any extension:
return [
'ja' => [
'complex' => ['比較して', '設計して', '最適化して'],
'simple' => ['とは', 'こんにちは'],
'multiPart' => [' と比べて'],
],
];Or add signals at runtime:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['aim']['complexitySignals']['de']['complex'][] = 'analysiere';AiM can score the quality of AI responses using a second model as a judge ("LLM-as-a-judge"). Grading is opt-in per provider configuration and runs after the response has been delivered to the caller, so it adds no latency to the live request.
On any provider configuration (Admin Tools > AiM > Providers), open the LLM Grading tab:
| Field | Purpose |
|---|---|
grading_enabled |
Turns grading on for this configuration |
judge_configuration_uid |
A different AiM configuration used to score responses — typically a cheaper or specialized model that supports the conversation capability |
grading_rubric |
The judge's instructions: what to evaluate (factual accuracy, relevance, tone, ...). The required JSON output format is appended automatically. |
Grading covers ConversationRequest and TextGenerationRequest. It only runs when the effective privacy level is standard, reduced and none skip it, since the judge needs the prompt and response content.
- After a successful, gradeable response,
GraderMiddlewaremarks the request log rowgrade_status = pendingand registers a shutdown function. - The shutdown function runs after the response is flushed to the caller, then calls the judge model.
- The judge returns a JSON
{score, label, reason}, written back to the row (grade_score,grade_label,grade_reason).
If the shutdown path is missed (CLI crash, an unusual SAPI), a scheduler command picks up the stragglers:
vendor/bin/typo3 aim:grade-pendingRun it from the TYPO3 scheduler every few minutes. It grades rows still marked pending that are older than --min-age seconds (default 60), so it never races the live shutdown handler. The request log module shows a warning when a pending backlog builds up.
The judge assigns one of four labels. When it returns a score but no recognizable label, the label is derived from the score:
| Label | Score range |
|---|---|
poor |
0.00–0.39 |
fair |
0.40–0.64 |
good |
0.65–0.84 |
excellent |
0.85–1.00 |
The judge call deliberately bypasses the middleware pipeline (it would otherwise produce a duplicate request-log row), but its cost is still rolled into the judge configuration's total_cost and recorded on the graded row's judge_cost column.
Add middleware to intercept all AI requests:
use B13\Aim\Attribute\AsAiMiddleware;
use B13\Aim\Middleware\AiMiddlewareInterface;
#[AsAiMiddleware(priority: 50)]
class MyMiddleware implements AiMiddlewareInterface
{
public function process(
AiRequestInterface $request,
AiProviderInterface $provider,
ProviderConfiguration $configuration,
AiMiddlewareHandler $next,
): TextResponse {
// Before: inspect or modify request
$response = $next->handle($request, $provider, $configuration);
// After: inspect or modify response
return $response;
}
}Every request DTO carries a metadata array that lands in the metadata JSON column of tx_aim_request_log. To attach extension-specific context, enrich it from your custom middleware via $request->withMetadata([...]) and forward the new instance. The original request stays immutable; downstream middlewares see the merged metadata:
#[AsAiMiddleware(priority: 80)]
final class MyExtensionContextMiddleware implements AiMiddlewareInterface
{
public function process(
AiRequestInterface $request,
AiProviderInterface $provider,
ProviderConfiguration $configuration,
AiMiddlewareHandler $next,
): TextResponse {
$request = $request->withMetadata([
'my_ext.additional' => 'info',
]);
return $next->handle($request, $provider, $configuration);
}
}For richer or separate logging, register a middleware at a lower priority than RequestLoggingMiddleware (use a priority below -700). It sees the response, the resolved $configuration, and any metadata enriched by earlier middlewares, and is free to write wherever it likes without touching tx_aim_request_log:
#[AsAiMiddleware(priority: -750)]
final class MyExtensionDetailedLogger implements AiMiddlewareInterface
{
public function __construct(private readonly MyExtensionLogRepository $repository) {}
public function process(
AiRequestInterface $request,
AiProviderInterface $provider,
ProviderConfiguration $configuration,
AiMiddlewareHandler $next,
): TextResponse {
$response = $next->handle($request, $provider, $configuration);
$this->repository->record([
'provider' => $configuration->providerIdentifier,
'model' => $response->usage->modelUsed,
'metadata' => $request->metadata,
'tokens' => $response->usage->getTotalTokens(),
'cost' => $response->usage->cost,
// ...any custom shape you need
]);
return $response;
}
}The middleware pipeline is intentionally the only logging extension point: it gives you the request, response, configuration, and middleware context in one place, plus full control over where the data goes.
| Middleware | Priority | Purpose |
|---|---|---|
RetryWithFallbackMiddleware |
100 | Catches errors, retries with fallback providers |
AccessControlMiddleware |
90 | Provider access, capability permissions, budgets, rate limits |
SmartRoutingMiddleware |
75 | Complexity classification, cost-based model downgrade |
CapabilityValidationMiddleware |
50 | Validates provider capability, auto-reroutes if needed |
GraderMiddleware |
-600 | Schedules LLM-as-a-judge grading after a successful response |
RequestLoggingMiddleware |
-700 | Logs every request (respects privacy levels) |
CostTrackingMiddleware |
-800 | Updates cumulative cost per configuration |
EventDispatchMiddleware |
-900 | Fires BeforeAiRequestEvent / AfterAiResponseEvent |
CoreDispatchMiddleware |
-1000 | Routes request to the correct provider capability method |
| Event | When | Use Case |
|---|---|---|
BeforeAiRequestEvent |
Before provider call | Modify request, add logging, enforce policies |
AfterAiResponseEvent |
After provider response | Post-processing, notifications, analytics |
AiRequestReroutedEvent |
When capability gate reroutes | Monitor misconfigurations, track rerouting patterns |
AiM adds an AiM module under Admin Tools with two sub-modules:
Manage AI provider configurations:
- API keys, models, token costs
- Group restrictions (
be_groups), privacy levels, rerouting protection, auto model switch - Available Providers: modal with clickable model badges to enable/disable models
- Provider verification: test connectivity with a minimal probe request, results persisted
- Last used: timestamp per configuration with link to request log
Monitor all AI requests:
- Statistics dashboard: total requests, total cost, total tokens, success rate, average duration
- Filtered log view: filter by provider, extension, request type, success/failure
- User tracking: shows the backend username for each request (empty for CLI/automation)
- Full content: prompt, system prompt, and response content per request (respects privacy levels)
- Complexity classification: score, label, and reason for each request
- Quality grades: LLM-as-a-judge score, label, and reason per request when grading is enabled
- Token details: prompt, completion, cached, and reasoning token breakdowns
- Rerouting info: fallback and capability rerouting details
When typo3/cms-dashboard is installed, AiM registers five widgets and a pre-configured dashboard preset ("AiM: AI Analytics"):
| Widget | Type | Shows |
|---|---|---|
| Recent Requests | Table | Last 10 requests with extension, model, tokens, cost, status |
| Provider Usage | Doughnut chart | Request distribution across providers |
| Model Usage | Bar chart | Request count per model |
| Success Rate | Doughnut chart | Successful vs failed requests |
| Extension Usage | Doughnut chart | Which extensions generate the most requests |
All widgets are refreshable and grouped under "AiM" in the widget picker. The recent requests widget includes a button to open the full request log module.
| Table | Purpose |
|---|---|
tx_aim_configuration |
Provider configurations (TCA-managed). API keys, models, cost tracking, governance settings. |
tx_aim_request_log |
Per-request log (no TCA). Tokens, cost, duration, prompt/response content, complexity classification, rerouting details, LLM grading results. |
tx_aim_usage_budget |
Per-user budget tracking. Rolling period counters for tokens, cost, and request count. |
See ext_tables.sql for the full schema.
cd typo3conf/ext/aim
# Unit tests (30 tests, 54 assertions)
Build/Scripts/runTests.sh -s unit
# Functional tests (24 tests, 57 assertions)
Build/Scripts/runTests.sh -s functional
# With specific PHP version
Build/Scripts/runTests.sh -s unit -p 8.3
# Specific test
Build/Scripts/runTests.sh -s unit -- --filter BudgetService- TYPO3 v12.4, v13.4, or v14.0+
- PHP 8.1+
- No AI provider dependencies (bring your own via Symfony AI bridges or native implementations)
GPL-2.0-or-later
Created by Oli Bartsch for b13 GmbH, Stuttgart.


