qwen-sci 0.2.2__py3-none-any.whl

src/agents/research_plan_author/render.py

@@ -0,0 +1,166 @@
+"""End-to-end, design-only Research Plan TeX/PDF rendering orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Mapping
+from typing import Any
+
+from .latex_compiler import LatexCompilerError, compile_latex_project, resolve_executable
+from .pdf_validator import PdfValidationError, PdfValidationResult, validate_pdf
+from .render_artifacts import AuthorRenderArtifactPaths, AuthorRenderArtifactWriter, RenderArtifactError
+from .template_profile import TemplateProfileError, load_template_profile
+from .tex_renderer import TexRenderError, TexRenderResult, render_tex_project
+
+
+class AuthorRenderingError(RuntimeError):
+    """Typed render failure with retained source/diagnostic artifacts."""
+
+    def __init__(self, stage: str, message: str, *, paths: AuthorRenderArtifactPaths | None = None) -> None:
+        super().__init__(f"{stage}: {message}")
+        self.stage = stage
+        self.paths = paths
+
+
+@dataclass(frozen=True)
+class AuthorRenderingResult:
+    artifacts: AuthorRenderArtifactPaths
+    tex: TexRenderResult
+    pdf_validation: PdfValidationResult
+
+
+def _mapping(value: object) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def render_research_plan_document(
+    document: Mapping[str, Any],
+    *,
+    output_dir: str | Path,
+    timestamp: str,
+    preparation_collision_index: int,
+    template_dir: str | Path,
+    template_profile: str | Path | None = None,
+    template_main: str | None = None,
+    latex_engine: str | Path | None = None,
+    bibtex: str | Path | None = None,
+    pdf_renderer: str | Path | None = None,
+    compile_timeout_seconds: int = 180,
+    configured_rendering: Mapping[str, Any] | None = None,
+    author_name: str = "Anonymous Research Plan Author",
+    logger: Any | None = None,
+) -> AuthorRenderingResult:
+    """Render, compile, and validate a proposal PDF without an execution fallback."""
+
+    settings = _mapping(configured_rendering)
+    writer = AuthorRenderArtifactWriter(output_dir)
+    paths = writer.allocate(timestamp=timestamp, preparation_collision_index=preparation_collision_index)
+    try:
+        profile = load_template_profile(template_profile or _text(settings.get("template_profile")) or "markers_v1", main_tex=template_main or _text(settings.get("main_tex")) or None)
+    except TemplateProfileError as error:
+        raise AuthorRenderingError("template", str(error), paths=paths) from error
+    try:
+        if logger is not None:
+            logger.emit("tex_render", "started", status="RUNNING", profile_id=profile.profile_id)
+        tex = render_tex_project(
+            document,
+            template_dir=template_dir,
+            project_dir=paths.project_dir,
+            profile=profile,
+            author_name=author_name,
+        )
+        writer.publish_sources(tex, paths)
+        if logger is not None:
+            logger.emit(
+                "tex_render",
+                "completed",
+                status="COMPLETED",
+                profile_id=profile.profile_id,
+                emitted_bibliography_count=len(tex.bibliography.emitted_keys),
+                bibliography_needs_completion_count=len(tex.bibliography.needs_completion),
+            )
+    except (TexRenderError, RenderArtifactError) as error:
+        if logger is not None:
+            logger.emit("tex_render", "failed", level="ERROR", status="FAILED", error=str(error))
+        raise AuthorRenderingError("tex_render", str(error), paths=paths) from error
+    try:
+        engine = resolve_executable(
+            explicit=latex_engine,
+            environment_variable="SCIENCE_LATEX_ENGINE",
+            configured=settings.get("engine"),
+            fallback="pdflatex",
+            label="LaTeX engine",
+        )
+        bibtex_engine = None
+        if tex.bibliography.emitted_keys:
+            bibtex_engine = resolve_executable(
+                explicit=bibtex,
+                environment_variable="SCIENCE_BIBTEX",
+                configured=settings.get("bibtex"),
+                fallback="bibtex",
+                label="BibTeX engine",
+            )
+    except LatexCompilerError as error:
+        raise AuthorRenderingError("latex_compile", str(error), paths=paths) from error
+    try:
+        compile_result = compile_latex_project(
+            tex.project_dir,
+            main_tex=tex.main_tex,
+            latex_engine=engine,
+            bibtex=bibtex_engine,
+            run_bibtex=bool(tex.bibliography.emitted_keys),
+            timeout_seconds=max(1, int(compile_timeout_seconds)),
+            staged_pdf_path=paths.staged_pdf,
+            logger=logger,
+        )
+    except LatexCompilerError as error:
+        writer.discard_staged_pdf(paths)
+        raise AuthorRenderingError("latex_compile", str(error), paths=paths) from error
+    try:
+        writer.publish_compile_diagnostics(paths, report=compile_result.report, log_text=compile_result.log_text)
+    except RenderArtifactError as error:
+        writer.discard_staged_pdf(paths)
+        raise AuthorRenderingError("artifacts", str(error), paths=paths) from error
+    if not compile_result.success:
+        writer.discard_staged_pdf(paths)
+        raise AuthorRenderingError(
+            "latex_compile",
+            "LaTeX compilation failed; retained compile log and structured diagnostics",
+            paths=paths,
+        )
+    try:
+        renderer = resolve_executable(
+            explicit=pdf_renderer,
+            environment_variable="SCIENCE_PDF_RENDERER",
+            configured=settings.get("pdf_renderer"),
+            fallback="pdftoppm",
+            label="PDF renderer",
+        )
+        validation = validate_pdf(
+            paths.staged_pdf,
+            renderer=renderer,
+            timeout_seconds=max(1, int(settings.get("pdf_validation_timeout_seconds") or 60)),
+            logger=logger,
+        )
+        writer.publish_pdf_validation(paths, validation.report)
+    except (PdfValidationError, LatexCompilerError, RenderArtifactError) as error:
+        if isinstance(error, PdfValidationError) and error.report is not None:
+            try:
+                writer.publish_pdf_validation(paths, error.report)
+            except RenderArtifactError:
+                pass
+        writer.discard_staged_pdf(paths)
+        raise AuthorRenderingError("pdf_validation", str(error), paths=paths) from error
+    try:
+        writer.publish_validated_pdf(paths)
+    except RenderArtifactError as error:
+        raise AuthorRenderingError("artifacts", str(error), paths=paths) from error
+    return AuthorRenderingResult(artifacts=paths, tex=tex, pdf_validation=validation)
+
+
+__all__ = ["AuthorRenderingError", "AuthorRenderingResult", "render_research_plan_document"]

src/agents/research_plan_author/render_artifacts.py

@@ -0,0 +1,187 @@
+"""Atomic, non-overwriting publication of Author TeX/PDF render artifacts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Any, Mapping
+
+from .tex_renderer import TexRenderResult
+
+
+class RenderArtifactError(RuntimeError):
+    """Raised when a render artifact cannot be allocated or published safely."""
+
+
+@dataclass(frozen=True)
+class AuthorRenderArtifactPaths:
+    timestamp: str
+    preparation_collision_index: int
+    render_collision_index: int
+    project_dir: Path
+    tex: Path
+    bibtex: Path
+    bibliography_needs_completion: Path
+    render_manifest: Path
+    compile_log: Path
+    compile_json: Path
+    pdf_validation_json: Path
+    pdf: Path
+    staged_pdf: Path
+
+    def as_dict(self) -> dict[str, str | int]:
+        return {
+            "timestamp": self.timestamp,
+            "preparation_collision_index": self.preparation_collision_index,
+            "render_collision_index": self.render_collision_index,
+            "project_dir": str(self.project_dir),
+            "tex": str(self.tex),
+            "bibtex": str(self.bibtex),
+            "bibliography_needs_completion": str(self.bibliography_needs_completion),
+            "render_manifest": str(self.render_manifest),
+            "compile_log": str(self.compile_log),
+            "compile_json": str(self.compile_json),
+            "pdf_validation_json": str(self.pdf_validation_json),
+            "pdf": str(self.pdf),
+        }
+
+
+def _json_text(payload: object) -> str:
+    return json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False) + "\n"
+
+
+def _write_bytes_without_overwrite(path: Path, content: bytes) -> None:
+    temporary: Path | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, raw_path = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+        temporary = Path(raw_path)
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        try:
+            os.link(temporary, path)
+        except FileExistsError as error:
+            raise RenderArtifactError(f"artifact target already exists: {path}") from error
+        except OSError:
+            descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+            with os.fdopen(descriptor, "wb") as handle, temporary.open("rb") as source:
+                handle.write(source.read())
+                handle.flush()
+                os.fsync(handle.fileno())
+    except OSError as error:
+        raise RenderArtifactError(f"cannot publish artifact '{path.name}': {error}") from error
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def _write_text_without_overwrite(path: Path, content: str) -> None:
+    _write_bytes_without_overwrite(path, content.encode("utf-8"))
+
+
+class AuthorRenderArtifactWriter:
+    """Reserve one timestamped artifact family and publish it without overwrites."""
+
+    def __init__(self, output_dir: str | Path) -> None:
+        self.output_dir = Path(output_dir).expanduser().resolve()
+
+    def allocate(
+        self,
+        *,
+        timestamp: str,
+        preparation_collision_index: int,
+    ) -> AuthorRenderArtifactPaths:
+        try:
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as error:
+            raise RenderArtifactError(f"cannot create Author render output directory: {error}") from error
+        preparation_suffix = "" if preparation_collision_index == 0 else f"_{preparation_collision_index}"
+        for render_collision_index in range(1000):
+            render_suffix = "" if render_collision_index == 0 else f"_render{render_collision_index}"
+            stem = f"research_plan_{timestamp}{preparation_suffix}{render_suffix}"
+            paths = AuthorRenderArtifactPaths(
+                timestamp=timestamp,
+                preparation_collision_index=preparation_collision_index,
+                render_collision_index=render_collision_index,
+                project_dir=self.output_dir / f"{stem}_project",
+                tex=self.output_dir / f"{stem}.tex",
+                bibtex=self.output_dir / f"references_{timestamp}{preparation_suffix}{render_suffix}.bib",
+                bibliography_needs_completion=self.output_dir
+                / f"bibliography_needs_completion_{timestamp}{preparation_suffix}{render_suffix}.json",
+                render_manifest=self.output_dir / f"research_plan_render_{timestamp}{preparation_suffix}{render_suffix}.json",
+                compile_log=self.output_dir / f"compile_{timestamp}{preparation_suffix}{render_suffix}.log",
+                compile_json=self.output_dir / f"compile_{timestamp}{preparation_suffix}{render_suffix}.json",
+                pdf_validation_json=self.output_dir / f"pdf_validation_{timestamp}{preparation_suffix}{render_suffix}.json",
+                pdf=self.output_dir / f"{stem}.pdf",
+                staged_pdf=self.output_dir / f".{stem}.pdf.staging",
+            )
+            targets = [
+                paths.project_dir,
+                paths.tex,
+                paths.bibtex,
+                paths.bibliography_needs_completion,
+                paths.render_manifest,
+                paths.compile_log,
+                paths.compile_json,
+                paths.pdf_validation_json,
+                paths.pdf,
+                paths.staged_pdf,
+            ]
+            if not any(target.exists() for target in targets):
+                return paths
+        raise RenderArtifactError(f"could not allocate an unused render artifact family for timestamp '{timestamp}'")
+
+    def publish_sources(self, rendered: TexRenderResult, paths: AuthorRenderArtifactPaths) -> None:
+        if rendered.project_dir.resolve() != paths.project_dir.resolve():
+            raise RenderArtifactError("rendered TeX project does not match its allocated artifact directory")
+        try:
+            _write_bytes_without_overwrite(paths.tex, rendered.main_tex.read_bytes())
+            _write_bytes_without_overwrite(paths.bibtex, rendered.bibtex.read_bytes())
+            _write_text_without_overwrite(
+                paths.bibliography_needs_completion,
+                _json_text(
+                    {
+                        "schema_version": "research_plan_author_bibliography_completion_v1",
+                        "needs_completion": list(rendered.bibliography.needs_completion),
+                    }
+                ),
+            )
+            _write_text_without_overwrite(paths.render_manifest, _json_text(rendered.as_dict()))
+        except OSError as error:
+            raise RenderArtifactError(f"cannot publish generated TeX/BibTeX sources: {error}") from error
+
+    def publish_compile_diagnostics(
+        self,
+        paths: AuthorRenderArtifactPaths,
+        *,
+        report: Mapping[str, Any],
+        log_text: str,
+    ) -> None:
+        _write_text_without_overwrite(paths.compile_log, str(log_text))
+        _write_text_without_overwrite(paths.compile_json, _json_text(dict(report)))
+
+    def publish_pdf_validation(self, paths: AuthorRenderArtifactPaths, report: Mapping[str, Any]) -> None:
+        _write_text_without_overwrite(paths.pdf_validation_json, _json_text(dict(report)))
+
+    def publish_validated_pdf(self, paths: AuthorRenderArtifactPaths) -> None:
+        if not paths.staged_pdf.is_file():
+            raise RenderArtifactError("validated PDF staging file does not exist")
+        try:
+            _write_bytes_without_overwrite(paths.pdf, paths.staged_pdf.read_bytes())
+        finally:
+            paths.staged_pdf.unlink(missing_ok=True)
+
+    def discard_staged_pdf(self, paths: AuthorRenderArtifactPaths) -> None:
+        paths.staged_pdf.unlink(missing_ok=True)
+
+
+__all__ = [
+    "AuthorRenderArtifactPaths",
+    "AuthorRenderArtifactWriter",
+    "RenderArtifactError",
+]