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.mdindex 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 modelA 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.mdindex 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.pyindex 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 excfname = 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.pyindex 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 = 0filename: 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 missingdef compute_relevance(candidate: AssetCandidate, query: str) -> float:@@ -387,18 +447,34 @@ def score_candidate(candidate: AssetCandidate, request: ImageSearchRequest) -> fif 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) -> fif 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