jupytermind 0.3.0

package/src/ai_scientist/peer_review.py

@@ -0,0 +1,60 @@
+"""Peer-review routing based on persisted manuscript language metadata."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ai_scientist.evidence_registry import latest_evidence, record_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+from ai_scientist.skill_invocation import SkillInvoker
+
+PEER_REVIEW_DEPENDENCIES = {
+    "ja": {"skillId": "japanese-prose", "version": "0.3.0"},
+    "en": {"skillId": "tech-writer", "version": "0.3.0"},
+}
+
+
+class PeerReviewBlockedError(ValueError):
+    """Peer review cannot proceed without supported manuscript language metadata."""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# @id CODE-AISCI-012
+# @implements REQ-AISCI-011, REQ-AISCI-012, REQ-AISCI-013
+# @design DES-AISCI-008
+def review_manuscript(handle: ResearchProjectHandle, invoker: SkillInvoker) -> dict:
+    """Delegate peer review using the persisted manuscript language metadata."""
+    manuscript = latest_evidence(handle, "manuscript-writing")
+    language = manuscript.metadata.get("language") if manuscript is not None else None
+    if language not in PEER_REVIEW_DEPENDENCIES:
+        raise PeerReviewBlockedError(
+            "Supported manuscript language metadata is required before peer-review."
+        )
+    dependency = PEER_REVIEW_DEPENDENCIES[language]
+    response = invoker.invoke(
+        dependency["skillId"],
+        dependency["version"],
+        "review",
+        {"manuscriptPath": manuscript.artifact_path},
+    )
+    artifact = handle.review_dir / "peer-review.md"
+    artifact.write_text(response["content"], encoding="utf-8")
+    record = record_evidence(
+        handle,
+        "peer-review",
+        artifact,
+        "markdown",
+        _now(),
+        metadata={"language": language},
+    )
+    return {
+        "phase": "peer-review",
+        "artifact": {
+            "phase": record.phase,
+            "path": record.artifact_path,
+            "metadata": record.metadata,
+        },
+    }

package/src/ai_scientist/phase_gate.py

@@ -0,0 +1,74 @@
+"""Phase gate enforcement for ai_scientist."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from ai_scientist.phase_state import PHASE_ORDER, load_phase_state, record_override
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+@dataclass(frozen=True)
+class GateDecision:
+    """Outcome of a phase gate check."""
+
+    allowed: bool
+    message: str
+    blocked_on: str | None = None
+    override_applied: bool = False
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# @id CODE-AISCI-006
+# @implements REQ-AISCI-006
+# @design DES-AISCI-004
+# @id CODE-AISCI-008
+# @implements REQ-AISCI-007
+# @design DES-AISCI-004
+def check_gate(
+    handle: ResearchProjectHandle,
+    requested_phase: str,
+    override: dict[str, str] | None = None,
+) -> GateDecision:
+    """Allow only the active phase unless an explicit single-request override exists."""
+    state = load_phase_state(handle)
+    current = state.active_phase
+    if requested_phase == current:
+        return GateDecision(True, f"{requested_phase} is active and allowed.")
+
+    predecessors = [
+        phase
+        for phase in PHASE_ORDER[: PHASE_ORDER.index(requested_phase)]
+        if phase not in state.completed_phases
+    ]
+    if not predecessors:
+        # requested_phase is an earlier phase whose own predecessors are all
+        # complete (e.g. re-running an already-completed phase); there is no
+        # incomplete predecessor to block on, so allow it without an override.
+        return GateDecision(True, f"{requested_phase}'s predecessors are complete; allowed.")
+    blocked_on = predecessors[0]
+
+    if override is None:
+        return GateDecision(
+            allowed=False,
+            blocked_on=blocked_on,
+            message=f"Cannot run {requested_phase} because {blocked_on} is incomplete.",
+        )
+
+    record_override(
+        handle,
+        requested_phase=requested_phase,
+        reason=override["reason"],
+        incomplete_predecessors=predecessors,
+        timestamp=_now(),
+    )
+    return GateDecision(
+        allowed=True,
+        blocked_on=None,
+        override_applied=True,
+        message=f"Override applied for {requested_phase}.",
+    )

package/src/ai_scientist/phase_state.py

@@ -0,0 +1,230 @@
+"""Persistent phase state for ai_scientist projects."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from uuid import uuid4
+
+from ai_scientist.completion_gate import validate_completion_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+
+if sys.platform == "win32":  # pragma: no cover - exercised only on Windows
+    import msvcrt
+else:
+    import fcntl
+
+PHASE_ORDER = (
+    "research-planning",
+    "literature-review",
+    "experimental-design",
+    "data-analysis",
+    "manuscript-writing",
+    "peer-review",
+    "reproducibility-check",
+    "presentation",
+)
+DEFAULT_STATE_PATH = ".ai_scientist_phase_state.json"
+
+
+@dataclass(frozen=True)
+class OverrideRecord:
+    """A durable single-request override audit record."""
+
+    request_id: str
+    timestamp: str
+    requested_phase: str
+    reason: str
+    incomplete_predecessors: list[str]
+
+
+@dataclass(frozen=True)
+class PhaseState:
+    """Persisted lifecycle state."""
+
+    active_phase: str | None
+    completed_phases: list[str]
+    incomplete_phases: list[str]
+    overrides: list[OverrideRecord] = field(default_factory=list)
+
+
+def _state_path(handle: ResearchProjectHandle) -> Path:
+    return handle.root / DEFAULT_STATE_PATH
+
+
+def _lock_path(handle: ResearchProjectHandle) -> Path:
+    return _state_path(handle).with_suffix(".lock")
+
+
+# Test seam: called once per mutating read-modify-write cycle, after the
+# state has been read under the exclusive lock and before it is written
+# back. A no-op in production; tests may monkeypatch it to deterministically
+# exercise concurrent-writer scenarios (DES-AISCI-003 cross-process safety).
+def _after_locked_read_hook() -> None:
+    return None
+
+
+@contextlib.contextmanager
+def _locked(handle: ResearchProjectHandle):
+    """Serialize read-modify-write access to this project's phase state file.
+
+    An OS-level advisory exclusive lock on a sibling ``.lock`` file makes the
+    read-decide-write cycle in :func:`mark_phase_complete` and
+    :func:`record_override` safe across separate CLI invocations (DES-AISCI-003:
+    "Must be read-modify-write safe across separate CLI invocations"),
+    preventing one invocation's transition from silently clobbering another's.
+
+    Closes jupytermind#64 / CHANGE-019 (ADR-0075): see TEST-AISCI-041.
+    The lock is scoped per phase-state file, so unrelated projects never
+    contend with each other.
+    """
+    lock_path = _lock_path(handle)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(lock_path, "a+b") as lock_file:
+        if sys.platform == "win32":  # pragma: no cover - exercised only on Windows
+            msvcrt.locking(lock_file.fileno(), msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                lock_file.seek(0)
+                msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+
+def _initial_state() -> PhaseState:
+    return PhaseState(
+        active_phase=PHASE_ORDER[0],
+        completed_phases=[],
+        incomplete_phases=list(PHASE_ORDER[1:]),
+        overrides=[],
+    )
+
+
+def _read_state(handle: ResearchProjectHandle) -> PhaseState:
+    path = _state_path(handle)
+    if not path.exists():
+        return _initial_state()
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return PhaseState(
+        active_phase=payload["active_phase"],
+        completed_phases=payload["completed_phases"],
+        incomplete_phases=payload["incomplete_phases"],
+        overrides=[OverrideRecord(**item) for item in payload.get("overrides", [])],
+    )
+
+
+def _write_state(handle: ResearchProjectHandle, state: PhaseState) -> None:
+    path = _state_path(handle)
+    temp_path = path.with_suffix(".tmp")
+    temp_path.write_text(
+        json.dumps(
+            {
+                "active_phase": state.active_phase,
+                "completed_phases": state.completed_phases,
+                "incomplete_phases": state.incomplete_phases,
+                "overrides": [asdict(record) for record in state.overrides],
+            },
+            indent=2,
+            ensure_ascii=False,
+        ),
+        encoding="utf-8",
+    )
+    temp_path.replace(path)
+
+
+# @id CODE-AISCI-004
+# @implements REQ-AISCI-004
+# @design DES-AISCI-003
+def load_phase_state(handle: ResearchProjectHandle) -> PhaseState:
+    """Load or initialize the project's phase state."""
+    state = _read_state(handle)
+    if not _state_path(handle).exists():
+        _write_state(handle, state)
+    return state
+
+
+def active_phase(handle: ResearchProjectHandle) -> str | None:
+    """Return the current active phase."""
+    return load_phase_state(handle).active_phase
+
+
+def _next_phase(phase: str) -> str | None:
+    index = PHASE_ORDER.index(phase)
+    if index + 1 >= len(PHASE_ORDER):
+        return None
+    return PHASE_ORDER[index + 1]
+
+
+# @id CODE-AISCI-005
+# @implements REQ-AISCI-005
+# @design DES-AISCI-003
+def mark_phase_complete(handle: ResearchProjectHandle, phase: str) -> PhaseState:
+    """Mark ``phase`` complete when it is the active phase and matching evidence exists."""
+    if phase not in PHASE_ORDER:
+        raise ValueError(f"Unknown phase: {phase!r}.")
+    with _locked(handle):
+        state = load_phase_state(handle)
+        _after_locked_read_hook()
+        if phase != state.active_phase:
+            raise ValueError(
+                f"Cannot complete {phase}: it is not the active phase ({state.active_phase})."
+            )
+        if not validate_completion_evidence(handle, phase):
+            raise ValueError(f"Cannot complete {phase} without matching evidence.")
+        completed = list(state.completed_phases)
+        if phase not in completed:
+            completed.append(phase)
+        next_active = _next_phase(phase)
+        incomplete = [item for item in PHASE_ORDER if item not in completed and item != next_active]
+        updated = PhaseState(
+            active_phase=next_active,
+            completed_phases=completed,
+            incomplete_phases=incomplete,
+            overrides=state.overrides,
+        )
+        _write_state(handle, updated)
+    return updated
+
+
+# @id CODE-AISCI-007
+# @implements REQ-AISCI-007
+# @design DES-AISCI-004
+def record_override(
+    handle: ResearchProjectHandle,
+    requested_phase: str,
+    reason: str,
+    incomplete_predecessors: list[str],
+    timestamp: str,
+) -> OverrideRecord:
+    """Persist one override audit entry without mutating active phase."""
+    with _locked(handle):
+        state = load_phase_state(handle)
+        _after_locked_read_hook()
+        record = OverrideRecord(
+            request_id=str(uuid4()),
+            timestamp=timestamp,
+            requested_phase=requested_phase,
+            reason=reason,
+            incomplete_predecessors=incomplete_predecessors,
+        )
+        updated = PhaseState(
+            active_phase=state.active_phase,
+            completed_phases=state.completed_phases,
+            incomplete_phases=state.incomplete_phases,
+            overrides=[*state.overrides, record],
+        )
+        _write_state(handle, updated)
+    return record
+
+
+def list_overrides(handle: ResearchProjectHandle) -> list[OverrideRecord]:
+    """Return persisted override audit records."""
+    return load_phase_state(handle).overrides

package/src/ai_scientist/presentation.py

@@ -0,0 +1,56 @@
+"""Presentation-planner delegation."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ai_scientist.evidence_registry import latest_evidence, query_evidence, record_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+from ai_scientist.skill_invocation import SkillInvoker
+
+PRESENTATION_DEPENDENCY = {"skillId": "presentation-planner", "version": "0.3.0"}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# @id CODE-AISCI-013
+# @implements REQ-AISCI-014
+# @design DES-AISCI-009
+def build_presentation(handle: ResearchProjectHandle, invoker: SkillInvoker) -> dict:
+    """Delegate presentation planning and record the resulting outline."""
+    manuscript = latest_evidence(handle, "manuscript-writing")
+    if manuscript is None:
+        raise ValueError("A manuscript artifact is required before the presentation phase.")
+    evidence_manifest = [
+        {
+            "phase": record.phase,
+            "artifactPath": record.artifact_path,
+            "artifactKind": record.artifact_kind,
+            "createdAt": record.created_at,
+            "metadata": record.metadata,
+        }
+        for record in query_evidence(handle)
+        if record.phase != "presentation"
+    ]
+    response = invoker.invoke(
+        PRESENTATION_DEPENDENCY["skillId"],
+        PRESENTATION_DEPENDENCY["version"],
+        "plan",
+        {
+            "manuscriptPath": manuscript.artifact_path if manuscript is not None else "",
+            "evidenceManifest": evidence_manifest,
+        },
+    )
+    artifact = handle.presentation_dir / "presentation-plan.md"
+    artifact.write_text(response["content"], encoding="utf-8")
+    record = record_evidence(handle, "presentation", artifact, "markdown", _now())
+    return {
+        "phase": "presentation",
+        "artifact": {
+            "phase": record.phase,
+            "path": record.artifact_path,
+            "metadata": record.metadata,
+        },
+    }

package/src/ai_scientist/project_config.py

@@ -0,0 +1,31 @@
+"""Project-scoped configuration for ai_scientist."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ai_scientist.project_handle import ResearchProjectHandle
+
+DEFAULT_CONFIG_PATH = ".ai_scientist_project.json"
+
+
+def _config_path(handle: ResearchProjectHandle) -> Path:
+    return handle.root / DEFAULT_CONFIG_PATH
+
+
+def load_project_config(handle: ResearchProjectHandle) -> dict:
+    """Load project configuration, defaulting to an empty mapping."""
+    path = _config_path(handle)
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_project_config(handle: ResearchProjectHandle, config: dict) -> Path:
+    """Persist project configuration atomically."""
+    path = _config_path(handle)
+    temp_path = path.with_suffix(".tmp")
+    temp_path.write_text(json.dumps(config, indent=2, ensure_ascii=False), encoding="utf-8")
+    temp_path.replace(path)
+    return path

package/src/ai_scientist/project_handle.py

@@ -0,0 +1,74 @@
+"""Research workspace resolution for ai_scientist."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ai_data_scientist.project_manager import (
+    InvalidProjectNameError,
+    ProjectHandle,
+    resolve_project,
+)
+
+PHASE_DIRECTORIES = {
+    "planning": "planning",
+    "literature": "literature",
+    "design": "design",
+    "manuscript": "manuscript",
+    "review": "review",
+    "reproducibility": "reproducibility",
+    "presentation": "presentation",
+}
+
+
+@dataclass(frozen=True)
+class ResearchProjectHandle:
+    """Stable ai_scientist project paths derived from ai-data-scientist."""
+
+    name: str
+    root: Path
+    notebook_path: Path
+    planning_dir: Path
+    literature_dir: Path
+    design_dir: Path
+    manuscript_dir: Path
+    review_dir: Path
+    reproducibility_dir: Path
+    presentation_dir: Path
+
+
+def _ensure_phase_dirs(handle: ProjectHandle) -> ResearchProjectHandle:
+    phase_paths = {name: handle.root / directory for name, directory in PHASE_DIRECTORIES.items()}
+    for path in phase_paths.values():
+        path.mkdir(parents=True, exist_ok=True)
+    return ResearchProjectHandle(
+        name=handle.name,
+        root=handle.root,
+        notebook_path=handle.notebook_path,
+        planning_dir=phase_paths["planning"],
+        literature_dir=phase_paths["literature"],
+        design_dir=phase_paths["design"],
+        manuscript_dir=phase_paths["manuscript"],
+        review_dir=phase_paths["review"],
+        reproducibility_dir=phase_paths["reproducibility"],
+        presentation_dir=phase_paths["presentation"],
+    )
+
+
+# @id CODE-AISCI-002
+# @implements REQ-AISCI-002
+# @design DES-AISCI-002
+# @id CODE-AISCI-003
+# @implements REQ-AISCI-003
+# @design DES-AISCI-002
+def resolve_research_project(
+    name: str,
+    projects_root: Path | str | None = None,
+) -> ResearchProjectHandle:
+    """Resolve the shared stable project handle and create ai_scientist dirs."""
+    if not isinstance(name, str):
+        raise InvalidProjectNameError(
+            f"Project name must be a string, got {type(name).__name__} ({name!r})."
+        )
+    return _ensure_phase_dirs(resolve_project(name, projects_root=projects_root))

package/src/ai_scientist/reproducibility.py

@@ -0,0 +1,20 @@
+"""Reproducibility check phase handler."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ai_scientist.evidence_registry import record_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def handle_reproducibility_check(handle: ResearchProjectHandle, instruction: str) -> dict:
+    """Create a reproducibility artifact and record it."""
+    artifact = handle.reproducibility_dir / "reproducibility-check.md"
+    artifact.write_text(instruction, encoding="utf-8")
+    record_evidence(handle, "reproducibility-check", artifact, "markdown", _now())
+    return {"phase": "reproducibility-check", "artifact_path": str(artifact)}

package/src/ai_scientist/research_planning.py

@@ -0,0 +1,20 @@
+"""Research planning phase handler."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ai_scientist.evidence_registry import record_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def handle_research_planning(handle: ResearchProjectHandle, instruction: str) -> dict:
+    """Create a planning artifact and record it as evidence."""
+    artifact = handle.planning_dir / "research-plan.md"
+    artifact.write_text(instruction, encoding="utf-8")
+    record_evidence(handle, "research-planning", artifact, "markdown", _now())
+    return {"phase": "research-planning", "artifact_path": str(artifact)}

package/src/ai_scientist/skill_invocation.py

@@ -0,0 +1,21 @@
+"""Skill invocation abstraction for sibling Copilot skills."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class SkillInvoker(Protocol):
+    """Minimal sibling-skill invocation contract."""
+
+    def invoke(self, skill_id: str, version: str, mode: str, payload: dict) -> dict: ...
+
+
+class DefaultSkillInvoker:
+    """Placeholder implementation for non-test Python execution contexts."""
+
+    def invoke(self, skill_id: str, version: str, mode: str, payload: dict) -> dict:
+        raise NotImplementedError(
+            "Sibling skill invocation must be provided by the Copilot agent runtime. "
+            "See .github/skills/ai-scientist/SKILL.md for the delegation contract."
+        )

package/src/ai_scientist/tdd_gate.py

@@ -0,0 +1,99 @@
+"""Local helper for REQ-AISCI-024's configured test-suite gate.
+
+The configured suite is the release proof that every REQ-AISCI requirement,
+including npm-packaging coverage added in CHANGE-023, has executable
+verification in the ai_scientist test corpus.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+_SKIPPED_TEST_RE = re.compile(r"\b\d+\s+skipped\b", re.IGNORECASE)
+
+
+class TestSuiteGateError(RuntimeError):
+    """Configured test-suite run failed the ai_scientist TDD gate."""
+
+
+def _is_pytest_invocation(command: Sequence[str]) -> bool:
+    """True only for an actual pytest invocation: an executable literally
+    named ``pytest``/``pytest-<suffix>``, or ``-m pytest``. A substring match
+    against arbitrary command parts would also match an unrelated script or
+    test-file path that merely contains "pytest" in its name. Closes a
+    rubber-duck finding from the CHANGE-019 review; see TEST-AISCI-047."""
+    parts = [str(part) for part in command]
+    for index, part in enumerate(parts):
+        basename = Path(part).name
+        if basename == "pytest" or basename.startswith("pytest-"):
+            return True
+        if part == "-m" and index + 1 < len(parts) and parts[index + 1] == "pytest":
+            return True
+    return False
+
+
+def _unapproved_skips(report_path: str, approved_skips: frozenset[str]) -> list[str]:
+    """Return skipped test nodeids from the musubix-json pytest report that
+    are not present in ``approved_skips``, structurally (not by text-parsing
+    console output). Closes jupytermind#67 / CHANGE-019 (ADR-0091); see
+    TEST-AISCI-044 and TEST-AISCI-045."""
+    with open(report_path, encoding="utf-8") as handle:
+        report = json.load(handle)
+    skipped = [
+        test["nodeid"] for test in report.get("tests", []) if test.get("outcome") == "skipped"
+    ]
+    return sorted(nodeid for nodeid in skipped if nodeid not in approved_skips)
+
+
+# @id CODE-AISCI-024
+# @implements REQ-AISCI-024
+# @design DES-AISCI-019
+def run_configured_test_suite(
+    command: Sequence[str],
+    *,
+    approved_skips: frozenset[str] = frozenset(),
+) -> subprocess.CompletedProcess[str]:
+    """Execute the configured test suite command and return its completed
+    process, failing on any non-zero exit or any unapproved skipped test.
+
+    Skip detection is structural (via a ``pytest-json-report`` machine
+    report) rather than console-text parsing whenever the command invokes
+    pytest, so a differently worded summary line cannot hide a real skip and
+    an explicitly approved skip does not fail the gate. CHANGE-023 relies on
+    the same suite gate to certify the new REQ-AISCI-025 packaging
+    regression alongside the pre-existing REQ-AISCI coverage set.
+    """
+    is_pytest = _is_pytest_invocation(command)
+    report_path: str | None = None
+    full_command = list(command)
+    if is_pytest:
+        fd, report_path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        full_command = [*command, "--json-report", f"--json-report-file={report_path}"]
+
+    try:
+        result = subprocess.run(full_command, check=False, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise TestSuiteGateError("Configured test suite failed.")
+
+        if report_path is not None:
+            unapproved = _unapproved_skips(report_path, approved_skips)
+            if unapproved:
+                raise TestSuiteGateError(
+                    "Configured test suite reported unapproved skipped tests: "
+                    + ", ".join(unapproved)
+                )
+        else:
+            combined_output = "\n".join(part for part in (result.stdout, result.stderr) if part)
+            if _SKIPPED_TEST_RE.search(combined_output):
+                raise TestSuiteGateError("Configured test suite reported skipped tests.")
+        return result
+    finally:
+        if report_path is not None:
+            Path(report_path).unlink(missing_ok=True)