Templated-PPT-Master/runtime/ppt-master/scripts/docs/visualization-recall.md

Visualization Candidate Recall

visualization_recall.py gives Default Strategist or the Quick Generate main agent one bounded deterministic shortlist across the live Chart and Table family registries. It exposes the selected full catalog only when the caller explicitly requests semantic review. The tool reads these indexes on every invocation and maintains no second category or keyword index:

• templates/charts/charts_index.json
• templates/tables/tables_index.json

Qualitative Structure does not enter recall. Default records its relationship model in §IX; Quick keeps the same decision in active context. Both load executor-structure.md and compose the shapes for the current page.

Recall candidates

Describe one page's information shape with 3-8 concise English semantic tags. Translate source-language or industry terms into structural meaning first.

python3 skills/ppt-master/scripts/visualization_recall.py recall \
  --page P03 \
  --tag "time series" \
  --tag "three metrics" \
  --tag "direction over time" \
  --limit 6

Use --family chart|table only when the page semantics already make that boundary certain; the default all preserves unified Chart/Table recall. --limit accepts 3-8 and defaults to 6. Read the returned JSON unfiltered: tail, head, grep, or another truncator can discard higher-ranked candidates. confidence reports lexical strength only and never decides fit.

At high / medium, retain no-template-match when none fits. At low / none, select a fitting bounded candidate directly; otherwise rerun the same command once with --semantic-fallback, compare the returned selection rules semantically, and only then retain no-template-match. The full-catalog review is a narrow low-confidence no-match gate, not a routine recall step.

Field	Contract
page	Input P<NN> page key
family_filter	Requested family or all
semantic_tags	Deduplicated input tags
confidence	Lexical recall strength; never a selection decision
candidates	Ranked family/key references, SVG paths, summaries, scores, and matched tags
semantic_fallback	Selected live catalogs, present only with --semantic-fallback
no_template_match	Explicit fallback; blocked at low/none until semantic fallback review

The scorer treats the key and summary Pick clause as positive evidence and the Skip clause as negative evidence. A term found only in Skip cannot make a candidate eligible. Unicode input is NFKC-normalized before matching. The active profile owner still applies semantic judgment and prefers the most specific valid information structure.

Validate selected references

Validate every selected reference before Default writes Design Spec §VII and spec_lock.md page_visualizations, or before Quick opens it for immediate use:

python3 skills/ppt-master/scripts/visualization_recall.py validate \
  chart/line_chart table/record_table

The command is read-only. It exits 0 when every supplied reference resolves to a registered SVG and 1 otherwise. New planning supplies canonical family/key. When validating an existing legacy mapping, opt into bare-key resolution explicitly; every key must resolve uniquely:

python3 skills/ppt-master/scripts/visualization_recall.py validate \
  --legacy-bare pros_cons_chart

A Default no-template-match page appears in neither §VII nor page_visualizations; record its custom fallback in §IX. A qualitative Structure is not a no-match case: describe its relationships in §IX and build it without catalog lookup.

Selection boundary

• Default records Page | Family | Template | Usage for each positive selection and projects family/key into page_visualizations.
• Usage is one concise page-local purpose; detailed adaptation remains in §IX.
• Quick keeps the selected reference and purpose only in active context.
• Structure is a separate runtime information model, never a catalog candidate or page_visualizations entry.
• Never serialize no-template-match, empty tables, summaries, paths, or runners-up into planning artifacts.
• Open only the selected SVG for its mapped page. It is a flexible reference, not a type, geometry, style, or native-replacement lock.

Legacy compatibility

chart_recall.py remains a compatibility wrapper for existing callers. It uses the same scorer and live Chart/Table registries, preserves bare-key validation and the historical JSON shape, and resolves live candidates to their current family paths. New prompts and automation use visualization_recall.py.

When validate --legacy-bare receives one of the 36 retired canonical Structure bare keys, the shared resolver returns kind=legacy-structure-intent, family=structure, and the original key without path or reference. This compatibility result is a semantic hint for old page_charts, not a live catalog entry, and never participates in recall.