Phase 2: Pipeline orchestration layer with stages and tests

Add composable pipeline framework decomposing the monolithic
GenerateParameters() into discrete stages:

- poltype/pipeline/stage.py: Stage ABC, StageResult, StageStatus enum
- poltype/pipeline/context.py: PipelineContext (mutable per-run state)
- poltype/pipeline/runner.py: PipelineRunner orchestrator
- poltype/pipeline/stages/: 6 concrete stage stubs (input_prep,
  geometry_opt, esp, multipole, torsion, finalization)
- __init__.py files for poltype, config, molecule, qm, pipeline packages
- tests/unit/test_pipeline.py: 56 comprehensive unit tests

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: leucinw <30535093+leucinw@users.noreply.github.com>

Author: Copilot

poltype/__init__.py

@@ -0,0 +1,14 @@
+"""
+poltype – typed, modular Poltype2 pipeline.
+
+Top-level re-exports for convenience::
+
+    from poltype import PoltypeConfig, Molecule
+"""
+
+from __future__ import annotations
+
+from poltype.config.schema import PoltypeConfig
+from poltype.molecule.molecule import Molecule
+
+__all__ = ["PoltypeConfig", "Molecule"]

poltype/config/__init__.py

@@ -0,0 +1,15 @@
+"""
+poltype.config – configuration schema and loading utilities.
+
+Re-exports the typed dataclasses and the ``load_config`` helper so
+callers can write::
+
+    from poltype.config import PoltypeConfig, load_config
+"""
+
+from __future__ import annotations
+
+from poltype.config.loader import load_config
+from poltype.config.schema import PoltypeConfig, QMConfig, ResourceConfig
+
+__all__ = ["PoltypeConfig", "QMConfig", "ResourceConfig", "load_config"]

poltype/molecule/__init__.py

@@ -0,0 +1,13 @@
+"""
+poltype.molecule – canonical molecule representation.
+
+Re-exports the :class:`Molecule` wrapper so callers can write::
+
+    from poltype.molecule import Molecule
+"""
+
+from __future__ import annotations
+
+from poltype.molecule.molecule import Molecule
+
+__all__ = ["Molecule"]

poltype/pipeline/__init__.py

@@ -0,0 +1,21 @@
+"""
+poltype.pipeline – composable pipeline orchestration layer.
+
+Re-exports the core framework types so callers can write::
+
+    from poltype.pipeline import Stage, PipelineContext, PipelineRunner
+"""
+
+from __future__ import annotations
+
+from poltype.pipeline.context import PipelineContext
+from poltype.pipeline.runner import PipelineRunner
+from poltype.pipeline.stage import Stage, StageResult, StageStatus
+
+__all__ = [
+    "Stage",
+    "StageResult",
+    "StageStatus",
+    "PipelineContext",
+    "PipelineRunner",
+]

poltype/pipeline/context.py

@@ -0,0 +1,125 @@
+"""
+poltype.pipeline.context – mutable per-run pipeline state.
+
+A :class:`PipelineContext` is created once at the beginning of a
+pipeline run and flows through every stage.  It carries:
+
+* the immutable :class:`PoltypeConfig`,
+* the current :class:`Molecule` (which may be replaced after geometry
+  optimisation),
+* the selected :class:`QMBackend`,
+* an ``artifacts`` dict for inter-stage data exchange, and
+* a ``stage_results`` dict that records the outcome of each stage.
+
+This module has **no dependency on PoltypeModules** and can be
+unit-tested in isolation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from poltype.config.schema import PoltypeConfig
+from poltype.molecule.molecule import Molecule
+from poltype.pipeline.stage import StageResult
+from poltype.qm.backend import QMBackend
+
+
+class PipelineContext:
+    """Mutable per-run state that flows through every pipeline stage.
+
+    Parameters
+    ----------
+    config:
+        Immutable run configuration.
+    molecule:
+        Initial molecule (may be ``None`` if loaded during the
+        input-preparation stage).
+    backend:
+        QM backend to use for calculations (may be ``None`` if
+        selected during the pipeline).
+    work_dir:
+        Working directory for file I/O.  Defaults to the current
+        working directory.
+    """
+
+    def __init__(
+        self,
+        config: PoltypeConfig,
+        molecule: Optional[Molecule] = None,
+        backend: Optional[QMBackend] = None,
+        work_dir: Optional[Path] = None,
+    ) -> None:
+        self._config = config
+        self._molecule = molecule
+        self._backend = backend
+        self._work_dir = Path(work_dir).resolve() if work_dir else Path.cwd()
+        self.artifacts: Dict[str, Any] = {}
+        self.stage_results: Dict[str, StageResult] = {}
+
+    # -- read-only property for config --
+
+    @property
+    def config(self) -> PoltypeConfig:
+        """Immutable run configuration."""
+        return self._config
+
+    # -- molecule (reassignable) --
+
+    @property
+    def molecule(self) -> Optional[Molecule]:
+        """Current molecule (may be replaced after geometry optimisation)."""
+        return self._molecule
+
+    @molecule.setter
+    def molecule(self, value: Optional[Molecule]) -> None:
+        self._molecule = value
+
+    # -- backend (reassignable) --
+
+    @property
+    def backend(self) -> Optional[QMBackend]:
+        """QM backend for the run."""
+        return self._backend
+
+    @backend.setter
+    def backend(self, value: Optional[QMBackend]) -> None:
+        self._backend = value
+
+    # -- work_dir --
+
+    @property
+    def work_dir(self) -> Path:
+        """Working directory for file I/O."""
+        return self._work_dir
+
+    # -- artifact helpers --
+
+    def get_artifact(self, key: str, default: Any = None) -> Any:
+        """Retrieve an artifact by key, returning *default* if absent."""
+        return self.artifacts.get(key, default)
+
+    def set_artifact(self, key: str, value: Any) -> None:
+        """Store an artifact for downstream stages."""
+        self.artifacts[key] = value
+
+    # -- molecule replacement --
+
+    def update_molecule(self, new_mol: Molecule) -> None:
+        """Replace the current molecule (e.g. after geometry optimisation).
+
+        Parameters
+        ----------
+        new_mol:
+            The new molecule to use for subsequent stages.
+        """
+        self._molecule = new_mol
+
+    def __repr__(self) -> str:
+        mol_name = self._molecule.name if self._molecule else "None"
+        return (
+            f"PipelineContext(config=PoltypeConfig, "
+            f"molecule={mol_name!r}, "
+            f"work_dir={str(self._work_dir)!r})"
+        )

poltype/pipeline/runner.py

@@ -0,0 +1,103 @@
+"""
+poltype.pipeline.runner – pipeline orchestrator.
+
+The :class:`PipelineRunner` iterates an ordered list of :class:`Stage`
+objects, executing each in turn against a shared
+:class:`PipelineContext`.  Stages may be skipped (config flags),
+succeed, or fail — a failure halts the pipeline immediately.
+
+This module has **no dependency on PoltypeModules** and can be
+unit-tested in isolation.
+
+Example::
+
+    from poltype.pipeline import PipelineRunner, PipelineContext
+    from poltype.pipeline.stages import InputPreparationStage
+
+    runner = PipelineRunner()
+    runner.add_stage(InputPreparationStage())
+    ctx = runner.run(PipelineContext(config=my_config))
+"""
+
+from __future__ import annotations
+
+import time
+from typing import List, Optional
+
+from poltype.pipeline.context import PipelineContext
+from poltype.pipeline.stage import Stage, StageResult, StageStatus
+
+
+class PipelineRunner:
+    """Executes a sequence of pipeline stages against a shared context.
+
+    Parameters
+    ----------
+    stages:
+        Optional initial list of stages.  More stages can be added
+        later via :meth:`add_stage`.
+    """
+
+    def __init__(self, stages: Optional[List[Stage]] = None) -> None:
+        self._stages: List[Stage] = list(stages) if stages else []
+
+    def add_stage(self, stage: Stage) -> PipelineRunner:
+        """Append a stage to the pipeline.
+
+        Returns ``self`` so calls can be chained::
+
+            runner.add_stage(A()).add_stage(B())
+        """
+        self._stages.append(stage)
+        return self
+
+    def run(self, context: PipelineContext) -> PipelineContext:
+        """Execute all stages in order.
+
+        For each stage the runner:
+
+        1. Checks :meth:`Stage.should_skip` — if ``True``, records a
+           ``SKIPPED`` result and moves on.
+        2. Calls :meth:`Stage.execute` and records the result.
+        3. If the result status is ``FAILED``, stops the pipeline.
+        4. Merges ``result.artifacts`` into ``context.artifacts``.
+
+        Parameters
+        ----------
+        context:
+            Mutable pipeline state shared across stages.
+
+        Returns
+        -------
+        PipelineContext
+            The same context object, enriched with stage results and
+            artifacts.
+        """
+        for stage in self._stages:
+            # -- skip check --
+            if stage.should_skip(context):
+                result = StageResult(
+                    status=StageStatus.SKIPPED,
+                    message=f"Stage '{stage.name}' skipped by should_skip()",
+                )
+                context.stage_results[stage.name] = result
+                continue
+
+            # -- execute --
+            t0 = time.monotonic()
+            result = stage.execute(context)
+            result.elapsed_seconds = time.monotonic() - t0
+
+            context.stage_results[stage.name] = result
+
+            # -- stop on failure --
+            if result.status is StageStatus.FAILED:
+                break
+
+            # -- merge artifacts --
+            context.artifacts.update(result.artifacts)
+
+        return context
+
+    def __repr__(self) -> str:
+        return f"PipelineRunner(stages={len(self._stages)})"