[AI Bundle][Platform] Integrate template rendering into Message API

[wachterjohannes]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	Fix #258
License	MIT

Summary

Adds a new prompt-template component to the Symfony AI monorepo, filling a gap we identified in our (Christopher Hertel and me) recent discussion about missing core functionality for prompt management.

Background

This implementation merges and adapts code from both sulu.ai and modelflow-ai projects, bringing battle-tested prompt templating into the Symfony AI ecosystem with a more extensible architecture.

Architecture

The component uses a strategy pattern for rendering, allowing different template processors to be plugged in:

• StringRenderer (default): Simple {variable} replacement with zero dependencies
• ExpressionRenderer: Advanced expression evaluation using Symfony Expression Language (optional)
• Extensible: Ready for additional renderers like Twig, Mustache, or custom implementations

Key Features

• Zero core dependencies (only PHP 8.2+)
• Factory pattern for exceptions with typed error methods
• Immutable readonly classes throughout
• Interface-first design for maximum flexibility
• Comprehensive test coverage (42 tests, 52 assertions)
• PHPStan level 6 compliant

Usage Examples

Simple variable replacement:

$template = PromptTemplate::fromString('Hello {name}!');
echo $template->format(['name' => 'World']); // "Hello World!"

Expression-based rendering:
$renderer = new ExpressionRenderer();
$template = new PromptTemplate('Total: {price * quantity}', $renderer);
echo $template->format(['price' => 10, 'quantity' => 5]); // "Total: 50"

Custom renderer:
class TwigRenderer implements RendererInterface {
    public function render(string $template, array $values): string {
        // Twig implementation
    }
}

This provides a solid foundation for prompt template management across the Symfony AI ecosystem while maintaining the flexibility to adapt to different rendering needs.

[chr-hertel]

Thanks for this @wachterjohannes - would really love to get this in 🙏

two things that we need to sort here:

1. is it a standalone component? for that we need to sort how we would use and render the template with the Message & Platform
2. terminology: we currently don't use the terminology "prompt", but "message" - i'd prefer to go with that here as well like MessageTemplate

we could have something like:

$template = new Symfony\AI\Platform\Message\Template::expression('Total: {price * quantity}');
$message = Message::forSystem($template);
$messages = new MessageBag($message);

$result = $platform->invoke('gpt-4o-mini', $messages, [
    'template_vars' => ['price' => 10, 'quantity' => 5],
]);

and later - while serializing - take care of the rendering - potentially throw an error on unsupported types.

with type being only a string instead of a renderer instance + named construct for promoted use:

class Template
{
    public function __construct(
        private string $template,
        private string $type,
    ) { }

    public static function string(string $template): self;
    public static function expression(string $template): self;
    public static function twig(string $template): self
    {
        return new self($template, 'twig');
    }
}

WDYT?

[wachterjohannes]

@chr-hertel in my opinion an own component makes sense as it is totally independent to the other component and as you mentioned we could integrate it into the agent and platform. @OskarStark what do you think.

Regarding the renaming - makes totally sense and i will do that when the decission over the component is final :)

[chr-hertel]

My thinking always is: API first, then implementation, then slicing. That's why i would delay that component discussion.

Templates alone are not valuable, they need an integration into the Message I'd say

[wachterjohannes]

@chr-hertel both are absolutly thru statements :) so let us wait for feedback from @OskarStark

[OskarStark]

Lets go with the platform component first 👍

[wachterjohannes]

@OskarStark that was luck 😂 pushed a few minutes ago!

[OskarStark]

Why is it needed for an assistant message, which comes from the LLM? 🤔

[wachterjohannes]

you are totally right :) will remove that from the AssistantMessage

[chr-hertel]

still in

[chr-hertel]

Awesome - you pretty much nailed it - only small stuff & fabbot - thanks already!

[wachterjohannes]

@chr-hertel fixed your comments

[chr-hertel]

how would we ever end up here - it's not installed in the bundle, right? should we do it with req --dev?

[chr-hertel]

also not needed?

Suggested change

	public static function ofAssistant(string|Template|null $content = null, ?array $toolCalls = null): AssistantMessage
	public static function ofAssistant(?string $content = null, ?array $toolCalls = null): AssistantMessage

[chr-hertel]

missed that before

Suggested change

	final readonly class ExpressionLanguageTemplateRenderer implements TemplateRendererInterface
	final class ExpressionLanguageTemplateRenderer implements TemplateRendererInterface

[chr-hertel]

Suggested change

	final readonly class StringTemplateRenderer implements TemplateRendererInterface
	final class StringTemplateRenderer implements TemplateRendererInterface

[chr-hertel]

all those : void return type declarations on test* methods have to go, according to Symfony code style

[chr-hertel]

please rename the folder to template and split into 4 different files - locally I'm executing all examples from time to time in parallel - and it will go faster like that