From ebd9a2ac0f356ef643443111ec71939f5ed269fb Mon Sep 17 00:00:00 2001
From: Paulo Castellano <paulo@castellanos.llc>
Date: Wed, 17 Jun 2026 17:03:42 -0300
Subject: [PATCH] feat(ai-templates): content template contract + value objects

---
 app/Ai/Templates/AiContentTemplate.php | 60 ++++++++++++++++++++++++++
 app/Ai/Templates/GeneratedPost.php     | 23 ++++++++++
 app/Ai/Templates/TemplateContext.php   | 21 +++++++++
 3 files changed, 104 insertions(+)
 create mode 100644 app/Ai/Templates/AiContentTemplate.php
 create mode 100644 app/Ai/Templates/GeneratedPost.php
 create mode 100644 app/Ai/Templates/TemplateContext.php

diff --git a/app/Ai/Templates/AiContentTemplate.php b/app/Ai/Templates/AiContentTemplate.php
new file mode 100644
index 00000000..8ec3d62a
--- /dev/null
+++ b/app/Ai/Templates/AiContentTemplate.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Ai\Templates;
+
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+
+interface AiContentTemplate
+{
+    /** Stable key used in the request + registry, e.g. 'image_card'. */
+    public function key(): string;
+
+    /** i18n key for the gallery label. */
+    public function name(): string;
+
+    /** i18n key for the gallery description. */
+    public function description(): string;
+
+    /** Public path to the preview thumbnail shown in the picker. */
+    public function previewAsset(): string;
+
+    /** Whether a social account must be selected for this template. */
+    public function needsAccount(): bool;
+
+    /**
+     * Content types (by value) this template can produce. Empty = all AI formats.
+     *
+     * @return array<int, string>
+     */
+    public function supportedFormats(): array;
+
+    /** The 'format' string passed to the generator agent (e.g. 'single'). */
+    public function generatorFormat(): string;
+
+    /** The Blade view path for the generator prompt. */
+    public function promptView(): string;
+
+    /**
+     * The structured-output schema for the generator.
+     *
+     * @return array<string, mixed>
+     */
+    public function schema(JsonSchema $schema, TemplateContext $context): array;
+
+    /**
+     * Text fields (by structured-output key) the humanizer should rewrite.
+     * Empty = skip humanization.
+     *
+     * @return array<string, string>
+     */
+    public function humanizableFields(): array;
+
+    /**
+     * Build the post from the (humanized) structured output.
+     *
+     * @param  array<string, mixed>  $structured
+     */
+    public function assemble(array $structured, TemplateContext $context): GeneratedPost;
+}
diff --git a/app/Ai/Templates/GeneratedPost.php b/app/Ai/Templates/GeneratedPost.php
new file mode 100644
index 00000000..690807e6
--- /dev/null
+++ b/app/Ai/Templates/GeneratedPost.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Ai\Templates;
+
+use App\Enums\PostPlatform\ContentType;
+
+/**
+ * The output of a template's assemble(): the caption to store as Post.content,
+ * the media items to attach, and the content type the post platform should use.
+ */
+class GeneratedPost
+{
+    /**
+     * @param  array<int, array<string, mixed>>  $media
+     */
+    public function __construct(
+        public string $content,
+        public array $media,
+        public ?ContentType $contentType,
+    ) {}
+}
diff --git a/app/Ai/Templates/TemplateContext.php b/app/Ai/Templates/TemplateContext.php
new file mode 100644
index 00000000..9a0cb16b
--- /dev/null
+++ b/app/Ai/Templates/TemplateContext.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Ai\Templates;
+
+use App\Models\SocialAccount;
+use App\Models\Workspace;
+
+/**
+ * Everything a template needs to assemble a post from the LLM output.
+ */
+class TemplateContext
+{
+    public function __construct(
+        public Workspace $workspace,
+        public ?SocialAccount $socialAccount,
+        public string $format,
+        public int $imageCount,
+    ) {}
+}