PHPackages                             mgamadeus/ddd-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mgamadeus/ddd-ai

ActiveLibrary[Utility & Helpers](/categories/utility)

mgamadeus/ddd-ai
================

AI model management, prompt system, and Argus AI integration traits for mgamadeus/ddd

1.2.1(2w ago)0159↓33.3%1MITPHP

Since Apr 14Pushed 2d agoCompare

[ Source](https://github.com/mgamadeus/ddd-ai)[ Packagist](https://packagist.org/packages/mgamadeus/ddd-ai)[ RSS](/packages/mgamadeus-ddd-ai/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (22)Used By (1)

mgamadeus/ddd-ai
================

[](#mgamadeusddd-ai)

AI model management, prompt system, and Argus AI integration traits for the [mgamadeus/ddd](https://github.com/mgamadeus/ddd) framework.

Installation
------------

[](#installation)

```
composer require mgamadeus/ddd-ai
```

What it does
------------

[](#what-it-does)

Provides the infrastructure for AI-powered features:

- **AIModel** — catalog of 60+ AI models (OpenAI GPT-4o through GPT-5.4, o3/o4 reasoning, Meta Llama, image models FLUX/Imagen, audio, embeddings) with pricing and capability metadata
- **AIPrompt** — template system with `{%parameter%}` substitution and token estimation
- **Argus AI traits** — plug into any Argus repo entity to add LLM-powered loading via OpenAI/Google Gemini APIs
- **Batch services** — OpenAI and OpenRouter server-side integration (batch controllers for Argus endpoints)
- **Cost tracking** — per-operation cost estimation and budget enforcement

Configuration
-------------

[](#configuration)

### AI Models

[](#ai-models)

Models are loaded from `config/app/AI/models.php` (ships with 60+ model definitions). Override by placing your own `config/app/AI/models.php` in your project — project config takes priority.

### AI Prompts

[](#ai-prompts)

Prompts are markdown files loaded from `config/app/AI/Prompts/` using dot-notation paths:

```
$prompt = AIPrompt::getService()->getAIPromptByName('Common.Texts.DetectedLanguage');
// Loads: config/app/AI/Prompts/Common/Texts/DetectedLanguage.md
```

Override any prompt by placing a file at the same path in your project's `config/app/AI/Prompts/`.

### Environment Variables

[](#environment-variables)

The AI module itself requires no environment variables. The underlying Argus module needs `ARGUS_API_ENDPOINT` configured (see [ddd-argus](https://github.com/mgamadeus/ddd-argus)).

AI batch services require the OpenRouter/OpenAI API keys to be configured in the Argus batch gateway.

Service registration
--------------------

[](#service-registration)

Add to your project's `services.yaml`:

```
# DDD Module: ddd-ai
DDD\Domain\AI\Services\:
    resource: '%kernel.project_dir%/vendor/mgamadeus/ddd-ai/src/Domain/AI/Services/*'
    public: true

DDD\Domain\Batch\Services\AI\:
    resource: '%kernel.project_dir%/vendor/mgamadeus/ddd-ai/src/Domain/Batch/Services/AI/*'
    public: true
```

Usage
-----

[](#usage)

### Adding AI to an Argus repo entity

[](#adding-ai-to-an-argus-repo-entity)

```
use DDD\Domain\AI\Entities\Models\AIModel;
use DDD\Domain\AI\Repo\Argus\Attributes\ArgusLanguageModel;
use DDD\Domain\AI\Repo\Argus\Traits\ArgusAILanguageModelTrait;
use DDD\Domain\Base\Repo\Argus\Attributes\ArgusLoad;
use DDD\Domain\Base\Repo\Argus\Traits\ArgusTrait;
use DDD\Domain\Base\Repo\Argus\Utils\ArgusCache;

#[ArgusLoad(
    loadEndpoint: 'POST:/ai/openRouter/chatCompletions',
    cacheLevel: ArgusCache::CACHELEVEL_MEMORY_AND_DB,
    cacheTtl: ArgusCache::CACHELEVEL_NONE
)]
#[ArgusLanguageModel(
    defaultAIModelName: AIModel::MODEL_OPENAI_GPT5_2,
    defaultAIPromptName: 'My.Custom.Prompt',
)]
class ArgusMyAIEntity extends MyEntity
{
    use ArgusTrait, ArgusAILanguageModelTrait;

    public function getAIPromptWithParametersApplied(): AIPrompt
    {
        $prompt = $this->getAIPrompt();
        $prompt->setParameter('locale', 'de-DE');
        return $prompt;
    }

    public function getUserContent(): string|array
    {
        return 'The text to process';
    }

    protected function applyLoadResult(string $resultText): void
    {
        $this->result = $resultText;
    }
}
```

### Supported vendors

[](#supported-vendors)

- **OpenAI** (default) — chat completions, embeddings, audio, image
- **Google Gemini** — alternative payload format, auto-detected by vendor
- **Fal.ai** — image generation models (FLUX, Sana, etc.)
- **OpenRouter** — multi-model gateway

Batch controllers
-----------------

[](#batch-controllers)

The module ships `BatchAIController` with endpoints for:

- `/ai/openRouter/chatCompletions` — LLM chat completions
- `/ai/openRouter/embeddings` — text embeddings

Import in your project's `routes.yaml` to activate:

```
batch_ai:
    resource: '%kernel.project_dir%/vendor/mgamadeus/ddd-ai/src/Presentation/Api/Batch/AI'
    type: annotation
    prefix: '/api/batch'
```

Or extend the controller in your app to customize behavior.

### Security

[](#security)

Batch endpoints must be secured with ROLE\_SUPER\_ADMIN. Ensure your `security.yaml` includes:

```
# config/symfony/default/packages/security.yaml
security:
    access_control:
        - { path: ^/api/batch, roles: ROLE_SUPER_ADMIN }
```

Argus clients authenticate automatically using the account specified by:

```
# Must have SUPER_ADMIN role — bearer token is sent with every Argus API call
CLI_DEFAULT_ACCOUNT_ID_FOR_CLI_OPERATIONS=1
```

See [ddd-argus](https://github.com/mgamadeus/ddd-argus) for the full security configuration example.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance99

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

21

Last Release

15d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2896811?v=4)[mgamadeus](/maintainers/mgamadeus)[@mgamadeus](https://github.com/mgamadeus)

---

Top Contributors

[![mgamadeus](https://avatars.githubusercontent.com/u/2896811?v=4)](https://github.com/mgamadeus "mgamadeus (24 commits)")

### Embed Badge

![Health badge](/badges/mgamadeus-ddd-ai/health.svg)

```
[![Health](https://phpackages.com/badges/mgamadeus-ddd-ai/health.svg)](https://phpackages.com/packages/mgamadeus-ddd-ai)
```

###  Alternatives

[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

317117.1k1](/packages/cognesy-instructor-php)[compwright/php-session

Standalone session implementation that does not rely on the PHP session module or the $\_SESSION global, ideal for ReactPHP applications

189.8k](/packages/compwright-php-session)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)