Xmon Ai Content Bundle

https://github.com/xmon-org/ai-content-bundle
Admin
Symfony 7 bundle for AI content generation (text and images) with a fallback system between...
Tokens:73,613
Snippets:257
Trust Score:1.3
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Environment Setup for ai-content-bundle

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/CONTRIBUTING.md

Instructions to clone the repository and install project dependencies using Composer. This is the initial step for setting up your local development environment.

```bash
git clone https://github.com/xmon-org/ai-content-bundle.git
cd ai-content-bundle
composer install
composer check
```

--------------------------------

### Task Configuration - Free Setup (YAML)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/configuration.md

Example YAML configuration for a free AI task setup, utilizing cost-effective models like Mistral and Flux. This configuration is often the default when no specific settings are provided.

```yaml
# Just use: xmon_ai_content: ~ 
# Which gives you:
tasks:
    news_content:
        default_model: 'mistral'
        allowed_models: ['mistral', 'nova-micro', 'openai-fast']
    image_prompt:
        default_model: 'mistral'
        allowed_models: ['mistral', 'openai-fast', 'nova-micro']
    image_generation:
        default_model: 'flux'
        allowed_models: ['flux', 'zimage', 'turbo']

text:
    model: 'mistral'
    fallback_models: ['nova-micro', 'gemini-fast', 'openai-fast']

image:
    model: 'flux'
    fallback_models: ['zimage', 'turbo']
```

--------------------------------

### AI Content Bundle Debug Command Output Example

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/development.md

An example output of the `bin/console xmon:ai:debug` command, illustrating the configuration details for text and image providers, task models, and other settings. This helps in understanding the current state of the bundle's configuration.

```text
$ bin/console xmon:ai:debug

xmon-org/ai-content-bundle Configuration
========================================

Text Provider (Pollinations)
----------------------------
 Setting            Value
 Status             ✓ Available
 API Key            Not set (free tier)
 Default Model      mistral
 Fallback Models    nova-micro → gemini-fast → openai-fast
 Retries per Model  2
 Retry Delay        3s
 Timeout            60s
 Endpoint Mode      openai

Image Provider (Pollinations)
-----------------------------
 Setting            Value
 Status             ✓ Available
 API Key            Not set (free tier)
 Default Model      flux
 Fallback Models    zimage → turbo
 Retries per Model  2
 Retry Delay        3s
 Timeout            120s
 Default Size       1280x720
 Quality            high
 Private            Yes

Task Models
-----------
 Task              Default Model   Cost    Allowed Models
 news_content      mistral         FREE    mistral, nova-micro, openai-fast
 image_prompt      mistral         FREE    mistral, openai-fast, nova-micro
 image_generation  flux            FREE    flux, zimage, turbo

Styles, Compositions, Palettes, Extras, Presets...

Use bin/console debug:config xmon_ai_content for full YAML configuration.

> **Note:** The output above shows a free-tier configuration. With an API key, you'll see premium models (gemini, claude, gptimage, seedream, etc.) with their costs.
```

--------------------------------

### Manual Git Hook Setup

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/CONTRIBUTING.md

Command to manually set up git hooks if they are not working automatically after installation. This ensures that pre-commit checks are functional.

```bash
composer setup-hooks
```

--------------------------------

### Task Configuration - Premium Setup (YAML)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/configuration.md

Example YAML configuration for premium AI task settings, prioritizing high-quality models for news content and image generation. It specifies default and allowed models for each task type.

```yaml
tasks:
    news_content:
        default_model: 'claude'
        allowed_models: ['claude', 'gemini']
    image_prompt:
        default_model: 'gemini-fast'
        allowed_models: ['gemini-fast', 'openai-fast']
    image_generation:
        default_model: 'gptimage'
        allowed_models: ['gptimage', 'seedream', 'flux']
```

--------------------------------

### Budget-Based Task Type Configurations (Premium & Free Tiers)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Shows example configurations for task types in `xmon_ai_content.yaml` for both premium (best quality) and free (no cost) tiers, specifying default and allowed models along with estimated costs.

```yaml
tasks:
    news_content:
        default_model: 'claude'        # ~$0.003/article
        allowed_models: ['claude', 'gemini']
    image_prompt:
        default_model: 'gemini-fast'   # ~$0.00008/prompt
        allowed_models: ['gemini-fast', 'openai-fast']
    image_generation:
        default_model: 'gptimage'      # ~$0.006/image
        allowed_models: ['gptimage', 'seedream', 'flux']
```

```yaml
tasks:
    news_content:
        default_model: 'openai'        # Free tier
        allowed_models: ['openai', 'openai-fast', 'mistral']
    image_prompt:
        default_model: 'openai-fast'   # Free tier
        allowed_models: ['openai-fast', 'mistral']
    image_generation:
        default_model: 'flux'          # Free tier
        allowed_models: ['flux', 'turbo']
```

--------------------------------

### Get Available Prompt Templates (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/prompt-templates.md

This PHP code demonstrates how to retrieve available prompt templates using the `PromptTemplateService`. It shows methods for listing template keys, getting the names of all available templates, and fetching the full data for a specific template.

```php
// List of available templates (key => name)
$templates = $this->promptTemplates->getTemplates();
// ['image_subject' => 'Image Subject Generator', 'summarizer' => 'Content Summarizer', ...]

// Get full template data
$template = $this->promptTemplates->getTemplate('image_subject');
// ['name' => '...', 'description' => '...', 'system' => '...', 'user' => '...']

// All available keys
$keys = $this->promptTemplates->getTemplateKeys();
// ['image_subject', 'summarizer', 'title_generator']
```

--------------------------------

### Install SonataMedia Bundle for Integration

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This command installs the SonataMedia bundle, which is required for integrating xmon-org/ai-content-bundle with Sonata's media management features.

```bash
composer require sonata-project/media-bundle
```

--------------------------------

### Rendering Prompt Templates with Variants (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/prompt-templates.md

Provides a PHP example demonstrating how to use the `PromptTemplateService` to render a prompt template that includes variants. The `render()` method automatically processes these variants, populating the system and user prompts. The output includes a `selected_variants` key when variants have been successfully processed and applied.

```php
use Xmon\AiContentBundle\Service\PromptTemplateService;

class MyService
{
    public function __construct(
        private readonly PromptTemplateService $promptTemplates,
    ) {}

    public function generateScene(string $title, string $summary): array
    {
        $result = $this->promptTemplates->render('image_scene', [
            'title' => $title,
            'summary' => $summary,
        ]);

        // $result contains:
        // [
        //     'system' => 'Genera una escena usando:
        //                  - UBICACIÓN: patio de museo con fuente
        //                  - AMBIENTE: contemplación tranquila
        //                  IMPORTANTE: Responde EN INGLÉS.',
        //     'user' => 'Título: Mi Artículo\n\nResumen: ...',
        //     'selected_variants' => [
        //         'location' => 'patio de museo con fuente',
        //         'mood' => 'contemplación tranquila',
        //     ]
        // ]

        return $result;
    }
}
```

--------------------------------

### Getting Available Models

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Provides methods to retrieve information about AI models that are available and configured for specific task types.

```APIDOC
## Getting Available Models

### Description
This section details how to query the available AI models, including those permitted for a specific task type, formatted options for UI elements, and the default model designated for a task.

### Method
GET (Implied by getter methods)

### Endpoint
`/api/ai-content/models` (Implied)

### Parameters
#### Query Parameters
- **task_type** (Enum: `TaskType::NEWS_CONTENT`, etc.) - Required - The task type to query available models for.

### Responses
#### Success Response (200)
- **models** (Object) - A map where keys are model identifiers and values are `ModelInfo` objects, listing models allowed for the task.
- **options** (Object) - A map suitable for UI select elements, mapping model identifiers to user-friendly display strings.
- **default_model** (String) - The identifier of the default model configured for the task.
```

--------------------------------

### Install xmon-org/ai-content-bundle using Composer

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This command installs the main xmon-org/ai-content-bundle package using Composer. It's the primary step for integrating the bundle into your project.

```bash
composer require xmon-org/ai-content-bundle
```

--------------------------------

### Verify Installation Command

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This bash command is used to verify the installation and configuration of the XMON AI content bundle. It runs a debug command provided by the bundle, which outputs status information about providers, models, and templates.

```bash
bin/console xmon:ai:debug
```

--------------------------------

### Install Assets - Standard

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This bash command installs the necessary assets for the AI content bundle in a standard (non-Docker) environment. It uses the Symfony console command for asset management.

```bash
bin/console assets:install --symlink
```

--------------------------------

### Get Image Options for UI (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/styles-presets.md

Demonstrates how to use the ImageOptionsService to retrieve various image-related options for populating form selects. It injects the service and calls methods like getStyles(), getCompositions(), getPalettes(), getExtras(), and getPresets().

```php
use Xmon\AiContentBundle\Service\ImageOptionsService;

class MyAdmin
{
    public function __construct(
        private readonly ImageOptionsService $imageOptions,
    ) {}

    public function getFormChoices(): array
    {
        return [
            'styles' => $this->imageOptions->getStyles(),
            // ['sumi-e' => 'Sumi-e (tinta japonesa)', 'watercolor' => 'Acuarela', ...]

            'compositions' => $this->imageOptions->getCompositions(),
            'palettes' => $this->imageOptions->getPalettes(),
            'extras' => $this->imageOptions->getExtras(),
            'presets' => $this->imageOptions->getPresets(),
        ];
    }
}
```

--------------------------------

### YAML Example: Disabling, Overriding, and Adding Image Options

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/image-options.md

Provides a YAML example showcasing how to manage image generation options. It covers disabling specific bundle defaults, overriding existing bundle options by using the same key, and adding entirely new custom options.

```yaml
xmon_ai_content:
    image_options:
        # Disable a bundle default
        disable_defaults:
            styles: ['baroque']  # Remove baroque style from bundle

        # Override an existing bundle style
        styles:
            impressionist:  # Same key as bundle = override
                label: 'My Impressionist'
                prompt: 'my custom impressionist prompt'
                group: 'Overridden'

            # Add a completely new style
            my-new-style:
                label: 'Brand New Style'
                prompt: 'new style prompt'
                group: 'Custom'

```

--------------------------------

### Best Practices

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Offers guidance on matching AI models to specific tasks, restricting model usage based on budget, and wisely choosing default models.

```APIDOC
## Best Practices

### 1. Match Model to Task

- **NEWS_CONTENT**: Use quality models (claude, gemini) - content matters
- **IMAGE_PROMPT**: Use fast models (gemini-fast) - just generating descriptions
- **IMAGE_GENERATION**: Match to your content type

### 2. Restrict Allowed Models by Budget

Only include models you're willing to pay for. Configuration is typically done via YAML:

```yaml
# Tight budget - only free models
image_generation:
    default_model: 'flux'
    allowed_models: ['flux', 'turbo']  # No premium models

# Flexible budget - include premium
image_generation:
    default_model: 'gptimage'
    allowed_models: ['flux', 'gptimage', 'seedream']  # Free + premium
```

### 3. Use Default Model Wisely

The default model is used when no model is specified. Choose based on your typical use case:

```yaml
# If most content is premium quality
news_content:
    default_model: 'claude'

# If testing frequently
image_generation:
    default_model: 'flux'  # Free for testing
```
```

--------------------------------

### Text Configuration Example (YAML)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/providers.md

Provides a YAML configuration snippet for setting up text generation parameters. It includes API key, default model selection, fallback models, retry mechanisms, timeouts, and endpoint mode configuration.

```yaml
xmon_ai_content:
    text:
        api_key: '%env(XMON_AI_POLLINATIONS_API_KEY)%'  # Optional - defaults are free tier
        model: 'mistral'                   # Default model (free tier)
        fallback_models: ['nova-micro', 'gemini-fast', 'openai-fast']  # Free tier fallbacks
        retries_per_model: 2               # Retries before next model
        retry_delay: 3                     # Seconds between retries
        timeout: 60
        endpoint_mode: 'openai'            # 'openai' (default) or 'simple'
```

--------------------------------

### Configure Custom Anchor Visual Guidelines

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/image-subject-generator.md

Provides an example of how to override default visual guidelines for anchor types and add new domain-specific anchor types in the `config/packages/xmon_ai_content.yaml` file. This allows for customization of image generation based on specific content domains.

```yaml
# config/packages/xmon_ai_content.yaml
xmon_ai_content:
    image_subject:
        anchor_types:
            # Override default guidelines
            PLACE: 'Include distinctive regional landscape, traditional architecture, and natural elements specific to this location.'
            PERSON: 'Feature a distinguished silhouette (NEVER detailed face) with elements suggesting their discipline or profession.'

            # Add domain-specific types
            PRODUCT: 'Feature the product prominently in an elegant, professional setting.'
            TECHNOLOGY: 'Include futuristic or technical visual elements representing the technology.'
```

--------------------------------

### Generate AI Image with Preset and Option Override using PromptBuilder

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/styles-presets.md

Illustrates how to use a preset as a foundation for an AI image prompt and then override specific options, such as composition, to fine-tune the final prompt.

```php
$prompt = $this->promptBuilder->build(
    subject: 'aikido seminar group photo',
    options: [
        'preset' => 'zen-contemplativo',
        'composition' => 'rule-of-thirds', // Override from preset
    ]
);
```

--------------------------------

### Controller Override Example (PHP - Before Migration)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/style-providers.md

Illustrates a previous method of overriding style resolution directly within a controller. This approach is being replaced by the style provider pattern for better flexibility.

```php
protected function resolveGlobalStyle(): string
{
    $config = $this->configRepository->getConfiguracion();
    return $config?->getBaseStylePreview() ?? parent::resolveGlobalStyle();
}
```

--------------------------------

### Generating Text Using Prompt Templates

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Demonstrates the integration with PromptTemplateService to render and use structured prompts for text generation. It fetches system and user prompts from a template and then uses AiTextService to generate the content.

```php
use Xmon\AiContentBundle\Service\PromptTemplateService;
use Xmon\AiContentBundle\Service\AiTextService;

class MyService
{
    public function __construct(
        private readonly PromptTemplateService $promptTemplates,
        private readonly AiTextService $aiTextService,
    ) {}

    public function summarize(string $content): string
    {
        $prompts = $this->promptTemplates->render('summarizer', [
            'content' => $content,
        ]);

        return $this->aiTextService->generate(
            $prompts['system'],
            $prompts['user']
        )->getText();
    }
}
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/CONTRIBUTING.md

Examples demonstrating the Conventional Commits format for various types of changes, including features, fixes, breaking changes, documentation updates, and refactoring. This format aids in automated versioning and changelog generation.

```bash
git commit -m "feat(text): add streaming support for text generation"
git commit -m "fix(image): resolve timeout with large prompts"
git commit -m "feat(config)!: change YAML structure for image settings

BREAKING CHANGE: image.providers.pollinations is now image (flat structure)"
git commit -m "docs: add image generation examples"
git commit -m "refactor(text): simplify fallback logic"
```

--------------------------------

### Retrieve Allowed and Formatted AI Models for Task Types (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Shows how to fetch AI models that are permitted for a given task type. It includes methods to get a raw list of allowed models, a formatted list suitable for UI select elements (including cost information), and the default model configured for the task.

```php
use Xmon\AiContentBundle\Enum\TaskType;

// Get models allowed for a task type
$models = $this->aiTextService->getAllowedModelsForTask(TaskType::NEWS_CONTENT);
// Returns: ['claude' => ModelInfo, 'gemini' => ModelInfo, ...]

// Get models formatted for UI select
$options = $this->aiTextService->getAllowedModelsForSelect(TaskType::NEWS_CONTENT);
// Returns: ['claude' => 'Claude Sonnet 4.5 (~65 resp/$)', 'gemini' => 'Gemini 3 Flash (~330 resp/$)']

// Get default model for a task
$default = $this->aiTextService->getDefaultModelForTask(TaskType::NEWS_CONTENT);
// Returns: 'gemini' (or whatever is configured)

```

--------------------------------

### Install Assets - Docker

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This bash command installs the AI content bundle assets within a Dockerized PHP environment. It executes the Symfony console command via `docker compose exec`.

```bash
docker compose exec php bin/console assets:install --symlink
```

--------------------------------

### Resolving Style Prompt from Key in Controller/Service

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/image-options.md

Provides an example of how to resolve the full image style prompt from a stored key, typically after a selection has been made using the `getStylesGroupedByKey()` format.

```php
$prompt = $this->imageOptions->getStylePrompt($selectedKey);
```

--------------------------------

### Minimal xmon_ai_content Bundle Configuration

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This is the most basic configuration for the xmon_ai_content bundle, enabling it to work out-of-the-box with free-tier models without requiring an API key. It utilizes default settings for text and image generation.

```yaml
# config/packages/xmon_ai_content.yaml
xmon_ai_content: ~  # That's it! Uses free-tier defaults
```

--------------------------------

### Generating Content for Specific Task Types

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Explains how to use the generateForTask() method with TaskType enums for production environments. This allows configuring different models for different purposes, such as generating news content or image prompts.

```php
use Xmon\AiContentBundle\Enum\TaskType;
use Xmon\AiContentBundle\Service\AiTextService;

class NewsContentGenerator
{
    public function __construct(
        private readonly AiTextService $aiTextService,
    ) {}

    public function generateContent(string $title, string $summary): string
    {
        // Uses the model configured for NEWS_CONTENT task
        $result = $this->aiTextService->generateForTask(
            TaskType::NEWS_CONTENT,
            'You are a professional journalist.',
            "Write an article about: {$title}\n\nSummary: {$summary}",
        );

        return $result->getText();
    }

    public function generateImagePrompt(string $title): string
    {
        // Uses the model configured for IMAGE_PROMPT task (typically faster/cheaper)
        $result = $this->aiTextService->generateForTask(
            TaskType::IMAGE_PROMPT,
            'Generate a scene description for image generation.',
            "Title: {$title}",
        );

        return $result->getText();
    }
}
```

--------------------------------

### Install Assets with Symlink (Bash)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/admin-integration.md

This bash command, executed inside a Docker container, installs assets with symlinks. It's used to resolve issues where symlinks point to incorrect paths, ensuring assets are properly linked within the application's public directory.

```bash
# Run inside Docker container
docker compose exec php bin/console assets:install --symlink
```

--------------------------------

### Install Bundle Assets via Console

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/admin-integration.md

Publishes CSS and JavaScript files to the public bundles directory. This command creates a symbolic link for the bundle's assets, making them accessible.

```bash
bin/console assets:install --symlink
```

--------------------------------

### PHP: Summarize Content using PromptTemplateService

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/prompt-templates.md

Renders the 'summarizer' prompt template with the given content and uses AiTextService to generate a summary. Depends on PromptTemplateService and AiTextService.

```php
use Xmon\AiContentBundle\Service\PromptTemplateService;
use Xmon\AiContentBundle\Service\AiTextService;

class MyService
{
    public function __construct(
        private readonly PromptTemplateService $promptTemplates,
        private readonly AiTextService $aiTextService,
    ) {}

    public function summarize(string $content): string
    {
        $prompts = $this->promptTemplates->render('summarizer', [
            'content' => $content,
        ]);

        return $this->aiTextService->generate(
            $prompts['system'],
            $prompts['user']
        )->getText();
    }
}
```

--------------------------------

### Basic Configuration for ai-content-bundle

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/README.md

This is a basic YAML configuration for the ai-content-bundle. It enables the bundle to work out of the box with free-tier models without requiring specific API keys or complex setup.

```yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false

    XtendIMoneyAIContentBundle:
        resource: "../src/"
        exclude:
            - "../src/DependencyInjection/"
            - "../src/Entity/"
            - "../src/Kernel.php"

    # default configuration for the bundle
    Xtend\IMoney\AIContentBundle\Config\AIContentBundleConfig:
        # If you want to use custom models, you can uncomment and configure them here
        # For example:
        # models:
        #   text:
        #     claude:
        #       api_url: '%env(CLAUDE_API_URL)%'
        #       api_key: '%env(CLAUDE_API_KEY)%'
        #     gpt:
        #       api_url: '%env(GPT_API_URL)%'
        #       api_key: '%env(GPT_API_KEY)%'
        #   image:
        #     sdxl:
        #       api_url: '%env(SDXL_API_URL)%'
        #       api_key: '%env(SDXL_API_KEY)%'

```

--------------------------------

### Override Model at Runtime

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Demonstrates how to override the default AI model for specific text and image generation calls by providing a model name and other parameters in the options array.

```APIDOC
## Override Model at Runtime

You can override the default model for a specific call:

### Text Generation Example
```php
// Use a specific model (must be in allowed_models)
$result = $this->aiTextService->generateForTask(
    TaskType::NEWS_CONTENT,
    $systemPrompt,
    $userMessage,
    ['model' => 'gemini']  // Override default
);
```

### Image Generation Example
```php
// For images
$result = $this->aiImageService->generateForTask(
    $prompt,
    ['model' => 'seedream', 'width' => 1920, 'height' => 1080]
);
```
```

--------------------------------

### Validate Options with PromptBuilder (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/styles-presets.md

Illustrates how the PromptBuilder validates provided options, throwing an AiProviderException if an invalid option, such as an 'invalid-preset', is used. This ensures data integrity before prompt generation.

```php
try {
    $prompt = $this->promptBuilder->build('subject', [
        'preset' => 'invalid-preset'
    ]);
} catch (AiProviderException $e) {
    // "Unknown preset: invalid-preset"
}

```

--------------------------------

### Generate Image Subject using ImageSubjectGenerator

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/image-subject-generator.md

Demonstrates the basic usage of the ImageSubjectGenerator service to generate an image subject from a given title and summary. It shows how to instantiate the service and call the generate method.

```php
use Xmon\AiContentBundle\Service\ImageSubjectGenerator;

class MyService
{
    public function __construct(
        private readonly ImageSubjectGenerator $imageSubjectGenerator,
    ) {}

    public function generateImageSubject(): string
    {
        $subject = $this->imageSubjectGenerator->generate(
            title: '50th Anniversary of Aikido in Galicia',
            summary: 'The Real Federacion Gallega de Judo celebrates 50 years of aikido practice in the region with a special seminar.',
        );

        // Result: "A distinguished aikido master silhouette performing a ceremonial bow
        // against the backdrop of rocky Atlantic coastline with Celtic stone monuments,
        // golden numerals 50 subtly integrated into the misty horizon"

        return $subject;
    }
}
```

--------------------------------

### Get Presets for Form PHP

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/image-options.md

Retrieves all presets with their resolved style, composition, and palette prompts. This method is utilized by AiStyleConfigType and AiStyleConfigurableTrait::buildStylePreview(). The returned array uses English keys for preset data.

```php
<?php

return [
    'preset-key' => [
        'name' => 'Preset Name',
        'description' => 'Optional description',
        'style' => 'resolved style prompt',
        'composition' => 'resolved composition prompt',
        'palette' => 'resolved palette prompt',
    ],
];

```

--------------------------------

### AI Content Bundle Testing Commands

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/development.md

Commands for performing basic testing on the AI Content Bundle code. This includes PHP syntax checks, static analysis with PHPStan, and running unit tests with PHPUnit.

```bash
# Run PHP syntax check
php -l src/**/*.php

# Run PHPStan (if configured)
vendor/bin/phpstan analyse src/

# Run tests (if configured)
vendor/bin/phpunit
```

--------------------------------

### Cost Estimation

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Provides detailed cost breakdowns for different tiers (Seed and Flower) and example scenarios for article and image generation.

```APIDOC
## Cost Estimation

### Seed tier (gemini + flux):

| Operation | Model | Cost |
|-----------|-------|------|
| Article content | gemini | ~$0.003 |
| Image prompt | gemini-fast | ~$0.0004 |
| Image generation | flux | FREE |
| **Complete article** | | **~$0.004** |

> **250 articles (with images) ≈ $1 USD**

### Flower tier (claude + gptimage):

| Operation | Model | Cost |
|-----------|-------|------|
| Article content | claude | ~$0.015 |
| Image prompt | claude-fast | ~$0.005 |
| Image generation | gptimage | ~$0.000008 |
| **Complete article** | | **~$0.02** |

> **50 articles (with images) ≈ $1 USD**
```

--------------------------------

### Image Configuration Example (YAML)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/providers.md

Illustrates a YAML configuration for image generation settings. This includes API key, default model, fallback models, retry parameters, timeouts, image dimensions, quality settings, negative prompts, and privacy options.

```yaml
xmon_ai_content:
    image:
        api_key: '%env(XMON_AI_POLLINATIONS_API_KEY)%'  # Optional - defaults are free tier
        model: 'flux'                      # Default model (free tier)
        fallback_models: ['zimage', 'turbo']  # Free tier fallbacks
        retries_per_model: 2               # Retries before next model
        retry_delay: 3                     # Seconds between retries
        timeout: 120
        width: 1280                        # Default width
        height: 720                        # Default height
        quality: 'high'                    # low, medium, high, hd
        negative_prompt: 'worst quality, blurry, text, letters, watermark, human faces'
        private: true                      # Hide from Pollinations public feeds
        nofeed: true                       # Do not add to public feed
```

--------------------------------

### Get Default Model for Task (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Retrieves the default AI model designated for a particular task type. This is the model that will be used if no specific model is provided during a generation request.

```php
$defaultModel = $this->aiTextService->getDefaultModelForTask(TaskType::IMAGE_PROMPT);
// 'gemini-fast'
```

--------------------------------

### Getting Model Information

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Provides methods to retrieve information about available AI models, including listings for specific tasks, formatted options for UI selects, and default model retrieval.

```APIDOC
## Getting Model Information

### List Allowed Models for a Task

Retrieves a list of allowed models with full `ModelInfo` objects for a given task.

```php
// Get allowed models with full info (ModelInfo objects)
$models = $this->aiTextService->getAllowedModelsForTask(TaskType::NEWS_CONTENT);

foreach ($models as $key => $modelInfo) {
    echo $key;                         // 'claude'
    echo $modelInfo->name;             // 'Claude Sonnet 4.5'
    echo $modelInfo->responsesPerPollen; // 330
    echo $modelInfo->getFormattedCost(); // '~330 per pollen'
}
```

### For UI Selects

Formats model information suitable for HTML select dropdowns.

```php
// Get models formatted for HTML selects
$options = $this->aiImageService->getAllowedModelsForSelect();
// ['gptimage' => 'OpenAI Image 1 Mini (~160 per pollen)', ...]
```

### Get Default Model

Retrieves the default model configured for a specific task.

```php
$defaultModel = $this->aiTextService->getDefaultModelForTask(TaskType::IMAGE_PROMPT);
// 'gemini-fast'
```
```

--------------------------------

### YAML Template Validation Error Example

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/prompt-templates.md

This YAML template illustrates a validation error scenario where a placeholder '{variant_missing}' is used in the system prompt, but no corresponding entry exists in the 'variants' section. This will result in an 'AiProviderException'.

```yaml
# This will throw AiProviderException
prompts:
    templates:
        broken:
            system: 'Use {variant_missing}'  # Error: no 'missing' in variants
            variants:
                other: ['option1']

```

--------------------------------

### Get Last Model Used by Generator

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/image-subject-generator.md

Demonstrates how to retrieve the name of the last model that processed a request by the ImageSubjectGenerator service. This helps in understanding which AI model was utilized for a specific generation task.

```php
$subject = $this->imageSubjectGenerator->generate($title, $summary);

// See which model processed the request
$model = $this->imageSubjectGenerator->getLastModel();
echo "Model used: " . $model; // e.g., "gemini-fast"
```

--------------------------------

### Get Allowed Models for Task (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Retrieves a list of all models permitted for a specific task, along with detailed information for each model. This allows for programmatic inspection of model availability and characteristics, such as cost and response rates.

```php
// Get allowed models with full info (ModelInfo objects)
$models = $this->aiTextService->getAllowedModelsForTask(TaskType::NEWS_CONTENT);

foreach ($models as $key => $modelInfo) {
    echo $key;                         // 'claude'
    echo $modelInfo->name;             // 'Claude Sonnet 4.5'
    echo $modelInfo->responsesPerPollen; // 330
    echo $modelInfo->getFormattedCost(); // '~330 per pollen'
}
```

--------------------------------

### Generate AI Image with Individual Options using PromptBuilder

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/styles-presets.md

Shows how to construct an AI image prompt by specifying individual options such as style, composition, palette, and extras, instead of using a preset. This offers more granular control over the image generation.

```php
$prompt = $this->promptBuilder->build(
    subject: 'serene bamboo forest at dawn',
    options: [
        'style' => 'watercolor',
        'composition' => 'panoramic',
        'palette' => 'earth-tones',
        'extras' => ['atmospheric', 'no-text'],
    ]
);
```

--------------------------------

### Get Models Formatted for UI Select (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Fetches AI models specifically formatted for use in HTML select dropdowns. This utility simplifies the process of populating UI elements with model choices, often including a formatted cost estimate.

```php
// Get models formatted for HTML selects
$options = $this->aiImageService->getAllowedModelsForSelect();
// ['gptimage' => 'OpenAI Image 1 Mini (~160 per pollen)', ...]
```

--------------------------------

### YAML Monolog Configuration for AI Logging

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/image-subject-generator.md

Configures the Monolog logging service in a Symfony application to capture logs specifically from the 'ai' channel. This setup directs debug-level messages from the 'ai' channel to a dedicated file (`ai.log`) within the application's logs directory, aiding in debugging AI-related processes.

```yaml
# config/packages/monolog.yaml
monolog:
    handlers:
        ai:
            type: stream
            path: "%kernel.logs_dir%/ai.log"
            level: debug
            channels: ["ai"]
```

--------------------------------

### Conditional Service Loading in PHP

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/architecture.md

Demonstrates how to conditionally load service configuration files in a PHP application based on the existence of specific interfaces. This is useful for integrating optional features like SonataMedia or SonataAdmin.

```php
// In XmonAiContentExtension.php

// SonataMedia integration
if (interface_exists(MediaManagerInterface::class)) {
    $loader->load('services_media.yaml');
}

// Sonata Admin integration
if (interface_exists(AdminInterface::class)) {
    $loader->load('services_admin.yaml');
}
```

--------------------------------

### PHP Prompt Template Service Usage

Source: https://context7.com/xmon-org/ai-content-bundle/llms.txt

Demonstrates how to use the PromptTemplateService and AiTextService in PHP to generate article summaries. It includes rendering templates with variables and generating text based on system and user prompts. Dependencies include AiTextService and PromptTemplateService.

```php
<?php

use Xmon\AiContentBundle\Service\AiTextService;
use Xmon\AiContentBundle\Service\PromptTemplateService;
use Xmon\AiContentBundle\Enum\TaskType;

class ArticleService
{
    public function __construct(
        private readonly AiTextService $aiTextService,
        private readonly PromptTemplateService $promptTemplateService,
    ) {}

    public function generateSummary(string $title, string $content): string
    {
        // Render template with variables
        $rendered = $this->promptTemplateService->render('article_summary', [
            'title' => $title,
            'content' => $content,
        ]);

        // Generate text with rendered prompts
        $result = $this->aiTextService->generateForTask(
            TaskType::NEWS_CONTENT,
            systemPrompt: $rendered['system'],
            userMessage: $rendered['user'],
        );

        return $result->getTextTrimmed();
    }

    public function listAvailableTemplates(): array
    {
        // Get all template keys and names
        return $this->promptTemplateService->getTemplates();
        // Returns: ['article_summary' => 'Article Summary', ...]
    }

    public function renderCustomTemplate(string $templateKey, array $variables): array
    {
        // Check if template exists
        if (!$this->promptTemplateService->hasTemplate($templateKey)) {
            throw new \InvalidArgumentException("Template not found: {$templateKey}");
        }

        // Render with optional variant selection
        return $this->promptTemplateService->render($templateKey, $variables);
        // Returns: ['system' => '...', 'user' => '...', 'selected_variants' => [...]]
    }
}

```

--------------------------------

### Generate AI Image with Preset using PromptBuilder

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/styles-presets.md

Demonstrates how to use the PromptBuilder service to generate an AI image prompt using a predefined preset. It requires injecting PromptBuilder and AiImageService and calling the build method with the subject and preset option.

```php
use Xmon\AiContentBundle\Service\PromptBuilder;
use Xmon\AiContentBundle\Service\AiImageService;

class MyService
{
    public function __construct(
        private readonly PromptBuilder $promptBuilder,
        private readonly AiImageService $aiImageService,
    ) {}

    public function generateImage(): ImageResult
    {
        // Build prompt with preset
        $prompt = $this->promptBuilder->build(
            subject: 'aikidoka meditating in a traditional dojo',
            options: ['preset' => 'sumi-e-clasico']
        );

        // Result:
        // "aikidoka meditating in a traditional dojo, sumi-e Japanese ink wash
        //  painting, elegant brushstrokes, traditional, generous negative space,
        //  minimalist, breathing room, monochromatic color scheme, no text, ..."

        return $this->aiImageService->generate($prompt);
    }
}
```

--------------------------------

### Check AI Provider Configuration and Availability (PHP)

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Provides methods to verify if the text generation provider is set up and ready for use, and to retrieve a list of all AI providers that are currently available within the system. This is crucial for ensuring the service is operational before attempting generation.

```php
// Check if the text provider is configured and available
if ($this->aiTextService->isConfigured()) {
    // Ready to generate
}

// Get list of available providers
$providers = $this->aiTextService->getAvailableProviders();
// Returns: ['pollinations']

```

--------------------------------

### Build Style from Preset PHP

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/reference/image-options.md

Constructs a complete style string using a specified preset key, an optional suffix, and additional parameters. This method is designed to generate a formatted style string based on preset configurations.

```php
<?php

// Example usage (assuming $imageOptions is an instance of the relevant class)
// $styleString = $imageOptions->buildStyleFromPreset('abstract-modern', '-detailed', ['detail_level' => 'high']);

```

--------------------------------

### Generate AI Images with Styled Prompts (PHP)

Source: https://context7.com/xmon-org/ai-content-bundle/llms.txt

Demonstrates how to use the PromptBuilder and AiImageService in PHP to generate AI images. It shows methods for generating images using predefined style presets, custom style configurations, and globally defined styles. This requires the XmonAiContentBundle.

```php
<?php

use Xmon\AiContentBundle\Service\AiImageService;
use Xmon\AiContentBundle\Service\PromptBuilder;
use Xmon\AiContentBundle\Enum\TaskType;

class StyledImageGenerator
{
    public function __construct(
        private readonly AiImageService $aiImageService,
        private readonly PromptBuilder $promptBuilder,
    ) {}

    public function generateWithPreset(string $subject): array
    {
        // Use a predefined style preset
        $prompt = $this->promptBuilder->build($subject, [
            'preset' => 'sumi-e', // Preset includes style, composition, palette
        ]);
        // Result: "aikidoka meditating, sumi-e ink wash, negative space, monochrome"

        $result = $this->aiImageService->generateForTask(
            prompt: $prompt,
            options: [
                'width' => 1280,
                'height' => 720,
            ]
        );

        return [
            'image' => $result->toBase64(),
            'prompt' => $prompt,
        ];
    }

    public function generateWithCustomStyle(string $subject): array
    {
        // Build prompt with individual options
        $prompt = $this->promptBuilder->build($subject, [
            'style' => 'digital-art',
            'composition' => 'rule-of-thirds',
            'palette' => 'vibrant',
            'extras' => ['high-detail', 'dramatic-lighting'],
            'custom_prompt' => 'cinematic atmosphere',
        ]);

        $result = $this->aiImageService->generateForTask($prompt);

        return [
            'image' => $result->toDataUri(),
            'prompt' => $prompt,
        ];
    }

    public function generateFromGlobalStyle(string $subject): string
    {
        // Apply global style from configuration
        $prompt = $this->promptBuilder->buildWithGlobalStyle($subject);

        $result = $this->aiImageService->generateForTask($prompt);

        return $result->toBase64();
    }
}

```

--------------------------------

### Error Handling

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/task-types.md

Details the exception thrown when a requested AI model is not present in the allowed list for a given task.

```APIDOC
## Error Handling

If a requested model is not in `allowed_models`, an exception is thrown.

```php
try {
    $result = $this->aiTextService->generateForTask(
        TaskType::NEWS_CONTENT,
        $system,
        $user,
        ['model' => 'gpt-4-turbo'],  // Not in allowed_models
    );
} catch (AiProviderException $e) {
    // "Model 'gpt-4-turbo' is not allowed for task 'news_content'"
}
```
```

--------------------------------

### Checking Provider Status

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Details how to verify if the AI text provider is configured and available for use, and how to list all available providers.

```APIDOC
## Checking Provider Status

### Description
Before attempting to generate content, it's important to ensure that the AI provider is correctly configured and operational. This section describes how to check the configuration status and retrieve a list of all providers that are currently available.

### Method
GET (Implied by `isConfigured` and `getAvailableProviders` methods)

### Endpoint
`/api/ai-content/status` (Implied)

### Parameters
N/A

### Responses
#### Success Response (200)
- **is_configured** (Boolean) - `true` if the AI text provider is configured and ready, `false` otherwise.
- **available_providers** (Array of Strings) - A list of identifiers for all AI providers that are currently available (e.g., `['pollinations']`).
```

--------------------------------

### Implement Database Style Provider in PHP

Source: https://context7.com/xmon-org/ai-content-bundle/llms.txt

This PHP class implements the AiStyleProviderInterface to fetch style configurations from a database repository. It defines methods for retrieving global styles, default image models, debug mode settings, and provider priority. It depends on a ConfiguracionRepository and the AiStyleProviderInterface.

```php
<?php

namespace App\Provider;

use App\Repository\ConfiguracionRepository;
use Xmon\AiContentBundle\Provider\AiStyleProviderInterface;

final class ConfiguracionStyleProvider implements AiStyleProviderInterface
{
    public function __construct(
        private readonly ConfiguracionRepository $repository,
    ) {}

    public function getGlobalStyle(): string
    {
        $config = $this->repository->getConfiguracion();

        if ($config === null) {
            return ''; // Empty = skip this provider
        }

        return $config->getBaseStylePreview();
    }

    public function getDefaultImageModel(): ?string
    {
        $config = $this->repository->getConfiguracion();

        return $config?->getAiImageModel();
    }

    public function getAiDebugMode(): ?bool
    {
        $config = $this->repository->getConfiguracion();

        return $config?->getAiDebugMode();
    }

    public function getPriority(): int
    {
        return 100; // Higher than YAML (0) = takes precedence
    }

    public function isAvailable(): bool
    {
        return $this->repository->getConfiguracion() !== null;
    }
}

```

--------------------------------

### Full xmon_ai_content Bundle Configuration

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/installation.md

This YAML configuration provides detailed settings for the xmon_ai_content bundle, allowing customization of tasks, text generation parameters (API key, models, retries, timeout), image generation parameters (API key, models, dimensions, quality, prompts), and SonataMedia integration.

```yaml
# config/packages/xmon_ai_content.yaml
xmon_ai_content:
    # Task-based model configuration
    tasks:
        news_content:
            default_model: 'gemini'
            allowed_models: ['gemini', 'deepseek', 'mistral', 'openai']
        image_prompt:
            default_model: 'gemini-fast'
            allowed_models: ['gemini-fast', 'openai-fast', 'mistral']
        image_generation:
            default_model: 'flux'
            allowed_models: ['flux', 'turbo', 'gptimage']

    # Text generation (Pollinations API)
    text:
        api_key: '%env(XMON_AI_POLLINATIONS_API_KEY)%'
        model: 'gemini'
        fallback_models: ['mistral', 'deepseek']
        retries_per_model: 2
        retry_delay: 3
        timeout: 60
        endpoint_mode: 'openai'

    # Image generation (Pollinations API)
    image:
        api_key: '%env(XMON_AI_POLLINATIONS_API_KEY)%'
        model: 'flux'
        fallback_models: ['turbo']
        retries_per_model: 2
        retry_delay: 3
        timeout: 120
        width: 1280
        height: 720
        quality: 'high'
        negative_prompt: 'worst quality, blurry, text, letters, watermark'
        private: true
        nofeed: true

    # SonataMedia integration (optional)
    media:
        default_context: 'default'
        provider: 'sonata.media.provider.image'
```

--------------------------------

### Error Handling

Source: https://github.com/xmon-org/ai-content-bundle/blob/main/docs/guides/text-generation.md

Explains how to catch and handle exceptions that may occur during AI provider interactions, such as rate limits or timeouts.

```APIDOC
## Error Handling

### Description
Proper error handling is crucial when interacting with external AI providers. This section outlines how to catch specific exceptions, such as `AiProviderException`, and extract relevant information to manage failures gracefully, including rate limiting and timeouts.

### Method
POST / GET / PUT / DELETE (Depends on the operation)

### Endpoint
Various endpoints within the AI Content Bundle service.

### Parameters
N/A (Error handling is typically done via exception catching)

### Request Example
```php
try {
    // Attempt an AI generation operation
    $result = $this->aiTextService->generate($systemPrompt, $userMessage);
} catch (AiProviderException $e) {
    // Handle the caught exception
    // ...
}
```

### Response
#### Error Response (e.g., 429, 500)
- **exception_type** (String) - The type of exception thrown (e.g., `AiProviderException`).
- **provider** (String) - The name of the AI provider that caused the error (e.g., 'pollinations').
- **http_status_code** (Integer | null) - The HTTP status code returned by the provider (e.g., 429 for rate limiting, 500 for server errors, null for timeouts).
- **message** (String) - A detailed error message explaining the issue.

#### Response Example
```json
{
  "exception_type": "AiProviderException",
  "provider": "pollinations",
  "http_status_code": 429,
  "message": "Rate limit exceeded. Please try again later."
}
```
```
Tokens:
Raw