processforge 0.3.16__tar.gz → 0.3.19__tar.gz

{processforge-0.3.16 → processforge-0.3.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: processforge
-Version: 0.3.16
+Version: 0.3.19
 Summary: A Python-based process simulation framework for chemical engineering applications.
 Author-email: Processforge Team <team@processforge.dev>
 License-Expression: BSD-3-Clause
@@ -114,12 +114,18 @@ uv tool install "processforge[modelica]"
 
 4. **Look at the output**
 
-   `pf apply` writes results under `outputs/`:
-   - `*_results.zarr` — simulation results store (per-variable arrays, composition flattened)
-   - `*_results.zarr.schema.json` — schema file describing streams, variables, dtypes, units, shapes, and run provenance
-   - `*.pfstate/` — versioned snapshot store with a `latest` pointer
+    `pf apply` (and `pf run`) write a single unified archive under `outputs/`:
 
-   For flowsheets with Tank units (dynamic), use `pf run` instead of `pf apply` to solve with the SM solver.
+    - `outputs/<base>.pfarchive/` — the unified store for a flowsheet's solved state and outputs:
+      - `snapshots/` — Zarr store of converged state vectors (one group per successful `pf apply`), each with `x`/`x_delta` arrays and config/var-name/metadata attributes, plus a `latest` pointer (powers warm-start, drift detection, and homotopy).
+      - `runs/<run_id>.json` — the run manifest: every stream and unit engine output (values, units, dtypes, shapes) and run provenance (backend, version, flowsheet hash).
+      - `outputs/streams/<name>.json` — per-stream timeseries from the solve.
+      - `artifacts.json` — content-addressed registry of all output artifacts (local + remote URIs).
+      - `index.json` — `field_name → occurrences` index for fast cross-run lookups.
+      - `latest_run` — plain-text pointer to the most recent run.
+    - `outputs/<base>_divergence.json` — written only when both direct and homotopy solves fail on `pf apply`, capturing drifted params, solver stats, and top residual violators.
+
+    For dynamic flowsheets with Tank units, use `pf run` (not `pf apply`, which is steady-state EO only) to solve with the dynamic engine.
 
 ## Python API
 

{processforge-0.3.16 → processforge-0.3.19}/README.md

@@ -52,12 +52,18 @@ uv tool install "processforge[modelica]"
 
 4. **Look at the output**
 
-   `pf apply` writes results under `outputs/`:
-   - `*_results.zarr` — simulation results store (per-variable arrays, composition flattened)
-   - `*_results.zarr.schema.json` — schema file describing streams, variables, dtypes, units, shapes, and run provenance
-   - `*.pfstate/` — versioned snapshot store with a `latest` pointer
-
-   For flowsheets with Tank units (dynamic), use `pf run` instead of `pf apply` to solve with the SM solver.
+    `pf apply` (and `pf run`) write a single unified archive under `outputs/`:
+
+    - `outputs/<base>.pfarchive/` — the unified store for a flowsheet's solved state and outputs:
+      - `snapshots/` — Zarr store of converged state vectors (one group per successful `pf apply`), each with `x`/`x_delta` arrays and config/var-name/metadata attributes, plus a `latest` pointer (powers warm-start, drift detection, and homotopy).
+      - `runs/<run_id>.json` — the run manifest: every stream and unit engine output (values, units, dtypes, shapes) and run provenance (backend, version, flowsheet hash).
+      - `outputs/streams/<name>.json` — per-stream timeseries from the solve.
+      - `artifacts.json` — content-addressed registry of all output artifacts (local + remote URIs).
+      - `index.json` — `field_name → occurrences` index for fast cross-run lookups.
+      - `latest_run` — plain-text pointer to the most recent run.
+    - `outputs/<base>_divergence.json` — written only when both direct and homotopy solves fail on `pf apply`, capturing drifted params, solver stats, and top residual violators.
+
+    For dynamic flowsheets with Tank units, use `pf run` (not `pf apply`, which is steady-state EO only) to solve with the dynamic engine.
 
 ## Python API
 

{processforge-0.3.16 → processforge-0.3.19}/flowsheets/openmc/msre_eigenvalue.json

@@ -7,7 +7,7 @@
   "providers": {
     "openmc": {
       "type": "openmc",
-      "url": "http://localhost:9001",
+      "url": "https://processforge-openmc-production.up.railway.app",
       "output_dir": "openmc/msre_run",
       "cross_sections": "${OPENMC_DATA_ROOT}/cross_sections/cross_sections.xml"
     }
@@ -26,7 +26,7 @@
       "id": 2,
       "density": 9.0,
       "density_units": "g/cm3",
-      "temperature": 400.0,
+      "temperature": 300.0,
       "elements": [
         { "element": "Ni", "percent": 0.72, "percent_type": "wo" },
         { "element": "Mo", "percent": 0.16, "percent_type": "wo" },

{processforge-0.3.16 → processforge-0.3.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "processforge"
-version = "0.3.16"
+version = "0.3.19"
 description = "A Python-based process simulation framework for chemical engineering applications."
 readme = "README.md"
 license = "BSD-3-Clause"

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/__init__.py

@@ -29,7 +29,7 @@ from .units.flash import Flash
 from .units.heater import Heater
 from .eo import EOFlowsheet, EOSolver
 
-__version__ = "0.3.16"
+__version__ = "0.3.19"
 
 __all__ = [
     "Flowsheet",

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/api/serve.py

@@ -99,7 +99,31 @@ def run(body: dict):
         provider.teardown()
 
 
+def _log_startup() -> None:
+    """Report where runs are kept and the S3 upload status at server start."""
+    root = os.environ.get("PROCESSFORGE_OUTPUT_DIR", "outputs")
+    logger.info(
+        f"Provider run outputs (scratch) are kept locally in: {root} "
+        f"(per-provider subdirs: outputs/openmc, outputs/festim)."
+    )
+    if os.environ.get("S3_BUCKET"):
+        bucket = os.environ["S3_BUCKET"]
+        logger.info(f"Remote artifact upload enabled → S3 bucket '{bucket}'.")
+        from processforge.utils.s3_upload import validate_s3
+
+        validate_s3()  # fail fast on misconfigured credentials
+    else:
+        logger.warning(
+            "S3_BUCKET not set — remote upload disabled; runs are ephemeral "
+            "on this container."
+        )
+
+
+_log_startup()
+
+
 if __name__ == "__main__":
     import uvicorn
 
     uvicorn.run(app, host="0.0.0.0", port=DEFAULT_PORT)
+

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/cli/apply.py

@@ -27,6 +27,20 @@ def _persist_run(archive, fs, results, run_info, config, base_name, snapshot_id)
     manifest.snapshot_id = snapshot_id
     stream_results = {k: v for k, v in results.items() if not hasattr(v, "fields")}
     archive.save_run(manifest, stream_results=stream_results)
+
+    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
+    # inside the archive, mirroring `pf run`.
+    try:
+        from ..result import save_results_zarr
+
+        save_results_zarr(
+            results,
+            os.path.join(archive.path, "results.zarr"),
+            run_info,
+        )
+    except Exception as e:
+        logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
+
     logger.info(f"Run saved    : {run_id}")
     return run_id
 

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/cli/run.py

@@ -87,6 +87,8 @@ def run(
         logger.info("=== Dynamic Results ===")
         results = fs.run()
 
+        _check_for_failed_units(fs)
+
         if hasattr(fs, "converged"):
             if fs.converged:
                 logger.info("Dynamic simulation converged.")
@@ -106,6 +108,8 @@ def run(
         logger.info("=== Steady-State EO Results ===")
         results = fs.run()
 
+        _check_for_failed_units(fs)
+
         if hasattr(fs, "converged"):
             if fs.converged:
                 logger.info("Steady-state simulation converged.")
@@ -130,6 +134,21 @@ def run(
     }
     archive.save_run(manifest, stream_results=stream_results)
 
+    # Always persist a Zarr copy of the standardized outputs (fields + artifacts)
+    # inside the archive. Works for every provider (OpenMC, CoolProp, FESTIM,
+    # Cantera) and for both local and remote docker runs — remote artifacts
+    # reference their S3 remote_uris.
+    try:
+        from ..result import save_results_zarr
+
+        save_results_zarr(
+            results,
+            os.path.join(archive.path, "results.zarr"),
+            run_info,
+        )
+    except Exception as e:
+        logger.warning(f"Failed to write results.zarr: {type(e).__name__}: {e}")
+
     logger.info(f"Backend      : {display_backend(config, getattr(fs, 'backend', 'dynamic'))}")
     logger.info(f"Run saved    : {os.path.join(archive_path, 'runs', run_id + '.json')}")
 
@@ -153,3 +172,32 @@ def run(
             logger.info(f"Plots saved: {base_name}_results.png, {base_name}_timeseries.png")
         except Exception as e:
             logger.warning(f"Failed to generate plots: {type(e).__name__}: {e}")
+
+
+def _check_for_failed_units(fs):
+    """Fail loudly if any SolverUnit run returned ``status="failed"``.
+
+    Containerized providers return HTTP 200 with a structured ``EngineOutput``
+    (status="failed") rather than raising, so the failure would otherwise be
+    swallowed and recorded as a successful run. Surface it clearly and exit
+    non-zero.
+    """
+    from ..types import EngineOutput
+
+    failed = {
+        name: out
+        for name, out in getattr(fs, "engine_outputs", {}).items()
+        if isinstance(out, EngineOutput) and out.status == "failed"
+    }
+    if not failed:
+        return
+
+    for name, out in failed.items():
+        err = out.error
+        category = getattr(err, "category", "unknown") if err else "unknown"
+        message = getattr(err, "message", "") if err else ""
+        logger.error(f"Unit '{name}' simulation FAILED [{category}]: {message}")
+        hint = getattr(err, "hint", "") if err else ""
+        if hint:
+            logger.error(f"  hint: {hint}")
+    raise SystemExit(1)

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/persistence/artifact_store.py

@@ -1,7 +1,6 @@
 """Content-addressed artifact storage for simulation outputs.
 
-Replaces the old ``upload_directory_to_s3`` whole-directory dump.  Providers
-declare their output files as :class:`~processforge.types.OutputArtifact`
+Providers declare their output files as :class:`~processforge.types.OutputArtifact`
 records (with ``local_path``); the :class:`ArtifactStore` computes a content
 hash, uploads each to object storage under a deterministic, reproducible key,
 and fills in ``remote_uris``.  The CLI and the container server both use this
@@ -120,13 +119,58 @@ class ArtifactStore:
     # Container-side convenience: persist all artifacts in engine outputs
     # ------------------------------------------------------------------
     def persist_outputs(self, outputs, *, run_id: str = "", flowsheet_hash: str = "", unit: str = ""):
-        """Upload every artifact referenced by *outputs*.
+        """Upload every artifact referenced by *outputs* to object storage.
 
-        Mutates the artifacts in place, filling ``remote_uris``.  ``outputs``
-        may be a single object or an iterable of them.
+        Uploads the explicitly-declared artifacts, then sweeps each output's
+        ``run_dir`` for any remaining files so *all* model outputs (not just the
+        ones a provider happened to declare) reach S3.  Newly swept files are
+        appended to ``out.artifacts`` with ``remote_uris`` filled.  Mutates the
+        artifacts in place.  ``outputs`` may be a single object or an iterable.
         """
+        if not self.bucket:
+            logger.debug(
+                "Remote artifact upload disabled (S3_BUCKET not set); provider "
+                "run outputs remain in the container's local scratch only."
+            )
+            return
+
         items = outputs if isinstance(outputs, (list, tuple)) else [outputs]
+        uploaded = 0
+        local_only = 0
         for out in items:
+            seen_paths: set[str] = set()
             for art in getattr(out, "artifacts", []):
-                if art.local_path and (self.bucket or os.environ.get("S3_BUCKET")):
-                    self.upload(art, run_id=run_id, flowsheet_hash=flowsheet_hash, unit=unit)
+                if not art.local_path:
+                    continue
+                seen_paths.add(os.path.abspath(art.local_path))
+                self.upload(art, run_id=run_id, flowsheet_hash=flowsheet_hash, unit=unit)
+                if art.remote_uris:
+                    uploaded += 1
+                else:
+                    local_only += 1
+
+            run_dir = getattr(out, "run_dir", "") or ""
+            if run_dir and os.path.isdir(run_dir):
+                for root, _dirs, files in os.walk(run_dir):
+                    for name in files:
+                        path = os.path.abspath(os.path.join(root, name))
+                        if path in seen_paths:
+                            continue
+                        seen_paths.add(path)
+                        art = OutputArtifact(
+                            name=name,
+                            kind=_artifact_kind(name),
+                            local_path=path,
+                            source="local",
+                        )
+                        self.upload(art, run_id=run_id, flowsheet_hash=flowsheet_hash, unit=unit)
+                        if art.remote_uris:
+                            out.artifacts.append(art)
+                            uploaded += 1
+                        else:
+                            local_only += 1
+
+        logger.info(
+            f"Artifact persistence: {uploaded} uploaded to S3, {local_only} local-only."
+        )
+

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/providers/container_client.py

@@ -10,14 +10,13 @@ as a thin HTTP wrapper around that server.
 Request/response contract (matches ``processforge.api.serve``)
 ----------------------------------------------------------------
 * ``POST /run`` with a JSON body
-  ``{"unit_config", "materials", "inlet", "output_dir", "provider_config"}``.
+  ``{"unit_config", "materials", "inlet", "provider_config"}``.
 * JSON response ``{"status", "sim_type", <scalars…>, "metadata"}`` deserialised
   into a :class:`~processforge.types.SimulationResult`.
 """
 from __future__ import annotations
 
 import json
-import os
 import urllib.error
 import urllib.request
 from typing import TYPE_CHECKING, Optional
@@ -54,7 +53,6 @@ class ContainerProviderClient(AbstractProvider):
     def __init__(self, provider_type: str):
         self._ptype = provider_type
         self._url: Optional[str] = None
-        self._provider_output_dir: str = "outputs"
         self._provider_config: Optional["ProviderConfig"] = None
         self._materials: dict = {}
         self._initialized: bool = False
@@ -91,6 +89,7 @@ class ContainerProviderClient(AbstractProvider):
             "out": unit_config.out,
             "sim_type": unit_config.sim_type,
             "solver_config": unit_config.solver_config,
+            "geometry_config": unit_config.geometry_config,
             **unit_config.extra,
         }
 
@@ -122,14 +121,6 @@ class ContainerProviderClient(AbstractProvider):
         """Store config, resolve URL, verify the Docker service is reachable."""
         self._url = self._resolve_url(provider_config)
 
-        out_dir = os.path.expandvars(
-            getattr(provider_config, "output_dir", "outputs") or "outputs"
-        )
-        if not os.path.isabs(out_dir):
-            root = os.environ.get("PROCESSFORGE_OUTPUT_DIR", "outputs")
-            out_dir = os.path.join(root, out_dir)
-        self._provider_output_dir = out_dir
-
         # Material registry — serialised into /run and used by validate_material().
         self._materials = dict(flowsheet_config.materials)
         self._provider_config = provider_config
@@ -190,7 +181,6 @@ class ContainerProviderClient(AbstractProvider):
             "unit_config": self._serialize_unit_config(unit_config),
             "materials": self._serialize_materials(self._materials),
             "inlet": inlet,
-            "output_dir": self._provider_output_dir,
             "provider_config": provider_config_dump,
             "run_id": run_id,
             "flowsheet_hash": flowsheet_hash,

processforge-0.3.19/src/processforge/providers/errors.py

@@ -0,0 +1,276 @@
+"""Provider-side run-error classification.
+
+When a simulation is executed *inside* a provider/engine (e.g. OpenMC or FESTIM
+running in a Docker container) the run can fail for reasons that live entirely
+in the engine — missing nuclear-data temperatures, an MPI process abort, a
+geometry that excludes a source point, a tally that references an unknown
+filter, … . These are distinct from *flowsheet/setup* errors (bad JSON, unknown
+material, schema validation), which are caught earlier during initialization or
+flowsheet validation.
+
+This module gives every provider a single, structured way to capture such a
+run-time failure:
+
+* :class:`ProviderRunError` — a typed, engine-agnostic record of what failed,
+  attributed to ``source="provider"`` so Processforge (and the user) can tell a
+  runtime engine error apart from a flowsheet configuration error.
+* :func:`classify_run_error` — turn an exception (plus any captured
+  stdout/stderr from the engine) into a :class:`ProviderRunError`, picking a
+  category and a
+  concrete remediation hint where one is known.
+* :func:`make_failed_output` — build the ``EngineOutput(status="failed")`` that
+  providers return, populated with the classification.
+
+Categories are intentionally broad so a new engine signature can be added here
+without touching the providers.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from pydantic import BaseModel
+
+# Error categories. Strings (not an Enum) so they serialize cleanly in JSON
+# through the provider HTTP API and are easy to match on in tests/docs.
+NUCLEAR_DATA = "nuclear_data"
+CROSS_SECTIONS = "cross_sections"
+MPI_ABORT = "mpi_abort"
+GEOMETRY = "geometry"
+TALLY = "tally"
+CONVERGENCE = "convergence"
+INPUT_VALIDATION = "input_validation"
+ENVIRONMENT = "environment"
+UNKNOWN = "unknown"
+
+# (category, compiled-regex, remediation hint). First match wins.
+# Order matters: more specific (and more actionable) patterns come first.
+_ERROR_SIGNATURES: list[tuple[str, re.Pattern[str], str]] = [
+    (
+        NUCLEAR_DATA,
+        re.compile(
+            r"nuclear data library does not contain cross sections",
+            re.IGNORECASE,
+        ),
+        (
+            "The cross-section library lacks data at the requested "
+            "temperature. "
+            "Either set the material temperature to a value present in the library "
+            "(e.g. 300 K), or enable openmc.Settings.temperature handling "
+            "(temperature_method / multipole interpolation) so intermediate "
+            "temperatures are treated."
+        ),
+    ),
+    (
+        CROSS_SECTIONS,
+        re.compile(
+            r"cross section[s]? (file|library|data|xml)|"
+            r"could not (find|read|open).*cross_section|"
+            r"no cross sections (available|found)|"
+            r"cross_sections\.xml",
+            re.IGNORECASE,
+        ),
+        (
+            "Cross-section data could not be located or parsed. Verify the "
+            "provider 'cross_sections' path points at a valid cross_sections.xml "
+            "and that the data directory is mounted into the container."
+        ),
+    ),
+    (
+        MPI_ABORT,
+        re.compile(r"MPI_ABORT|mpi abort|orted: \w+ rank", re.IGNORECASE),
+        (
+            "The solver process crashed (MPI_ABORT). The root cause is usually the "
+            "preceding engine error (e.g. nuclear-data or geometry failure); fix "
+            "that first. If it occurs with no preceding error, the container may "
+            "be out of memory or MPI may be misconfigured."
+        ),
+    ),
+    (
+        GEOMETRY,
+        re.compile(
+            r"geometry ?error|cannot find cell|no cell found|"
+            r"particle (got )?lost|surface .*? not (found|defined)|"
+            r"universe .*? not (found|defined)|geometry does not contain",
+            re.IGNORECASE,
+        ),
+        (
+            "The problem geometry is invalid or the source/particles fall outside "
+            "it. Check geometry_config dimensions and the source_point location, "
+            "and ensure every referenced material region is filled."
+        ),
+    ),
+    (
+        TALLY,
+        re.compile(r"tally ?error|tally .*? (not|does not) (exist|have)|invalid filter", re.IGNORECASE),
+        (
+            "A tally or its filter is invalid. Check mesh_tallies / tally scores, "
+            "filter IDs, and that referenced cells/meshes exist in the geometry."
+        ),
+    ),
+    (
+        CONVERGENCE,
+        re.compile(
+            r"did not converge|maximum number of (iterations|resampling)|"
+            r"failed to converge|stagnat",
+            re.IGNORECASE,
+        ),
+        (
+            "The solve did not converge. Increase batches/iterations or relax "
+            "tolerances in solver_config; verify the model is well-posed."
+        ),
+    ),
+    (
+        INPUT_VALIDATION,
+        re.compile(
+            r"valueerror|keyerror|typeerror|validation ?error|"
+            r"expected .*? (got|found)|missing .*? argument",
+            re.IGNORECASE,
+        ),
+        (
+            "The engine rejected the resolved configuration. This usually means a "
+            "value in solver_config/geometry_config is out of range or mistyped."
+        ),
+    ),
+    (
+        ENVIRONMENT,
+        re.compile(
+            r"permission denied|no such file or directory|"
+            r"cannot (write|create) .*? directory|"
+            r"shared library|lib[a-z0-9]+\.so",
+            re.IGNORECASE,
+        ),
+        (
+            "An environment/container issue (file permissions, missing library, "
+            "or unwritable output dir). Check the container mounts and that the "
+            "output directory is writable."
+        ),
+    ),
+]
+
+
+class ProviderRunError(BaseModel):
+    """Structured record of a run-time failure that originated in a provider/engine.
+
+    Attributes:
+        category: One of the ``*`` constants above (``nuclear_data``, ``mpi_abort``,
+            …). ``unknown`` when no signature matched.
+        source: Always ``"provider"`` — distinguishes engine run-time failures
+            from flowsheet/setup validation errors.
+        message: A concise, human-readable one-line summary of the failure.
+        type: The Python exception class name (e.g. ``RuntimeError``).
+        detail: The full captured error text (engine stderr/stdout + traceback
+            tail). May be long; this is what gets logged.
+        hint: A concrete remediation suggestion where a category is recognised,
+            else a generic pointer to check the engine log.
+    """
+
+    category: str = UNKNOWN
+    source: str = "provider"
+    message: str = ""
+    type: str = "Exception"
+    detail: str = ""
+    hint: str = (
+        "Inspect the engine log / run directory for the root cause; this is a "
+        "run-time error raised by the provider, not a flowsheet configuration error."
+    )
+
+    @classmethod
+    def from_exception(
+        cls,
+        exc: BaseException,
+        captured: str = "",
+        category: Optional[str] = None,
+    ) -> "ProviderRunError":
+        """Build a :class:`ProviderRunError` from an exception (category overridable)."""
+        text = str(exc)
+        if captured:
+            text = f"{text}\n\n{captured}".strip()
+        # Prefer an explicitly supplied category (e.g. a provider already knows).
+        if category is None:
+            category = _classify_text(text)
+        return cls(
+            category=category,
+            message=_summarize(text) or f"{type(exc).__name__}: {text}",
+            type=type(exc).__name__,
+            detail=text,
+            hint=_hint_for(category),
+        )
+
+
+def classify_run_error(
+    engine: str,
+    exc: BaseException,
+    captured: str = "",
+) -> ProviderRunError:
+    """Classify a provider run-time exception into a :class:`ProviderRunError`.
+
+    Args:
+        engine: Engine name (``"openmc"``, ``"festim"``, …) — recorded for context
+            only (it does not change classification today).
+        exc: The exception raised by the engine run.
+        captured: Optional captured engine stdout/stderr, used to improve the
+            classification when the raised message is terse.
+
+    Returns:
+        A populated :class:`ProviderRunError` (``source="provider"``).
+    """
+    err = ProviderRunError.from_exception(exc, captured=captured)
+    err.message = f"[{engine}] {err.message}"
+    return err
+
+
+def make_failed_output(
+    engine: str,
+    sim_type: str,
+    run_dir,
+    err: ProviderRunError,
+    unit: str = "",
+) -> "EngineOutput":  # type: ignore[name-defined]  # imported lazily to avoid cycle
+    """Build the ``EngineOutput(status="failed")`` providers return on a run error."""
+    from processforge.types import EngineOutput
+
+    return EngineOutput(
+        status="failed",
+        engine=engine,
+        sim_type=sim_type,
+        unit=unit,
+        error=err,
+        run_dir=str(getattr(run_dir, "resolve", lambda: run_dir)()),
+        diagnostics={
+            "run_dir": str(getattr(run_dir, "resolve", lambda: run_dir)()),
+            "error": err.detail,
+            "error_category": err.category,
+            "error_source": err.source,
+        },
+    )
+
+
+def _classify_text(text: str) -> str:
+    for category, pattern, _hint in _ERROR_SIGNATURES:
+        if pattern.search(text):
+            return category
+    return UNKNOWN
+
+
+def _hint_for(category: str) -> str:
+    for cat, _pattern, hint in _ERROR_SIGNATURES:
+        if cat == category:
+            return hint
+    return ProviderRunError().hint
+
+
+def _summarize(text: str, limit: int = 280) -> str:
+    """Return the most diagnostic single line of ``text`` (engine ERROR lines win)."""
+    lines = [ln.strip() for ln in text.splitlines() if ln.strip()]
+    if not lines:
+        return ""
+    for ln in lines:
+        if ln.upper().startswith("ERROR") or "ERROR:" in ln.upper():
+            return ln[:limit]
+    # Fall back to the first line that looks like a message (not a banner/traceback).
+    for ln in lines:
+        if ln.startswith(("Traceback", "File ", "raise ", "Proc:", "NOTE:")):
+            continue
+        return ln[:limit]
+    return lines[0][:limit]

{processforge-0.3.16 → processforge-0.3.19}/src/processforge/providers/festim_provider.py

@@ -67,6 +67,7 @@ from processforge.types import (
     OutputField,
     OutputProvenance,
 )
+from processforge.providers.errors import classify_run_error, make_failed_output
 from processforge.units import Quantity
 
 if TYPE_CHECKING:
@@ -771,15 +772,8 @@ class FestimProvider(AbstractProvider):
             logger.exception(
                 f"FestimProvider: '{sim_type}' failed in '{run_dir}': {exc}"
             )
-            return EngineOutput(
-                status="failed",
-                engine="festim",
-                sim_type=sim_type,
-                diagnostics={
-                    "run_dir": str(run_dir.resolve()),
-                    "error": str(exc),
-                },
-            )
+            err = classify_run_error("festim", exc)
+            return make_failed_output("festim", sim_type, run_dir, err)
         finally:
             os.chdir(prev_cwd)
 
@@ -794,6 +788,7 @@ class FestimProvider(AbstractProvider):
             artifacts=artifacts,
             diagnostics=diagnostics,
             provenance=OutputProvenance(),
+            run_dir=str(run_dir),
         )
 
     def _resolve_run_dir(self) -> pathlib.Path: