108 lines
4.9 KiB
Markdown
108 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|