Upload 22 files

pcswmm_ai/__init__.py

@@ -0,0 +1,28 @@
+"""PCSWMM AI SDK.
+
+The PCSWMM application injects ``pcpy`` into its Script Editor and
+JupyterLab runtimes. This package therefore uses dependency injection:
+
+    from pcswmm_ai import PCSWMMClient
+    client = PCSWMMClient(pcpy)
+
+The package never imports ``pcpy`` directly.
+"""
+
+from .client import PCSWMMClient
+from .exceptions import (
+    PCSWMMError,
+    ProjectNotOpenError,
+    LayerNotFoundError,
+    ResultsNotAvailableError,
+)
+
+__all__ = [
+    "PCSWMMClient",
+    "PCSWMMError",
+    "ProjectNotOpenError",
+    "LayerNotFoundError",
+    "ResultsNotAvailableError",
+]
+
+__version__ = "0.4.0"

pcswmm_ai/capabilities.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ModelCapabilityService:
+    """Detect model features without assuming a specific project type."""
+
+    def __init__(self, collections):
+        self._collections = collections
+
+    def counts(self) -> dict[str, int]:
+        summary = self._collections.summary()
+        return {
+            row["collection"]: int(row["count"] or 0)
+            for row in summary
+        }
+
+    def detect(self) -> dict[str, Any]:
+        counts = self.counts()
+
+        has_storage = counts.get("Storages", 0) > 0
+        has_outlet_structures = any(
+            counts.get(name, 0) > 0
+            for name in ("Orifices", "Weirs", "Outlets", "Pumps")
+        )
+        has_conveyance = any(
+            counts.get(name, 0) > 0
+            for name in ("Conduits", "Pumps", "Orifices", "Weirs", "Outlets")
+        )
+        has_subcatchments = counts.get("Subcatchments", 0) > 0
+        has_quality = counts.get("Pollutants", 0) > 0
+        has_lid = counts.get("LIDControls", 0) > 0
+        has_snow = counts.get("SnowPacks", 0) > 0
+        has_groundwater = counts.get("Aquifers", 0) > 0
+        has_controls = counts.get("Controls", 0) > 0
+
+        if has_storage and has_outlet_structures and counts.get("Nodes", 0) <= 5:
+            model_archetype = "detention_or_storage_model"
+        elif has_storage and has_conveyance:
+            model_archetype = "collection_system_with_storage"
+        elif has_conveyance and has_subcatchments:
+            model_archetype = "urban_drainage_network"
+        elif has_subcatchments and not has_conveyance:
+            model_archetype = "runoff_only_model"
+        else:
+            model_archetype = "general_swmm_model"
+
+        return {
+            "model_archetype": model_archetype,
+            "has_subcatchments": has_subcatchments,
+            "has_conveyance": has_conveyance,
+            "has_storage": has_storage,
+            "has_outlet_structures": has_outlet_structures,
+            "has_water_quality": has_quality,
+            "has_lid": has_lid,
+            "has_snowmelt": has_snow,
+            "has_groundwater": has_groundwater,
+            "has_controls": has_controls,
+            "counts": counts,
+        }
+
+    def applicable_review_modules(self) -> list[str]:
+        capability = self.detect()
+        modules = ["project", "inventory", "topology", "scenario_paths"]
+
+        if capability["has_subcatchments"]:
+            modules.append("hydrology")
+        if capability["has_conveyance"]:
+            modules.append("hydraulics")
+        if capability["has_storage"]:
+            modules.append("storage")
+        if capability["has_outlet_structures"]:
+            modules.append("outlet_structures")
+        if capability["has_water_quality"]:
+            modules.append("water_quality")
+        if capability["has_lid"]:
+            modules.append("lid")
+        if capability["has_groundwater"]:
+            modules.append("groundwater")
+        if capability["has_snowmelt"]:
+            modules.append("snowmelt")
+        if capability["has_controls"]:
+            modules.append("controls")
+
+        return modules

pcswmm_ai/client.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .capabilities import ModelCapabilityService
+from .collections import CollectionService
+from .engineering import EngineeringReviewService
+from .hydraulics import HydraulicResultReviewService
+from .hydrology import HydrologyReviewService
+from .layers import LayerService
+from .objects import ObjectService
+from .pond import PondReviewService
+from .project import ProjectService
+from .qaqc import QAQCService
+from .result_queries import ResultQueryService
+from .results import ResultService
+from .review_engine import GenericReviewEngine
+from .scenarios import ScenarioReviewService
+from .simulation import SimulationService
+from .storage import StorageReviewService
+from .topology import TopologyService
+
+
+class PCSWMMClient:
+    """Generic facade over PCSWMM's injected ``pcpy`` object."""
+
+    def __init__(self, pcpy: Any):
+        if pcpy is None:
+            raise ValueError("The injected PCSWMM pcpy object is required.")
+
+        self.pcpy = pcpy
+        self.project = ProjectService(pcpy)
+        self.collections = CollectionService(pcpy, self.project)
+        self.layers = LayerService(pcpy, self.project)
+        self.objects = ObjectService(self.collections)
+        self.simulation = SimulationService(pcpy, self.project)
+        self.results = ResultService(pcpy, self.project)
+        self.result_queries = ResultQueryService(self.results)
+        self.qaqc = QAQCService(self.layers)
+        self.topology = TopologyService(self.objects)
+        self.engineering = EngineeringReviewService(
+            self.layers,
+            self.objects,
+            self.topology,
+        )
+        self.hydrology = HydrologyReviewService(
+            self.layers,
+            self.objects,
+        )
+        self.storage = StorageReviewService(self.objects)
+        self.pond = PondReviewService(self.objects)
+        self.scenarios = ScenarioReviewService(self.collections)
+        self.hydraulics = HydraulicResultReviewService(
+            self.collections,
+            self.result_queries,
+        )
+        self.capabilities = ModelCapabilityService(self.collections)
+        self.review_engine = GenericReviewEngine(
+            self.project,
+            self.collections,
+            self.capabilities,
+            self.topology,
+            self.engineering,
+            self.hydrology,
+            self.storage,
+            self.scenarios,
+        )
+
+        # Backward-compatible alias.
+        self.review_report = self.review_engine
+
+    def health(self) -> dict[str, Any]:
+        return {
+            "pcpy_type": str(type(self.pcpy)),
+            "project_open": self.project.is_open,
+            "project": self.project.summary() if self.project.is_open else None,
+            "capabilities": (
+                self.capabilities.detect()
+                if self.project.is_open
+                else None
+            ),
+        }

pcswmm_ai/collections.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .project import ProjectService
+from .utils import dictionary_items, safe_count, public_names
+
+
+class CollectionService:
+    def __init__(self, pcpy: Any, project: ProjectService):
+        self._pcpy = pcpy
+        self._project = project
+
+    def get(self, name: str):
+        self._project.require_open()
+        swmm = self._project.swmm
+
+        if not hasattr(swmm, name):
+            raise KeyError(f"SWMM collection not found: {name}")
+
+        return getattr(swmm, name)
+
+    def names(self) -> list[str]:
+        candidates = [
+            "Scenarios", "Nodes", "Links", "Subcatchments", "Junctions",
+            "Outfalls", "Dividers", "Storages", "Conduits", "Pumps",
+            "Orifices", "Weirs", "Outlets", "Raingages", "Curves",
+            "TimeSeries", "Controls", "Patterns", "Pollutants",
+        ]
+
+        available = []
+        for name in candidates:
+            try:
+                self.get(name)
+                available.append(name)
+            except Exception:
+                pass
+        return available
+
+    def summary(self) -> list[dict[str, Any]]:
+        rows = []
+        for name in self.names():
+            collection = self.get(name)
+            rows.append({
+                "collection": name,
+                "count": safe_count(collection),
+                "type": str(type(collection)),
+            })
+        return rows
+
+    def keys(self, name: str) -> list[str]:
+        collection = self.get(name)
+
+        try:
+            return [str(key) for key in list(collection.Keys)]
+        except Exception:
+            return [str(key) for key, _ in dictionary_items(collection)]
+
+    def items(self, name: str) -> list[tuple[str, Any]]:
+        return [(str(key), value) for key, value in dictionary_items(self.get(name))]
+
+    def inspect_object(self, collection_name: str, object_name: str) -> dict[str, Any]:
+        collection = self.get(collection_name)
+
+        try:
+            obj = collection[object_name]
+        except Exception as exc:
+            raise KeyError(
+                f"{object_name!r} was not found in {collection_name}."
+            ) from exc
+
+        values = {}
+        for name in public_names(obj):
+            try:
+                value = getattr(obj, name)
+                if callable(value):
+                    continue
+                values[name] = value
+            except Exception:
+                pass
+
+        return {
+            "collection": collection_name,
+            "name": object_name,
+            "type": str(type(obj)),
+            "values": values,
+            "public_members": public_names(obj),
+        }

pcswmm_ai/engineering.py

@@ -0,0 +1,37 @@
+class EngineeringReviewService:
+    def __init__(self,layers,objects,topology): self.layers,self.objects,self.topology=layers,objects,topology
+    @staticmethod
+    def num(r,names):
+        for n in names:
+            try:
+                if r.get(n) not in (None,""): return float(r[n])
+            except Exception: pass
+        return None
+    def conduit_screening(self):
+        out=[]
+        for r in self.objects.collection_records("Conduits"):
+            L=self.num(r,("Length","Len")); D=self.num(r,("Geom1","Diameter","Height")); S=self.num(r,("Slope","PipeSlope"))
+            issues=[]
+            if L is not None and L<=0: issues.append("non-positive length")
+            if D is not None and D<=0: issues.append("non-positive diameter/height")
+            if S is not None and S<0: issues.append("negative slope")
+            if issues: out.append({"Name":r.get("Name"),"issues":issues,"Length":L,"DiameterOrHeight":D,"Slope":S})
+        return out
+    def subcatchment_screening(self):
+        try: rows=self.layers.records("Subcatchments")
+        except Exception: rows=self.objects.collection_records("Subcatchments")
+        out=[]
+        for r in rows:
+            A=self.num(r,("Area","TotalArea")); I=self.num(r,("PctImperv","PercentImpervious","%Imperv")); W=self.num(r,("Width",)); S=self.num(r,("Slope","%Slope")); O=r.get("Outlet")
+            issues=[]
+            if A is not None and A<=0: issues.append("non-positive area")
+            if I is not None and not 0<=I<=100: issues.append("imperviousness outside 0–100%")
+            if W is not None and W<=0: issues.append("non-positive width")
+            if S is not None and S<0: issues.append("negative slope")
+            if O in (None,""): issues.append("missing outlet")
+            if issues: out.append({"Name":r.get("Name"),"Outlet":O,"Area":A,"PctImperv":I,"Width":W,"Slope":S,"issues":issues})
+        return out
+    def model_screening_summary(self):
+        return {"orphan_link_count":len(self.topology.orphan_links()),"isolated_node_count":len(self.topology.isolated_nodes()),
+                "duplicate_link_pair_count":len(self.topology.duplicate_link_pairs()),"conduit_finding_count":len(self.conduit_screening()),
+                "subcatchment_finding_count":len(self.subcatchment_screening())}

pcswmm_ai/exceptions.py

@@ -0,0 +1,14 @@
+class PCSWMMError(RuntimeError):
+    """Base exception for the SDK."""
+
+
+class ProjectNotOpenError(PCSWMMError):
+    """Raised when a PCSWMM project is required but is not open."""
+
+
+class LayerNotFoundError(PCSWMMError):
+    """Raised when a requested PCSWMM map layer is unavailable."""
+
+
+class ResultsNotAvailableError(PCSWMMError):
+    """Raised when simulation output or graph files are unavailable."""

pcswmm_ai/hydraulics.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .collections import CollectionService
+from .result_queries import ResultQueryService
+
+
+class HydraulicResultReviewService:
+    """Batch time-series summaries for common SWMM hydraulic outputs."""
+
+    def __init__(
+        self,
+        collections: CollectionService,
+        result_queries: ResultQueryService,
+    ):
+        self._collections = collections
+        self._result_queries = result_queries
+
+    def peak_link_results(
+        self,
+        variable: str,
+        units: str,
+        object_names: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        names = object_names or self._collections.keys("Links")
+        return self._result_queries.peak_for_objects(
+            "Links", variable, units, names
+        )
+
+    def peak_node_results(
+        self,
+        variable: str,
+        units: str,
+        object_names: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        names = object_names or self._collections.keys("Nodes")
+        return self._result_queries.peak_for_objects(
+            "Nodes", variable, units, names
+        )
+
+    def peak_subcatchment_results(
+        self,
+        variable: str,
+        units: str,
+        object_names: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        names = object_names or self._collections.keys("Subcatchments")
+        return self._result_queries.peak_for_objects(
+            "Subcatchments", variable, units, names
+        )

pcswmm_ai/hydrology.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .layers import LayerService
+from .objects import ObjectService
+
+
+class HydrologyReviewService:
+    """Deterministic screening of subcatchment hydrologic parameters."""
+
+    def __init__(self, layers: LayerService, objects: ObjectService):
+        self._layers = layers
+        self._objects = objects
+
+    @staticmethod
+    def _number(record: dict[str, Any], names: tuple[str, ...]):
+        for name in names:
+            value = record.get(name)
+            if value in (None, ""):
+                continue
+            try:
+                return float(value)
+            except Exception:
+                continue
+        return None
+
+    def records(self) -> list[dict[str, Any]]:
+        try:
+            return self._layers.records("Subcatchments")
+        except Exception:
+            return self._objects.collection_records("Subcatchments")
+
+    def review(
+        self,
+        width_ratio_min: float = 0.1,
+        width_ratio_max: float = 20.0,
+    ) -> list[dict[str, Any]]:
+        """Screen common SWMM subcatchment inputs.
+
+        Width-ratio limits are screening values only and are intentionally
+        configurable. They are not municipal criteria.
+        """
+        findings = []
+
+        for row in self.records():
+            name = row.get("Name")
+            area = self._number(row, ("Area", "TotalArea"))
+            width = self._number(row, ("Width",))
+            slope = self._number(row, ("Slope", "%Slope"))
+            pct_imp = self._number(
+                row,
+                ("PctImperv", "PercentImpervious", "%Imperv", "Imperv"),
+            )
+            curve_number = self._number(row, ("CurveNumber", "CN"))
+            n_imp = self._number(row, ("ImpervN", "NImperv"))
+            n_perv = self._number(row, ("PervN", "NPerv"))
+            outlet = row.get("Outlet")
+
+            issues = []
+
+            if area is not None and area <= 0:
+                issues.append("non-positive area")
+            if width is not None and width <= 0:
+                issues.append("non-positive width")
+            if slope is not None and slope < 0:
+                issues.append("negative slope")
+            if pct_imp is not None and not 0 <= pct_imp <= 100:
+                issues.append("imperviousness outside 0–100%")
+            if curve_number is not None and not 0 <= curve_number <= 100:
+                issues.append("curve number outside 0–100")
+            if n_imp is not None and n_imp <= 0:
+                issues.append("non-positive impervious Manning n")
+            if n_perv is not None and n_perv <= 0:
+                issues.append("non-positive pervious Manning n")
+            if outlet in (None, ""):
+                issues.append("missing outlet")
+
+            width_area_ratio = None
+            if area and width is not None:
+                width_area_ratio = width / area
+                if not width_ratio_min <= width_area_ratio <= width_ratio_max:
+                    issues.append("width-to-area ratio outside screening range")
+
+            if issues:
+                findings.append({
+                    "Name": name,
+                    "Area": area,
+                    "Width": width,
+                    "WidthAreaRatio": width_area_ratio,
+                    "Slope": slope,
+                    "PctImperv": pct_imp,
+                    "CurveNumber": curve_number,
+                    "Outlet": outlet,
+                    "issues": issues,
+                })
+
+        return findings
+
+    def summary(self) -> dict[str, Any]:
+        rows = self.records()
+        findings = self.review()
+
+        total_area = 0.0
+        weighted_impervious_area = 0.0
+        impervious_available = False
+
+        for row in rows:
+            area = self._number(row, ("Area", "TotalArea"))
+            pct_imp = self._number(
+                row,
+                ("PctImperv", "PercentImpervious", "%Imperv", "Imperv"),
+            )
+            if area is not None:
+                total_area += area
+            if area is not None and pct_imp is not None:
+                weighted_impervious_area += area * pct_imp / 100.0
+                impervious_available = True
+
+        weighted_pct_imp = None
+        if total_area > 0 and impervious_available:
+            weighted_pct_imp = 100.0 * weighted_impervious_area / total_area
+
+        return {
+            "subcatchment_count": len(rows),
+            "total_area_model_units": total_area,
+            "weighted_percent_impervious": weighted_pct_imp,
+            "finding_count": len(findings),
+        }

pcswmm_ai/layers.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .exceptions import LayerNotFoundError
+from .project import ProjectService
+
+
+DEFAULT_LAYER_NAMES = [
+    "Rain Gages", "Subcatchments", "Junctions", "Outfalls",
+    "Dividers", "Storage Units", "Conduits", "Pumps",
+    "Orifices", "Weirs", "Outlets",
+]
+
+
+class LayerService:
+    def __init__(self, pcpy: Any, project: ProjectService):
+        self._pcpy = pcpy
+        self._project = project
+
+    def get(self, layer_name: str):
+        self._project.require_open()
+        try:
+            return self._pcpy.Map.Layer[layer_name]
+        except Exception as exc:
+            raise LayerNotFoundError(
+                f"PCSWMM map layer not found: {layer_name}"
+            ) from exc
+
+    def names(self) -> list[str]:
+        self._project.require_open()
+
+        for attribute_name in ("Names", "keys", "Keys"):
+            try:
+                value = getattr(self._pcpy.Map.Layer, attribute_name)
+                value = value() if callable(value) else value
+                names = [str(item) for item in list(value)]
+                if names:
+                    return sorted(set(names))
+            except Exception:
+                pass
+
+        names = []
+        for layer_name in DEFAULT_LAYER_NAMES:
+            try:
+                self.get(layer_name)
+                names.append(layer_name)
+            except LayerNotFoundError:
+                pass
+        return names
+
+    def attributes(self, layer_name: str) -> list[str]:
+        layer = self.get(layer_name)
+        try:
+            return [str(name) for name in list(layer.Attributes)]
+        except Exception:
+            return []
+
+    def entities(self, layer_name: str, query: str | None = None) -> list[Any]:
+        layer = self.get(layer_name)
+        if query:
+            return list(layer.get_entities(query))
+        return list(layer.get_entities())
+
+    def records(self, layer_name: str, query: str | None = None) -> list[dict[str, Any]]:
+        attributes = self.attributes(layer_name)
+        records = []
+
+        for entity in self.entities(layer_name, query=query):
+            row = {}
+            for attribute in attributes:
+                try:
+                    row[attribute] = entity[attribute]
+                except Exception:
+                    row[attribute] = None
+            records.append(row)
+
+        return records

pcswmm_ai/objects.py

@@ -0,0 +1,18 @@
+from .utils import public_names
+class ObjectService:
+    def __init__(self, collections): self._collections=collections
+    @staticmethod
+    def to_record(obj):
+        r={}
+        for n in public_names(obj):
+            try: v=getattr(obj,n)
+            except Exception: continue
+            if callable(v): continue
+            try: r[n]=v if isinstance(v,(str,int,float,bool)) or v is None else str(v)
+            except Exception: r[n]=None
+        return r
+    def collection_records(self,name):
+        out=[]
+        for key,obj in self._collections.items(name):
+            row={"Name":key,"ObjectType":name}; row.update(self.to_record(obj)); out.append(row)
+        return out

pcswmm_ai/pond.py

@@ -0,0 +1,5 @@
+from .storage import StorageReviewService
+
+
+class PondReviewService(StorageReviewService):
+    """Backward-compatible alias for StorageReviewService."""

pcswmm_ai/project.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .exceptions import ProjectNotOpenError
+from .utils import safe_count, safe_text
+
+
+class ProjectService:
+    def __init__(self, pcpy: Any):
+        self._pcpy = pcpy
+
+    @property
+    def is_open(self) -> bool:
+        try:
+            _ = self._pcpy.SWMM
+            return True
+        except Exception:
+            return False
+
+    def require_open(self):
+        if not self.is_open:
+            raise ProjectNotOpenError(
+                "No active PCSWMM/SWMM5 project is open."
+            )
+
+    @property
+    def swmm(self):
+        self.require_open()
+        return self._pcpy.SWMM
+
+    def summary(self) -> dict[str, Any]:
+        self.require_open()
+        swmm = self.swmm
+
+        collection_names = {
+            "scenario_count": "Scenarios",
+            "node_count": "Nodes",
+            "link_count": "Links",
+            "junction_count": "Junctions",
+            "conduit_count": "Conduits",
+            "subcatchment_count": "Subcatchments",
+            "storage_count": "Storages",
+            "outfall_count": "Outfalls",
+        }
+
+        result = {
+            "captured_at": datetime.now().isoformat(timespec="seconds"),
+            "project_open": True,
+            "project_name": safe_text(swmm.ProjectName),
+            "project_folder": safe_text(swmm.ProjectFolder),
+            "model_file": safe_text(swmm.FilePath),
+            "swmm_version": safe_text(swmm.Version),
+            "run_status": safe_text(swmm.RunStatus),
+        }
+
+        for output_name, attribute_name in collection_names.items():
+            try:
+                result[output_name] = safe_count(getattr(swmm, attribute_name))
+            except Exception:
+                result[output_name] = None
+
+        try:
+            result["graph_file_count"] = safe_count(self._pcpy.Graph.Files)
+        except Exception:
+            result["graph_file_count"] = 0
+
+        return result
+
+    def open_project(self, path: str):
+        self._pcpy.open_project(path)
+        return self.summary()

pcswmm_ai/qaqc.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .layers import LayerService
+
+
+class QAQCService:
+    """Deterministic, read-only screening utilities."""
+
+    def __init__(self, layers: LayerService):
+        self._layers = layers
+
+    def duplicate_names(self, layer_name: str, name_field: str = "Name") -> list[dict[str, Any]]:
+        records = self._layers.records(layer_name)
+        groups: dict[str, list[int]] = {}
+
+        for index, record in enumerate(records):
+            value = record.get(name_field)
+            if value is None:
+                continue
+            groups.setdefault(str(value), []).append(index)
+
+        return [
+            {"name": name, "record_indices": indices, "count": len(indices)}
+            for name, indices in groups.items()
+            if len(indices) > 1
+        ]
+
+    def null_attributes(self, layer_name: str, attributes: list[str]) -> list[dict[str, Any]]:
+        findings = []
+        records = self._layers.records(layer_name)
+
+        for index, record in enumerate(records):
+            missing = [
+                attribute for attribute in attributes
+                if record.get(attribute) in (None, "")
+            ]
+            if missing:
+                findings.append({
+                    "record_index": index,
+                    "name": record.get("Name"),
+                    "missing_attributes": missing,
+                })
+
+        return findings
+
+    def numeric_threshold(
+        self,
+        layer_name: str,
+        attribute: str,
+        operator: str,
+        threshold: float,
+    ) -> list[dict[str, Any]]:
+        operations = {
+            ">": lambda value: value > threshold,
+            ">=": lambda value: value >= threshold,
+            "<": lambda value: value < threshold,
+            "<=": lambda value: value <= threshold,
+            "==": lambda value: value == threshold,
+            "!=": lambda value: value != threshold,
+        }
+        if operator not in operations:
+            raise ValueError(f"Unsupported operator: {operator}")
+
+        findings = []
+        for record in self._layers.records(layer_name):
+            try:
+                value = float(record[attribute])
+            except Exception:
+                continue
+
+            if operations[operator](value):
+                findings.append(record)
+
+        return findings

pcswmm_ai/result_queries.py

@@ -0,0 +1,10 @@
+class ResultQueryService:
+    def __init__(self,results): self.results=results
+    def peak_for_objects(self,group,variable,units,names):
+        out=[]
+        for name in names:
+            try:
+                rec=self.results.timeseries(group,variable,units,name)
+                out.append({"object":name,"variable":variable,"units":units,**self.results.summarize(rec)})
+            except Exception as e: out.append({"object":name,"variable":variable,"units":units,"error":str(e)})
+        return out

pcswmm_ai/results.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .exceptions import ResultsNotAvailableError
+from .project import ProjectService
+from .utils import safe_count
+
+
+class ResultService:
+    def __init__(self, pcpy: Any, project: ProjectService):
+        self._pcpy = pcpy
+        self._project = project
+
+    def graph_files(self) -> list[Any]:
+        self._project.require_open()
+        try:
+            return list(self._pcpy.Graph.Files)
+        except Exception:
+            return []
+
+    def require_graph_file(self, index: int = 0):
+        files = self.graph_files()
+        if not files:
+            raise ResultsNotAvailableError(
+                "No PCSWMM graph/output file is available. Run the model first."
+            )
+        try:
+            return files[index]
+        except IndexError as exc:
+            raise ResultsNotAvailableError(
+                f"Graph file index {index} is unavailable."
+            ) from exc
+
+    def timeseries(
+        self,
+        object_group: str,
+        result_variable: str,
+        units: str,
+        object_name: str,
+        graph_file_index: int = 0,
+    ) -> list[dict[str, Any]]:
+        graph_file = self.require_graph_file(graph_file_index)
+
+        data = graph_file.get_data(
+            object_group,
+            result_variable,
+            units,
+            object_name,
+        )
+
+        records = []
+        for index, item in enumerate(data):
+            row = {
+                "index": index,
+                "value": getattr(item, "Value", None),
+            }
+
+            for candidate in ("DateTime", "Time", "Date", "X"):
+                try:
+                    value = getattr(item, candidate)
+                    if value is not None:
+                        row["time"] = value
+                        break
+                except Exception:
+                    pass
+
+            records.append(row)
+
+        return records
+
+    @staticmethod
+    def summarize(records: list[dict[str, Any]]) -> dict[str, Any]:
+        numeric = []
+        for record in records:
+            try:
+                numeric.append((float(record["value"]), record))
+            except Exception:
+                pass
+
+        if not numeric:
+            return {"count": len(records)}
+
+        minimum = min(numeric, key=lambda pair: pair[0])
+        maximum = max(numeric, key=lambda pair: pair[0])
+        mean = sum(pair[0] for pair in numeric) / len(numeric)
+
+        return {
+            "count": len(numeric),
+            "minimum": minimum[0],
+            "maximum": maximum[0],
+            "mean": mean,
+            "peak_time": maximum[1].get("time"),
+        }

pcswmm_ai/review_engine.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+
+class GenericReviewEngine:
+    """Run only review modules applicable to the active model."""
+
+    def __init__(
+        self,
+        project,
+        collections,
+        capabilities,
+        topology,
+        engineering,
+        hydrology,
+        storage,
+        scenarios,
+    ):
+        self._project = project
+        self._collections = collections
+        self._capabilities = capabilities
+        self._topology = topology
+        self._engineering = engineering
+        self._hydrology = hydrology
+        self._storage = storage
+        self._scenarios = scenarios
+
+    def run(self) -> dict[str, Any]:
+        capability = self._capabilities.detect()
+
+        report = {
+            "generated_at": datetime.now().isoformat(timespec="seconds"),
+            "classification": (
+                "Automated screening draft; professional engineering review required"
+            ),
+            "project": self._project.summary(),
+            "capabilities": capability,
+            "applicable_modules": self._capabilities.applicable_review_modules(),
+            "inventory": self._collections.summary(),
+            "topology": {
+                "link_endpoints": self._topology.link_endpoints(),
+                "orphan_links": self._topology.orphan_links(),
+                "isolated_nodes": self._topology.isolated_nodes(),
+                "duplicate_link_pairs": self._topology.duplicate_link_pairs(),
+            },
+            "general_engineering": {
+                "summary": self._engineering.model_screening_summary(),
+                "conduit_findings": self._engineering.conduit_screening(),
+                "subcatchment_findings": self._engineering.subcatchment_screening(),
+            },
+            "scenario_paths": {
+                "summary": self._scenarios.summary(),
+                "path_status": self._scenarios.path_status(),
+            },
+        }
+
+        if capability["has_subcatchments"]:
+            report["hydrology"] = {
+                "summary": self._hydrology.summary(),
+                "findings": self._hydrology.review(),
+            }
+
+        if capability["has_storage"] or capability["has_outlet_structures"]:
+            report["storage_and_outlets"] = {
+                "summary": self._storage.summary(),
+                "storage_records": self._storage.storage_records(),
+                "outlet_structure_records": (
+                    self._storage.outlet_structure_records()
+                ),
+                "findings": self._storage.review(),
+            }
+
+        return report

pcswmm_ai/review_report.py

@@ -0,0 +1,8 @@
+from .review_engine import GenericReviewEngine
+
+
+class ReviewReportService(GenericReviewEngine):
+    """Backward-compatible alias for GenericReviewEngine."""
+
+    def build(self):
+        return self.run()

pcswmm_ai/scenarios.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .collections import CollectionService
+
+
+class ScenarioReviewService:
+    def __init__(self, collections: CollectionService):
+        self._collections = collections
+
+    def paths(self) -> list[str]:
+        return self._collections.keys("Scenarios")
+
+    def path_status(self) -> list[dict[str, Any]]:
+        rows = []
+        for raw_path in self.paths():
+            path = Path(raw_path)
+            rows.append({
+                "scenario_path": raw_path,
+                "exists": path.exists(),
+                "suffix": path.suffix.lower(),
+                "file_name": path.name,
+                "parent": str(path.parent),
+            })
+        return rows
+
+    def summary(self) -> dict[str, Any]:
+        rows = self.path_status()
+        missing = [row for row in rows if not row["exists"]]
+        return {
+            "scenario_count": len(rows),
+            "existing_path_count": len(rows) - len(missing),
+            "missing_path_count": len(missing),
+        }

pcswmm_ai/simulation.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .project import ProjectService
+from .utils import safe_count, safe_text
+
+
+class SimulationService:
+    def __init__(self, pcpy: Any, project: ProjectService):
+        self._pcpy = pcpy
+        self._project = project
+
+    def run(self) -> dict[str, Any]:
+        self._project.require_open()
+
+        started = datetime.now()
+        self._pcpy.SWMM.run()
+        finished = datetime.now()
+
+        try:
+            graph_file_count = safe_count(self._pcpy.Graph.Files)
+        except Exception:
+            graph_file_count = 0
+
+        return {
+            "status": "completed",
+            "started_at": started.isoformat(timespec="seconds"),
+            "finished_at": finished.isoformat(timespec="seconds"),
+            "elapsed_seconds": round((finished - started).total_seconds(), 3),
+            "run_status": safe_text(self._pcpy.SWMM.RunStatus),
+            "graph_file_count": graph_file_count,
+        }
+
+    def refresh_output(self):
+        self._project.require_open()
+        self._pcpy.SWMM.refresh_output()

pcswmm_ai/storage.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class StorageReviewService:
+    """Generic review of SWMM storage nodes and outlet structures."""
+
+    def __init__(self, objects):
+        self._objects = objects
+
+    def storage_records(self) -> list[dict[str, Any]]:
+        return self._objects.collection_records("Storages")
+
+    def outlet_structure_records(self) -> list[dict[str, Any]]:
+        rows = []
+        for collection_name in ("Orifices", "Weirs", "Outlets", "Pumps"):
+            for row in self._objects.collection_records(collection_name):
+                item = dict(row)
+                item["StructureCollection"] = collection_name
+                rows.append(item)
+        return rows
+
+    @staticmethod
+    def _number(record: dict[str, Any], names: tuple[str, ...]):
+        for name in names:
+            value = record.get(name)
+            if value in (None, ""):
+                continue
+            try:
+                return float(value)
+            except Exception:
+                pass
+        return None
+
+    def review(self) -> list[dict[str, Any]]:
+        findings = []
+
+        for row in self.storage_records():
+            issues = []
+            depth = self._number(row, ("Depth", "MaxDepth"))
+            surcharge = self._number(row, ("SurchargeDepth",))
+            curve = row.get("Curve")
+            curve_type = row.get("StorageCurveType")
+
+            if depth is not None and depth <= 0:
+                issues.append("non-positive storage depth")
+            if surcharge is not None and surcharge < 0:
+                issues.append("negative surcharge depth")
+            if (
+                curve_type
+                and str(curve_type).upper() == "TABULAR"
+                and curve in (None, "", "*")
+            ):
+                issues.append("tabular storage without identified curve")
+
+            if issues:
+                findings.append({
+                    "Object": row.get("Name"),
+                    "Category": "Storage",
+                    "Depth": depth,
+                    "SurchargeDepth": surcharge,
+                    "Curve": curve,
+                    "CurveType": curve_type,
+                    "issues": issues,
+                })
+
+        for row in self.outlet_structure_records():
+            issues = []
+            inlet = row.get("InletNode")
+            outlet = row.get("OutletNode")
+            coeff = self._number(row, ("DischargeCoeff", "Coefficient"))
+            height = self._number(row, ("Height", "Geom1"))
+            width = self._number(row, ("Width", "Geom2"))
+
+            if inlet in (None, ""):
+                issues.append("missing inlet node")
+            if outlet in (None, ""):
+                issues.append("missing outlet node")
+            if coeff is not None and coeff <= 0:
+                issues.append("non-positive discharge coefficient")
+            if height is not None and height <= 0:
+                issues.append("non-positive opening height")
+            if width is not None and width < 0:
+                issues.append("negative opening width")
+
+            if issues:
+                findings.append({
+                    "Object": row.get("Name"),
+                    "Category": row.get("StructureCollection"),
+                    "InletNode": inlet,
+                    "OutletNode": outlet,
+                    "DischargeCoeff": coeff,
+                    "Height": height,
+                    "Width": width,
+                    "issues": issues,
+                })
+
+        return findings
+
+    def summary(self) -> dict[str, Any]:
+        storages = self.storage_records()
+        structures = self.outlet_structure_records()
+        findings = self.review()
+
+        return {
+            "storage_count": len(storages),
+            "outlet_structure_count": len(structures),
+            "finding_count": len(findings),
+        }

pcswmm_ai/topology.py

@@ -0,0 +1,29 @@
+class TopologyService:
+    FROM_FIELDS=("FromNode","FromNodeName","InletNode","Node1","UpstreamNode","USNode","From")
+    TO_FIELDS=("ToNode","ToNodeName","OutletNode","Node2","DownstreamNode","DSNode","To")
+    def __init__(self,objects): self._objects=objects
+    @staticmethod
+    def _first(r,names):
+        for n in names:
+            v=r.get(n)
+            if v not in (None,""): return str(v)
+        return None
+    def link_endpoints(self):
+        return [{"link":r.get("Name"),"from_node":self._first(r,self.FROM_FIELDS),"to_node":self._first(r,self.TO_FIELDS)}
+                for r in self._objects.collection_records("Links")]
+    def orphan_links(self):
+        nodes={r.get("Name") for r in self._objects.collection_records("Nodes")}
+        out=[]
+        for r in self.link_endpoints():
+            miss=[n for n in (r["from_node"],r["to_node"]) if n and n not in nodes]
+            if miss: out.append({**r,"missing_nodes":miss})
+        return out
+    def isolated_nodes(self):
+        nodes={r.get("Name") for r in self._objects.collection_records("Nodes")}
+        connected=set()
+        for r in self.link_endpoints(): connected.update(n for n in (r["from_node"],r["to_node"]) if n)
+        return [{"node":n} for n in sorted(nodes-connected)]
+    def duplicate_link_pairs(self):
+        g={}
+        for r in self.link_endpoints(): g.setdefault((r["from_node"],r["to_node"]),[]).append(r["link"])
+        return [{"from_node":k[0],"to_node":k[1],"links":v,"count":len(v)} for k,v in g.items() if k!=(None,None) and len(v)>1]

pcswmm_ai/utils.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+
+def safe_text(value: Any, default: str | None = None) -> str | None:
+    try:
+        if value is None:
+            return default
+        return str(value)
+    except Exception:
+        return default
+
+
+def safe_count(collection: Any) -> int | None:
+    """Return a collection count for Python or .NET-style collections."""
+    try:
+        return len(collection)
+    except Exception:
+        pass
+
+    try:
+        return int(collection.Count)
+    except Exception:
+        return None
+
+
+def as_list(collection: Any) -> list[Any]:
+    """Convert common Python.NET collections to a Python list."""
+    if collection is None:
+        return []
+
+    try:
+        return list(collection)
+    except Exception:
+        pass
+
+    try:
+        return list(collection.Values)
+    except Exception:
+        return []
+
+
+def dictionary_items(collection: Any) -> list[tuple[Any, Any]]:
+    """Return key/value pairs from PCSWMM's PythonDictionaryExt."""
+    if collection is None:
+        return []
+
+    for method_name in ("items", "iteritems"):
+        try:
+            method = getattr(collection, method_name)
+            return list(method())
+        except Exception:
+            pass
+
+    try:
+        return [(key, collection[key]) for key in list(collection.Keys)]
+    except Exception:
+        return []
+
+
+def public_names(obj: Any) -> list[str]:
+    return sorted(name for name in dir(obj) if not name.startswith("_"))