AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
refactor(native-shapes): remove heuristic preset recall
hugohe3527478f301ba
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.mdindex 01cd88f7..6c054cff 100644--- a/skills/ppt-master/references/native-shape-authoring.md+++ b/skills/ppt-master/references/native-shape-authoring.md@@ -28,13 +28,10 @@ these calls through shell loops, merge stderr, or add a downstream parser when`--compact` exists.`list --search` and `list --grouped --search` are optional spelling/location-helpers. `recommend` is an optional heuristic fallback when the complete-vocabulary still leaves several plausible families; it is neither required-evidence nor a selection authority, and zero results never establish that a-shape is unavailable or unsuitable. Run `describe <name> --compact` only when-a serious candidate needs objective identity, adjustment, connector, path,-connection-site, or text-rectangle facts. Executor makes the final comparison-through §§1–2.1; no query narrows the already-loaded vocabulary.+helpers. Run `describe <name> --compact` only when a serious candidate needs+objective identity, adjustment, connector, path, connection-site, or+text-rectangle facts. Executor makes the final comparison through §§1–2.1;+filtered lookup cannot narrow the already-loaded vocabulary.## 1. Contour Selection and Materialization Gate@@ -105,7 +102,7 @@ Apply this page-local sequence before drawing:| Pass | Action | Result ||---|---|---|| Job | State what the object must do for the reader before naming a shape. | Page role plus any real relationship, direction, aspect, text load, or literal scope. |-| Browse | Compare that job against the complete loaded vocabulary; move from Office category to contour family to exact name. | A small candidate set chosen by meaning, not scorer rank or syntax convenience. |+| Browse | Compare that job against the complete loaded vocabulary; move from Office category to contour family to exact name. | A small candidate set chosen by meaning, not syntax convenience. || Inspect | When exact facts could change the decision, run `describe --compact` directly for those candidates and compare identity, scope, adjustments, connector status, paths, text rectangle, and connection sites. | Objective geometry evidence without prescribed use. || Select | Choose the contour whose inference and visual character fit the page, including a neutral primitive when neutrality is useful. | One page-fit contour; no syntax decision yet. || Encode | Apply §1's materialization gate. | Ordinary SVG primitive, helper-authored preset, Boolean result, or necessary freeform. |@@ -117,11 +114,6 @@ python3 "${SKILL_DIR}/scripts/preset_shape_svg.py" describe chevron --compactpython3 "${SKILL_DIR}/scripts/preset_shape_svg.py" list --search connector```-**Reference — not a constraint**: `recommend --compact` remains available as a-legacy-compatible heuristic for an unresolved family search. Read it as another-browse aid only; its filters, scores, and returned limit cannot prove fit,-misfit, or absence.-**Hard rule — semantic fit, not name association**: a preset name, topic word,or metaphor is not evidence of use. Respect `literal_only` and `scope` beforevisual preference. For example, a scroll is not a generic playbook carrier, adiff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex b6b02408..e15fb252 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -213,19 +213,12 @@ Runtime capability discovery reads[`preset-shape-vocabulary.md`](../references/preset-shape-vocabulary.md), whichlists all 187 exact names by Office category and objective contour family.`list [--search QUERY]` and `list --grouped [--search QUERY]` remain optional-location and compatibility views; they do not replace the complete vocabulary.+location views; they do not replace the complete vocabulary.`describe --compact` returns the selected preset's objective identity, Officecategory, family, scope, literal boundary, adjustments, connector/path facts,connection sites, and text-rectangle availability. Plain `describe` preserves-the full nested legacy semantics payload.--`recommend` remains an optional heuristic browse aid for unresolved family-searches. Its result is neither a whitelist nor an automatic selection, and a-zero-match result is not evidence that a preset is absent or unsuitable.-`recommend --compact` keeps criteria, counts, selection note, and reduced-candidate records; plain `recommend` preserves the full payload. A zero-match-recommendation is valid JSON with exit code 0; a zero-match `list --search`-remains a failed lookup with exit code 1.+the full nested semantics payload. A zero-match `list --search` remains+a failed lookup with exit code 1.The helper never writes a page or project file. Select one exact semanticstock-shape match, inspect the emitted fragment, and insert it into thediff --git a/skills/ppt-master/scripts/pptx_shapes/semantics.py b/skills/ppt-master/scripts/pptx_shapes/semantics.pyindex a75125a5..a941005f 100644--- a/skills/ppt-master/scripts/pptx_shapes/semantics.py+++ b/skills/ppt-master/scripts/pptx_shapes/semantics.py@@ -83,9 +83,6 @@ SEMANTIC_TEXT_CAPACITIES = ("none", "short", "medium", "high")SEMANTIC_VISUAL_WEIGHTS = ("quiet", "moderate", "strong", "emblematic")SEMANTIC_SCOPES = ("general", "literal", "flowchart", "navigation")-_TEXT_CAPACITY_RANK = {- value: index for index, value in enumerate(SEMANTIC_TEXT_CAPACITIES)-}_QUERY_TOKEN_RE = re.compile(r"[a-z0-9]+")_CAMEL_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")_QUERY_STOP_WORDS = frozenset({@@ -143,18 +140,15 @@ class PresetShapeSemantics:groups = _require_list(root.get("groups"), "catalog.groups")self._groups: list[dict[str, object]] = []self._preset_semantics: dict[str, dict[str, object]] = {}- self._group_order: dict[str, int] = {}- self._preset_order = {- name: index for index, name in enumerate(expected_names)- }+ group_ids: set[str] = set()for index, raw_group in enumerate(groups):group = self._normalize_group(raw_group, index)group_id = str(group["id"])- if group_id in self._group_order:+ if group_id in group_ids:raise PresetShapeDataError(f"Duplicate preset semantic group: {group_id!r}")- self._group_order[group_id] = index+ group_ids.add(group_id)self._groups.append(group)presets = group["presets"]assert isinstance(presets, dict)@@ -274,116 +268,6 @@ class PresetShapeSemantics:"office_categories": category_payloads,}- def recommend(- self,- *,- roles: Sequence[str],- scope: str = "general",- relationships: Sequence[str] = (),- directionality: str | None = None,- aspect: str | None = None,- text_capacity: str | None = None,- visual_weight: str | None = None,- query: str = "",- limit: int = 12,- ) -> dict[str, object]:- """Return a diverse, semantics-matched candidate recall set."""-- query_tokens = _query_tokens(query)- candidates: list[dict[str, object]] = []- for details in self._preset_semantics.values():- if scope != "all" and details["scope"] != scope:- continue-- role_matches = [role for role in roles if role in details["roles"]]- if not role_matches:- continue- relationship_matches = [- relationship- for relationship in relationships- if relationship in details["relationships"]- ]- if relationships and not relationship_matches:- continue- if directionality and directionality not in details["directionality"]:- continue- if aspect and not _aspect_matches(details["aspects"], aspect):- continue- if text_capacity and not _capacity_matches(- str(details["text_capacity"]),- text_capacity,- ):- continue- if visual_weight and details["visual_weight"] != visual_weight:- continue-- query_score = _query_score(details, query_tokens, query)- if query_tokens and query_score == 0:- continue- score = (- len(role_matches) * 20- + len(relationship_matches) * 12- + (5 if directionality else 0)- + (4 if aspect else 0)- + (3 if text_capacity else 0)- + (2 if visual_weight else 0)- + query_score- )- why = [f"role={value}" for value in role_matches]- why.extend(- f"relationship={value}" for value in relationship_matches- )- if directionality:- why.append(f"directionality={directionality}")- if aspect:- why.append(f"aspect={aspect}")- if text_capacity:- why.append(f"text_capacity>={text_capacity}")- if visual_weight:- why.append(f"visual_weight={visual_weight}")- if query_tokens:- why.append(f"query={query}")- candidates.append({- "score": score,- "preset": details["preset"],- "office_category": {- "id": details["office_category"],- "label": details["office_category_label"],- },- "group": details["id"],- "scope": details["scope"],- "intent": details["intent"],- "why": why,- "recommended_for": details["recommended_for"],- "avoid_for": details["avoid_for"],- "literal_only": details["literal_only"],- })-- ordered = self._diverse_order(candidates)- return {- "criteria": {- "roles": list(roles),- "scope": scope,- "relationships": list(relationships),- "directionality": directionality,- "aspect": aspect,- "text_capacity": text_capacity,- "visual_weight": visual_weight,- "query": query,- },- "candidate_count": len(candidates),- "returned_count": min(len(ordered), limit),- "selection_note": (- "Heuristic browse candidates only. Compare them against the complete "- "vocabulary and page context; scores, filters, and the returned limit "- "do not decide fit or absence."- if ordered- else "No heuristic candidates matched. This does not prove absence; "- "select from the complete vocabulary directly or change the criteria."- ),- "candidates": ordered[:limit],- }-def _normalize_group(self,raw_group: object,@@ -544,34 +428,6 @@ class PresetShapeSemantics:"presets": normalized_presets,}- def _diverse_order(- self,- candidates: list[dict[str, object]],- ) -> list[dict[str, object]]:- candidates.sort(- key=lambda item: (- -int(item["score"]),- self._group_order[str(item["group"])],- self._preset_order[str(item["preset"])],- )- )- ordered: list[dict[str, object]] = []- scores = sorted({int(item["score"]) for item in candidates}, reverse=True)- for score in scores:- score_items = [item for item in candidates if item["score"] == score]- first_by_group: list[dict[str, object]] = []- remaining: list[dict[str, object]] = []- seen_groups: set[str] = set()- for item in score_items:- group_id = str(item["group"])- target = first_by_group if group_id not in seen_groups else remaining- target.append(item)- seen_groups.add(group_id)- ordered.extend(first_by_group)- ordered.extend(remaining)- return ordered--@lru_cache(maxsize=1)def get_preset_shape_semantics() -> PresetShapeSemantics:"""Return the process-wide, lazily loaded bundled semantic catalog."""@@ -685,33 +541,3 @@ def _matches_query(details: dict[str, object], query_tokens: Sequence[str]) -> breturn Truehaystack = _search_text(details)return all(token in haystack for token in query_tokens)---def _query_score(- details: dict[str, object],- query_tokens: Sequence[str],- query: str,-) -> int:- if not query_tokens:- return 0- haystack = _search_text(details)- matches = sum(1 for token in query_tokens if token in haystack)- if matches == 0:- return 0- score = matches * 4- normalized_query = " ".join(_query_tokens(query))- if normalized_query and normalized_query in haystack:- score += 10- preset = str(details["preset"])- if query.casefold() == preset.casefold():- score += 20- return score---def _aspect_matches(values: object, requested: str) -> bool:- assert isinstance(values, tuple)- return requested in values or "flexible" in values---def _capacity_matches(actual: str, requested: str) -> bool:- return _TEXT_CAPACITY_RANK[actual] >= _TEXT_CAPACITY_RANK[requested]diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.pyindex 9318eca4..faf8e097 100644--- a/skills/ppt-master/scripts/preset_shape_svg.py+++ b/skills/ppt-master/scripts/preset_shape_svg.py@@ -2,14 +2,13 @@"""PPT Master - Preset Shape SVG Fragment Tool-Browse and inspect DrawingML presets, optionally run heuristic recall, or print-compact canonical native-preset SVG groups to stdout for manual insertion into-a hand-authored page or template.+Browse and inspect DrawingML presets, or print compact canonical native-preset+SVG groups to stdout for manual insertion into a hand-authored page or+template.Usage:python3 scripts/preset_shape_svg.py list [--grouped] [--search QUERY]python3 scripts/preset_shape_svg.py describe PRESET [--compact]- python3 scripts/preset_shape_svg.py recommend --role ROLE [options] [--compact]python3 scripts/preset_shape_svg.py render PRESET --id ID --frame X Y W Hpython3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASH@@ -34,16 +33,7 @@ from typing import Sequencefrom console_encoding import configure_utf8_stdiofrom pptx_shapes import CONNECTOR_PRESET_TYPES, get_preset_registry-from pptx_shapes.semantics import (- SEMANTIC_ASPECTS,- SEMANTIC_DIRECTIONALITY,- SEMANTIC_RELATIONSHIPS,- SEMANTIC_ROLES,- SEMANTIC_SCOPES,- SEMANTIC_TEXT_CAPACITIES,- SEMANTIC_VISUAL_WEIGHTS,- get_preset_shape_semantics,-)+from pptx_shapes.semantics import get_preset_shape_semanticsfrom pptx_to_svg.preset_authoring import render_preset_shape_fragment@@ -112,73 +102,6 @@ def build_parser() -> argparse.ArgumentParser:),)- recommend_parser = subparsers.add_parser(- "recommend",- help="Optionally recall heuristic preset candidates as JSON.",- )- recommend_parser.add_argument(- "--role",- action="append",- required=True,- choices=SEMANTIC_ROLES,- help="Required page role; repeat to allow multiple roles.",- )- recommend_parser.add_argument(- "--relationship",- action="append",- default=[],- choices=SEMANTIC_RELATIONSHIPS,- help="Required relationship fit; repeat to allow alternatives.",- )- recommend_parser.add_argument(- "--scope",- choices=("all", *SEMANTIC_SCOPES),- default="general",- help=(- "Semantic scope. The general default excludes literal-only, "- "flowchart, and navigation shapes."- ),- )- recommend_parser.add_argument(- "--directionality",- choices=SEMANTIC_DIRECTIONALITY,- help="Required direction or route character.",- )- recommend_parser.add_argument(- "--aspect",- choices=SEMANTIC_ASPECTS,- help="Required frame tendency; flexible candidates also match.",- )- recommend_parser.add_argument(- "--text-capacity",- choices=SEMANTIC_TEXT_CAPACITIES,- help="Minimum useful text capacity.",- )- recommend_parser.add_argument(- "--visual-weight",- choices=SEMANTIC_VISUAL_WEIGHTS,- help="Required visual-weight band.",- )- recommend_parser.add_argument(- "--query",- default="",- help="Optional English intent terms used to refine the recall set.",- )- recommend_parser.add_argument(- "--limit",- type=_positive_integer,- default=12,- help="Maximum returned candidates; default: 12.",- )- recommend_parser.add_argument(- "--compact",- action="store_true",- help=(- "Print a reduced recall view for direct inspection without "- "downstream parsing."- ),- )-render_parser = subparsers.add_parser("render",help="Print one canonical authored-preset <g> fragment to stdout.",@@ -344,42 +267,6 @@ def main(argv: Sequence[str] | None = None) -> int:print(json.dumps(payload, ensure_ascii=False, indent=2))return 0- if args.command == "recommend":- full_payload = get_preset_shape_semantics().recommend(- roles=args.role,- scope=args.scope,- relationships=args.relationship,- directionality=args.directionality,- aspect=args.aspect,- text_capacity=args.text_capacity,- visual_weight=args.visual_weight,- query=args.query,- limit=args.limit,- )- payload = (- {- "criteria": full_payload["criteria"],- "candidate_count": full_payload["candidate_count"],- "returned_count": full_payload["returned_count"],- "selection_note": full_payload["selection_note"],- "candidates": [- {- "preset": candidate["preset"],- "scope": candidate["scope"],- "literal_only": candidate["literal_only"],- "intent": candidate["intent"],- "why": candidate["why"],- "avoid_for": candidate["avoid_for"],- }- for candidate in full_payload["candidates"]- ],- }- if args.compact- else full_payload- )- print(json.dumps(payload, ensure_ascii=False, indent=2))- return 0-if args.command == "render-batch":try:items = _read_batch_items(args.input)@@ -426,16 +313,6 @@ def _parse_adjustments(values: Sequence[str]) -> dict[str, str]:return adjustments-def _positive_integer(value: str) -> int:- try:- number = int(value)- except ValueError as exc:- raise argparse.ArgumentTypeError("expected a positive integer") from exc- if number < 1:- raise argparse.ArgumentTypeError("expected a positive integer")- return number--def _style_from_args(args: argparse.Namespace) -> dict[str, str]:return _style_from_values(fill=args.fill,diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex 100c41a0..10bc87f8 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -570,10 +570,8 @@ and any applicable topology resolve, applyto the transient geometry job, actual content, resolved style, and completeloaded native vocabulary before writing coordinates. Select through directsemantic comparison; use `describe --compact` only when objective geometry-facts could change a serious candidate decision. Optional search or-recommendation output cannot narrow or replace the vocabulary. This move owns-the exact-fit geometry gate, independent-relationship / carrier fit,+facts could change a serious candidate decision. This move owns the exact-fit+geometry gate, independent relationship / carrier fit,contour-family / exact-result choice, reader effect for a generic or undrawnresult, running actual-geometry signature, and materialization boundary. Aprimitive remains valid when it wins this comparison; there is no preset quota.