mage-os / module-ai-base

v1.0.0 2026-10-08 17:51 UTC

Requires

• php: ^8.2
• magento/framework: ^103.0.8 || ^104.0
• magento/module-backend: ^102.0 || ^103.0
• magento/module-config: ^101.2 || ^102.0
• magento/module-cron: ^100.4
• magento/module-reports: ^100.4
• magento/module-store: ^101.1 || ^102.0
• magento/module-ui: ^101.2 || ^102.0
• symfony/ai-anthropic-platform: ^0.14
• symfony/ai-open-ai-platform: ^0.14
• symfony/ai-platform: ^0.14
• symfony/http-client: ^7.3 || ^8.0

Requires (Dev)

• bitexpert/phpstan-magento: ^0.44
• magento/magento-coding-standard: *
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.5

Suggests

• symfony/ai-azure-platform: Enables the bundled AI client and Test Connection for Azure OpenAI.
• symfony/ai-deep-seek-platform: Enables the bundled AI client and Test Connection for Deepseek.
• symfony/ai-gemini-platform: Enables the bundled AI client and Test Connection for Google Gemini.
• symfony/ai-generic-platform: Enables the bundled AI client and Test Connection for OpenAI-Compatible (LiteLLM, OpenRouter-style gateways, and other self-hosted OpenAI-compatible servers).
• symfony/ai-hugging-face-platform: Enables the bundled AI client and Test Connection for HuggingFace.
• symfony/ai-lm-studio-platform: Enables the bundled AI client and Test Connection for LM Studio.
• symfony/ai-ollama-platform: Enables the bundled AI client and Test Connection for Ollama.
• symfony/ai-open-router-platform: Enables the bundled AI client and Test Connection for OpenRouter.

OSL-3.0, AFL-3.0

• Michiel Gerritsen
• David Lambauer
• Mage-OS contributors

Published on Packagist.org on 2026-10-08 18:26 UTC

README

One place in Magento to configure your AI providers, one client every module can use to call them, and a dashboard that shows what each module spends.

Stores > Configuration > Mage-OS > AI Configuration	Reports > AI Token Usage

What it provides

• Provider configuration. OpenAI, Anthropic, Google Gemini, Azure OpenAI, DeepSeek, OpenRouter, Hugging Face, Ollama, LM Studio and any OpenAI-compatible gateway. Add a provider more than once, name each row, switch rows off, test the connection and refresh the model list from the form. API keys are encrypted at rest and never shown again.
• One client for every provider. Chat, streaming, tool calls and reasoning through a single interface. Options like max_tokens and tool_choice are translated per provider, and failures come back as typed exceptions you can retry or skip.
• Let the admin choose. A ready-made source model for your own system.xml, so a store picks which configured service your feature uses.
• Usage tracking. Token counts per module, service and store, on a dashboard, a grid and a CLI report. Prompts and responses are never stored.
• Extensible. Add your own provider with one class and a few lines of di.xml.

Installation

composer require mage-os/module-ai-base
bin/magento module:enable MageOS_AiBase
bin/magento setup:upgrade

Requires Magento 2.4.8+ or Mage-OS 1.1+, and PHP 8.2+. OpenAI and Anthropic work out of the box; every other provider needs its Symfony AI bridge package, which the admin form names when it's missing.

The client is built on symfony/ai-platform 0.14, which is experimental. This module's Api interfaces absorb its changes; code that reaches the Symfony platform directly does not.

Usage

use MageOS\AiBase\Api\AiClientFactoryInterface;

class ProductSummary
{
    public function __construct(
        private readonly AiClientFactoryInterface $aiClientFactory,
    ) {
    }

    public function summarize(string $description): string
    {
        return $this->aiClientFactory
            ->create(consumer: 'Vendor_ProductSummary')
            ->complete('Summarize this product description: ' . $description);
    }
}

chat() and streamChat() cover conversations, tools and streaming. The Consumer Guide has the full picture.

Documentation

• Consumer Guide: make AI calls, handle failures, let the admin pick a service, what's stable
• Provider Guide: add a provider, wire a client bridge, the admin form
• Usage Tracking: what is recorded, where to see it, retention
• Architecture: components, data flows, security model, design decisions

Contributing

See CONTRIBUTING.md and our Code of Conduct.

Security

Please report vulnerabilities privately, as described in SECURITY.md, not in a public issue.