syntaxmatrix 2.5.8.2__py3-none-any.whl → 2.6.1__py3-none-any.whl

syntaxmatrix/agentic/agents.py

@@ -2,8 +2,9 @@
 from __future__ import annotations
 import os, re, json, textwrap, requests
 import pandas as pd
-
-from typing import Optional, List
+import uuid
+import io
+from typing import Optional, List, Any, Dict
 
 from syntaxmatrix import utils
 from syntaxmatrix.settings.model_map import GPT_MODELS_LATEST
@@ -13,6 +14,14 @@ from google.genai import types
 import tiktoken
 from google.genai.errors import APIError
 
+from io import BytesIO
+from PIL import Image
+
+from dataclasses import dataclass
+import hashlib
+from PIL import Image
+from syntaxmatrix.page_layout_contract import normalise_layout, validate_layout
+
 
 def token_calculator(total_input_content, llm_profile):
 
@@ -42,7 +51,7 @@ def token_calculator(total_input_content, llm_profile):
         input_prompt_tokens = len(enc.encode(total_input_content))
         return input_prompt_tokens    
 
-def mlearning_agent(user_prompt, system_prompt, coding_profile):
+def mlearning_agent(user_prompt, system_prompt, coder_profile):
     """
     Returns:
         (text, usage_dict)
@@ -58,11 +67,12 @@ def mlearning_agent(user_prompt, system_prompt, coding_profile):
         }
     """
 
-    # coding_profile['client'] = _prof.get_client(coding_profile)
-    _client = coding_profile["client"]
-    _provider = coding_profile["provider"].lower()
-    _model = coding_profile["model"]
-    
+    _coder_profile = _prof.get_profile('coder')
+    _coder_profile['client'] = _prof.get_client(_coder_profile)
+    _client = _coder_profile['client']
+    _provider = _coder_profile["provider"].lower()
+    _model = _coder_profile["model"]
+
     usage = {
         "provider": _provider,
         "model": _model,
@@ -185,7 +195,7 @@ def mlearning_agent(user_prompt, system_prompt, coding_profile):
 
     # Anthropic
     def anthropic_generate_code():  
-        nonlocal usage      
+            
         try:        
             resp = _client.messages.create(
                 model=_model,
@@ -292,15 +302,16 @@ def mlearning_agent(user_prompt, system_prompt, coding_profile):
     return code, usage
     
 
-def refine_question_agent(raw_question: str, dataset_context: str | None = None) -> str:
-    
-    def response_agent(user_prompt, system_prompt, llm_profile, temp=0.0, max_tokens=128):
-        _profile = llm_profile
-        
-        _client = _profile["client"]
-        _provider = _profile["provider"].lower()
-        _model = _profile["model"]
-        
+def context_compatibility(question: str, dataset_context: str | None = None) -> str:
+
+    _profile = _prof.get_profile('classifier') or _prof.get_profile('admin')
+    _profile['client'] = _prof.get_client(_profile)
+    _client = _profile['client']
+    _provider = _profile.get("provider").lower()
+    _model = _profile.get("model")
+
+    def compatibility_response(user_prompt, system_prompt, temp=0.0, max_tokens=128):
+                        
         # Google GenAI
         if _provider == "google":
             resp = _client.models.generate_content(
@@ -384,37 +395,32 @@ def refine_question_agent(raw_question: str, dataset_context: str | None = None)
         return "Configure LLM Profiles or contact your administrator."
 
     system_prompt = ("""
-        - You are a Machine Learning (ML) and Data Science (DS) expert.
-        - Your goal is to use the provided dataset summary to convert given question into clear ML job specifications.
-        - Use the provided dataset summary to respect columns and aid you in properly refining the user question.
-        - Include chronological outline in order to guide a code generator to avoid falling off tracks. 
-        - DO NOT include any prelude or preamble. Just the refined tasks.
-        - If and only if the dataset summary columns are not relevant to your desired columns that you deduced by analysing the question, and you suspect that the wrong dataset was used in the dataset summary, stop and just say: 'incompatible'.
+        - You are a Machine Learning (ML) and Data Science (DS) expert who detects incompatibilities between user questions and dataset summaries.
+        - Your goal is to analyze the question and the provided dataset summary to determine if they are compatible. 
+        - If and only if the dataset summary columns are not relevant to your desired columns that you have deduced, by analysing the question, and you suspect that the wrong dataset was used in the dataset summary, you MUST STOP just say: 'incompatible'.      
+        - If they are compatible, just 'compatible'.
+        - DO NOT include any prelude or preamble. Just the response: 'incompatible' or 'compatible'.
     """)
 
-    user_prompt = f"User question:\n{raw_question}\n\n"
+    user_prompt = f"User question:\n{question}\n\n"
     if dataset_context:
         user_prompt += f"Dataset summary:\n{dataset_context}\n"
 
-    _refiner_profile =  _prof.get_profile("classification") or _prof.get_profile("admin")
-    if not _refiner_profile:
-        return "ERROR"
-
-    _refiner_profile['client'] = _prof.get_client(_refiner_profile)
-
-    refined_question = response_agent(user_prompt, system_prompt, _refiner_profile, temp=0.0, max_tokens=128)
-    return refined_question
+    compatibility = compatibility_response(user_prompt, system_prompt, temp=0.0, max_tokens=120)
+    return compatibility
   
 
 def classify_ml_job_agent(refined_question, dataset_profile):   
     import ast
-    def ml_response(user_prompt, system_prompt, profile):
-        _profile = profile  # _prof.get_profile["admin"]
-        
-        _client = _profile["client"]
-        _provider = _profile["provider"].lower()
-        _model = _profile["model"]
+    
+    _profile = _prof.get_profile('classifier') or _prof.get_profile('admin')
+    _profile['client'] = _prof.get_client(_profile)
+    _client = _profile['client']
+    _provider = _profile["provider"].lower()
+    _model = _profile["model"]
 
+    def ml_response(user_prompt, system_prompt): 
+        
         prompt = user_prompt + "\n\n" + system_prompt
         
         # Google GenAI
@@ -520,10 +526,17 @@ def classify_ml_job_agent(refined_question, dataset_profile):
         return "Configure LLM Profiles or contact your administrator."
 
     system_prompt = ("""
-        You are a strict machine learning task classifier for an ML workbench.
-        Your goal is to correctly label the user's task specifications with the most relevant tags from a fixed list.
-        You Must always have 'data_preprocessing' as the 1st tag. Then add all other relevant tags. 
-        You should return only your list of tags, no prelude or preamble.
+        "You are an expert ML task extractor. Your job is to analyze the user's task description and extract every implied or explicit machine learning (ML) task that would be necessary to accomplish the user's goals. Use the provided list of ML tasks as your reference for classification.
+        Core Instruction:
+        Extract every implied or explicit ML task. Format the response solely as a simple, flat list of tasks. Use concise, imperative verbs. Do not include explanations, examples, preludes, conclusions, or any non-task text.
+
+        Extraction Rules:
+        Ignore all context-setting, descriptions, goals, and commentary.
+        Convert every actionable step, data operation, and visualization generation into a discrete task.
+        Generalize any dataset-specific terms (e.g., column names) to their functional purpose.
+        Treat "CoT" or reasoning steps as a source for data preparation tasks.
+        Do not include steps like "No Scaling required" or "No Modeling required" as tasks.
+        Output only the list. No titles, headers, numbering or bullet points.
     """)
 
     # --- 1. Define the Master List of ML Tasks (Generalized) ---
@@ -568,24 +581,1106 @@ def classify_ml_job_agent(refined_question, dataset_profile):
     if dataset_profile:
         user_prompt += f"\nDataset profile:\n{dataset_profile}\n"
         
-    llm_profile =  _prof.get_profile("classification") or _prof.get_profile("admin")
-    if not llm_profile:
-        return (
-            "<div class='smx-alert smx-alert-warn'>"
-                "No LLM profile is configured for Classification. Please, do that in the Admin panel or contact your Administrator."
-            "</div>"
-        )
-
 
-    llm_profile['client'] = _prof.get_client(llm_profile)
-
-    tasks = ml_response(user_prompt, system_prompt, llm_profile)
+    tasks = ml_response(user_prompt, system_prompt)
     try:
         return ast.literal_eval(tasks)
     except Exception:
         return tasks
 
 
+# ─────────────────────────────────────────────────────────
+# Agentic Page Generation (plan JSON → validate → Pixabay → compile HTML)
+# ─────────────────────────────────────────────────────────
+def agentic_generate_page(*,
+    page_slug: str,
+    website_description: str,
+    client_dir: str,
+    pixabay_api_key: str = "",
+    llm_profile: dict | None = None,
+    max_retries: int = 2,
+    max_images: int = 9,
+) -> dict:
+    """
+    Returns:
+      {
+        "slug": "<slug>",
+        "plan": <dict>,
+        "html": "<compiled html>",
+        "notes": [..]
+      }
+    """
+
+    _ICON_SVGS = {
+        "spark": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M12 2l1.2 6.2L20 12l-6.8 3.8L12 22l-1.2-6.2L4 12l6.8-3.8L12 2z"/></svg>',
+        "shield": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M12 2l7 4v6c0 5-3.5 9-7 10-3.5-1-7-5-7-10V6l7-4z"/></svg>',
+        "stack": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M12 2l9 5-9 5-9-5 9-5z"/><path d="M3 12l9 5 9-5"/><path d="M3 17l9 5 9-5"/></svg>',
+        "chart": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M3 3v18h18"/><path d="M7 14v4"/><path d="M12 10v8"/><path d="M17 6v12"/></svg>',
+        "rocket": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M5 13l4 6 6-4c6-4 5-12 5-12S13 2 9 8l-4 5z"/><path d="M9 8l7 7"/>'
+                '<path d="M5 13l-2 2"/><path d="M11 19l-2 2"/></svg>',
+        "plug": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M9 2v6"/><path d="M15 2v6"/><path d="M7 8h10"/>'
+                '<path d="M12 8v7a4 4 0 0 1-4 4H7"/><path d="M12 8v7a4 4 0 0 0 4 4h1"/></svg>',
+        "arrow": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M5 12h12"/><path d="M13 6l6 6-6 6"/></svg>',
+        "users": '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">'
+                '<path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/>'
+                '<circle cx="9" cy="7" r="4"/>'
+                '<path d="M23 21v-2a4 4 0 0 0-3-3.87"/>'
+                '<path d="M16 3.13a4 4 0 0 1 0 7.75"/></svg>',
+    }
+
+    _PLACEHOLDER_PATTERNS = [
+        r"\blorem\b",
+        r"\bplaceholder\b",
+        r"coming soon",
+        r"add (?:a|your|an)\b",
+        r"replace this",
+        r"insert (?:your|a)\b",
+        r"dummy text",
+        r"example (?:text|copy)\b",
+    ]
+
+    _PX_BANNED_TAGS = {
+        "shoe", "shoes", "sneaker", "sneakers", "footwear", "fashion",
+        "lingerie", "bikini", "underwear", "swimwear",
+    }
+
+
+    def _strip(s: str) -> str:
+        return (s or "").strip()
+
+    def _slugify(s: str) -> str:
+        s = _strip(s).lower()
+        s = re.sub(r"[^a-z0-9\s\-]", "", s)
+        s = re.sub(r"\s+", "-", s).strip("-")
+        s = re.sub(r"-{2,}", "-", s)
+        return s or "page"
+
+    def _title_from_slug(slug: str) -> str:
+        t = _strip(slug).replace("-", " ").replace("_", " ")
+        t = re.sub(r"\s+", " ", t)
+        return (t[:1].upper() + t[1:]) if t else "New page"
+
+    def _contains_placeholders(text: str) -> bool:
+        t = (text or "").lower()
+        for pat in _PLACEHOLDER_PATTERNS:
+            if re.search(pat, t):
+                return True
+        return False
+
+    def _extract_domain_keywords(website_description: str, max_terms: int = 6) -> list[str]:
+        """
+        Very lightweight keyword extraction to keep Pixabay queries on-topic.
+        No ML needed: just pick frequent meaningful tokens.
+        """
+        wd = (website_description or "").lower()
+        wd = re.sub(r"[^a-z0-9\s\-]", " ", wd)
+        toks = [t for t in re.split(r"\s+", wd) if 3 <= len(t) <= 18]
+        stop = {
+            "this", "that", "with", "from", "into", "your", "their", "have", "will",
+            "also", "more", "than", "them", "such", "only", "when", "where", "which",
+            "what", "about", "page", "website", "company", "product", "service",
+            "syntaxmatrix", "framework", "system", "platform",
+        }
+        freq = {}
+        for t in toks:
+            if t in stop:
+                continue
+            freq[t] = freq.get(t, 0) + 1
+        ranked = sorted(freq.items(), key=lambda x: x[1], reverse=True)
+        out = [k for k, _ in ranked[:max_terms]]
+        # Always anchor to software/AI semantics if present
+        anchors = []
+        for a in ["ai", "assistant", "dashboard", "retrieval", "vector", "ml", "analytics", "deployment"]:
+            if a in wd and a not in out:
+                anchors.append(a)
+        return (anchors + out)[:max_terms]
+
+    def _get_json_call(system_prompt: str, user_prompt: str) -> dict:
+        
+        llm_profile = _prof.get_profile('coder')
+        llm_profile['client'] = _prof.get_client(llm_profile)
+        client = llm_profile["client"]
+        model = llm_profile["model"]
+        provider = llm_profile["provider"].lower()
+
+        
+        def openai_sdk_response():
+            resp = client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                response_format={"type": "json_object"},
+            )
+            
+            # Access the text via choices[0].message.content
+            txt = resp.choices[0].message.content.strip()
+            
+            try:
+                return json.loads(txt)
+            except Exception:
+                # try to salvage first JSON object (consistent with your other providers)
+                m = re.search(r"\{.*\}", txt, re.S)
+                if not m:
+                    raise RuntimeError(f"Model did not return JSON. Output was:\n{txt[:800]}")
+                return json.loads(m.group(0))
+    
+
+        if provider == "google":
+            cfg = types.GenerateContentConfig(
+                system_instruction=system_prompt,
+                response_mime_type="application/json",
+            )
+            resp = client.models.generate_content(
+                model=model,
+                contents=user_prompt,
+                config=cfg,
+            )
+            txt = (resp.text or "").strip()
+            try:
+                return json.loads(txt)
+            except Exception:
+                # try to salvage first JSON object
+                m = re.search(r"\{.*\}", txt, re.S)
+                if not m:
+                    raise RuntimeError(f"Model did not return JSON. Output was:\n{txt[:800]}")
+                return json.loads(m.group(0))
+        
+
+        if provider == "openai":
+            if int(model.split("gpt-")[1][0])>=5:
+                response = client.responses.create(
+                    model=model, 
+                    instructions=system_prompt, 
+                    input=[
+                        {"role": "user", "content": user_prompt}
+                    ],
+                    reasoning={"effort": "medium"},
+                    text=[
+                        {"verbosity": "low"},
+                        {"format": {"type": "json_object"}}
+                    ],
+                )
+
+                txt = (response.output_text or "")
+                try:
+                    return json.loads(txt)
+                except Exception:
+                    # try to salvage first JSON object
+                    m = re.search(r"\{.*\}", txt, re.S)
+                    if not m:
+                        raise RuntimeError(f"Model did not return JSON. Output was:\n{txt[:800]}")
+                    return json.loads(m.group(0))
+
+            else:
+                return openai_sdk_response()
+
+
+        if provider == "anthropic":
+            # Anthropic requires a max_tokens parameter
+            resp = client.messages.create(
+                model=model,
+                system=system_prompt,
+                messages=[
+                    {"role": "user", "content": user_prompt}
+                ],
+                max_tokens=4096, 
+            )
+            
+            # Anthropic returns a list of content blocks
+            txt = resp.content[0].text.strip()
+            
+            try:
+                return json.loads(txt)
+            except Exception:
+                # try to salvage first JSON object (same logic as your Google snippet)
+                m = re.search(r"\{.*\}", txt, re.S)
+                if not m:
+                    raise RuntimeError(f"Model did not return JSON. Output was:\n{txt[:800]}")
+                return json.loads(m.group(0))
+        
+        return openai_sdk_response()
+
+
+    def _page_plan_system_prompt(spec: dict) -> str:
+        allowed_sections = spec.get("allowed_section_types") or ["hero", "features", "gallery", "testimonials", "faq", "cta", "richtext"]
+        req = spec.get("required_sections") or []
+
+        req_lines = ""
+        if req:
+            req_lines = "REQUIRED SECTIONS (must appear in this exact order):\n" + "\n".join(
+                [f"- {r['id']} (type: {r['type']})" for r in req]
+            )
+
+        return f"""
+        You are a senior UX designer + product copywriter for modern software websites.
+
+        TASK:
+        Create a complete page plan (content + structure) for a page builder.
+
+        RULES (strict):
+        - No placeholders, no “add your…”, no “replace this…”, no “lorem ipsum”, no “coming soon”.
+        - All copy must be final, meaningful, and grounded in the provided WEBSITE_DESCRIPTION.
+        - Produce a page that looks like a finished, publish-ready website page.
+        - Choose section types and item types from the allowed lists.
+        - Choose icon names only from the allowed icon list.
+        - Provide image search queries for items that need images. Keep queries on-topic (software/AI/tech).
+
+        {req_lines}
+
+        OUTPUT:
+        Return ONLY valid JSON.
+
+        ALLOWED SECTION TYPES:
+        {chr(10).join([f"- {t}" for t in allowed_sections])}
+
+        ALLOWED ITEM TYPES:
+        - card
+        - quote
+        - faq
+
+        ALLOWED ICONS:
+        - spark, shield, stack, chart, rocket, plug, arrow, users
+
+        JSON SCHEMA:
+        {{
+          "page": "<slug>",
+          "category": "<string>",
+          "template": {{ "id": "<string>", "version": "<string>" }},
+          "meta": {{
+            "pageTitle": "<string>",
+            "summary": "<string>"
+          }},
+          "sections": [
+            {{
+              "id": "<string>",
+              "type": "<sectionType>",
+              "title": "<string>",
+              "text": "<string>",
+              "cols": 1-5,
+              "items": [
+                {{
+                  "id": "<string>",
+                  "type": "<itemType>",
+                  "title": "<string>",
+                  "text": "<string>",
+                  "icon": "<iconName or empty>",
+                  "imgQuery": "<search query or empty>",
+                  "needsImage": true|false
+                }}
+              ]
+            }}
+          ]
+        }}
+
+        GUIDANCE:
+        - Keep sections between {spec.get("min_sections", 4)} and {spec.get("max_sections", 7)}.
+        - Keep total images between {spec.get("min_images", 6)} and {spec.get("max_images", 9)}.
+        """.strip()
+
+
+    def _make_page_plan(*, page_slug: str, website_description: str, template_spec: dict) -> dict:
+        slug = _slugify(page_slug)
+        wd = _strip(website_description)
+        if not wd:
+            raise ValueError("website_description is empty. Pass smx.website_description if the form field is blank.")
+
+        domain_terms = _extract_domain_keywords(wd)
+        user_prompt = json.dumps({
+            "PAGE_SLUG": slug,
+            "PAGE_TITLE": _title_from_slug(slug),
+            "WEBSITE_DESCRIPTION": wd,
+            "DOMAIN_KEYWORDS": domain_terms,
+            "HARD_REQUIREMENTS": {
+                "no_placeholders": True,
+                "uk_english": True,
+                "min_sections": 4,
+                "max_sections": 7,
+                "min_images": 6,
+                "max_images": 9
+            }
+        }, indent=2)
+
+        plan = _get_json_call(
+            system_prompt=_page_plan_system_prompt(template_spec),
+            user_prompt=user_prompt
+        )
+
+        plan["page"] = slug
+        plan["category"] = template_spec["category"]
+        plan["template"] = template_spec["template"]
+
+        # Normalise a few fields
+        plan["page"] = slug
+        if "sections" not in plan or not isinstance(plan["sections"], list):
+            raise RuntimeError("Invalid plan: missing sections[]")
+
+        return plan
+
+
+    def _validate_plan_or_raise(plan: dict) -> None:
+        if not isinstance(plan, dict):
+            raise ValueError("Plan is not a dict.")
+
+        if not plan.get("page"):
+            raise ValueError("Plan missing 'page'.")
+
+        secs = plan.get("sections")
+        if not isinstance(secs, list) or len(secs) < 3:
+            raise ValueError("Plan must have at least 3 sections.")
+
+        total_imgs = 0
+        for s in secs:
+            if not isinstance(s, dict):
+                raise ValueError("Section is not an object.")
+            if _contains_placeholders(s.get("title", "")) or _contains_placeholders(s.get("text", "")):
+                raise ValueError("Plan contains placeholder text in section title/text.")
+
+            items = s.get("items") or []
+            if not isinstance(items, list):
+                raise ValueError("Section items must be a list.")
+            for it in items:
+                if not isinstance(it, dict):
+                    raise ValueError("Item is not an object.")
+                if _contains_placeholders(it.get("title", "")) or _contains_placeholders(it.get("text", "")):
+                    raise ValueError("Plan contains placeholder text in item title/text.")
+                if it.get("needsImage"):
+                    total_imgs += 1
+
+        if total_imgs < 4:
+            raise ValueError("Plan is too light on imagery; needs at least 4 items marked needsImage=true.")
+
+
+    def _repair_plan(*, plan: dict, error_msg: str, website_description: str) -> dict:
+        # Ask Gemini to repair the plan, not recreate randomly.
+        system_prompt = _page_plan_system_prompt() + "\n\nYou are repairing an existing plan. Keep it consistent and improve only what is needed."
+        user_prompt = json.dumps({
+            "ERROR": error_msg,
+            "WEBSITE_DESCRIPTION": website_description,
+            "PLAN": plan
+        }, indent=2)
+
+        fixed = _get_json_call(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt
+        )
+        fixed["page"] = plan.get("page") or fixed.get("page")
+        return fixed
+    
+    def _ensure_hero_image(plan: dict, default_url: str = "/static/assets/hero-default.svg") -> None:
+        """Guarantee hero.imageUrl exists so contract validation never fails."""
+        sections = plan.get("sections") if isinstance(plan.get("sections"), list) else []
+        hero = next((s for s in sections if isinstance(s, dict) and (s.get("type") or "").lower() == "hero"), None)
+        if not hero:
+            return
+
+        def _first_image_in_items(items):
+            if not isinstance(items, list):
+                return ""
+            for it in items:
+                if not isinstance(it, dict):
+                    continue
+                u = (it.get("imageUrl") or "").strip()
+                if u:
+                    return u
+            return ""
+
+        # 1) Use hero.imageUrl if present
+        img = (hero.get("imageUrl") or "").strip()
+
+        # 2) Else use hero.items[*].imageUrl
+        if not img:
+            img = _first_image_in_items(hero.get("items"))
+
+        # 3) Else use first image anywhere else in the plan
+        if not img:
+            for s in sections:
+                if not isinstance(s, dict):
+                    continue
+                img = _first_image_in_items(s.get("items"))
+                if img:
+                    break
+
+        # 4) Final fallback
+        if not img:
+            img = default_url
+
+        hero["imageUrl"] = img
+
+        # Back-compat: ensure hero.items[0].imageUrl exists too (your normaliser also does this)
+        items = hero.get("items") if isinstance(hero.get("items"), list) else []
+        if items:
+            if not (items[0].get("imageUrl") or "").strip():
+                items[0]["imageUrl"] = img
+        else:
+            hero["items"] = [{"id": "hero_media", "type": "card", "title": "Hero image", "text": "", "imageUrl": img}]
+
+    TEMPLATE_SPECS = {
+        "generic_v1": {
+            "category": "landing",
+            "template": {"id": "generic_v1", "version": "1.0.0"},
+            "allowed_section_types": ["hero", "features", "gallery", "testimonials", "faq", "cta", "richtext"],
+            "required_sections": [],
+            "min_sections": 4,
+            "max_sections": 7,
+            "min_images": 6,
+            "max_images": 9,
+        },
+        "services_grid_v1": {
+            "category": "services",
+            "template": {"id": "services_grid_v1", "version": "1.0.0"},
+            "allowed_section_types": ["hero", "services", "process", "proof", "faq", "cta", "richtext"],
+            "required_sections": [
+                {"id": "sec_hero", "type": "hero"},
+                {"id": "sec_services", "type": "services"},
+                {"id": "sec_process", "type": "process"},
+                {"id": "sec_proof", "type": "proof"},
+                {"id": "sec_faq", "type": "faq"},
+                {"id": "sec_cta", "type": "cta"},
+            ],
+            "min_sections": 6,
+            "max_sections": 6,
+            "min_images": 6,
+            "max_images": 9,
+        },
+        "services_detail_v1": {
+            "category": "services",
+            "template": {"id": "services_detail_v1", "version": "1.0.0"},
+            "allowed_section_types": ["hero", "offers", "comparison", "process", "case_studies", "faq", "cta", "richtext"],
+            "required_sections": [
+                {"id": "sec_hero", "type": "hero"},
+                {"id": "sec_offers", "type": "offers"},
+                {"id": "sec_comparison", "type": "comparison"},
+                {"id": "sec_process", "type": "process"},
+                {"id": "sec_case_studies", "type": "case_studies"},
+                {"id": "sec_faq", "type": "faq"},
+                {"id": "sec_cta", "type": "cta"},
+            ],
+            "min_sections": 7,
+            "max_sections": 7,
+            "min_images": 6,
+            "max_images": 9,
+        },
+        "about_glass_hero_v1": {
+            "category": "about",
+            "template": {"id": "about_glass_hero_v1", "version": "1.0.0"},
+            "allowed_section_types": ["hero", "story", "values", "logos", "team", "testimonials", "faq", "cta", "richtext"],
+            "required_sections": [
+                {"id": "sec_hero", "type": "hero"},
+                {"id": "sec_story", "type": "story"},
+                {"id": "sec_values", "type": "values"},
+                {"id": "sec_cta", "type": "cta"},
+            ],
+            "min_sections": 4,
+            "max_sections": 7,
+            "min_images": 6,
+            "max_images": 9,
+        },
+    }
+
+    def _select_template_spec(slug: str) -> dict:
+        s = _slugify(slug)
+        if "service" in s:
+            if any(k in s for k in ("pricing", "plan", "plans", "package", "packages", "tier", "tiers")):
+                return TEMPLATE_SPECS["services_detail_v1"]
+            return TEMPLATE_SPECS["services_grid_v1"]
+        if "about" in s:
+            return TEMPLATE_SPECS["about_glass_hero_v1"]
+        return TEMPLATE_SPECS["generic_v1"]
+
+
+    PIXABAY_API_URL = "https://pixabay.com/api/"
+
+    def _pixabay_search(api_key: str, query: str, *, category: str = "AI", per_page: int = 20, timeout: int = 15) -> list[dict]:
+        q = _strip(query)
+        if not api_key or not q:
+            return []
+        params = {
+            "key": api_key,
+            "q": q,
+            "image_type": "photo",
+            "orientation": "horizontal",
+            "safesearch": "true",
+            "editors_choice": "false",
+            "order": "popular",
+            "category": category or "AI" or "Artificial Intelligence" or "computer",
+            "per_page": max(3, min(200, int(per_page or 20))),
+            "page": 1,
+        }
+        r = requests.get(PIXABAY_API_URL, params=params, timeout=timeout)
+        r.raise_for_status()
+        data = r.json() or {}
+        return data.get("hits") or []
+
+
+    def _is_pixabay_url(url: str) -> bool:
+        u = _strip(url).lower()
+        return u.startswith("https://") and ("pixabay.com" in u)
+
+
+    def _fetch_bytes(url: str, timeout: int = 20) -> bytes:
+        if not _is_pixabay_url(url):
+            raise ValueError("Only Pixabay URLs are allowed")
+        r = requests.get(url, stream=True, timeout=timeout)
+        r.raise_for_status()
+        return r.content
+
+
+    def _save_image(img_bytes: bytes, out_path_no_ext: str, *, max_width: int = 1920) -> str:
+        img = Image.open(io.BytesIO(img_bytes))
+        img.load()
+
+        if img.width > int(max_width or 1920):
+            ratio = (int(max_width) / float(img.width))
+            new_h = max(1, int(round(img.height * ratio)))
+            img = img.resize((int(max_width), new_h), Image.LANCZOS)
+
+        has_alpha = ("A" in img.getbands())
+        ext = ".png" if has_alpha else ".jpg"
+        out_path = out_path_no_ext + ext
+        os.makedirs(os.path.dirname(out_path), exist_ok=True)
+
+        if ext == ".jpg":
+            rgb = img.convert("RGB") if img.mode != "RGB" else img
+            rgb.save(out_path, "JPEG", quality=85, optimize=True, progressive=True)
+        else:
+            img.save(out_path, "PNG", optimize=True)
+
+        return out_path
+
+
+    def _pick_pixabay_hit(hits: list[dict], *, min_width: int) -> dict | None:
+        for h in hits:
+            tags = (h.get("tags") or "").lower()
+            if any(b in tags for b in _PX_BANNED_TAGS):
+                continue
+            w = int(h.get("imageWidth") or 0)
+            if w >= int(min_width or 0):
+                return h
+        # fallback: first non-banned
+        for h in hits:
+            tags = (h.get("tags") or "").lower()
+            if any(b in tags for b in _PX_BANNED_TAGS):
+                continue
+            return h
+        return None
+
+
+    def fill_plan_images_from_pixabay(plan: dict, *, api_key: str, client_dir: str, max_width: int = 1920, max_downloads: int = 9) -> dict:
+        if not api_key:
+            return plan
+
+        media_dir = os.path.join(client_dir, "uploads", "media")
+        imported_dir = os.path.join(media_dir, "images", "imported")
+        os.makedirs(imported_dir, exist_ok=True)
+
+        used_ids = set()
+        downloads = 0
+
+        domain_terms = []
+        try:
+            meta = plan.get("meta") or {}
+            domain_terms = _extract_domain_keywords(meta.get("summary") or "", max_terms=5)
+        except Exception:
+            domain_terms = []
+
+        for s in (plan.get("sections") or []):
+            items = s.get("items") or []
+            for it in items:
+                if downloads >= max_downloads:
+                    return plan
+                if not it.get("needsImage"):
+                    continue
+                if _strip(it.get("imageUrl")):
+                    continue
+
+                q = _strip(it.get("imgQuery"))
+                if not q:
+                    # if model forgot: make something safe and on-topic
+                    q = f"{_strip(it.get('title'))} software ai dashboard"
+
+                # keep the query on-domain
+                if domain_terms:
+                    q = f"{q} " + " ".join(domain_terms[:3])
+
+                min_w = 1920 if (s.get("type") == "hero") else 1100
+
+                hits = _pixabay_search(api_key, q, category="computer")
+                if not hits:
+                    continue
+
+                chosen = _pick_pixabay_hit(hits, min_width=min_w)
+                if not chosen:
+                    continue
+
+                pid = int(chosen.get("id") or 0)
+                if not pid or pid in used_ids:
+                    continue
+                used_ids.add(pid)
+
+                web_u = _strip(chosen.get("webformatURL") or "")
+                large_u = _strip(chosen.get("largeImageURL") or "")
+
+                base = os.path.join(imported_dir, f"pixabay-{pid}")
+                existing = None
+                for ext in (".jpg", ".png"):
+                    if os.path.exists(base + ext):
+                        existing = base + ext
+                        break
+
+                if existing:
+                    rel = os.path.relpath(existing, media_dir).replace("\\", "/")
+                    it["imageUrl"] = f"/uploads/media/{rel}"
+                    continue
+
+                try:
+                    b1 = _fetch_bytes(web_u)
+                    img1 = Image.open(io.BytesIO(b1)); img1.load()
+
+                    chosen_bytes = b1
+                    if img1.width < min_w and large_u:
+                        try:
+                            b2 = _fetch_bytes(large_u)
+                            img2 = Image.open(io.BytesIO(b2)); img2.load()
+                            if img2.width > img1.width:
+                                chosen_bytes = b2
+                        except Exception:
+                            pass
+
+                    saved = _save_image(chosen_bytes, base, max_width=max_width)
+                    rel = os.path.relpath(saved, media_dir).replace("\\", "/")
+                    it["imageUrl"] = f"/uploads/media/{rel}"
+                    downloads += 1
+                except Exception:
+                    continue
+
+        return plan
+
+
+    # ─────────────────────────────────────────────────────────
+    # Compile plan JSON → modern HTML (responsive + animations)
+    # ─────────────────────────────────────────────────────────
+    def compile_plan_to_html(plan: dict) -> str:
+        page_slug = _slugify(plan.get("page") or "page")
+        page_id = f"smx-page-{page_slug}"
+
+        sections = list(plan.get("sections") or [])
+        meta = plan.get("meta") or {}
+
+        # Useful anchor targets for CTAs
+        sec_id_by_type = {}
+        for s in sections:
+            st = (s.get("type") or "").lower()
+            sid = _strip(s.get("id"))
+            if st and sid and st not in sec_id_by_type:
+                sec_id_by_type[st] = sid
+
+        def esc(s: str) -> str:
+            s = s or ""
+            s = s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+            s = s.replace('"', "&quot;").replace("'", "&#39;")
+            return s
+
+        def _btn(label: str, href: str, *, primary: bool = False) -> str:
+            label = _strip(label)
+            href = _strip(href)
+            if not label or not href:
+                return ""
+            cls = "btn btn-primary" if primary else "btn"
+            return f'<a class="{cls}" href="{esc(href)}">{esc(label)}</a>'
+
+        def icon(name: str) -> str:
+            svg = _ICON_SVGS.get((name or "").strip().lower())
+            if not svg:
+                return ""
+            return f'<span class="smx-ic">{svg}</span>'
+
+        css = f"""
+        <style>
+            #{page_id} {{
+            --r: 18px;
+            --bd: rgba(148,163,184,.25);
+            --fg: #0f172a;
+            --mut: #475569;
+            --card: rgba(255,255,255,.78);
+            --bg: #f8fafc;
+            font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
+            background: var(--bg);
+            color: var(--fg);
+            overflow-x: clip;
+            }}
+            @media (prefers-color-scheme: dark){{
+            #{page_id} {{
+                --fg: #e2e8f0;
+                --mut: #a7b3c6;
+                --card: rgba(2,6,23,.45);
+                --bg: radial-gradient(circle at 20% 10%, rgba(30,64,175,.25), rgba(2,6,23,.95) 55%);
+                --bd: rgba(148,163,184,.18);
+            }}
+            }}
+            #{page_id} .wrap{{ max-width:1120px; margin:0 auto; padding:0 18px; }}
+            #{page_id} .sec{{ padding:56px 0; }}
+            #{page_id} .kicker{{ color:var(--mut); font-size:.92rem; margin:0 0 8px; }}
+            #{page_id} h1{{ font-size:clamp(2rem,3.4vw,3.1rem); line-height:1.08; margin:0 0 12px; }}
+            #{page_id} h2{{ font-size:clamp(1.35rem,2.2vw,1.95rem); margin:0 0 10px; }}
+            #{page_id} p{{ margin:0; color:var(--mut); line-height:1.65; }}
+            #{page_id} .hero{{ padding:0; }}
+            #{page_id} .card{{ border:1px solid var(--bd); border-radius:var(--r); background:var(--card); padding:14px; }}
+            #{page_id} .btnrow{{ display:flex; gap:10px; flex-wrap:wrap; margin-top:18px; }}
+            #{page_id} .btn{{ display:inline-flex; gap:8px; align-items:center; border-radius:999px; padding:10px 14px;
+            border:1px solid var(--bd); text-decoration:none; background: rgba(99,102,241,.12); color:inherit; }}
+            #{page_id} .btn-primary{{ background: rgba(99,102,241,.22); border-color: rgba(99,102,241,.35); }}
+            #{page_id} .btn:hover{{ transform: translateY(-1px); }}
+            #{page_id} .grid{{ display:grid; gap:12px; }}
+            #{page_id} img{{ width:100%; height:auto; border-radius: calc(var(--r) - 6px); display:block; }}
+            #{page_id} .smx-ic{{ width:20px; height:20px; display:inline-block; opacity:.9; }}
+            #{page_id} .smx-ic svg{{ width:20px; height:20px; }}
+
+            /* HERO BANNER */
+            #{page_id} .hero-banner{{
+                position:relative;
+                width:100%;
+                min-height:clamp(380px, 60vh, 680px);
+                display:flex;
+                align-items:flex-end;
+                overflow:hidden;
+            }}
+            #{page_id} .hero-bg{{
+                position:absolute; inset:0;
+                background-position:center;
+                background-size:cover;
+                background-repeat:no-repeat;
+                transform:scale(1.02);
+                filter:saturate(1.02);
+            }}
+            #{page_id} .hero-overlay{{
+                position:absolute; inset:0;
+                background:linear-gradient(90deg,
+                    rgba(2,6,23,.62) 0%,
+                    rgba(2,6,23,.40) 42%,
+                    rgba(2,6,23,.14) 72%,
+                    rgba(2,6,23,.02) 100%
+                );
+            }}
+            @media (max-width: 860px){{
+                #{page_id} .hero-overlay{{
+                    background:linear-gradient(180deg,
+                        rgba(2,6,23,.16) 0%,
+                        rgba(2,6,23,.55) 70%,
+                        rgba(2,6,23,.70) 100%
+                    );
+                }}
+            }}
+            #{page_id} .hero-content{{ position:relative; width:100%; padding:72px 18px 48px; }}
+            #{page_id} .hero-panel{{
+                max-width:700px;
+                border:1px solid rgba(148,163,184,.30);
+                background:rgba(2,6,23,.24);
+                border-radius:var(--r);
+                padding:18px;
+                backdrop-filter: blur(4px);
+                -webkit-backdrop-filter: blur(4px);
+                box-shadow: 0 18px 40px rgba(2,6,23,.18);
+                color:#e2e8f0;
+            }}
+            #{page_id} .hero-panel p{{ color:rgba(226,232,240,.84); }}
+            #{page_id} .hero-panel h1{{ text-shadow:0 10px 30px rgba(2,6,23,.45); }}
+            #{page_id} .hero-panel .kicker{{
+                margin:0 0 8px;
+                font-size:.9rem;
+                color:#a5b4fc;
+                text-transform:uppercase;
+                letter-spacing:.18em;
+                opacity:.95;
+            }}
+            #{page_id} .hero-panel .btn{{
+                background:rgba(15,23,42,.55);
+                border-color:rgba(148,163,184,.45);
+                color:#e2e8f0;
+            }}
+            #{page_id} .hero-panel .btn-primary{{
+                background:rgba(79,70,229,.92);
+                border-color:rgba(129,140,248,.70);
+            }}
+            #{page_id} .lead{{ margin-top:10px; font-size:1.05rem; line-height:1.65; }}
+
+            /* FAQ */
+            #{page_id} .faq details{{ border:1px solid var(--bd); border-radius:14px; background:var(--card); padding:12px 14px; }}
+            #{page_id} .faq summary{{ cursor:pointer; font-weight:600; }}
+            #{page_id} .faq details + details{{ margin-top:10px; }}
+
+            #{page_id} .quote{{ font-size:1.02rem; line-height:1.6; color:inherit; }}
+            #{page_id} .mut{{ color:var(--mut); }}
+
+            #{page_id} .reveal{{ opacity:0; transform:translateY(14px); transition:opacity .55s ease, transform .55s ease; }}
+            #{page_id} .reveal.in{{ opacity:1; transform:none; }}
+            @media (prefers-reduced-motion: reduce){{ #{page_id} .reveal{{ transition:none; transform:none; opacity:1; }} }}
+        </style>
+        """.strip()
+
+        js = f"""
+        <script>
+            (function(){{
+            const root = document.getElementById("{page_id}");
+            if(!root) return;
+            const els = root.querySelectorAll(".reveal");
+            const io = new IntersectionObserver((entries)=>{{
+                entries.forEach(e=>{{ if(e.isIntersecting) e.target.classList.add("in"); }});
+            }}, {{ threshold: 0.12 }});
+            els.forEach(el=>io.observe(el));
+            }})();
+        </script>
+        """.strip()
+
+        parts = [f'<div id="{page_id}">', css]
+
+        for s in sections:
+            st = (s.get("type") or "section").lower()
+            title = esc(s.get("title") or "")
+            text = esc(s.get("text") or "")
+            cols = int(s.get("cols") or 3)
+            cols = max(1, min(5, cols))
+            items = s.get("items") or []
+            sec_dom_id = _strip(s.get("id"))
+            sec_id_attr = f' id="{esc(sec_dom_id)}"' if sec_dom_id else ""
+
+            # HERO BANNER (no /admin links)
+            if st == "hero":
+                hero_img = ""
+                for it in items:
+                    u = _strip(it.get("imageUrl"))
+                    if u:
+                        hero_img = u
+                        break
+
+                primary = meta.get("primaryCta") or {}
+                secondary = meta.get("secondaryCta") or {}
+                cta_anchor = "#" + (sec_id_by_type.get("cta") or "sec_cta")
+                feats_anchor = "#" + (sec_id_by_type.get("features") or "sec_features")
+
+                primary_label = primary.get("label") or "Request a demo"
+                primary_href = primary.get("href") or cta_anchor
+                secondary_label = secondary.get("label") or "See capabilities"
+                secondary_href = secondary.get("href") or feats_anchor
+
+                bg_style = f"style=\"background-image:url('{esc(hero_img)}')\"" if hero_img else ""
+
+                parts.append(f"""
+                    <section class="hero hero-banner"{sec_id_attr}>
+                        <div class="hero-bg" {bg_style}></div>
+                        <div class="hero-overlay"></div>
+                        <div class="wrap hero-content">
+                            <div class="hero-panel reveal">
+                                <p class="kicker">{esc(meta.get("pageTitle") or title)}</p>
+                                <h1>{title}</h1>
+                                <p class="lead">{text}</p>
+                                <div class="btnrow">
+                                    {_btn(primary_label, primary_href, primary=True)}
+                                    {_btn(secondary_label, secondary_href)}
+                                </div>
+                            </div>
+                        </div>
+                    </section>
+                """.strip())
+                continue
+
+            # FAQ as accordion
+            if st == "faq":
+                qa = []
+                for it in items:
+                    q = esc(it.get("title") or "")
+                    a = esc(it.get("text") or "")
+                    if not q and not a:
+                        continue
+                    qa.append(
+                        f"<details class=\"reveal\"><summary>{q}</summary>"
+                        f"<div class=\"mut\" style=\"margin-top:8px;\">{a}</div></details>"
+                    )
+
+                parts.append(f"""
+                <section class="sec faq"{sec_id_attr}>
+                    <div class="wrap">
+                        <h2 class="reveal">{title}</h2>
+                        {"<p class='reveal' style='margin-bottom:14px;'>" + text + "</p>" if text else ""}
+                        {"".join(qa)}
+                    </div>
+                </section>
+                """.strip())
+                continue
+
+            # Testimonials styled differently
+            if st == "testimonials":
+                cards = []
+                for it in items:
+                    quote = esc(it.get("text") or "")
+                    who = esc(it.get("title") or "")
+                    if not quote:
+                        continue
+                    cards.append(
+                        f"<div class='card reveal'><div class='quote'>“{quote}”</div>"
+                        f"<div class='mut' style='margin-top:10px;font-weight:600;'>{who}</div></div>"
+                    )
+
+                grid_html = (
+                    f'<div class="grid" style="grid-template-columns:repeat({max(1, min(cols, 3))}, minmax(0,1fr));">'
+                    + "\n".join(cards) + "</div>"
+                ) if cards else ""
+
+                parts.append(f"""
+                <section class="sec"{sec_id_attr}>
+                    <div class="wrap">
+                        <h2 class="reveal">{title}</h2>
+                        {"<p class='reveal' style='margin-bottom:14px;'>" + text + "</p>" if text else ""}
+                        {grid_html}
+                    </div>
+                </section>
+                """.strip())
+                continue
+
+            # Stats + Logos break rhythm so pages look different
+            if st in ("stats", "logos"):
+                cards = []
+                for it in items:
+                    it_title = esc(it.get("title") or "")
+                    it_text = esc(it.get("text") or "")
+                    img = _strip(it.get("imageUrl"))
+                    if st == "logos" and img:
+                        cards.append(
+                            f"<div class='card reveal' style='padding:12px;display:flex;align-items:center;justify-content:center;'>"
+                            f"<img loading='lazy' decoding='async' src='{esc(img)}' alt='{it_title}' style='max-height:46px;width:auto;border-radius:0;'>"
+                            f"</div>"
+                        )
+                    else:
+                        cards.append(
+                            f"<div class='card reveal'><div style='font-size:1.35rem;font-weight:800;line-height:1.1;'>{it_title}</div>"
+                            f"<div class='mut' style='margin-top:8px;'>{it_text}</div></div>"
+                        )
+
+                use_cols = max(2, min(cols, 5))
+                grid_html = (
+                    f'<div class="grid" style="grid-template-columns:repeat({use_cols}, minmax(0,1fr));">'
+                    + "\n".join(cards) + "</div>"
+                ) if cards else ""
+
+                parts.append(f"""
+                <section class="sec"{sec_id_attr}>
+                    <div class="wrap">
+                        {"<h2 class='reveal'>" + title + "</h2>" if title else ""}
+                        {"<p class='reveal' style='margin-bottom:14px;'>" + text + "</p>" if text else ""}
+                        {grid_html}
+                    </div>
+                </section>
+                """.strip())
+                continue
+
+            # Default cards grid (features, gallery, process, integrations, team, timeline, richtext, cta etc.)
+            cards = []
+            for it in items:
+                it_title = esc(it.get("title") or "")
+                it_text = esc(it.get("text") or "")
+                it_icon = icon(it.get("icon") or "")
+                img = _strip(it.get("imageUrl"))
+                img_html = f'<img loading="lazy" decoding="async" src="{esc(img)}" alt="{it_title}">' if img else ""
+                cards.append(f"""
+                <div class="card reveal">
+                    {img_html}
+                    <div style="display:flex; gap:10px; align-items:center; margin-top:{'10px' if img_html else '0'};">
+                        {it_icon}
+                        <h3 style="margin:0; font-size:1.05rem;">{it_title}</h3>
+                    </div>
+                    <p style="margin-top:8px;">{it_text}</p>
+                </div>
+                """.strip())
+
+            grid_html = (
+                f'<div class="grid" style="grid-template-columns:repeat({cols}, minmax(0,1fr));">'
+                + "\n".join(cards) + "</div>"
+            ) if cards else ""
+
+            parts.append(f"""
+            <section class="sec"{sec_id_attr}>
+                <div class="wrap">
+                    <h2 class="reveal">{title}</h2>
+                    {"<p class='reveal' style='margin-bottom:14px;'>" + text + "</p>" if text else ""}
+                    {grid_html}
+                </div>
+            </section>
+            """.strip())
+
+        parts.append(js)
+        parts.append("</div>")
+        return "\n\n".join(parts)
+
+    notes = []
+
+    tpl_spec = _select_template_spec(page_slug)
+    plan = _make_page_plan(page_slug=page_slug, website_description=website_description, template_spec=tpl_spec)
+
+
+    for attempt in range(max_retries + 1):
+        try:
+            _validate_plan_or_raise(plan)
+            break
+        except Exception as e:
+            notes.append(f"plan_validation_failed: {e}")
+            if attempt >= max_retries:
+                raise
+            plan = _repair_plan(plan=plan, error_msg=str(e), website_description=website_description)
+
+    # Fill images locally (Pixabay) to avoid broken links
+    if pixabay_api_key:
+        try:
+            plan = fill_plan_images_from_pixabay(
+                plan,
+                api_key=pixabay_api_key,
+                client_dir=client_dir,
+                max_width=1920,
+                max_downloads=max_images
+            )
+        except Exception as e:
+            notes.append(f"pixabay_fill_failed: {e}")
+    
+    # Normalise and validate against the layout contract (after images exist)
+    plan = normalise_layout(
+        plan,
+        default_category=(plan.get("category") or "landing"),
+        default_template_id=((plan.get("template") or {}).get("id") or "generic_v1"),
+        default_template_version=((plan.get("template") or {}).get("version") or "1.0.0"),
+        mode="prod",
+    )
+
+    _ensure_hero_image(plan)
+
+    issues = validate_layout(plan)
+    errors = [i for i in issues if i.level == "error"]
+    if errors:
+        msg = "layout_contract_validation_failed:\n" + "\n".join([f"{e.path}: {e.message}" for e in errors])
+        notes.append(msg)
+        raise RuntimeError(msg)
+
+    # Final sanity check: no placeholders left
+    blob = json.dumps(plan, ensure_ascii=False)
+    if _contains_placeholders(blob):
+        raise RuntimeError("Refusing to publish: plan still contains placeholder-style text.")
+
+    html = compile_plan_to_html(plan)
+    return {
+        "slug": _slugify(plan.get("page") or page_slug),
+        "plan": plan,
+        "html": html,
+        "notes": notes,
+    }
+
+
+
 def text_formatter_agent(text):
     """
     Parses an ML job description using the Gemini API with Structured JSON Output.