nexu-io/open-design · error · ValueError

brief mode reads markdown/text raw material, not rendered de

Error message

brief mode reads markdown/text raw material, not rendered decks: {path}. Extract the text first (see scripts/pptx_qa.py's dump/inspect output for an existing .ppt/.pptx) and pass that as --source. If this is a deck Humanize PPT already rendered, run the presentation checkup instead: --qa-from <path-to-this-file.pptx>.

What it means

Raised by read_source in humanize_ppt_v2.py as `raise ValueError(...)` when the --source path has a .ppt or .pptx suffix. Brief mode is designed to consume raw markdown/text raw material, not a rendered deck; passing a binary deck is treated as a user error. The message explicitly redirects: extract text first, or use --qa-from for an already-rendered deck checkup.

Source

Thrown at plugins/community/humanize-ppt/scripts/humanize_ppt_v2.py:201

        shutil.rmtree(out)
        out.mkdir(parents=True, exist_ok=True)
        return None
    marker_list = " or ".join(HUMANIZE_OUT_MARKERS)
    return (
        f"--out {out} already exists, is not empty, and does not look like a "
        f"previous Humanize PPT run (no {marker_list} "
        "at its root). Refusing to wipe it: it may hold content you did not intend "
        "to lose. Point --out at a dedicated run directory, or pass --force to wipe "
        "it anyway.\n"
    )


def read_source(source):
    path = Path(source).expanduser()
    if not path.exists():
        raise FileNotFoundError(f"source not found: {path}")
    if path.suffix.lower() in {".ppt", ".pptx"}:
        raise ValueError(
            f"brief mode reads markdown/text raw material, not rendered decks: {path}. "
            "Extract the text first (see scripts/pptx_qa.py's dump/inspect output for an "
            "existing .ppt/.pptx) and pass that as --source. If this is a deck Humanize "
            "PPT already rendered, run the presentation checkup instead: "
            "--qa-from <path-to-this-file.pptx>."
        )
    text = path.read_text(encoding="utf-8", errors="replace")
    return path, text, markdown_segments(text)


def strip_md(line):
    line = re.sub(r"^#{1,6}\s*", "", line.strip())
    line = re.sub(r"^[-*+]\s+", "", line)
    line = re.sub(r"^\d+[.)]\s+", "", line)
    line = re.sub(r"[`*_>\[\]]", "", line)
    return line.strip()

View on GitHub (pinned to 5be4028344)

Solutions

Convert the deck to markdown/text first — the message points at scripts/pptx_qa.py's dump/inspect output: run `python3 pptx_qa.py dump foo.pptx > foo.md` (or the project's documented extractor), then pass the extracted text as --source.
If the deck was already produced by Humanize PPT and you want a checkup, use `--qa-from foo.pptx` instead of `--source`.
If you actually have markdown but misnamed it .pptx, rename the file to .md/.txt and re-run.
Double-check the pipeline ordering: ensure the extraction stage runs before the humanize stage.

Example fix

// before
python3 humanize_ppt_v2.py --source deck.pptx
# -> ValueError: brief mode reads markdown/text raw material, not rendered decks

// after
python3 pptx_qa.py dump deck.pptx > deck.md
python3 humanize_ppt_v2.py --source deck.md

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

source_path = Path(args.source).expanduser()
if source_path.suffix.lower() in {".ppt", ".pptx"}:
    raise SystemExit(
        "Brief mode needs markdown/text, not a deck. "
        "Run: python3 pptx_qa.py dump <deck> > out.md, then pass out.md as --source."
    )
# safe to pass to read_source

Try / catch

try:
    path, text, segments = read_source(args.source)
except ValueError as exc:
    raise SystemExit(str(exc)) from exc

Prevention

Establish a single upstream extraction step that always emits markdown, never a raw deck.
Document the two distinct inputs clearly: --source (raw material) vs --qa-from (rendered deck).
Add a file-extension preflight to the pipeline driver so misuse is caught with a friendlier message.
When in doubt, run pptx_qa.py dump first and inspect the extracted text.

When it happens

Trigger: Passing a PowerPoint file (`foo.pptx`, `FOO.PPT`) to `humanize_ppt_v2 --source` in brief mode. The suffix check is case-insensitive (`.lower()`), so any casing triggers it. Common when a user confuses the brief-mode input with the QA/inspection input.

Common situations: User downloads a .pptx and assumes humanize-ppt ingests decks directly; misreading the help text; pipeline stage miswired so the rendered deck feeds back into the brief stage; case-sensitive filesystem masking the issue on Windows/macOS.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/6b5a47ccabe391ff. Report an issue: GitHub.