Skip to content

2654400439/Paper2Seminar / skills/paper-ppt-orchestrator

paper-ppt-orchestrator

Verified

Build complete fixed-layout academic-paper presentations from a PDF with bundled PPTX and one-page HTML templates. Use for full paper reading, complexity-aware slide budgeting, subsection coverage mapping, figure extraction, TikZ or Matplotlib evidence visuals, deterministic PPTX assembly, and final QA. Trigger for requests to turn a paper PDF into a discussion-group deck, especially 12-16+ page systems, security, networking, or measurement papers.

FileKindSize
SKILL.mdskill md17.9 KB
agents/openai.yamlconfig296 B
assets/one-page-summary.htmlother7.8 KB
assets/seminar-template.pptxbinary572.7 KB
references/content-design.mdmarkdown5.7 KB
references/data-viz.schema.jsonconfig2.9 KB
references/deck-plan.schema.jsonconfig8.5 KB
references/deck-sizing.mdmarkdown3.4 KB
references/environment-compatibility.mdmarkdown2.8 KB
references/feature-registry.jsonconfig1.4 KB
references/figure-extraction.mdmarkdown5.1 KB
references/job-request.defaults.jsonconfig1.6 KB
references/job-request.schema.jsonconfig7.5 KB
references/one-page-template.mdmarkdown3.1 KB
references/qa-gates.mdmarkdown10.0 KB
references/speaker-notes.mdmarkdown3.1 KB
references/template-contract.mdmarkdown5.1 KB
references/tikz-layout.mdmarkdown12.2 KB
references/visual-selection.mdmarkdown6.5 KB
references/workflow.mdmarkdown9.8 KB
requirements-doclayout.txtmarkdown238 B
requirements-ui.txtmarkdown39 B
requirements.txtmanifest68 B
scripts/apply_speaker_notes.pyscript6.1 KB
scripts/build_ppt.pyscript16.3 KB
scripts/crop_author_block.pyscript7.9 KB
scripts/crop_image_region.pyscript2.4 KB
scripts/export_pptx_pages.ps1script1.3 KB
scripts/extract_paper_assets.pyscript22.3 KB
scripts/job_request.pyscript17.1 KB
scripts/make_contact_sheet.pyscript4.0 KB
scripts/paper_ppt.pyscript17.1 KB
scripts/preflight_capabilities.pyscript8.3 KB
scripts/render_data_viz.pyscript14.6 KB
scripts/render_deck_overview.pyscript2.4 KB
scripts/render_one_page_html.pyscript13.4 KB
scripts/render_readability.pyscript4.1 KB
scripts/update_qa_status.pyscript10.1 KB
scripts/validate_deck_plan.pyscript33.9 KB
webapp/__init__.pyscript49 B
webapp/backend.pyscript14.5 KB
webapp/job_runner.pyscript3.2 KB
webapp/streamlit_app.pyscript17.3 KB

scripts/job_request.py

View on GitHub
#!/usr/bin/env python3
"""Compile and validate provider-neutral Paper2Seminar job requests."""

from __future__ import annotations

import argparse
import copy
import hashlib
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

import fitz
import jsonschema


SKILL_ROOT = Path(__file__).resolve().parents[1]
REFERENCE_DIR = SKILL_ROOT / "references"
SCHEMA_PATH = REFERENCE_DIR / "job-request.schema.json"
DEFAULTS_PATH = REFERENCE_DIR / "job-request.defaults.json"
FEATURE_REGISTRY_PATH = REFERENCE_DIR / "feature-registry.json"


class JobRequestError(RuntimeError):
    pass


def utc_now() -> str:
    return datetime.now(timezone.utc).isoformat()


def load_json(path: Path) -> dict[str, Any]:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise JobRequestError(f"cannot read {path.name}: {exc}") from exc
    if not isinstance(value, dict):
        raise JobRequestError(f"{path.name} must contain a JSON object")
    return value


def load_contract() -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    schema = load_json(SCHEMA_PATH)
    defaults = load_json(DEFAULTS_PATH)
    registry = load_json(FEATURE_REGISTRY_PATH)
    validate_contract(defaults, registry)
    return schema, defaults, registry


def validate_contract(defaults: dict[str, Any], registry: dict[str, Any]) -> None:
    if defaults.get("schema_version") != registry.get("schema_version"):
        raise JobRequestError("defaults and feature registry schema versions differ")
    default_profile = defaults.get("default_profile")
    profiles = defaults.get("profiles")
    if not isinstance(profiles, dict) or default_profile not in profiles:
        raise JobRequestError("default profile is missing")
    registered = registry.get("features")
    if not isinstance(registered, dict) or not registered:
        raise JobRequestError("feature registry is empty")
    registered_ids = set(registered)
    for profile_name, profile in profiles.items():
        features = profile.get("features") if isinstance(profile, dict) else None
        if not isinstance(features, dict) or set(features) != registered_ids:
            raise JobRequestError(
                f"profile '{profile_name}' features must exactly match the feature registry"
            )
        for feature_id, metadata in registered.items():
            value = features[feature_id]
            if value.get("status") != metadata.get("status"):
                raise JobRequestError(
                    f"feature '{feature_id}' status differs between profile and registry"
                )
            if value.get("enabled") != metadata.get("default_enabled"):
                raise JobRequestError(
                    f"feature '{feature_id}' default differs between profile and registry"
                )
            if metadata.get("status") == "reserved" and value.get("enabled"):
                raise JobRequestError(f"reserved feature '{feature_id}' cannot be enabled")


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as handle:
        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def inspect_paper_file(
    path: Path,
    title: str,
    title_cn: str = "",
    *,
    title_confirmed: bool = True,
) -> dict[str, Any]:
    try:
        document = fitz.open(path)
    except Exception as exc:
        raise JobRequestError(f"cannot open paper PDF: {exc}") from exc
    try:
        if document.page_count < 1:
            raise JobRequestError("paper PDF has no pages")
        return {
            "path": str(path.resolve()),
            "original_filename": path.name,
            "sha256": sha256_file(path),
            "page_count": document.page_count,
            "text_extractable": bool(document[0].get_text("text").strip()),
            "detected_title": title.strip(),
            "confirmed_title": title.strip(),
            "title_cn": title_cn.strip(),
            "title_confirmed": title_confirmed,
        }
    finally:
        document.close()


def interaction_checkpoints(mode: str) -> list[str]:
    return {
        "non_interactive": ["final"],
        "confirm_once": ["intake", "final"],
        "guided": ["intake", "plan", "assets", "slides", "final"],
    }[mode]


def compile_request(
    *,
    job_id: str,
    paper: dict[str, Any],
    template: dict[str, Any],
    paths: dict[str, str],
    configuration: dict[str, Any],
    source: str,
    interaction_mode: str,
    confirmed: bool,
    profile_name: str | None = None,
    agent_adapter: str = "codex",
    extensions: dict[str, Any] | None = None,
) -> dict[str, Any]:
    schema, defaults, registry = load_contract()
    selected_profile = profile_name or str(defaults["default_profile"])
    profiles = defaults["profiles"]
    if selected_profile not in profiles:
        raise JobRequestError(f"unknown job profile: {selected_profile}")
    profile = copy.deepcopy(profiles[selected_profile])

    presentation = profile["presentation"]
    for key in (
        "language",
        "target_minutes",
        "slide_count_mode",
        "target_slide_count",
        "presenter",
        "advisor",
    ):
        if key in configuration:
            presentation[key] = configuration[key]

    extraction = profile["extraction"]
    extraction.update(configuration.get("extraction", {}))
    visuals = profile["visuals"]
    visuals.update(configuration.get("visual_capabilities", {}))
    features = profile["features"]

    notes_override = configuration.get("speaker_notes", {})
    if notes_override:
        features["speaker_notes"]["enabled"] = bool(notes_override.get("enabled", True))
        features["speaker_notes"]["config"].update(
            {key: value for key, value in notes_override.items() if key != "enabled"}
        )
    readability_mode = configuration.get("readability_mode")
    if readability_mode is not None:
        features["readability"]["enabled"] = readability_mode != "off"
        features["readability"]["config"]["mode"] = readability_mode

    feature_overrides = configuration.get("features", {})
    if not isinstance(feature_overrides, dict):
        raise JobRequestError("configuration.features must be an object")
    for feature_id, override in feature_overrides.items():
        if feature_id not in registry["features"]:
            raise JobRequestError(
                f"feature '{feature_id}' is not registered; add it to feature-registry.json first"
            )
        if not isinstance(override, dict):
            raise JobRequestError(f"feature override '{feature_id}' must be an object")
        features[feature_id]["enabled"] = bool(
            override.get("enabled", features[feature_id]["enabled"])
        )
        if "config" in override:
            if not isinstance(override["config"], dict):
                raise JobRequestError(f"feature '{feature_id}' config must be an object")
            features[feature_id]["config"].update(override["config"])

    for feature_id, value in features.items():
        expected_status = registry["features"][feature_id]["status"]
        value["status"] = expected_status
        if expected_status == "reserved" and value["enabled"]:
            raise JobRequestError(f"reserved feature '{feature_id}' cannot be enabled")

    timestamp = utc_now()
    request = {
        "schema_version": "0.1",
        "job": {"id": job_id, "created_at": timestamp, "profile": selected_profile},
        "interaction": {
            "source": source,
            "mode": interaction_mode,
            "confirmed": confirmed,
            "confirmed_at": timestamp if confirmed else None,
            "review_checkpoints": interaction_checkpoints(interaction_mode),
        },
        "input": {"paper": paper, "template": template},
        "presentation": presentation,
        "extraction": extraction,
        "visuals": visuals,
        "features": features,
        "execution": {
            "agent_adapter": agent_adapter,
            "state": "pending",
            "paths": paths,
        },
        "extensions": extensions or {},
    }
    validate_request(request, schema=schema, registry=registry)
    return request


def validate_request(
    request: dict[str, Any],
    *,
    schema: dict[str, Any] | None = None,
    registry: dict[str, Any] | None = None,
) -> None:
    if schema is None or registry is None:
        loaded_schema, _defaults, loaded_registry = load_contract()
        schema = schema or loaded_schema
        registry = registry or loaded_registry
    try:
        jsonschema.Draft202012Validator(
            schema, format_checker=jsonschema.FormatChecker()
        ).validate(request)
    except jsonschema.ValidationError as exc:
        location = ".".join(str(value) for value in exc.absolute_path) or "$"
        raise JobRequestError(f"invalid job request at {location}: {exc.message}") from exc
    registered = registry["features"]
    for feature_id, value in request["features"].items():
        if feature_id not in registered:
            raise JobRequestError(f"unregistered feature in job request: {feature_id}")
        metadata = registered[feature_id]
        if value["status"] != metadata["status"]:
            raise JobRequestError(f"feature status mismatch: {feature_id}")
        if metadata["status"] == "reserved" and value["enabled"]:
            raise JobRequestError(f"reserved feature cannot be enabled: {feature_id}")

    interaction = request["interaction"]
    expected_checkpoints = interaction_checkpoints(interaction["mode"])
    if interaction["review_checkpoints"] != expected_checkpoints:
        raise JobRequestError(
            "interaction.review_checkpoints must match the selected interaction mode"
        )
    if interaction["confirmed"] != (interaction["confirmed_at"] is not None):
        raise JobRequestError(
            "interaction.confirmed and interaction.confirmed_at are inconsistent"
        )
    if interaction["mode"] == "non_interactive" and not interaction["confirmed"]:
        raise JobRequestError("non_interactive requests must already be confirmed")
    if interaction["source"] == "web_ui" and (
        interaction["mode"] != "non_interactive" or not interaction["confirmed"]
    ):
        raise JobRequestError(
            "web_ui requests must be confirmed and use non_interactive mode"
        )
    if interaction["confirmed"] and not request["input"]["paper"]["title_confirmed"]:
        raise JobRequestError("a confirmed request must include a confirmed paper title")


def write_request(path: Path, request: dict[str, Any]) -> None:
    validate_request(request)
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_suffix(path.suffix + ".tmp")
    temporary.write_text(
        json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
    )
    temporary.replace(path)


def execution_brief(request: dict[str, Any]) -> str:
    validate_request(request)
    paper = request["input"]["paper"]
    presentation = request["presentation"]
    extraction = request["extraction"]
    features = [
        feature_id
        for feature_id, value in request["features"].items()
        if value["enabled"] and value["status"] == "available"
    ]
    slide_count = (
        "按论文复杂度自动确定"
        if presentation["slide_count_mode"] == "auto"
        else f"{presentation['target_slide_count']} 页"
    )
    return "\n".join(
        (
            f"论文:{paper['confirmed_title']}",
            f"汇报:{presentation['language']} / {presentation['target_minutes']} 分钟 / {slide_count}",
            f"模板:{request['input']['template']['source']}",
            f"图表抽取:{extraction['backend']} / {extraction['device']} / {extraction['crop_dpi']} DPI",
            f"启用功能:{', '.join(features) if features else '无'}",
            f"交互策略:{request['interaction']['mode']} / "
            f"{'已确认' if request['interaction']['confirmed'] else '等待确认'}",
        )
    )


def confirm_request(path: Path) -> dict[str, Any]:
    request = load_json(path)
    validate_request(request)
    request["interaction"]["confirmed"] = True
    request["interaction"]["confirmed_at"] = utc_now()
    request["input"]["paper"]["title_confirmed"] = True
    write_request(path, request)
    return request


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    subparsers = parser.add_subparsers(dest="command", required=True)

    validate = subparsers.add_parser("validate", help="validate a job-request.json")
    validate.add_argument("request", type=Path)

    brief = subparsers.add_parser("brief", help="print a compact execution brief")
    brief.add_argument("request", type=Path)

    confirm = subparsers.add_parser("confirm", help="record explicit intake confirmation")
    confirm.add_argument("request", type=Path)

    defaults = subparsers.add_parser("defaults", help="print a named default profile")
    defaults.add_argument("--profile")

    init = subparsers.add_parser("init", help="create a job request for Skill or CLI use")
    init.add_argument("--paper", type=Path, required=True)
    init.add_argument("--template", type=Path, default=SKILL_ROOT / "assets" / "seminar-template.pptx")
    init.add_argument("--run-dir", type=Path, required=True)
    init.add_argument("--title", required=True)
    init.add_argument("--title-cn", default="")
    init.add_argument("--job-id", required=True)
    init.add_argument("--profile")
    init.add_argument("--source", choices=("skill_chat", "cli"), default="skill_chat")
    init.add_argument(
        "--interaction-mode",
        choices=("non_interactive", "confirm_once", "guided"),
        default="confirm_once",
    )
    init.add_argument("--confirmed", action="store_true")
    init.add_argument("--language", choices=("zh-CN", "en-US", "bilingual"))
    init.add_argument("--target-minutes", type=int)
    init.add_argument("--presenter")
    init.add_argument("--advisor")
    init.add_argument("--no-speaker-notes", action="store_true")
    init.add_argument("-o", "--output", type=Path, required=True)

    args = parser.parse_args()
    try:
        if args.command == "validate":
            request = load_json(args.request)
            validate_request(request)
            print(f"PASS: job request is valid: {args.request.resolve()}")
        elif args.command == "brief":
            print(execution_brief(load_json(args.request)))
        elif args.command == "confirm":
            request = confirm_request(args.request)
            print(f"Confirmed job request: {args.request.resolve()}")
            print(execution_brief(request))
        elif args.command == "defaults":
            _schema, payload, _registry = load_contract()
            profile_name = args.profile or payload["default_profile"]
            if profile_name not in payload["profiles"]:
                raise JobRequestError(f"unknown profile: {profile_name}")
            print(json.dumps(payload["profiles"][profile_name], ensure_ascii=False, indent=2))
        else:
            paper_path = args.paper.resolve()
            template_path = args.template.resolve()
            run_dir = args.run_dir.resolve()
            if not paper_path.is_file() or not template_path.is_file():
                raise JobRequestError("paper and template must exist")
            configuration = {
                key: value
                for key, value in {
                    "language": args.language,
                    "target_minutes": args.target_minutes,
                    "presenter": args.presenter,
                    "advisor": args.advisor,
                }.items()
                if value is not None
            }
            configuration["speaker_notes"] = {"enabled": not args.no_speaker_notes}
            paths = {
                "job_dir": str(run_dir),
                "deck_plan": str(run_dir / "deck-plan.json"),
                "output_pptx": str(run_dir / "build" / "presentation.pptx"),
                "capabilities": str(run_dir / "capabilities.json"),
            }
            request = compile_request(
                job_id=args.job_id,
                paper=inspect_paper_file(
                    paper_path,
                    args.title,
                    args.title_cn,
                    title_confirmed=args.confirmed,
                ),
                template={
                    "path": str(template_path),
                    "source": "custom" if args.template != SKILL_ROOT / "assets" / "seminar-template.pptx" else "bundled",
                    "sha256": sha256_file(template_path),
                },
                paths=paths,
                configuration=configuration,
                source=args.source,
                interaction_mode=args.interaction_mode,
                confirmed=args.confirmed,
                profile_name=args.profile,
            )
            write_request(args.output, request)
            print(f"Created job request: {args.output.resolve()}")
        return 0
    except (JobRequestError, OSError) as exc:
        print(f"ERROR: {exc}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall