Merge pull request #210 from TencentCloudADP/ppt-gen

[ppt-gen] Add support for new templates

Author: fpg2012

examples/ppt_gen/.gitignore

@@ -5,3 +5,4 @@
 *.json
 *.md
 data/
+templates/*

examples/ppt_gen/README.md

@@ -35,11 +35,12 @@ Run the PPT generation script.
 ```python
 python main.py \
   --file webpage.html \
-  --template_path templates/0.pptx \
-  --yaml_path yaml_example.yaml \
-  --pages 10 \
+  --template_path templates \
+  --yaml_path yaml_example2.yaml \
+  --pages 8 \
   --disable_tooluse \
-  --extra_prompt "Language should be English."
+  --extra_prompt "Ensure rich content. In English" \
+  --template_name 11
 ```
 
 The script will produce a `json` file and a `pptx` file if everything is OK. Pass `--yaml_path` to switch between different template definitions.

examples/ppt_gen/README.zh.md

@@ -30,11 +30,12 @@ wget https://www.nobelprize.org/prizes/physics/2025/popular-information/ -O webp
 ```python
 python main.py \
   --file webpage.html \
-  --template_path template/0.pptx \
-  --yaml_path yaml_example.yaml \
-  --pages 10 \
+  --template_path templates \
+  --yaml_path yaml_example2.yaml \
+  --pages 8 \
   --disable_tooluse \
-  --extra_prompt "确保PPT语言是中文"
+  --extra_prompt "确保PPT语言是中文" \
+  --template_name 11
 ```
 
 脚本会生成同名的 `json` 与 `pptx` 文件。通过 `--yaml_path` 可以切换不同的模板配置。

examples/ppt_gen/YAML_CONFIG_GUIDE.md

@@ -4,6 +4,13 @@
 
 This document explains how to describe PPT templates with YAML so that the `ppt_gen` example can generate consistent slides across different topics and layouts.
 
+## Overview
+
+There are two types of YAML configuration files:
+
+1. [`yaml_example.yaml`](./yaml_example.yaml) or [`yaml_example2.yaml`](./yaml_example2.yaml) - YAML configurations shared across multiple templates.
+2. Individual YAML configuration files for each specific PPT project, used to define project-specific slide types, override shared YAML slide types, and modify the page order in the template (`type_map`). These YAML files are placed in the same folder as the template's pptx file.
+
 ## YAML file layout
 
 A template YAML file (see [`yaml_example.yaml`](./yaml_example.yaml)) is composed of two sections:
@@ -14,6 +21,8 @@ A template YAML file (see [`yaml_example.yaml`](./yaml_example.yaml)) is compose
    - `type`: the logical slide type (must exist in `type_map`).
    - One or more **field specifications** that describe the expected payload for each placeholder.
 
+It is recommended to place `type_map` in the YAML configuration file for a specific PPT template. `type_map` should only list the pages supported by the template. For pages not listed in `type_map`, the `gen_schema.py` script will remove them from the final schema.
+
 ### Field specification keys
 
 Each field under a page block can use the following attributes:

examples/ppt_gen/YAML_CONFIG_GUIDE.zh.md

@@ -2,16 +2,25 @@
 
 本文档说明如何使用 YAML 描述 PPT 模板。
 
+## YAML的合并
+
+PPT模版的YAML配置主要有两种：
+
+1. [`yaml_example.yaml`](./yaml_example.yaml) 或者 [`yaml_example2.yaml`](./yaml_example2.yaml) 这类多个模版间共享的YAML配置。
+2. 每个具体PPT项目独有的YAML配置文件，用于定义该PPT特有的页面类型、覆盖共享yaml的页面类型、修改模版中的页面顺序（`type_map`）。和模版的pptx文件放在同一个文件夹中。
+
 ## YAML 文件结构
 
-YAML配置文件（见 [`yaml_example.yaml`](./yaml_example.yaml)）包括两部分：
+合并后的YAML主要包括两部分：
 
 1. **`type_map`**：按顺序将每种幻灯片的 `type` 映射到参考 PPT 模板中的幻灯片索引（从 0 开始）。渲染器根据该索引复制相应母版。
 2. **页面定义块**：每个 `<name>_page` 条目描述某类幻灯片的 schema，必须包含：
    - `description`：对页面的文字说明，会用于文档和 JSON Schema。
    - `type`：幻灯片类型，必须出现在 `type_map` 中。
    - 至少一个 **字段定义**，用于描述每个占位符希望接收的数据。
 
+建议将 `type_map` 放在具体 PPT 模版的 YAML 配置文件中。`type_map`只需要列出模版支持的页面，对于没有在其中列出的页面，`gen_schema.py`脚本会把它在最终的schema中去掉。
+
 ### 字段定义可用的键
 
 | 键名         | 说明 |

examples/ppt_gen/fill_template.py

@@ -1,11 +1,13 @@
 import json
 import logging
+import re
+from pathlib import Path
 from typing import Any
 
 import yaml
 from ppt_template_model import PageConfig
 from pptx import Presentation
-from utils import delete_slide, delete_slide_range, duplicate_slide, move_slide
+from utils import delete_slide_range, duplicate_slide, move_slide
 
 
 def fill_template_with_yaml_config(template_path, output_path, json_data, yaml_config: dict[str, Any]):
@@ -20,25 +22,30 @@ def fill_template_with_yaml_config(template_path, output_path, json_data, yaml_c
     for slide_data in slides_data:
         slide_type = slide_data.get("type")
         if not slide_type:
-            logging.warning("Skipped slide without type definition: %s", slide_data)
-            continue
+            raise ValueError("Slide data must contain a 'type' field")
 
         template_index = page_config.type_map.get(slide_type)
         if template_index is None or template_index >= len(prs.slides):
-            logging.warning("No template found for slide type '%s'", slide_type)
-            continue
+            raise ValueError("No template found for slide type '%s'", slide_type)
 
         template_slide = prs.slides[template_index]
-        if slide_type in ("title", "acknowledgement"):
+        if slide_type in ("title_page", "acknowledgement_page"):
             target_slide = template_slide
         else:
             target_slide = duplicate_slide(prs, template_slide)
 
         page_config.render(target_slide, slide_data)
 
-    delete_slide_range(prs, range(2, 12))
-    delete_slide(prs, 0)
-    move_slide(prs, 1, len(prs.slides) - 1)
+    # get title page
+    title_pages_idx = page_config.type_map.get("title_page")
+    acknowledgement_pages_idx = page_config.type_map.get("acknowledgement_page")
+    max_idx = max(list(page_config.type_map.values()))
+    # move title page to the first
+    move_slide(prs, title_pages_idx, 0)
+    # move acknowledgement page to the last
+    move_slide(prs, acknowledgement_pages_idx, len(prs.slides) - 1)
+    # remove all
+    delete_slide_range(prs, range(1, max_idx))
     prs.save(output_path)
 
 
@@ -47,16 +54,20 @@ def extract_json(content):
     Extract the json data from the given content.
     """
     # extract content within "```json" and "```"
-    json_data = content.split("```json")[1].split("```")[0]
-    return json_data
+    pattern = r"```json(.*?)```"
+    match = re.search(pattern, content, re.DOTALL)
+    if match:
+        return match.group(1)
+    return content
 
 
 if __name__ == "__main__":
     import argparse
     import datetime
 
     parser = argparse.ArgumentParser()
-    parser.add_argument("-t", "--template", type=str, default="templates/0.pptx")
+    parser.add_argument("-t", "--template", type=str, default="templates")
+    parser.add_argument("-n", "--template_name", type=str, default="0")
     default_output_filename = f"output-{datetime.datetime.now().strftime('%Y-%m-%d-%H-%M-%S')}.pptx"
     parser.add_argument("-o", "--output", type=str, default=default_output_filename)
     parser.add_argument("-i", "--input", type=str, required=True)
@@ -76,8 +87,21 @@ def extract_json(content):
     with open(input_json) as f:
         content = f.read()
     json_data = extract_json(content)
-
+    if not json_data:
+        raise ValueError("No JSON data found in input file")
     with open(args.yaml_config) as f:
         yaml_config = yaml.safe_load(f)
+    template_yaml = Path(template) / args.template_name / f"{args.template_name}.yaml"
+    if not template_yaml.exists():
+        template_config = {}
+    else:
+        with open(template_yaml) as f:
+            template_config = yaml.safe_load(f)
+    # merge
+    yaml_config.update(template_config)
+
+    print(json.dumps(yaml_config, indent=4))
+
+    template_path = Path(template) / args.template_name / f"{args.template_name}.pptx"
 
-    fill_template_with_yaml_config(template, output, json_data, yaml_config)
+    fill_template_with_yaml_config(template_path, output, json_data, yaml_config)

examples/ppt_gen/gen_schema.py

@@ -139,13 +139,19 @@ def build_schema(yaml_root: dict[str, Any]) -> dict[str, Any]:
             if isinstance(item, dict):
                 for t in item.keys():
                     allowed_types.add(str(t))
-    # Fallback: infer from page specs if type_map missing
-    if not allowed_types:
-        for key, value in yaml_root.items():
-            if isinstance(value, dict) and key != "type_map":
-                t = value.get("type")
-                if t:
-                    allowed_types.add(str(t))
+
+    not_allowed_types = []
+    for key, value in yaml_root.items():
+        if key == "type_map":
+            continue
+        if not isinstance(value, dict):
+            continue
+        t = value.get("type")
+        if t and t not in allowed_types:
+            not_allowed_types.append(key)
+    # remove not allowed types from yaml_root
+    for t in not_allowed_types:
+        del yaml_root[t]
 
     one_of = []
     # iterate keys excluding type_map
@@ -200,7 +206,7 @@ def build_schema(yaml_root: dict[str, Any]) -> dict[str, Any]:
             "Paragraph": {
                 "type": "object",
                 "properties": {
-                    "text": {"type": "string"},
+                    "text": {"type": "string", "maxLength": 200, "minLength": 10},
                     "bullet": {"type": "boolean", "default": False},
                     "level": {"type": "integer", "minimum": 0},
                 },
@@ -211,7 +217,7 @@ def build_schema(yaml_root: dict[str, Any]) -> dict[str, Any]:
                 "type": "object",
                 "properties": {
                     "title": {"type": "string", "maxLength": 4},
-                    "content": {"type": "string", "maxLength": 10},
+                    "content": {"type": "string", "maxLength": 200},
                 },
                 "required": ["title", "content"],
                 "additionalProperties": False,
@@ -224,7 +230,7 @@ def build_schema(yaml_root: dict[str, Any]) -> dict[str, Any]:
                         "properties": {
                             "paragraph": {
                                 "oneOf": [
-                                    {"type": "array", "items": {"$ref": "#/$defs/Paragraph"}, "minItems": 1},
+                                    {"type": "array", "items": {"$ref": "#/$defs/Paragraph"}, "minItems": 2},
                                     {"type": "string"},
                                 ]
                             }

examples/ppt_gen/main.py

@@ -2,6 +2,8 @@
 import asyncio
 import datetime
 import json
+import logging
+from pathlib import Path
 
 import yaml
 from fill_template import extract_json, fill_template_with_yaml_config
@@ -29,7 +31,8 @@ async def main():
     parser.add_argument("--extra_prompt", type=str, default="")
     parser.add_argument("--pages", type=int, default=15)
     parser.add_argument("--url", type=str, default=None)
-    parser.add_argument("--template_path", type=str, default="templates/0.pptx")
+    parser.add_argument("--template_path", type=str, default="templates")
+    parser.add_argument("--template_name", type=str, default="0")
     parser.add_argument("--yaml_path", type=str, default="yaml_example.yaml")
     parser.add_argument("--output_path", type=str, default=f"output-{current_date}.pptx")
     parser.add_argument("--output_json", type=str, default=f"output-{current_date}.json")
@@ -38,6 +41,17 @@ async def main():
 
     with open(args.yaml_path) as f:
         yaml_config = yaml.safe_load(f)
+    template_yaml_path = Path(args.template_path) / args.template_name / f"{args.template_name}.yaml"
+    if not template_yaml_path.exists():
+        logging.warning("Template yaml config not found")
+        template_yaml_config = {}
+    else:
+        with open(template_yaml_path) as f:
+            template_yaml_config = yaml.safe_load(f)
+
+    # merge yaml_config and template_yaml_config
+    yaml_config.update(template_yaml_config)
+
     schema = build_schema(yaml_config)
 
     # add json schema to instructions
@@ -71,12 +85,16 @@ async def main():
     final_result = result.final_output
     print(final_result)
 
+    json_data = extract_json(final_result)
+    if not json_data:
+        raise ValueError("No JSON data found in output")
+
     with open(args.output_json, "w") as f:
-        f.write(final_result)
+        f.write(json_data)
 
-    json_data = extract_json(final_result)
+    template_pptx_path = Path(args.template_path) / args.template_name / f"{args.template_name}.pptx"
     fill_template_with_yaml_config(
-        template_path=args.template_path,
+        template_path=template_pptx_path,
         output_path=args.output_path,
         json_data=json_data,
         yaml_config=yaml_config,

examples/ppt_gen/ppt_template_model.py

@@ -87,7 +87,8 @@ def render(self, slide, page_json: dict[str, Any]):
         logging.info(f"===Rendering page type: {page_type}===")
 
         # Get page configuration
-        page_config = self.pages.get(f"{page_type}_page", {})
+
+        page_config = self.pages.get(page_type, {})
 
         # Render all fields based on their type from YAML config
         for field_name, field_config in page_config.items():
@@ -96,9 +97,10 @@ def render(self, slide, page_json: dict[str, Any]):
 
             field_value = page_json.get(field_name)
             if field_value is None:
-                continue
+                raise ValueError(f"Field '{field_name}' not found in page JSON")
 
             field_type = field_config.get("type", "str")
+            print(f"field_name: {field_name}, field_type: {field_type}")
 
             if field_type == "str":
                 self._render_text_field(slide, field_name, field_value)
@@ -116,7 +118,7 @@ def render(self, slide, page_json: dict[str, Any]):
             elif field_type == "image":
                 self._render_basic_image_field(slide, field_name, field_value)
             else:
-                logging.warning(f"Unknown field type: {field_type}")
+                raise ValueError(f"Unknown field type: {field_type}")
 
     def _render_basic_image_field(self, slide, field_name: str, image_value):
         logging.info(f"{field_name}: {image_value}")
@@ -127,10 +129,11 @@ def _render_basic_image_field(self, slide, field_name: str, image_value):
 
     def _render_text_field(self, slide, field_name: str, text_value: str):
         """Render text field"""
-        logging.info(f"{field_name}: {text_value}")
         shape = find_shape_with_name_except(slide.shapes, field_name)
         if shape:
             handle_pure_text(text_value, shape, slide)
+        else:
+            raise ValueError(f"Shape not found for {field_name}")
 
     def _render_content_field(self, slide, field_name: str, content_value):
         """Render content field"""
@@ -149,7 +152,7 @@ def _render_content_list_field(self, slide, field_name: str, content_values: lis
             if shape:
                 handle_content(self._ensure_content_model(content_value), shape, slide)
             else:
-                logging.warning(f"Shape not found for {target_name}")
+                raise ValueError(f"Shape not found for {target_name}")
 
     def _render_item_list_field(self, slide, field_name: str, items: list):
         """Render item list field"""
@@ -160,9 +163,9 @@ def _render_item_list_field(self, slide, field_name: str, items: list):
     def _render_label_list_field(self, slide, field_name: str, labels: list):
         """Render label list field"""
         for i, label_text in enumerate(labels):
-            label_shape = find_shape_with_name_except(slide.shapes, f"label{i + 1}")
+            label_shape = find_shape_with_name_except(slide.shapes, f"{field_name}{i + 1}")
             if label_shape:
-                logging.info(f"label{i + 1}: {label_text}")
+                logging.info(f"{field_name}{i + 1}: {label_text}")
                 handle_pure_text(label_text, label_shape, slide)
 
     def _ensure_basic_image_model(self, image_value: Any) -> BasicImage:
@@ -238,6 +241,7 @@ def download_image(url, base_dir="."):
 
 def handle_pure_text(text: str, target_shape, slide):
     try:
+        logging.info(f"handle_pure_text: {text} =fill=> {target_shape.text_frame.text}")
         text_frame = target_shape.text_frame
         has_runs = any(paragraph.runs for paragraph in text_frame.paragraphs)
 
@@ -246,13 +250,13 @@ def handle_pure_text(text: str, target_shape, slide):
             paragraph = text_frame.paragraphs[0]
             run = paragraph.add_run()
             run.text = text
-            return
-
-        for paragraph in text_frame.paragraphs:
-            for run in paragraph.runs:
-                run.text = text
-                text = ""
+        else:
+            for paragraph in text_frame.paragraphs:
+                for run in paragraph.runs:
+                    run.text = text
+                    text = ""
     except Exception as e:
+        traceback.print_exc()
         logging.error(f"Failed to set text: {text} {e}")