Raven-1/tests/test_ppt_engine_assembly.py
Tchen 5b4cce3f43 feat(ppt-engine): deliver where the user named, one route onto a page, and the ten templates
## Summary

This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:

- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
  publish writes the deck under `out/` and copies the same measured bytes to the path
  the user named, recording it with `role: "delivery"`. The PDF preview rides along only
  where its own `.pdf` name is free: a file already at that stem is the user's and is
  left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
  template page and writing into it with `replace_text` is the only route; a page whose
  block raises loses only itself and the pages after it still build; a draft counts
  against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
  tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
  LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
  nothing names the near miss before the inventory; a text frame with no paragraph at
  all can be written into; a cloned page's title size is said; `row_type_drift` compares
  the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
  and one of them also answered "the string you named is on page N of this template".
  That clause needs the file a page was cloned out of, and the only refusal holding it
  was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
  which the runner already sets in the author's own process and which this module
  already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
  contrast gate also measures the render's own word boxes, as extra regions through the
  same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
  the dark ground and read as legible.

Decisions the union forced, none of which drops a behaviour:

- The publish record is built !602's way, with its delivery `role`, and written the way
  D49 requires -- read back off the file, atomic, and refused rather than silent when
  the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
  survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
  reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
  region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:

- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
  decision under two numbers.

Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.

## Type

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

## Verification

Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.

- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
  26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
  every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
  out plain `origin/main` in a clean worktree and ran the same two files: the same 6
  failed and 20 errors, the ids identical character for character. Nothing on this branch
  touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
  that failed on the previous revision is retired on the new base and its replacement,
  `test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
  The 6 failures and 20 errors are all cron timezone tests failing identically on plain
  `main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
  tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
  satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
  each run as a measurement rather than asserted; the `unreadable` gate was run through
  the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
  page 12 under one word at 1.6:1.

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

## Risk

User-visible changes: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.

Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.

Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.

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

## Related Issues

N/A
2026-09-11 05:52:36 +00:00

317 lines
15 KiB
Python

"""What gets registered, and the failure the predecessor could not see.
Its assembly function carried ten branches on one boolean, two of which
contradicted each other: a sub-route was registered under
`expert_outline and not free_composition` while `expert_outline` already implied
`free_composition`. Fifteen hundred lines of tooling were unreachable under every
configuration for months, and a test had frozen that as the expected behaviour.
The lesson is not "check that predicate". It is that assembly must verify its own
result against the route's declaration instead of trusting the arithmetic that
produced it.
"""
from __future__ import annotations
import logging
from pathlib import Path
import pytest
from raven_ppt.profiles import registry
from raven_ppt.tools.assembly import build_ppt_tools
pytest.importorskip("pptx")
def test_the_default_route_registers_its_tools(tmp_path: Path) -> None:
names = {tool.name for tool in build_ppt_tools(tmp_path)}
assert "ppt_build" in names
def test_every_registered_tool_is_one_the_route_asked_for(tmp_path: Path) -> None:
profile = registry.get(registry.DEFAULT)
names = {tool.name for tool in build_ppt_tools(tmp_path)}
assert names <= set(profile.tools), names - set(profile.tools)
def test_a_route_missing_a_tool_says_so_at_startup(tmp_path: Path, caplog) -> None:
"""Rather than at the point a model calls a tool nobody registered."""
with caplog.at_level(logging.WARNING):
build_ppt_tools(tmp_path)
missing = [r for r in caplog.records if "were not registered" in r.getMessage()]
if missing:
# The message must name what is absent; a warning that does not is noise.
assert "ppt_ingest" in missing[0].getMessage() or "ppt_figure_inspect" in missing[0].getMessage()
def test_an_unknown_route_falls_back_and_says_which(tmp_path: Path, caplog) -> None:
with caplog.at_level(logging.WARNING):
tools = build_ppt_tools(tmp_path, profile="no_such_route")
assert tools
assert any("falling back" in r.getMessage() for r in caplog.records)
def test_a_declared_route_with_no_backend_yet_registers_nothing(tmp_path: Path, caplog) -> None:
"""Saying so beats registering a route that fails at the first call."""
with caplog.at_level(logging.WARNING):
assert build_ppt_tools(tmp_path, profile="image_text") == []
assert any("not implemented yet" in r.getMessage() for r in caplog.records)
class _Provider:
async def chat_stream(self, *a, **k): # pragma: no cover - never called here
raise AssertionError
def test_the_gates_stand_with_or_without_a_second_model(tmp_path: Path) -> None:
"""A provider used to decide whether a whole stage existed. It buys per-page calls
inside `ppt_prepare` and `ppt_outline` now, and nothing about what a build measures:
the same measurer is wired either way."""
for tools in (build_ppt_tools(tmp_path), build_ppt_tools(tmp_path, provider=_Provider())):
tool = next(t for t in tools if t.name == "ppt_build")
assert tool.stage.measure is not None
# The vocabulary a model must never be handed: a type size, a font face, or a
# physical coordinate. Matched against the parts of a field name, so `font_size` and
# `slide_width` are caught the way `font` and `width` are.
PHYSICAL_QUANTITIES = (
"emu",
"inch",
"inches",
"px",
"pt",
"font",
"typeface",
"face",
"size",
"width",
"height",
"x0",
"y0",
"x1",
"y1",
"left",
"top",
)
# Normalised composition coordinates are the one documented exception (CLAUDE.md's
# hard invariant 1): a free-composition region is a 0..1000 grid and a vector canvas
# is 160x90, and neither is a physical quantity -- the engine maps them. Listed as
# whole field names rather than allowed by a rule, so the exception cannot widen on
# its own, and empty until a route actually declares one.
NORMALISED_FIELDS: frozenset[str] = frozenset()
def _named_fields(schema: object, path: str = "") -> list[str]:
"""Every field name anywhere in a JSON schema, with the route to it.
The check used to read `properties` at the top level only, which is the one place
a physical quantity was never going to appear: an outline's pages, a page's table
plan and a chart's series are all nested objects, and `ppt_outline` alone puts
three levels of them behind one top-level `pages`. Everything a schema can nest a
named field inside is followed -- `items`, the combinators, `$defs` and
`additionalProperties` when it is a schema rather than `False`.
"""
found: list[str] = []
if isinstance(schema, list):
for index, entry in enumerate(schema):
found.extend(_named_fields(entry, f"{path}[{index}]"))
return found
if not isinstance(schema, dict):
return found
for key, value in schema.items():
if key in ("properties", "$defs", "definitions", "patternProperties") and isinstance(value, dict):
for name, subschema in value.items():
found.append(f"{path}.{name}" if path else name)
found.extend(_named_fields(subschema, f"{path}.{name}" if path else name))
elif key in ("items", "prefixItems", "anyOf", "oneOf", "allOf", "not", "contains", "additionalProperties"):
found.extend(_named_fields(value, path))
return found
def test_the_schema_never_offers_a_physical_quantity(tmp_path: Path) -> None:
"""The hard invariant, checked at every depth a schema can hide a field at.
Two holes, and each made the check weaker than the sentence it was written for.
It compared the whole field name for equality against the banned list, so
`font_size`, `slide_width` and `body_font` all passed a test whose point is that
none of them may exist. And it read only the top-level `properties`, so every
field inside `ppt_outline`'s pages -- the part of the schema a model writes most
of -- was never looked at at all. Nothing violates it today, which is why the
weakness could sit there: a test that passes for the wrong reason looks exactly
like a test that passes.
"""
import re
offences = []
for tool in build_ppt_tools(tmp_path):
for field in _named_fields(tool.parameters):
name = field.rsplit(".", 1)[-1]
if name in NORMALISED_FIELDS:
continue
parts = {part.lower() for part in re.split(r"_|(?<=[a-z])(?=[A-Z])", name) if part}
caught = parts & set(PHYSICAL_QUANTITIES)
if caught:
offences.append(f"{tool.name}.{field} names {sorted(caught)}")
assert not offences, "the schema hands a model a physical quantity:\n " + "\n ".join(offences)
def test_the_scan_reaches_the_fields_the_flat_one_could_not_see(tmp_path: Path) -> None:
"""The guard on the guard: a recursive check that recursed into nothing would pass.
`ppt_outline` nests every page's fields under an array's `items`, so
`pages.claim` is only reachable by recursing through that array -- the shape the
old flat check was blind to, and the cheapest proof the new one is not. The
planted schema below carries the same nesting with a banned word at the bottom.
"""
tools = {tool.name: tool for tool in build_ppt_tools(tmp_path)}
outline = tools.get("ppt_outline")
if outline is None:
pytest.skip("the outline tool is not registered on the default route")
fields = _named_fields(outline.parameters)
assert "pages" in fields
assert "pages.claim" in fields, fields
assert "swept.url" in fields, fields
# And a field with a banned word in it has to be caught wherever it is nested.
planted = {
"type": "object",
"properties": {
"pages": {"type": "array", "items": {"type": "object", "properties": {"body_font": {"type": "string"}}}}
},
}
assert "pages.body_font" in _named_fields(planted)
def test_the_project_field_names_the_tool_that_actually_makes_a_project(tmp_path: Path) -> None:
"""Six of them named `ppt_ingest`, which on this route is optional and not first.
A model reading "the project, as given to ppt_ingest" and finding no project has
one place to go, and it is the wrong one: `ppt_ingest` is `required=False` here
and refuses a deck holding no sources, while `ppt_prepare` is the first required
stage and the call that creates the directory. Asserted against the route rather
than against the string, so renaming the entry stage moves the check with it.
"""
profile = registry.get(registry.DEFAULT)
entry = next(stage.tool for stage in profile.stages if stage.required and stage.tool)
offences = []
for tool in build_ppt_tools(tmp_path):
said = ((tool.parameters.get("properties") or {}).get("project") or {}).get("description") or ""
named = {name for name in profile.tools if name and name != tool.name and name in said}
if named - {entry}:
offences.append(f"{tool.name}.project points at {sorted(named - {entry})} rather than {entry}")
assert not offences, "\n ".join(["a project field names the wrong tool:", *offences])
def test_the_view_budget_reaches_both_sides_of_the_call_from_one_setting(tmp_path: Path) -> None:
"""`tools.ppt.viewsPerCall` has to arrive as one number, not as two that agree.
It was two hardcoded constants, 1 in the tool and 3 in the stage, and the tool's
won: a nineteen-page deck took nineteen builds to look at once. Assembly is where a
setting becomes a stage, so this is where a knob that is declared and never read
would show -- the failure this module's docstring is about.
"""
from raven_ppt.stages.build import BATCH_VIEWS
for wanted in (1, 3, 7):
build = next(t for t in build_ppt_tools(tmp_path, views_per_call=wanted) if t.name == "ppt_build")
assert build.stage.views_per_call == wanted
assert build.parameters["properties"]["slides"]["maxItems"] == wanted
unset = next(t for t in build_ppt_tools(tmp_path) if t.name == "ppt_build")
assert unset.stage.views_per_call == BATCH_VIEWS
def test_the_configured_default_is_the_one_the_stage_ships_with() -> None:
"""Two spellings of the same default, so they get a test rather than a comment.
`renderDpi` spells 144 in the slice, in assembly and in `DeckViews`, and nothing
checks that those stay the same number. This one is load-bearing in a way that one
is not: it is the batch size the unseen gate is written from, so a slice default
that drifted from the stage's would change what a deck must show to publish.
"""
from raven_ppt.plugin.config import EngineConfig
from raven_ppt.stages.build import BATCH_VIEWS
assert EngineConfig().views_per_call == BATCH_VIEWS
def test_a_view_budget_outside_the_range_is_refused_not_silently_clamped() -> None:
"""Zero renders would publish a deck nobody looked at; the gate reads the same
number, so it would also record nothing and refuse forever. Above twelve the reply
approaches the content-block ceiling an endpoint has already refused. The fork
said this with a pydantic range on tools.ppt; the plugin slice says it in
EngineConfig.from_slice, whose raise the factories turn into the fail-closed
sentinel hook (tests/test_ppt_engine_plugin.py pins that seat)."""
from raven_ppt.plugin.config import EngineConfig
assert EngineConfig.from_slice({"viewsPerCall": 12}).views_per_call == 12
assert EngineConfig.from_slice({"readerEffort": "low"}).reader_effort == "low"
assert EngineConfig.from_slice({}).reader_effort == "", "empty means the provider's own default"
with pytest.raises(ValueError):
EngineConfig.from_slice({"readerEffort": 3})
for bad in (0, -1, 13):
with pytest.raises(ValueError):
EngineConfig.from_slice({"viewsPerCall": bad})
def test_the_image_generator_answers_configured_from_the_live_host_section(tmp_path: Path, monkeypatch) -> None:
"""Same terms as the host's image_generate, asked live rather than at assembly:
the tool is always built, and `configured()` follows the section the reader
answers with now -- a key or a model offers it, an emptied section withdraws
it, and an ambient OPENROUTER_API_KEY alone does not offer it."""
from raven.config.schema import MediaToolConfig
monkeypatch.setenv("OPENROUTER_API_KEY", "ambient-chat-key")
section: dict[str, MediaToolConfig | None] = {"now": None}
tools = {t.name: t for t in build_ppt_tools(tmp_path, image_config=lambda: section["now"])}
generator = tools["ppt_generate_image"]
assert generator.configured() is False
section["now"] = MediaToolConfig()
assert generator.configured() is False, "an OpenRouter key set for chat must not switch on a tool that bills"
section["now"] = MediaToolConfig(api_key="k")
assert generator.configured() is True and generator.model == "openai/gpt-image-2.5-sunburst"
section["now"] = MediaToolConfig(model="qwen/qwen-image-2")
assert generator.configured() is True and generator.model == "qwen/qwen-image-2"
section["now"] = MediaToolConfig()
assert generator.configured() is False
assert "ppt_generate_image" in {t.name for t in build_ppt_tools(tmp_path)}, "built even with no reader lent"
def test_the_render_gate_follows_the_box_and_an_operators_number_still_wins() -> None:
"""An absent renderConcurrency is a question about the machine, not a default.
The fork spelled 2 and the shipped product spelled it after it, so every box
ran two conversions at once -- measured on 32 cores, seven templates take
50.3s seven-wide against 67.8s two-wide with the slowest single conversion
unchanged, so the fixed number was a 32-core box waiting for a two-core box's
answer. The slice no longer spells it (the launcher ledger pins that), which
makes this default the one the product actually runs on; a setting that is
written still wins, and the range is still refused rather than clamped.
"""
from raven_ppt.plugin.config import EngineConfig
from raven_ppt.services.render import default_concurrency
assert EngineConfig().render_concurrency == default_concurrency()
assert EngineConfig.from_slice({}).render_concurrency == default_concurrency()
assert EngineConfig.from_slice({"renderConcurrency": 1}).render_concurrency == 1
assert EngineConfig.from_slice({"renderConcurrency": 8}).render_concurrency == 8
for bad in (0, 9, -1):
with pytest.raises(ValueError):
EngineConfig.from_slice({"renderConcurrency": bad})
def test_the_stage_and_the_slice_read_the_same_gate() -> None:
"""The two seats that size the gate, kept on one number.
`DeckViews` is built by direct callers (a test, a script, the template tool's
thumbnails) as well as by assembly, so a stage default left at 2 would keep
half the callers on the old fixed number while the product moved.
"""
from raven_ppt.plugin.config import EngineConfig
from raven_ppt.services.render import default_concurrency
from raven_ppt.stages._views import DeckViews
assert DeckViews().concurrency == default_concurrency() == EngineConfig().render_concurrency