jupytermind 0.3.0

package/src/ai_materials_scientist/phase_field.py

@@ -0,0 +1,167 @@
+"""Phase-field microstructure evolution module (DES-AIMS-010 / REQ-AIMS-010)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ai_materials_scientist.evidence import record_run
+from ai_materials_scientist.validation import (
+    check_finite_array,
+    check_positive_output_interval,
+    check_positive_step_count,
+    register_validator,
+    validate_parameters,
+)
+
+_MODULE_NAME = "phase-field"
+_MODELS = ("allen-cahn", "cahn-hilliard")
+
+
+def _laplacian(c: np.ndarray, dx: float) -> np.ndarray:
+    """Periodic five-point discrete Laplacian L(c) (REQ-AIMS-010)."""
+    return (
+        np.roll(c, -1, axis=0)
+        + np.roll(c, 1, axis=0)
+        + np.roll(c, -1, axis=1)
+        + np.roll(c, 1, axis=1)
+        - 4 * c
+    ) / (dx**2)
+
+
+def _f_prime(c: np.ndarray) -> np.ndarray:
+    """Derivative of f(c) = c^2 * (1-c)^2."""
+    return 2 * c * (1 - c) ** 2 - 2 * (c**2) * (1 - c)
+
+
+# @id CODE-AIMS-010
+# @implements REQ-AIMS-010
+# @design DES-AIMS-010
+def compute_dt_bound(model: str, M: float, kappa: float, dx: float) -> float:
+    """Return the model-specific explicit stability time-step bound."""
+    lambda_max = 8.0 / (dx**2)
+    if model == "allen-cahn":
+        return 2.0 / (M * (2 + kappa * lambda_max))
+    if model == "cahn-hilliard":
+        return 2.0 / (M * lambda_max * (2 + kappa * lambda_max))
+    raise ValueError(f"model must be one of {_MODELS}, got {model!r}")
+
+
+def _phase_field_validator(params: dict) -> dict:
+    """DES-AIMS-002 registered validator for module_name='phase-field'."""
+    model = params["model"]
+    M = params["M"]
+    kappa = params["kappa"]
+    dx = params["dx"]
+    dt = params["dt"]
+
+    if model not in _MODELS:
+        return {"ok": False, "parameter": "model", "constraint": f"model in {_MODELS}"}
+    if M <= 0:
+        return {"ok": False, "parameter": "M", "constraint": "M > 0"}
+    if kappa < 0:
+        return {"ok": False, "parameter": "kappa", "constraint": "kappa >= 0"}
+    if dx <= 0:
+        return {"ok": False, "parameter": "dx", "constraint": "dx > 0"}
+    if dt <= 0:
+        return {"ok": False, "parameter": "dt", "constraint": "dt > 0"}
+
+    finite_check = check_finite_array("field0", params["field0"])
+    if not finite_check["ok"]:
+        return finite_check
+    steps_check = check_positive_step_count(params["steps"])
+    if not steps_check["ok"]:
+        return steps_check
+    interval_check = check_positive_output_interval(params["output_every"])
+    if not interval_check["ok"]:
+        return interval_check
+
+    dt_bound = compute_dt_bound(model, M, kappa, dx)
+    if dt > dt_bound:
+        return {
+            "parameter": "dt",
+            "ok": False,
+            "constraint": f"dt <= dt_bound ({dt_bound}) for model {model!r}",
+        }
+    return {"ok": True}
+
+
+register_validator(_MODULE_NAME, _phase_field_validator)
+
+
+def _validate(field0, model, dx, M, kappa, dt, steps, output_every) -> None:
+    """Route through the shared DES-AIMS-002 registry (REQ-AIMS-003)."""
+    result = validate_parameters(
+        _MODULE_NAME,
+        {
+            "field0": field0,
+            "model": model,
+            "dx": dx,
+            "M": M,
+            "kappa": kappa,
+            "dt": dt,
+            "steps": steps,
+            "output_every": output_every,
+        },
+    )
+    if not result["ok"]:
+        raise ValueError(f"{result['parameter']}: {result['constraint']}")
+
+
+# @id CODE-AIMS-911
+# @implements REQ-AIMS-010 REQ-AIMS-003
+# @design DES-AIMS-010
+def run_phase_field(
+    field0: np.ndarray,
+    model: str,
+    dx: float,
+    M: float,
+    kappa: float,
+    dt: float,
+    steps: int,
+    output_every: int,
+) -> dict:
+    """Integrate the Allen-Cahn or Cahn-Hilliard PDE and report snapshots.
+
+    Rejects any out-of-domain parameter (REQ-AIMS-003) before performing any
+    integration step or mutating ``field0``.
+    """
+    _validate(field0, model, dx, M, kappa, dt, steps, output_every)
+
+    c = field0.astype(np.float64).copy()
+    snapshots = [c.copy()]
+    times = [0.0]
+
+    for step in range(1, steps + 1):
+        mu = _f_prime(c) - kappa * _laplacian(c, dx)
+        if model == "allen-cahn":
+            c = c - dt * M * mu
+        else:  # cahn-hilliard
+            c = c + dt * M * _laplacian(mu, dx)
+        if step % output_every == 0:
+            snapshots.append(c.copy())
+            times.append(step * dt)
+
+    dt_bound = compute_dt_bound(model, M, kappa, dx)
+    return {
+        "snapshots": snapshots,
+        "times": times,
+        "dt_bound": dt_bound,
+    }
+
+
+# @id CODE-AIMS-912
+# @implements REQ-AIMS-010 REQ-AIMS-004 REQ-AIMS-005
+# @design DES-AIMS-010
+def run_phase_field_with_evidence(**kwargs) -> dict:
+    """Run phase-field and wrap the result as a reproducible RunRecord."""
+    result = run_phase_field(**kwargs)
+    return record_run(
+        module_name="phase-field",
+        unit_system="dimensionless-order-parameter",
+        params={k: v for k, v in kwargs.items() if k != "field0"},
+        arrays={
+            "snapshots": np.stack(result["snapshots"]),
+            "times": np.array(result["times"], dtype=np.float64),
+        },
+        seed=None,
+    )

package/src/ai_materials_scientist/validation.py

@@ -0,0 +1,70 @@
+"""Shared parameter & stability validator (DES-AIMS-002 / REQ-AIMS-003)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+ValidationResult = dict
+ValidatorFn = Callable[[dict[str, Any]], ValidationResult]
+
+_REGISTRY: dict[str, ValidatorFn] = {}
+
+
+def _ok() -> ValidationResult:
+    return {"ok": True}
+
+
+def _fail(parameter: str, constraint: str) -> ValidationResult:
+    return {"ok": False, "parameter": parameter, "constraint": constraint}
+
+
+# @id CODE-AIMS-002
+# @implements REQ-AIMS-003
+# @design DES-AIMS-002
+def check_finite_array(parameter: str, array: np.ndarray) -> ValidationResult:
+    """Reject a numeric array containing any non-finite (NaN/Inf) value."""
+    if not np.all(np.isfinite(array)):
+        return _fail(parameter, "all elements must be finite (no NaN/Inf)")
+    return _ok()
+
+
+# @id CODE-AIMS-913
+# @implements REQ-AIMS-003
+# @design DES-AIMS-002
+def check_positive_step_count(steps: int) -> ValidationResult:
+    """Reject a step count that is not a positive integer."""
+    if steps <= 0:
+        return _fail("steps", "steps > 0")
+    return _ok()
+
+
+# @id CODE-AIMS-914
+# @implements REQ-AIMS-003
+# @design DES-AIMS-002
+def check_positive_output_interval(output_every: int) -> ValidationResult:
+    """Reject an output interval that is not a positive integer."""
+    if output_every <= 0:
+        return _fail("output_every", "output_every > 0")
+    return _ok()
+
+
+# @id CODE-AIMS-915
+# @implements REQ-AIMS-003
+# @design DES-AIMS-002
+def register_validator(module_name: str, validator: ValidatorFn) -> None:
+    """Register ``module_name``'s own documented-domain validator function."""
+    _REGISTRY[module_name] = validator
+
+
+# @id CODE-AIMS-916
+# @implements REQ-AIMS-003
+# @design DES-AIMS-002
+def validate_parameters(module_name: str, params: dict[str, Any]) -> ValidationResult:
+    """Dispatch to ``module_name``'s registered validator before any simulation step."""
+    validator = _REGISTRY.get(module_name)
+    if validator is None:
+        return _fail("module", f"no validator registered for module '{module_name}'")
+    return validator(params)

package/src/ai_scientist/__init__.py

@@ -0,0 +1 @@
+"""AI Scientist research workflow package."""

package/src/ai_scientist/completion_gate.py

@@ -0,0 +1,15 @@
+"""Evidence-based completion validation."""
+
+from ai_scientist.evidence_registry import query_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+# @id CODE-AISCI-021
+# @implements REQ-AISCI-020
+# @design DES-AISCI-017
+def validate_completion_evidence(handle: ResearchProjectHandle, phase: str) -> bool:
+    """Require at least one correctly attributed evidence record for ``phase``."""
+    return any(
+        record.project == handle.name and record.phase == phase and bool(record.created_at)
+        for record in query_evidence(handle, phase)
+    )

package/src/ai_scientist/data_analysis.py

@@ -0,0 +1,46 @@
+"""Data-analysis delegation to ai-data-scientist."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import ai_data_scientist.project_manager as aids_project_manager
+from ai_data_scientist.mcp_gateway import run_and_record
+
+from ai_scientist.evidence_registry import record_evidence
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# @id CODE-AISCI-009
+# @implements REQ-AISCI-008
+# @design DES-AISCI-005
+def delegate_data_analysis(
+    handle: ResearchProjectHandle,
+    instruction: str,
+    mcp_client=None,
+) -> dict:
+    """Delegate notebook setup and optional execution to ai-data-scientist."""
+    if mcp_client is None:
+        raise ValueError("Data-analysis requires an MCP client for ai-data-scientist execution.")
+    aids_handle = aids_project_manager.resolve_project(handle.name)
+    if aids_handle.root != handle.root or aids_handle.notebook_path != handle.notebook_path:
+        raise ValueError("ai-data-scientist handle diverged from ai-scientist project handle.")
+    notebook_path = aids_project_manager.ensure_notebook(aids_handle)
+    execution = run_and_record(mcp_client, aids_handle, instruction)
+    record_evidence(
+        handle,
+        "data-analysis",
+        notebook_path,
+        "notebook",
+        _now(),
+        metadata={"executionRoutedVia": "ai_data_scientist.mcp_gateway"},
+    )
+    return {
+        "phase": "data-analysis",
+        "notebook_path": str(notebook_path),
+        "execution": execution,
+    }

package/src/ai_scientist/evidence_registry.py

@@ -0,0 +1,99 @@
+"""Durable evidence registry for ai_scientist phases."""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from ai_scientist.project_handle import ResearchProjectHandle
+
+DEFAULT_EVIDENCE_PATH = ".ai_scientist_evidence.json"
+_REGISTRY_LOCKS: dict[Path, threading.Lock] = {}
+_REGISTRY_LOCKS_GUARD = threading.Lock()
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+    """Recorded project evidence with phase attribution."""
+
+    project: str
+    phase: str
+    artifact_path: str
+    artifact_kind: str
+    created_at: str
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+def _registry_path(handle: ResearchProjectHandle) -> Path:
+    return handle.root / DEFAULT_EVIDENCE_PATH
+
+
+def _lock_for(path: Path) -> threading.Lock:
+    with _REGISTRY_LOCKS_GUARD:
+        lock = _REGISTRY_LOCKS.get(path)
+        if lock is None:
+            lock = threading.Lock()
+            _REGISTRY_LOCKS[path] = lock
+        return lock
+
+
+def _read_records(handle: ResearchProjectHandle) -> list[EvidenceRecord]:
+    path = _registry_path(handle)
+    if not path.exists():
+        return []
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return [EvidenceRecord(**item) for item in payload]
+
+
+def _write_records(handle: ResearchProjectHandle, records: list[EvidenceRecord]) -> None:
+    path = _registry_path(handle)
+    temp_path = path.with_suffix(".tmp")
+    temp_path.write_text(
+        json.dumps([asdict(record) for record in records], indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    temp_path.replace(path)
+
+
+# @id CODE-AISCI-020
+# @implements REQ-AISCI-020
+# @design DES-AISCI-016
+def record_evidence(
+    handle: ResearchProjectHandle,
+    phase: str,
+    artifact_path: Path | str,
+    artifact_kind: str,
+    timestamp: str,
+    metadata: dict[str, str] | None = None,
+) -> EvidenceRecord:
+    """Append one evidence record atomically."""
+    path = _registry_path(handle)
+    with _lock_for(path):
+        records = _read_records(handle)
+        record = EvidenceRecord(
+            project=handle.name,
+            phase=phase,
+            artifact_path=str(Path(artifact_path)),
+            artifact_kind=artifact_kind,
+            created_at=timestamp,
+            metadata=metadata or {},
+        )
+        records.append(record)
+        _write_records(handle, records)
+        return record
+
+
+def query_evidence(handle: ResearchProjectHandle, phase: str | None = None) -> list[EvidenceRecord]:
+    """Return all evidence, optionally filtered to one phase."""
+    records = _read_records(handle)
+    if phase is None:
+        return records
+    return [record for record in records if record.phase == phase]
+
+
+def latest_evidence(handle: ResearchProjectHandle, phase: str) -> EvidenceRecord | None:
+    """Return the most recently recorded evidence for ``phase``."""
+    records = query_evidence(handle, phase)
+    return records[-1] if records else None

package/src/ai_scientist/experimental_design.py

@@ -0,0 +1,20 @@
+"""Experimental design 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_experimental_design(handle: ResearchProjectHandle, instruction: str) -> dict:
+    """Create an experimental design artifact and record it."""
+    artifact = handle.design_dir / "experimental-design.md"
+    artifact.write_text(instruction, encoding="utf-8")
+    record_evidence(handle, "experimental-design", artifact, "markdown", _now())
+    return {"phase": "experimental-design", "artifact_path": str(artifact)}

package/src/ai_scientist/language.py

@@ -0,0 +1,14 @@
+"""Language detection for ai_scientist responses and metadata."""
+
+from ai_data_scientist.language_router import detect_language as _detect_language
+
+
+# @id CODE-AISCI-001
+# @implements REQ-AISCI-001
+# @design DES-AISCI-001
+# @id CODE-AISCI-010
+# @implements REQ-AISCI-010
+# @design DES-AISCI-007
+def detect_language(text: str) -> str:
+    """Reuse ai-data-scientist's deterministic language detector."""
+    return _detect_language(text)

package/src/ai_scientist/latex_renderer.py

@@ -0,0 +1,41 @@
+"""LaTeX rendering for tech-writer Markdown output."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _escape_latex(text: str) -> str:
+    replacements = {
+        "\\": r"\textbackslash{}",
+        "&": r"\&",
+        "%": r"\%",
+        "$": r"\$",
+        "#": r"\#",
+        "_": r"\_",
+        "{": r"\{",
+        "}": r"\}",
+        "~": r"\textasciitilde{}",
+        "^": r"\textasciicircum{}",
+    }
+    return "".join(replacements.get(character, character) for character in text)
+
+
+# @id CODE-AISCI-022
+# @implements REQ-AISCI-022
+# @design DES-AISCI-018
+def render_latex(markdown_path: Path) -> str:
+    """Render a small LaTeX document while preserving section order/content."""
+    body_lines: list[str] = []
+    for raw_line in markdown_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line:
+            body_lines.append("")
+        elif line.startswith("# "):
+            body_lines.append(f"\\section{{{_escape_latex(line[2:])}}}")
+        elif line.startswith("## "):
+            body_lines.append(f"\\subsection{{{_escape_latex(line[3:])}}}")
+        else:
+            body_lines.append(_escape_latex(line))
+    content = "\n".join(body_lines).strip()
+    return f"\\documentclass{{article}}\n\\begin{{document}}\n{content}\n\\end{{document}}\n"

package/src/ai_scientist/literature_review.py

@@ -0,0 +1,37 @@
+"""Literature review phase handler."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ai_scientist.evidence_registry import record_evidence
+from ai_scientist.mcp_gateway import McpGateway
+from ai_scientist.project_handle import ResearchProjectHandle
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def handle_literature_review(
+    handle: ResearchProjectHandle,
+    instruction: str,
+    gateway: McpGateway | None = None,
+    server_name: str | None = None,
+    tool_name: str = "literature-search",
+    tool_args: dict | None = None,
+) -> dict:
+    """Write a literature artifact, routing external lookups only through MCP."""
+    artifact = handle.literature_dir / "literature-review.md"
+    content = instruction
+    if gateway is not None and server_name is not None:
+        tool_result = gateway.call_tool(
+            server_name,
+            tool_name,
+            tool_args or {"query": instruction},
+            phase="literature-review",
+        )
+        content = str(tool_result.get("content", ""))
+    artifact.write_text(content, encoding="utf-8")
+    record_evidence(handle, "literature-review", artifact, "markdown", _now())
+    return {"phase": "literature-review", "artifact_path": str(artifact)}

package/src/ai_scientist/manifest.py

@@ -0,0 +1,87 @@
+"""Phase manifest loading and repo-local skill registry verification."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_SKILL_DIR = REPO_ROOT / ".github" / "skills" / "ai-scientist"
+DEFAULT_MANIFEST_PATH = DEFAULT_SKILL_DIR / "manifest.json"
+VENDORED_PATH = REPO_ROOT / ".github" / "skills" / "VENDORED.md"
+
+
+class ManifestVerificationError(ValueError):
+    """Manifest verification failed."""
+
+
+def _import_handler(module_path: str, function_name: str) -> None:
+    module = importlib.import_module(module_path)
+    handler = getattr(module, function_name)
+    if not callable(handler):
+        raise ManifestVerificationError(f"{module_path}.{function_name} is not callable")
+
+
+def _validate_skill_dependencies(phase: str, payload):
+    if phase == "peer-review":
+        if not isinstance(payload, dict) or set(payload) != {"ja", "en"}:
+            raise ManifestVerificationError("peer-review skillDependencies must contain ja and en")
+        return
+    if not isinstance(payload, list):
+        raise ManifestVerificationError(f"{phase}: skillDependencies must be a list")
+
+
+def _load_vendored_versions() -> dict[str, str]:
+    text = VENDORED_PATH.read_text(encoding="utf-8")
+    versions: dict[str, str] = {}
+    for skill_id, version in re.findall(r"\| `([^`]+)` \| [^|]+ \| `([^`]+)` \|", text):
+        versions[skill_id] = version.removeprefix("v")
+    return versions
+
+
+def scan_repo_skill_registry() -> dict[str, str | None]:
+    """Scan repo-local vendored skills as the verifiable startup registry."""
+    versions = _load_vendored_versions()
+    registry: dict[str, str | None] = {}
+    skills_dir = REPO_ROOT / ".github" / "skills"
+    for skill_path in skills_dir.glob("*/SKILL.md"):
+        lines = skill_path.read_text(encoding="utf-8").splitlines()
+        name_line = next((line for line in lines if line.startswith("name: ")), None)
+        if name_line is not None:
+            skill_id = name_line.split(":", 1)[1].strip()
+            registry[skill_id] = versions.get(skill_id)
+    return registry
+
+
+# @id CODE-AISCI-023
+# @implements REQ-AISCI-023
+# @design DES-AISCI-015
+def load_phase_manifest(path: Path | str = DEFAULT_MANIFEST_PATH) -> dict:
+    """Load the machine-readable ai_scientist phase manifest."""
+    manifest = json.loads(Path(path).read_text(encoding="utf-8"))
+    for phase, entry in manifest.items():
+        module_path = entry.get("modulePath")
+        function_name = entry.get("functionName")
+        if not module_path or not function_name:
+            raise ManifestVerificationError(f"{phase}: missing modulePath or functionName")
+        _validate_skill_dependencies(phase, entry.get("skillDependencies", []))
+        _import_handler(module_path, function_name)
+    return manifest
+
+
+def verify_manifest_against_registry(manifest: dict, registry: dict[str, str | None]) -> None:
+    """Verify every declared dependency exists in the startup registry scan."""
+    for phase, entry in manifest.items():
+        dependencies = entry.get("skillDependencies", [])
+        phase_dependencies = (
+            dependencies.values() if isinstance(dependencies, dict) else dependencies
+        )
+        for dependency in phase_dependencies:
+            skill_id = dependency["skillId"]
+            version = dependency["version"]
+            if registry.get(skill_id) != version:
+                raise ManifestVerificationError(
+                    f"{phase}: missing registry entry for {skill_id}@{version}"
+                )