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

docs(image-search): model-agnostic review flow + manual license tier

hugohe36ef072ce8fb5
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index d7934510..17f54feb 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -356,6 +356,7 @@ Whenever the slide uses an image with `Status: Sourced`, look up the correspondi
|---|---|
| `no-attribution` | Embed the `<image>` element only. **No credit element needed.** |
| `attribution-required` | Embed the `<image>` element **plus** a small inline `<text>` credit element per the visual spec in [image-searcher.md §7](./image-searcher.md). |
+| `manual` | Embed the `<image>` element only. **No credit element** — a user-supplied `--from-url` replacement; verifying usage rights / any required credit is the user's responsibility. |
The credit text is **not** rendered by post-processing or export — it must be present in the SVG you produce. The shape of the credit element (size, position, color, multi-image source line, hero gradient overlay) is specified in [image-searcher.md §7](./image-searcher.md). Do not invent a different style.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index e640efc6..a7f40233 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -67,7 +67,7 @@ After all rows reach terminal status:
- Every `slice` row has a generated element file, or is marked `Needs-Manual` because its parent sheet is not available
- No `Pending` rows remain
- `image_prompts.json` exists when ≥1 ai row processed; every entry has `status ∈ {Generated, Failed, Needs-Manual}` (no `Pending` remaining)
-- `image_sources.json` exists when ≥1 web row processed; every entry has `license_tier ∈ {no-attribution, attribution-required}`
+- `image_sources.json` exists when ≥1 web row processed; every entry has `license_tier ∈ {no-attribution, attribution-required, manual}` (`manual` = a user-supplied `--from-url` replacement)
> `Needs-Manual` is a legitimate terminal state for ai rows — Step 7 entry waits for the user to place the file. See [`image-generator.md`](./image-generator.md) §3.2 Offline Manual Mode.
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 0e802884..a42a051e 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -10,12 +10,13 @@ Role definition for the **web image acquisition path**: translate Strategist int
## 1. License Tier Discipline
-Every accepted image is classified into one of two tiers. Anything else is rejected outright.
+Every **provider-sourced** image is classified into one of two tiers; anything else is rejected outright. A third tier, `manual`, exists **only** for a user-supplied [`--from-url`](#5-running-image_searchpy) replacement — it is never the result of a provider search accepting an unknown license.
| Tier | Licenses | On-slide attribution |
|---|---|---|
| `no-attribution` | CC0, Public Domain, Pexels License, Pixabay Content License | None |
| `attribution-required` | CC BY, CC BY-SA | Inline credit `<text>` on the slide |
+| `manual` | User-supplied via `--from-url` (license unverified) | None — verifying rights / any credit is the user's responsibility |
**Forbidden — auto-rejected licenses**:
@@ -118,6 +119,10 @@ python3 scripts/image_search.py "<query>" \
| `--provider` | no | (chain) | Pin one provider |
| `--strict-no-attribution` | no | off | Restrict to no-attribution licenses; refuse CC BY / CC BY-SA |
| `--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 |
+| `--promote` | no | — | Promote a reviewed candidate to the target filename, e.g. `--promote candidate_03.jpg --filename team.jpg -o <dir>` |
+| `--from-url` | no | — | Manual replace: download a user-supplied image URL into `--filename` (recorded `license_tier: manual`); works without a multimodal model |
### Batch mode (≥ 2 web rows) — preferred
@@ -151,6 +156,43 @@ The runner searches all `Pending` / `Failed` rows concurrently, appends each suc
**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.
+### 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:
+
+- **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.
+
+**Replacement ladder when a best match is not right** (any reviewer):
+
+1. refine the query and re-run that row once;
+2. **manual URL replace (universal, model-agnostic)** — the user finds a better image anywhere and gives its URL; download and swap it in:
+ ```bash
+ python3 scripts/image_search.py --from-url <image-url> --filename <name>.jpg -o <project_path>/images
+ ```
+ Recorded with `license_tier: manual` — verifying usage rights is the user's call. Human replacement is a legitimate outcome, not a failure. It updates the image and `image_sources.json` but does **not** rewrite `image_queries.json`, so a row fixed this way may still read `Needs-Manual` in the batch manifest — harmless: the file is present, so export proceeds (executor-base §6.1);
+3. (opt-in) `--save-candidates` to pull auto-alternatives with their own `source_page_url`s, then `--promote` the best (below);
+4. if nothing fits, mark the row `Needs-Manual`.
+
+Web search is far cheaper than AI generation, so this review pass is well worth it.
+
+**This review never halts the pipeline** (image-base §6 hard rule). It runs inside Step 5 image acquisition: an image that cannot be verified or replaced right now becomes `Needs-Manual` and the deck still builds (placeholder), so generation flows straight into Step 6. Manual `--from-url` replacement is an improvement step, not a blocking gate — do it now, or later from live preview, without stopping the run.
+
+### Manual review candidates (escalation, opt-in)
+
+Candidate-pool saving is **off by default** — reach for it only when a best match fails confirmation, on a subjective topic, or for a prominent image (cover / chapter divider / `hero_page` / photo-led page).
+
+```bash
+python3 scripts/image_search.py "<query>" --filename <name>.jpg -o <project_path>/images \
+ --save-candidates --max-candidates 4
+```
+
+Saves the top candidates to `images/candidates/<stem>/` with a `candidates.json` manifest and one downscaled review copy per candidate under `candidates/<stem>/review/`. **Read the candidate review copies**, pick the best fit, then promote it — the full-resolution original is copied to the target filename:
+
+```bash
+python3 scripts/image_search.py --promote candidate_03.jpg --filename <name>.jpg -o <project_path>/images
+```
+
---
## 6. Manifest Format (`image_sources.json`)
@@ -196,7 +238,7 @@ Every successful download appends or replaces one entry keyed on `filename`:
|---|---|
| `width` / `height` | Measured from the file actually saved to disk. Use these for layout. |
| `metadata_dimensions` | Present only when upstream-claimed size differs from the saved file (preview vs original). Informational only. |
-| `license_tier` | Drives Executor's attribution decision. Only `no-attribution` / `attribution-required`. |
+| `license_tier` | Drives Executor's attribution decision: `no-attribution` / `attribution-required` for provider-sourced images, or `manual` for a user-supplied `--from-url` replacement (embed only; rights/credit are the user's responsibility). |
| `attribution_required` | Boolean alias of `license_tier == "attribution-required"`. |
| `attribution_text` | Pre-rendered canonical credit string. **Use as-is; do not regenerate.** |
| `stage` | `all` by default, or `no-attribution-only` when strict mode is used. |
@@ -278,6 +320,7 @@ Executor reads `image_sources.json` per slide that uses a Sourced image. For eac
|---|---|
| `no-attribution` | Embed `<image>` only |
| `attribution-required` | Embed `<image>` **and** an inline credit element per §7 |
+| `manual` | Embed `<image>` only — user-supplied URL (`--from-url`); verifying usage rights / any required credit is the user's responsibility |
Executor does not interpret raw license strings — `license_tier` is sufficient.
@@ -290,7 +333,8 @@ Executor does not interpret raw license strings — `license_tier` is sufficient
In addition to the shared checkpoint in [`image-base.md`](./image-base.md) §10:
- [ ] Every web row has a downloaded file at `project/images/<filename>` OR is marked `Needs-Manual`
-- [ ] Each `Sourced` row has a manifest entry with valid `license_tier` and non-empty `attribution_text`
+- [ ] Each `Sourced` web image was reviewed for fit — a multimodal model via its `images/.review/<stem>.jpg` copy, otherwise handed to the user via `source_page_url`; a poor fit was re-queried, replaced with `--from-url`, escalated via `--save-candidates` + `--promote`, or marked `Needs-Manual`
+- [ ] Each `Sourced` row has a manifest entry with valid `license_tier` and non-empty `attribution_text` (except `manual` `--from-url` rows, which carry no `attribution_text`)
- [ ] Any `attribution-required` image has visible inline credit text in the corresponding SVG
- [ ] `metadata_dimensions` warnings surfaced when downloaded preview is much smaller than upstream-claimed size
- [ ] `Needs-Manual` rows include the failure reason
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index c9e0e879..31a32424 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -49,6 +49,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
├── Existing / Generated → <image href="../images/xxx.png" .../>
├── Sourced + license_tier=no-attribution → <image href=...> only
├── Sourced + license_tier=attribution-required → <image href=...> + small <text> credit element on the slide
+ ├── Sourced + license_tier=manual → <image href=...> only (user-supplied --from-url; rights/credit are user responsibility)
├── Rendered formula → <image href="../images/formula_001.png" preserveAspectRatio="xMidYMid meet" .../>
└── Placeholder / Needs-Manual without file → Dashed border + description text
4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 16ec6696..99092775 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -215,6 +215,14 @@ python3 scripts/image_search.py "abstract gradient" \
-o projects/demo/images
```
+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).
+- `--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.
+
+Full review / escalation flow: [`image-searcher.md`](../../references/image-searcher.md) §5.
+
Output:
- Image saved to the specified output directory (auto-converts webp → jpg via Pillow when the filename extension demands)