Raven-1/tests/test_ppt_engine_state.py
Tchen-data 5a29ea225d
fix(raven-design): deck lane on the engine's modules, defaults first, one .pptx delivered (#451)
## Summary

The hand-built deck lane (Raven-Design at medium and high) and the deck
engine lane (Raven-PPT at max) as one product, measured on live runs.

- image_search for the deck lanes sits behind tools.web.search.images,
off by default and switched on by the design launcher; the readiness
probe for the deck route reads the target lane's own picture vendor; the
build-interpreter shim has a .cmd twin for native Windows.
- Deck route on Raven-Design: page furniture comes from the engine's
helper modules (ppt_layout, ppt_theme, ppt_icons, ppt_shapes,
ppt_charts) written beside the build script; diagrams, picture treatment
and cover/section compositions are drawn by hand. Five recorded runs had
each rewritten the same 48 helpers.
- Deck route keeps no anti-pattern ledger, contract or task state: nine
audited runs wrote the ledger 18 times and read it back never, and every
real fix came from reading a render. The editorial skill is read
alongside the deck skill; every page is read back from a render at 90
dpi or more before delivery.
- Defaults before questions: language of the request, general audience,
about 20 pages, light ground, memory first; ask at most once. Two of
three ask_user calls in the audit timed out unanswered.
- Formulas as pictures (matplotlib mathtext, dfrac promotion, serif
scale) and inline sub/superscript runs, shared by both lanes;
image_search for both lanes keyed by the selected search vendor; the
raven-python interpreter shim (sh wrapper, not a symlink); all three
tiers at 400 iterations.
- layouts.md gains nine compositions measured off the packaged
templates' reference pages; three rules ask for full components, a
hierarchy among them, and the whole page used.
- The max lane delivers the .pptx alone (D64); the PDF render stays the
engine's own preview.
- ppt-engine: template gates silenced on template pages, borrowed
template files kept apart from borrowed page numbers, the icon pen
follows the icon's side.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run --frozen pytest -q -x tests/test_agents_design_launcher.py tests/test_subagent_routing_backend.py tests/test_ppt_engine_build_tool.py tests/test_ppt_engine_build_stage.py tests/test_ppt_engine_assets_formulas.py tests/test_ppt_engine_gates_registry.py
# 299 passed
```

Live runs on a test stack (medium tier, glm-5.3-flash, the
eight-character request "make a deck introducing computer vision"): with
the editorial skill read, 20 pages, 18 of them carrying a searched
picture or a paper figure, delivered in 26 minutes with no question
asked, no task-state call, no ledger, no hand-written helper, renders at
90 dpi.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible: the max lane no longer delivers a PDF beside the deck; the
design lane asks fewer questions; the host loop offers image_search only
where tools.web.search.images is on. Rollback: revert the commits
touching agents/raven-design, raven/agent and
plugins-dist/ppt-engine/raven_ppt/stages/build.py; no data migration is
involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-16 08:02:01 -07:00

108 lines
4.2 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""A figure's two captions, as the reader of a deck's state is shown them.
`caption` is what the figure's own source printed under it; `visual_caption` is a
sentence a model wrote by looking at the pixels. `Figure.summary` used to render
`caption or visual_caption`, so the second arrived in a prompt, and in the citation
reasoning downstream, indistinguishable from the first.
The case these are built from is real. A marketing banner reading "OPEN SKILLS FOR
REAL AGENTS / Curate the ecosystem. Retrieve what matters. / 821K -> 96,401 open
skills, curated" was inspected, captioned as the architecture of a system, and the
built page then credited the picture to a product.
"""
from __future__ import annotations
from pathlib import Path
from raven_ppt.contracts import Project
from raven_ppt.services.state import (
CAPTION_LEGEND,
INSPECTED_CAPTION_LEAD,
SOURCE_CAPTION_LEAD,
DeckState,
Figure,
)
BANNER_CAPTION = (
"该信息图展示了包含技能库构建(SkillCorpus)、任务检索匹配以及智能体执行验证全流程的开放技能处理系统架构图。"
)
def _banner() -> Figure:
"""The figure as `figures.json` recorded it: no source caption, no label."""
return Figure(
figure_id="skillcorpus_paper-1b9bc44f2e",
kind="image",
visual_caption=BANNER_CAPTION,
file="skillcorpus_paper.jpg",
width_px=1672,
height_px=941,
)
def test_an_inspected_caption_is_never_presented_as_the_sources_own_words() -> None:
"""The defect, stated as a test: the banner's caption is a reading of a picture
and the summary may not offer it as anything a source said."""
said = _banner().summary()
assert BANNER_CAPTION[:20] in said, "the caption is still shown -- it is the only one there is"
assert INSPECTED_CAPTION_LEAD in said
assert SOURCE_CAPTION_LEAD not in said
assert f'"{BANNER_CAPTION}"' not in said, "quoting it makes it read as the words of whoever wrote the figure"
def test_a_source_caption_is_quoted_and_credited() -> None:
figure = Figure(figure_id="fig_3", kind="figure", label="Figure 3", caption="ablation on memory length")
said = figure.summary()
assert f'{SOURCE_CAPTION_LEAD}: "ablation on memory length"' in said
assert INSPECTED_CAPTION_LEAD not in said
def test_the_figure_line_names_the_file_the_program_places() -> None:
"""The id is not the file: a program wrote `fig("tiananmen-495f76b2e8.jpg")` off a
line that named only the id, and the file under PPT_FIGURES_DIR was `tiananmen.jpg`."""
figure = Figure(figure_id="tiananmen-495f76b2e8", kind="image", file="tiananmen.jpg", width_px=1200, height_px=800)
said = figure.summary()
assert "tiananmen-495f76b2e8 (image, 1200x800px, file tiananmen.jpg)" in said
assert "file" not in Figure(figure_id="fig_3", kind="figure").summary(), "no file, nothing said about one"
def test_both_captions_reach_the_reader_when_a_figure_carries_both() -> None:
"""`caption or visual_caption` returned one string, so whichever came second was
simply gone -- and the disagreement worth noticing was gone with it."""
figure = Figure(
figure_id="fig_3",
kind="figure",
caption="Mem0 memory extraction",
visual_caption="a three-stage pipeline drawn left to right",
)
said = figure.summary()
assert "Mem0 memory extraction" in said
assert "a three-stage pipeline drawn left to right" in said
assert said.index(SOURCE_CAPTION_LEAD) < said.index(INSPECTED_CAPTION_LEAD)
def test_the_figure_list_says_which_caption_is_which(tmp_path: Path) -> None:
state = DeckState(project=Project(workspace=tmp_path, slug="deck"), figures=(_banner(),))
assert CAPTION_LEGEND in state.summary()
def test_the_legend_stays_out_of_a_deck_whose_figures_were_never_inspected(tmp_path: Path) -> None:
"""It explains a distinction that is not on the page: every caption here is a
source's, so a line telling a reader how to tell them apart is noise."""
figure = Figure(figure_id="fig_3", kind="figure", caption="ablation on memory length")
state = DeckState(project=Project(workspace=tmp_path, slug="deck"), figures=(figure,))
said = state.summary()
assert "Figures extracted (1)" in said
assert CAPTION_LEGEND not in said