qwen-sci 0.2.2__py3-none-any.whl

src/agents/research_plan_author/idea_evolution.py

@@ -0,0 +1,223 @@
+"""Project a bounded, source-anchored Idea evolution appendix without invention."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Mapping
+
+from src.agents.experiment_design_agent.idea_intake import load_idea_artifact_bundle
+
+
+IDEA_EVOLUTION_APPENDIX_SCHEMA_VERSION = "idea_evolution_appendix_v1"
+
+
+class IdeaEvolutionError(ValueError):
+    """Raised when the requested Idea history conflicts with the selected direction."""
+
+
+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 _identifier_candidates(direction: Mapping[str, Any]) -> set[str]:
+    values = (
+        direction.get("id"),
+        direction.get("direction_id"),
+        direction.get("direction_mode"),
+        direction.get("title"),
+    )
+    return {_text(value) for value in values if _text(value)}
+
+
+def _selected_direction(idea_result: Mapping[str, Any], selected_direction_id: str) -> tuple[dict[str, Any], str]:
+    directions = idea_result.get("directions")
+    candidates = directions if isinstance(directions, list) else []
+    for index, raw_direction in enumerate(candidates):
+        direction = _mapping(raw_direction)
+        if selected_direction_id in _identifier_candidates(direction):
+            return direction, f"/directions/{index}"
+    primary_direction = _text(idea_result.get("primary_direction"))
+    if selected_direction_id == primary_direction:
+        for index, raw_direction in enumerate(candidates):
+            direction = _mapping(raw_direction)
+            if primary_direction in _identifier_candidates(direction):
+                return direction, f"/directions/{index}"
+    raise IdeaEvolutionError(
+        f"selected direction mismatch: '{selected_direction_id}' is not present in idea_result.json directions"
+    )
+
+
+def _snapshot(record: Mapping[str, Any]) -> dict[str, Any]:
+    allowed_fields = (
+        "id",
+        "direction_id",
+        "direction_mode",
+        "title",
+        "research_question",
+        "central_hypothesis",
+        "hypothesis",
+        "mechanism_or_relation",
+        "contribution",
+        "contributions",
+        "claim_scope",
+        "boundary_conditions",
+        "alternative_explanations",
+        "falsifiers",
+        "known_unknowns",
+        "target_gap_ids",
+    )
+    return {
+        field: deepcopy(record[field])
+        for field in allowed_fields
+        if field in record and record[field] not in (None, "", [], {})
+    }
+
+
+def _append_checkpoint(
+    checkpoints: list[dict[str, Any]],
+    *,
+    source_file: str,
+    source_path: str,
+    source_json_pointer: str,
+    record: Mapping[str, Any],
+) -> None:
+    snapshot = _snapshot(record)
+    if not snapshot:
+        return
+    if any(item["snapshot"] == snapshot for item in checkpoints):
+        return
+    checkpoints.append(
+        {
+            "checkpoint_id": f"checkpoint-{len(checkpoints) + 1}",
+            "checkpoint_type": "available_audit_snapshot",
+            "temporal_order": "unknown",
+            "source_file": source_file,
+            "source_path": source_path,
+            "source_json_pointer": source_json_pointer,
+            "snapshot": snapshot,
+        }
+    )
+
+
+def project_idea_evolution(
+    idea_result_path: str | Path,
+    *,
+    selected_direction_id: str,
+    max_iterations: int = 3,
+) -> dict[str, Any]:
+    """Project available Idea audit snapshots without inventing an iteration history.
+
+    The common Idea artifacts are parallel audit outputs from one run.  Their
+    filenames do not establish chronology or parentage, so they remain neutral
+    source checkpoints unless a future producer supplies auditable evolution
+    metadata.
+    """
+
+    if max_iterations not in {2, 3}:
+        raise ValueError("max_iterations must be either 2 or 3")
+    expected_direction_id = _text(selected_direction_id)
+    if not expected_direction_id:
+        raise IdeaEvolutionError("selected_direction_id is required for Idea evolution projection")
+    try:
+        bundle = load_idea_artifact_bundle(idea_result_path)
+    except (FileNotFoundError, ValueError) as error:
+        raise IdeaEvolutionError(str(error)) from error
+    idea_result = _mapping(bundle.get("idea_result"))
+    selected, selected_pointer = _selected_direction(idea_result, expected_direction_id)
+    source_paths = _mapping(bundle.get("source_paths"))
+    audit_sources = _mapping(bundle.get("audit_sources"))
+    checkpoints: list[dict[str, Any]] = []
+    candidate = _mapping(audit_sources.get("idea_candidate"))
+    _append_checkpoint(
+        checkpoints,
+        source_file="idea_candidate.json",
+        source_path=_text(source_paths.get("idea_candidate")),
+        source_json_pointer="/",
+        record=candidate,
+    )
+    portfolio = _mapping(audit_sources.get("idea_portfolio"))
+    selected_primary_idea = _mapping(
+        audit_sources.get("selected_primary_idea") or portfolio.get("selected_primary_idea")
+    )
+    _append_checkpoint(
+        checkpoints,
+        source_file="idea_portfolio.json",
+        source_path=_text(source_paths.get("idea_portfolio")),
+        source_json_pointer="/selected_primary_idea",
+        record=selected_primary_idea,
+    )
+    _append_checkpoint(
+        checkpoints,
+        source_file="idea_result.json",
+        source_path=_text(source_paths.get("idea_result")),
+        source_json_pointer=selected_pointer,
+        record=selected,
+    )
+    if len(checkpoints) > max_iterations:
+        checkpoints = [checkpoints[0], checkpoints[-1]] if max_iterations == 2 else checkpoints[-max_iterations:]
+        for index, checkpoint in enumerate(checkpoints, start=1):
+            checkpoint["checkpoint_id"] = f"checkpoint-{index}"
+    return {
+        "schema_version": IDEA_EVOLUTION_APPENDIX_SCHEMA_VERSION,
+        "status": "CHECKPOINTS_AVAILABLE" if len(checkpoints) >= 2 else "INSUFFICIENT_HISTORY",
+        "selected_direction_id": expected_direction_id,
+        "max_iterations": max_iterations,
+        "temporal_order": "unknown",
+        "checkpoints": checkpoints,
+        "iterations": [],
+        "missing_audit_sources": list(bundle.get("missing_sources") or []),
+        "authoring_constraints": {
+            "language": "en",
+            "do_not_invent_missing_iterations": True,
+            "do_not_describe_checkpoints_as_temporal_iterations": True,
+            "temporal_order_is_unknown_without_iteration_id_timestamp_parent_or_auditable_diff": True,
+            "do_not_present_idea_history_as_empirical_evidence": True,
+            "all_displayed_checkpoints_require_source_anchors": True,
+        },
+    }
+
+
+def disabled_idea_evolution() -> dict[str, Any]:
+    """Represent an explicit CLI opt-out without pretending history was unavailable."""
+
+    return {
+        "schema_version": IDEA_EVOLUTION_APPENDIX_SCHEMA_VERSION,
+        "status": "DISABLED",
+        "selected_direction_id": "",
+        "max_iterations": 0,
+        "temporal_order": "not_applicable",
+        "checkpoints": [],
+        "iterations": [],
+        "missing_audit_sources": [],
+        "authoring_constraints": {
+            "language": "en",
+            "do_not_invent_missing_iterations": True,
+            "do_not_describe_checkpoints_as_temporal_iterations": True,
+            "temporal_order_is_unknown_without_iteration_id_timestamp_parent_or_auditable_diff": True,
+            "do_not_present_idea_history_as_empirical_evidence": True,
+            "all_displayed_checkpoints_require_source_anchors": True,
+        },
+    }
+
+
+def unavailable_idea_evolution(reason: str) -> dict[str, Any]:
+    """Expose missing optional history explicitly rather than fabricating an appendix."""
+
+    payload = disabled_idea_evolution()
+    payload["status"] = "UNAVAILABLE"
+    payload["unavailable_reason"] = _text(reason)
+    return payload
+
+
+__all__ = [
+    "IDEA_EVOLUTION_APPENDIX_SCHEMA_VERSION",
+    "IdeaEvolutionError",
+    "disabled_idea_evolution",
+    "project_idea_evolution",
+    "unavailable_idea_evolution",
+]

src/agents/research_plan_author/input_loader.py

@@ -0,0 +1,76 @@
+"""Load and validate a canonical ExperimentDesign Author handoff."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+from pathlib import Path
+from typing import Any, Mapping
+
+from .contracts import validate_author_input
+
+
+class AuthorInputLoadError(ValueError):
+    """Raised when an Author handoff cannot safely enter the writing workflow."""
+
+
+def load_author_input_with_identity(path: str | Path) -> tuple[Path, dict[str, Any], dict[str, Any]]:
+    """Read, validate, snapshot, and identify one handoff from the same bytes."""
+
+    resolved_path = Path(path).expanduser().resolve()
+    if not resolved_path.is_file():
+        raise AuthorInputLoadError(f"Research Plan Author input is not a file: {resolved_path}")
+    try:
+        raw_bytes = resolved_path.read_bytes()
+    except OSError as error:
+        raise AuthorInputLoadError(f"Cannot read Research Plan Author input '{resolved_path}': {error}") from error
+    try:
+        payload = json.loads(raw_bytes.decode("utf-8"))
+    except json.JSONDecodeError as error:
+        raise AuthorInputLoadError(f"Research Plan Author input is not valid JSON: {resolved_path}: {error}") from error
+    except UnicodeDecodeError as error:
+        raise AuthorInputLoadError(f"Research Plan Author input is not UTF-8 JSON: {resolved_path}: {error}") from error
+    if not isinstance(payload, Mapping):
+        raise AuthorInputLoadError("Research Plan Author input must contain one JSON object")
+    errors = validate_author_input(payload)
+    if errors:
+        raise AuthorInputLoadError("Research Plan Author input validation failed: " + "; ".join(errors))
+    return (
+        resolved_path,
+        dict(payload),
+        {
+            "path": str(resolved_path),
+            "sha256": hashlib.sha256(raw_bytes).hexdigest(),
+            "byte_size": len(raw_bytes),
+        },
+    )
+
+
+def load_author_input(path: str | Path) -> tuple[Path, dict[str, Any]]:
+    """Read one explicit Author JSON artifact without selecting an ambiguous run file."""
+
+    resolved_path, payload, _identity = load_author_input_with_identity(path)
+    return resolved_path, payload
+
+
+def identify_author_input(path: str | Path) -> dict[str, Any]:
+    """Return a stable identity for the exact handoff bytes that were loaded."""
+
+    resolved_path = Path(path).expanduser().resolve()
+    try:
+        raw_bytes = resolved_path.read_bytes()
+    except OSError as error:
+        raise AuthorInputLoadError(f"Cannot identify Research Plan Author input '{resolved_path}': {error}") from error
+    return {
+        "path": str(resolved_path),
+        "sha256": hashlib.sha256(raw_bytes).hexdigest(),
+        "byte_size": len(raw_bytes),
+    }
+
+
+__all__ = [
+    "AuthorInputLoadError",
+    "identify_author_input",
+    "load_author_input",
+    "load_author_input_with_identity",
+]

src/agents/research_plan_author/latex_compiler.py

@@ -0,0 +1,260 @@
+"""Isolated, shell-free LaTeX/BibTeX compilation for Author render projects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+from time import perf_counter
+from collections.abc import Mapping
+from typing import Any
+
+
+LATEX_COMPILE_SCHEMA_VERSION = "research_plan_author_latex_compile_v1"
+
+
+class LatexCompilerError(RuntimeError):
+    """Raised when a required LaTeX executable cannot be resolved safely."""
+
+
+@dataclass(frozen=True)
+class LatexCompileResult:
+    success: bool
+    report: dict[str, Any]
+    log_text: str
+    staged_pdf: Path | None
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+def _absolute_executable_path(value: str | Path) -> Path:
+    """Make an executable path absolute without dereferencing its command name.
+
+    LaTeX distributions frequently expose ``pdflatex`` and ``xelatex`` as
+    symlinks to lower-level binaries.  The invoked filename selects the TeX
+    format, so resolving that symlink changes the command's behavior.
+    """
+
+    return Path(value).expanduser().absolute()
+
+
+def resolve_executable(
+    *,
+    explicit: str | Path | None,
+    environment_variable: str,
+    configured: str | Path | None,
+    fallback: str,
+    label: str,
+) -> Path:
+    """Resolve one executable in declared precedence order; a supplied bad path fails."""
+
+    candidates = (
+        ("explicit", _text(explicit)),
+        (f"environment:{environment_variable}", _text(os.environ.get(environment_variable))),
+        ("configuration", _text(configured)),
+        ("PATH", fallback),
+    )
+    for source, candidate in candidates:
+        if not candidate:
+            continue
+        path = Path(candidate).expanduser()
+        has_path_syntax = path.is_absolute() or any(separator in candidate for separator in ("/", "\\"))
+        if has_path_syntax:
+            executable_path = _absolute_executable_path(path)
+            if executable_path.is_file():
+                return executable_path
+            if source != "PATH":
+                raise LatexCompilerError(f"{label} from {source} is not an executable file: {executable_path}")
+            continue
+        located = shutil.which(candidate)
+        if located:
+            return _absolute_executable_path(located)
+        if source != "PATH":
+            raise LatexCompilerError(f"{label} from {source} is not available on PATH: {candidate}")
+    raise LatexCompilerError(
+        f"{label} is unavailable; set {environment_variable}, pass the matching CLI option, or configure it explicitly"
+    )
+
+
+def _safe_command(command: list[str]) -> list[str]:
+    return [str(argument).replace("\n", " ").replace("\r", " ")[:2000] for argument in command]
+
+
+def _run_command(command: list[str], *, cwd: Path, timeout_seconds: int) -> tuple[dict[str, Any], str]:
+    started_at = perf_counter()
+    safe = _safe_command(command)
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=str(cwd),
+            shell=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=max(1, int(timeout_seconds)),
+            check=False,
+        )
+        output = (completed.stdout or "") + ("\n" if completed.stdout and completed.stderr else "") + (completed.stderr or "")
+        return (
+            {
+                "command": safe,
+                "return_code": completed.returncode,
+                "timed_out": False,
+                "elapsed_ms": round((perf_counter() - started_at) * 1000, 3),
+            },
+            output,
+        )
+    except subprocess.TimeoutExpired as error:
+        stdout = error.stdout.decode("utf-8", "replace") if isinstance(error.stdout, bytes) else str(error.stdout or "")
+        stderr = error.stderr.decode("utf-8", "replace") if isinstance(error.stderr, bytes) else str(error.stderr or "")
+        return (
+            {
+                "command": safe,
+                "return_code": None,
+                "timed_out": True,
+                "elapsed_ms": round((perf_counter() - started_at) * 1000, 3),
+            },
+            stdout + ("\n" if stdout and stderr else "") + stderr,
+        )
+    except OSError as error:
+        return (
+            {
+                "command": safe,
+                "return_code": None,
+                "timed_out": False,
+                "elapsed_ms": round((perf_counter() - started_at) * 1000, 3),
+                "execution_error": type(error).__name__,
+            },
+            str(error),
+        )
+
+
+def compile_latex_project(
+    project_dir: str | Path,
+    *,
+    main_tex: str | Path,
+    latex_engine: str | Path,
+    bibtex: str | Path | None,
+    run_bibtex: bool,
+    timeout_seconds: int,
+    staged_pdf_path: str | Path,
+    logger: Any | None = None,
+) -> LatexCompileResult:
+    """Compile an isolated copy and stage a PDF only after all passes succeed."""
+
+    source_project = Path(project_dir).expanduser().resolve()
+    source_main = Path(main_tex).expanduser().resolve()
+    target_pdf = Path(staged_pdf_path).expanduser().resolve()
+    try:
+        main_relative = source_main.relative_to(source_project)
+    except ValueError as error:
+        raise LatexCompilerError("main TeX file must remain inside the render project") from error
+    if not source_project.is_dir() or not source_main.is_file():
+        raise LatexCompilerError("render project or main TeX file does not exist")
+    engine_path = _absolute_executable_path(latex_engine)
+    bibtex_path = _absolute_executable_path(bibtex) if bibtex else None
+    if not engine_path.is_file():
+        raise LatexCompilerError(f"LaTeX engine is not an executable file: {engine_path}")
+    if run_bibtex and (bibtex_path is None or not bibtex_path.is_file()):
+        raise LatexCompilerError("BibTeX is required by emitted references but is not an executable file")
+    base_name = main_relative.stem
+    commands: list[tuple[str, list[str]]] = [
+        (
+            "latex_initial",
+            [str(engine_path), "-interaction=nonstopmode", "-halt-on-error", "-no-shell-escape", main_relative.name],
+        )
+    ]
+    if run_bibtex:
+        commands.append(("bibtex", [str(bibtex_path), base_name]))
+    commands.extend(
+        [
+            (
+                "latex_resolve_references_1",
+                [str(engine_path), "-interaction=nonstopmode", "-halt-on-error", "-no-shell-escape", main_relative.name],
+            ),
+            (
+                "latex_resolve_references_2",
+                [str(engine_path), "-interaction=nonstopmode", "-halt-on-error", "-no-shell-escape", main_relative.name],
+            ),
+        ]
+    )
+    command_reports: list[dict[str, Any]] = []
+    log_parts: list[str] = []
+    failure_stage = ""
+    with tempfile.TemporaryDirectory(prefix="research-plan-author-compile-") as temporary_root:
+        workspace = Path(temporary_root) / "project"
+        shutil.copytree(source_project, workspace)
+        compile_cwd = workspace / main_relative.parent
+        for stage, command in commands:
+            if logger is not None:
+                logger.emit("latex_compile", "command_started", status="RUNNING", compile_stage=stage, command=_safe_command(command))
+            report, output = _run_command(command, cwd=compile_cwd, timeout_seconds=timeout_seconds)
+            report["stage"] = stage
+            command_reports.append(report)
+            log_parts.extend(
+                [
+                    f"===== {stage} =====",
+                    "COMMAND: " + " ".join(report["command"]),
+                    output.rstrip(),
+                    "",
+                ]
+            )
+            successful = report.get("return_code") == 0 and not report.get("timed_out")
+            if logger is not None:
+                logger.emit(
+                    "latex_compile",
+                    "command_completed" if successful else "command_failed",
+                    level="INFO" if successful else "ERROR",
+                    status="COMPLETED" if successful else "FAILED",
+                    compile_stage=stage,
+                    return_code=report.get("return_code"),
+                    timed_out=report.get("timed_out"),
+                    elapsed_ms=report.get("elapsed_ms"),
+                )
+            if not successful:
+                failure_stage = stage
+                break
+        compiled_pdf = compile_cwd / f"{base_name}.pdf"
+        success = not failure_stage and compiled_pdf.is_file() and compiled_pdf.stat().st_size > 0
+        if not success and not failure_stage:
+            failure_stage = "pdf_missing"
+            log_parts.append("Compilation commands completed but the expected PDF was not produced.\n")
+        staged: Path | None = None
+        if success:
+            target_pdf.parent.mkdir(parents=True, exist_ok=True)
+            if target_pdf.exists():
+                raise LatexCompilerError(f"staged PDF target already exists: {target_pdf}")
+            temporary_pdf = target_pdf.with_name(f".{target_pdf.name}.{os.getpid()}.tmp")
+            shutil.copy2(compiled_pdf, temporary_pdf)
+            os.replace(temporary_pdf, target_pdf)
+            staged = target_pdf
+    report = {
+        "schema_version": LATEX_COMPILE_SCHEMA_VERSION,
+        "generated_at": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
+        "success": bool(success),
+        "failure_stage": failure_stage,
+        "project_dir": str(source_project),
+        "main_tex": str(source_main),
+        "run_bibtex": bool(run_bibtex),
+        "timeout_seconds": int(timeout_seconds),
+        "allow_shell_escape": False,
+        "commands": command_reports,
+        "staged_pdf": str(staged) if staged is not None else "",
+    }
+    return LatexCompileResult(success=bool(success), report=report, log_text="\n".join(log_parts), staged_pdf=staged)
+
+
+__all__ = [
+    "LATEX_COMPILE_SCHEMA_VERSION",
+    "LatexCompileResult",
+    "LatexCompilerError",
+    "compile_latex_project",
+    "resolve_executable",
+]