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

fix(image-search): warn on weak required_terms gates

hugohe36fc0b3e119fa
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 38fbd295..82b845ca 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -87,6 +87,8 @@ Then `build_query_progression` tries: original → simplified (4 words) → simp
When the subject is an exact entity (landmark / person / company / product / venue), write `required_terms` at the same time you write the row's `query`. Use one required group per identity anchor and `|` for aliases / translations, e.g. `["Chongqing|重庆", "Jiefangbei|解放碑|Liberation Monument"]`. This keeps the query short for provider search while preventing metadata-ranked wrong entities from being accepted.
+Do **not** loosen `required_terms` to generic category words just to improve coverage. Terms like `canyon`, `grand canyon`, `stone pillar`, `ground fissure`, `ancient town`, `bridge`, `temple`, or `village` belong in the search query, not as the only identity gate. For small / Chinese-local attractions, the correct failure mode is `Needs-Manual` or a user-provided `--from-url`, not a visually plausible image of the wrong place.
+
**Forbidden — web negative prompts**: `not tourist snapshot`, `no amateur photo`, `avoid low quality`.
> Note: Keyword APIs search negative words literally.
@@ -158,6 +160,8 @@ Required per item: `filename`, `query`, `status` (`Pending`). Optional per-item
Use `required_terms` for **exact-entity images**: landmarks, people, companies, products, venues, named artworks, and named institutions. Each list item is required; alternatives inside one item use `|`. Example for a Chongqing landmark: `["Chongqing|重庆", "Jiefangbei|解放碑|Liberation Monument"]`. This is a metadata gate: candidates whose title / author / source URL do not satisfy every group are rejected before ranking, so a visually polished but wrong Rome / Hoi An image cannot win a Chongqing landmark row. Do **not** use `required_terms` for generic mood / background rows such as "modern city skyline" or "team collaboration".
+For less-covered local attractions, keep the strict identity gate rather than progressively deleting location anchors or replacing proper names with category words. If strict metadata cannot prove the entity, mark the row `Needs-Manual` and use the manual URL path when the user supplies a confirmed source.
+
The runner searches all `Pending` / `Failed` rows concurrently, appends each success to `image_sources.json` (the credit source of truth, idempotent on `filename`), and writes status back into `image_queries.json` — `Sourced` on success, `Needs-Manual` when the full provider/stage chain is exhausted. Status is saved after each completion, so an interrupted run preserves finished rows; re-running skips terminal rows. A single `web` row may still use single-query mode above.
**Pacing**: free providers (Wikimedia/Openverse) are rate-sensitive, so batch concurrency defaults to a modest **3** (`--concurrency N`, or `IMAGE_SEARCH_CONCURRENCY` env). Use `--concurrency 1` to restore strict one-at-a-time pacing. Single-query mode is one request at a time by nature.
@@ -183,6 +187,8 @@ A metadata-ranked top hit is *downloadable and token-relevant*, not necessarily
For exact-entity rows, suitability has two gates: `required_terms` first enforces metadata identity, then the `.review` image confirms the pixels actually show the right subject well enough. A row can still be rejected after passing `required_terms` if the visual is weak, cropped badly, or only tangentially shows the subject.
+Never treat a generic `required_terms` pass as acceptance. For example, matching `Ground Fissure` can return an unrelated transit station named Yunlong, and matching `stone pillar` can return a different scenic area. If the proper name / geography cannot be retained, stop at `Needs-Manual`.
+
**Replacement ladder when a best match is not right** (any reviewer):
1. refine the query and re-run that row once;
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 6774531c..f8824977 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -218,7 +218,7 @@ python3 scripts/image_search.py "abstract gradient" \
Suitability & manual replacement (a web top hit is metadata-relevant, not guaranteed visually right):
- By default only the best match is downloaded, plus a downscaled review copy at `images/.review/<stem>.jpg` (the placed asset stays full-resolution).
-- For exact subjects (landmarks, people, companies, products), use `--require-terms` or batch `required_terms` so visually plausible but wrong metadata is rejected before ranking. Example: `--require-terms Chongqing --require-terms "Jiefangbei|Liberation Monument"`.
+- For exact subjects (landmarks, people, companies, products), use `--require-terms` or batch `required_terms` so visually plausible but wrong metadata is rejected before ranking. Example: `--require-terms Chongqing --require-terms "Jiefangbei|Liberation Monument"`. Keep proper-name / geography anchors; do not broaden to generic terms like `canyon`, `stone pillar`, or `ancient town` just to improve coverage.
- `--save-candidates` (with `--max-candidates`, default 4) keeps an opt-in escalation pool under `candidates/<stem>/`; review it, then `--promote candidate_03.jpg --filename <name>.jpg`.
- `--from-url <url> --filename <name>.jpg` downloads a user-chosen image URL and replaces the target (recorded `license_tier: manual`) — the model-agnostic manual path; works even without a multimodal model.
diff --git a/skills/ppt-master/scripts/image_search.py b/skills/ppt-master/scripts/image_search.py
index 8cc1390c..af1da0f6 100644
--- a/skills/ppt-master/scripts/image_search.py
+++ b/skills/ppt-master/scripts/image_search.py
@@ -114,6 +114,44 @@ SEARCH_VALID_STATUSES = {
SEARCH_RETRYABLE_STATUSES = {SEARCH_STATUS_PENDING, SEARCH_STATUS_FAILED}
SEARCH_REQUIRED_ITEM_FIELDS = ("filename", "query", "status")
+_WEAK_REQUIRED_TERM_PARTS = frozenset({
+ "ancient town",
+ "bridge",
+ "canyon",
+ "cave",
+ "city",
+ "floating bridge",
+ "forest",
+ "gate",
+ "grand canyon",
+ "ground fissure",
+ "lake",
+ "monastery",
+ "monument",
+ "river",
+ "shrine",
+ "square",
+ "station",
+ "stone forest",
+ "stone pillar",
+ "stream",
+ "temple",
+ "valley",
+ "village",
+ "古城",
+ "古镇",
+ "地缝",
+ "大峡谷",
+ "寺",
+ "峡谷",
+ "广场",
+ "桥",
+ "洞",
+ "溪",
+ "石林",
+ "石柱",
+})
+
def _parse_required_terms(raw: object) -> tuple[str, ...]:
"""Parse entity-safety terms from CLI / batch JSON.
@@ -145,6 +183,28 @@ def _parse_required_terms(raw: object) -> tuple[str, ...]:
return tuple(terms)
+def _warn_weak_required_terms(required_terms: tuple[str, ...]) -> None:
+ """Warn when required_terms contain generic category words.
+
+ These terms are useful in the query but dangerous as identity gates:
+ broadening a small Chinese attraction from its proper name to "canyon" /
+ "stone pillar" raises coverage while admitting wrong entities.
+ """
+ weak: list[str] = []
+ for group in required_terms:
+ for part in group.split("|"):
+ normalized = part.strip().lower()
+ if normalized in _WEAK_REQUIRED_TERM_PARTS:
+ weak.append(part.strip())
+ if weak:
+ print(
+ " warning: required_terms contains generic category term(s) "
+ f"{weak}; keep proper-name / geography anchors too, and prefer "
+ "Needs-Manual or --from-url over loosening identity gates.",
+ file=sys.stderr,
+ )
+
+
# ---------------------------------------------------------------------------
# .env loading
# ---------------------------------------------------------------------------
@@ -842,6 +902,8 @@ def _search_one_item(
"""
orientation = item.get("orientation", "any") or "any"
strict = bool(item.get("strict_no_attribution", default_strict))
+ required_terms = _parse_required_terms(item.get("required_terms"))
+ _warn_weak_required_terms(required_terms)
request = ImageSearchRequest(
query=item["query"],
purpose=item.get("purpose", ""),
@@ -850,7 +912,7 @@ def _search_one_item(
slide=item.get("slide", ""),
min_width=int(item.get("min_width", default_min_width)),
min_height=int(item.get("min_height", default_min_height)),
- required_terms=_parse_required_terms(item.get("required_terms")),
+ required_terms=required_terms,
)
pinned = item.get("provider") or default_provider
@@ -1235,6 +1297,7 @@ def main(argv: Optional[list[str]] = None) -> int:
min_height=args.min_height,
required_terms=_parse_required_terms(args.require_terms),
)
+ _warn_weak_required_terms(request.required_terms)
providers = [args.provider] if args.provider else _default_provider_chain()