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

feat(image-search): entity-safety gate for exact-subject web rows

hugohe3f37c047308fa
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index a42a051e..38fbd295 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -85,6 +85,8 @@ Then `build_query_progression` tries: original → simplified (4 words) → simp
| Quality cues | **DO NOT ADD QUALITY CUES** like `professional editorial photography` or `clean composition`. These APIs use exact keyword matching; adding long adjectives will result in 0 matches. |
| Language | For Chinese landmarks: use precise Chinese names (e.g., `磁器口古镇`) if specifically targeting `--provider wikimedia`. For general stock providers (Pexels/Pixabay), use simple English nouns (e.g., `Chongqing Jiefangbei`); do NOT use complex Chinese sentences or overly long English descriptive strings which fail on these platforms. |
+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.
+
**Forbidden — web negative prompts**: `not tourist snapshot`, `no amateur photo`, `avoid low quality`.
> Note: Keyword APIs search negative words literally.
@@ -118,6 +120,7 @@ python3 scripts/image_search.py "<query>" \
| `--orientation` | no | `any` | `any` / `landscape` / `portrait` / `square` |
| `--provider` | no | (chain) | Pin one provider |
| `--strict-no-attribution` | no | off | Restrict to no-attribution licenses; refuse CC BY / CC BY-SA |
+| `--require-terms` | no | — | Entity-safety gate for exact subjects. Repeatable; comma separates required groups; `A|B` means aliases within one group. Example: `--require-terms Chongqing --require-terms "Jiefangbei|Liberation Monument"` |
| `--manifest` | no | (default) | Override manifest path |
| `--save-candidates` | no | off | Escalation only: also keep a review pool in `candidates/<stem>/`. Default downloads just the best match (+ a review copy) |
| `--max-candidates` | no | `4` | Pool size when `--save-candidates` is set |
@@ -139,23 +142,38 @@ python3 scripts/image_search.py --batch <project_path>/images/image_queries.json
{
"items": [
{
- "filename": "team.jpg",
- "query": "executive boardroom meeting",
- "slide": "03_team",
- "purpose": "background",
+ "filename": "jiefangbei.jpg",
+ "query": "Jiefangbei Chongqing downtown monument",
+ "slide": "03_landmark",
+ "purpose": "exact landmark photo",
"orientation": "landscape",
+ "required_terms": ["Chongqing", "Jiefangbei|Liberation Monument"],
"status": "Pending"
}
]
}
```
-Required per item: `filename`, `query`, `status` (`Pending`). Optional per-item overrides: `slide`, `purpose`, `orientation`, `provider`, `strict_no_attribution`, `min_width`, `min_height`.
+Required per item: `filename`, `query`, `status` (`Pending`). Optional per-item overrides: `slide`, `purpose`, `orientation`, `provider`, `strict_no_attribution`, `min_width`, `min_height`, `required_terms`.
+
+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".
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.
+### Ranking model
+
+`image_search.py` ranks provider metadata, not pixels. The order is deliberately conservative:
+
+1. hard reject: invalid license, zero query relevance, or any missing `required_terms`;
+2. identity priority: every required term group must match; candidates whose title also contains the required entity terms get an additional boost over candidates that only match via URL;
+3. query relevance: concrete query tokens dominate generic visual words like "photo", "high quality", "background";
+4. layout fit: requested orientation helps; mismatched orientation is a small penalty, not a hard reject;
+5. license / size tie-breakers: no-attribution is a small bonus; pixel count is capped so a huge but weakly relevant image cannot outrank a smaller accurate image.
+
+Do not tune this into a visual taste engine. The scorer prevents obvious metadata failures and produces a reviewable best match; the `.review` copy still decides whether the image is visually fit for the slide.
+
### Suitability review — with or without a multimodal model
A metadata-ranked top hit is *downloadable and token-relevant*, not necessarily *visually suitable* — `score_candidate` never sees pixels. So a web best match should be reviewed before it is trusted, by whichever reviewer is available:
@@ -163,6 +181,8 @@ A metadata-ranked top hit is *downloadable and token-relevant*, not necessarily
- **Multimodal model**: each download writes a downscaled review copy to `images/.review/<stem>.jpg` (the placed asset stays full-resolution; the bounded copy just keeps a very large original safe and quick to open). Read it and judge fit — subject, mood, quality, not just topic overlap.
- **Non-multimodal model (no vision)**: do **not** pretend to confirm. Hand off to a human — surface each web image's `source_page_url` from `image_sources.json` (live preview also shows the placed result) and let the user judge.
+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.
+
**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 99092775..6774531c 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -218,6 +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"`.
- `--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 eb5497fa..1cb58277 100644
--- a/skills/ppt-master/scripts/image_search.py
+++ b/skills/ppt-master/scripts/image_search.py
@@ -115,6 +115,36 @@ SEARCH_RETRYABLE_STATUSES = {SEARCH_STATUS_PENDING, SEARCH_STATUS_FAILED}
SEARCH_REQUIRED_ITEM_FIELDS = ("filename", "query", "status")
+def _parse_required_terms(raw: object) -> tuple[str, ...]:
+ """Parse entity-safety terms from CLI / batch JSON.
+
+ Multiple groups are ANDed. Alternatives inside one group are separated by
+ ``|``; comma splitting is accepted as CLI convenience. Examples:
+ ``["Chongqing", "Jiefangbei|Liberation Monument"]``.
+ """
+ if raw is None:
+ return ()
+ values: list[str]
+ if isinstance(raw, str):
+ values = [raw]
+ elif isinstance(raw, list):
+ values = []
+ for item in raw:
+ if not isinstance(item, str):
+ raise ValueError("required_terms items must be strings")
+ values.append(item)
+ else:
+ raise ValueError("required_terms must be a string or list of strings")
+
+ terms: list[str] = []
+ for value in values:
+ for part in value.split(","):
+ part = part.strip()
+ if part:
+ terms.append(part)
+ return tuple(terms)
+
+
# ---------------------------------------------------------------------------
# .env loading
# ---------------------------------------------------------------------------
@@ -332,8 +362,11 @@ def search_and_download(
item for item in provider_ranked if item[0] != float("-inf")
]
if not provider_ranked:
+ reason = "query"
+ if request.required_terms:
+ reason += f" / required_terms={list(request.required_terms)}"
print(
- f" no candidate matched the query; trying next provider/stage",
+ f" no candidate matched {reason}; trying next provider/stage",
file=sys.stderr,
)
continue
@@ -452,6 +485,11 @@ def _candidate_to_manifest_item(
"attribution_text": build_attribution_text(args.filename, candidate),
"status": "sourced",
}
+ required_terms = _parse_required_terms(
+ getattr(args, "required_terms", None) or getattr(args, "require_terms", None)
+ )
+ if required_terms:
+ item["required_terms"] = list(required_terms)
# Only carry upstream-claimed dimensions when they differ — this flags
# cases where the provider returned a preview rather than the original.
@@ -631,6 +669,7 @@ def fetch_url_replace(
purpose: str = "",
search_query: str = "",
orientation: str = "",
+ required_terms: tuple[str, ...] = (),
) -> int:
"""Download a user-supplied image URL into the target and record it.
@@ -687,6 +726,10 @@ def fetch_url_replace(
"status": "manual",
"note": "Manually supplied image URL; verifying usage rights is the user's responsibility.",
}
+ inherited_required_terms = _parse_required_terms(prior.get("required_terms"))
+ final_required_terms = inherited_required_terms or required_terms
+ if final_required_terms:
+ item["required_terms"] = list(final_required_terms)
written = write_sources_manifest(mpath, item)
print(f" manifest updated: {written}", file=sys.stderr)
return 0
@@ -739,6 +782,11 @@ def load_search_manifest(path: str) -> dict:
f"{prefix} status '{item['status']}' is invalid. "
f"Valid: {sorted(SEARCH_VALID_STATUSES)}"
)
+ if "required_terms" in item:
+ try:
+ _parse_required_terms(item["required_terms"])
+ except ValueError as exc:
+ raise ValueError(f"{prefix} {exc}") from exc
fname = item["filename"]
if fname in seen_filenames:
raise ValueError(f"{prefix} duplicate filename '{fname}'")
@@ -802,6 +850,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")),
)
pinned = item.get("provider") or default_provider
@@ -826,6 +875,7 @@ def _search_one_item(
purpose=item.get("purpose", ""),
query=item["query"],
orientation=orientation,
+ required_terms=request.required_terms,
)
manifest_item = _candidate_to_manifest_item(
candidate,
@@ -1006,6 +1056,18 @@ def build_parser() -> argparse.ArgumentParser:
default=800,
help="Minimum acceptable image height in pixels (default: 800).",
)
+ parser.add_argument(
+ "--require-terms",
+ action="append",
+ default=None,
+ metavar="TERM[,TERM...]",
+ help=(
+ "Entity-safety gate: require each metadata term group before a "
+ "candidate can be accepted. Repeatable; comma separates groups; "
+ "'A|B' means aliases within one group. Example: "
+ "--require-terms Chongqing --require-terms 'Jiefangbei|Liberation Monument'."
+ ),
+ )
parser.add_argument(
"--manifest",
default=None,
@@ -1114,6 +1176,7 @@ def main(argv: Optional[list[str]] = None) -> int:
purpose=args.purpose,
search_query=args.query or "",
orientation="" if args.orientation == "any" else args.orientation,
+ required_terms=_parse_required_terms(args.require_terms),
)
# --- Batch mode ---
@@ -1170,6 +1233,7 @@ def main(argv: Optional[list[str]] = None) -> int:
slide=args.slide,
min_width=args.min_width,
min_height=args.min_height,
+ required_terms=_parse_required_terms(args.require_terms),
)
providers = [args.provider] if args.provider else _default_provider_chain()
diff --git a/skills/ppt-master/scripts/image_sources/provider_common.py b/skills/ppt-master/scripts/image_sources/provider_common.py
index 5acb3ff5..6a438f80 100644
--- a/skills/ppt-master/scripts/image_sources/provider_common.py
+++ b/skills/ppt-master/scripts/image_sources/provider_common.py
@@ -208,6 +208,7 @@ class ImageSearchRequest:
min_height: int = 0
filename: str = ""
slide: str = ""
+ required_terms: tuple[str, ...] = ()
@dataclass
@@ -265,6 +266,7 @@ _SOFT_NOISE_WORDS = frozenset({
})
_TOKEN_STRIP_CHARS = ".,;:!?\"'()[]{},。;:!?、"
+_MATCH_SEPARATOR_RE = re.compile(r"""[\s\-_./:;,'"()[\]{}]+""")
def simplify_query(query: str, max_words: int = 4) -> str:
@@ -357,7 +359,65 @@ def _query_tokens(query: str) -> list[str]:
def _candidate_text(candidate: AssetCandidate) -> str:
"""Concatenate the candidate's matchable metadata fields for scoring."""
- return " ".join(filter(None, (candidate.title, candidate.author))).lower()
+ return " ".join(
+ filter(
+ None,
+ (
+ candidate.title,
+ candidate.author,
+ candidate.source_page_url,
+ ),
+ )
+ ).lower()
+
+
+def _normalize_match_text(text: str) -> str:
+ """Normalize metadata / required terms for conservative substring matching."""
+ lowered = (text or "").lower()
+ return _MATCH_SEPARATOR_RE.sub(" ", lowered).strip()
+
+
+def _term_group_alternatives(term_group: str) -> list[str]:
+ """Split one required term group into alternatives.
+
+ ``"Jiefangbei|Liberation Monument"`` means either alternative satisfies
+ that required group. Different list items are ANDed by
+ ``missing_required_terms``.
+ """
+ return [
+ _normalize_match_text(part)
+ for part in str(term_group or "").split("|")
+ if _normalize_match_text(part)
+ ]
+
+
+def missing_required_terms(
+ candidate: AssetCandidate,
+ required_terms: tuple[str, ...] | list[str] | None,
+) -> list[str]:
+ """Return required term groups not present in candidate metadata.
+
+ This is an entity-safety gate, not a fuzzy visual classifier. Use it for
+ exact subjects such as landmarks, people, companies, or products where a
+ visually nice but wrong image is worse than no image.
+ """
+ if not required_terms:
+ return []
+
+ text = _normalize_match_text(_candidate_text(candidate))
+ compact_text = text.replace(" ", "")
+ missing: list[str] = []
+ for group in required_terms:
+ alternatives = _term_group_alternatives(group)
+ if not alternatives:
+ continue
+ matched = any(
+ alt in text or alt.replace(" ", "") in compact_text
+ for alt in alternatives
+ )
+ if not matched:
+ missing.append(str(group))
+ return missing
def compute_relevance(candidate: AssetCandidate, query: str) -> float:
@@ -387,18 +447,34 @@ def score_candidate(candidate: AssetCandidate, request: ImageSearchRequest) -> f
if not candidate.license_tier:
return float("-inf")
+ required_misses = missing_required_terms(candidate, request.required_terms)
+ if required_misses:
+ return float("-inf")
+
relevance = compute_relevance(candidate, request.query)
- if relevance == 0.0:
+ if relevance == 0.0 and not request.required_terms:
return float("-inf")
score = relevance * 10000.0
+ title_text = _normalize_match_text(candidate.title)
+ compact_title = title_text.replace(" ", "")
+ for group in request.required_terms or ():
+ alternatives = _term_group_alternatives(group)
+ if any(
+ alt in title_text or alt.replace(" ", "") in compact_title
+ for alt in alternatives
+ ):
+ score += 1500.0
# Penalize infrastructure/transit metadata if the user didn't explicitly ask for it.
# This prevents high-res subway station photos from outranking actual tourist landmarks.
text = _candidate_text(candidate)
query_lower = request.query.lower()
- infra_terms = ["station", "subway", "metro", "rail", "transit", "airport", "bus", "地铁", "站", "轨道"]
-
+ infra_terms = [
+ "station", "subway", "metro", "rail", "transit", "airport", "bus",
+ "地铁", "站", "轨道",
+ ]
+
if not any(t in query_lower for t in infra_terms):
if any(t in text for t in infra_terms):
score -= 5000.0
@@ -416,9 +492,13 @@ def score_candidate(candidate: AssetCandidate, request: ImageSearchRequest) -> f
if request.min_height and candidate.height < request.min_height:
score -= 500.0
- # Larger images score higher, capped to avoid runaway dominance.
+ if candidate.license_tier == LICENSE_TIER_NO_ATTRIBUTION:
+ score += 250.0
+
+ # Larger images score higher, but only as a tie-breaker; entity accuracy
+ # and metadata relevance must dominate pixel count.
pixel_score = max(candidate.width, 0) * max(candidate.height, 0) / 1000.0
- score += min(pixel_score, 5000.0)
+ score += min(pixel_score, 1500.0)
return score