Skip to content

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.md
index 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 --compact
python3 "${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` before
visual preference. For example, a scroll is not a generic playbook carrier, a
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index 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), which
lists 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, Office
category, 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 semantic
stock-shape match, inspect the emitted fragment, and insert it into the
diff --git a/skills/ppt-master/scripts/pptx_shapes/semantics.py b/skills/ppt-master/scripts/pptx_shapes/semantics.py
index 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]) -> b
return True
haystack = _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.py
index 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 H
python3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASH
@@ -34,16 +33,7 @@ from typing import Sequence
from console_encoding import configure_utf8_stdio
from 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_semantics
from 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.md
index 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, apply
to the transient geometry job, actual content, resolved style, and complete
loaded native vocabulary before writing coordinates. Select through direct
semantic 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 undrawn
result, running actual-geometry signature, and materialization boundary. A
primitive remains valid when it wins this comparison; there is no preset quota.