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.mdindex 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.mdindex 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.mdindex 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 sufficientIn 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 reasondiff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.mdindex 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 text4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svgdiff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.mdindex 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)