flowgraph 0.1.2__py3-none-any.whl

flowgraph/application/workflow_web_catalog.py

@@ -0,0 +1,143 @@
+"""Export the non-executable workflow catalog consumed by the static web editor."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from flowgraph.adapters import ADAPTERS, AdapterGroup
+from flowgraph.application.port_conversions import PORT_CONVERSIONS
+from flowgraph.application.workflow_core import NodeDefinition, ParameterDefinition, PortDefinition
+from flowgraph.application.workflow_io import WORKFLOW_FORMAT, WORKFLOW_FORMAT_VERSION
+
+WEB_CATALOG_FORMAT = "flowgraph-web-node-catalog"
+WEB_CATALOG_VERSION = 1
+
+
+def workflow_web_catalog() -> dict[str, Any]:
+    """Return a JSON-compatible, non-executable description of the workflow catalog.
+
+    The result intentionally excludes node executors, port resolvers, runtime Python
+    types, and all other callable behavior. A static editor may use it to author and
+    structurally validate workflow JSON, but it cannot execute a workflow from it.
+    """
+    catalog = {
+        "format": WEB_CATALOG_FORMAT,
+        "version": WEB_CATALOG_VERSION,
+        "workflow_format": WORKFLOW_FORMAT,
+        "workflow_format_version": WORKFLOW_FORMAT_VERSION,
+        "groups": [_group_to_dict(group) for group in ADAPTERS.groups],
+        "conversions": [
+            {
+                "source_type_id": conversion.source_type_id,
+                "target_type_id": conversion.target_type_id,
+                "label": conversion.label,
+            }
+            for conversion in PORT_CONVERSIONS
+        ],
+    }
+    _assert_json_compatible(catalog)
+    return catalog
+
+
+def write_workflow_web_catalog(path: str | Path) -> Path:
+    """Write the deterministic static-editor catalog JSON to *path*.
+
+    Parameters
+    ----------
+    path:
+        Destination JSON file. Its parent directory must already exist.
+
+    Returns
+    -------
+    pathlib.Path
+        The resolved output path.
+    """
+    destination = Path(path)
+    if not destination.parent.is_dir():
+        raise ValueError(f"Web catalog output directory does not exist: {destination.parent}")
+    destination.write_text(
+        json.dumps(workflow_web_catalog(), indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return destination.resolve()
+
+
+def _group_to_dict(group: AdapterGroup) -> dict[str, Any]:
+    """Serialize an ordered catalog group and its nested groups."""
+    return {
+        "label": group.label,
+        "nodes": [_node_to_dict(definition) for definition in group.node_definitions],
+        "subgroups": [_group_to_dict(subgroup) for subgroup in group.subgroups],
+    }
+
+
+def _node_to_dict(definition: NodeDefinition) -> dict[str, Any]:
+    """Serialize static authoring metadata for one node definition."""
+    return {
+        "id": definition.id,
+        "icon": definition.icon,
+        "label": definition.label,
+        "description": definition.description,
+        "color": definition.color,
+        "presentation": definition.presentation,
+        "ports": [_port_to_dict(port) for port in definition.ports],
+        "parameters": [_parameter_to_dict(parameter) for parameter in definition.parameters],
+        "creates_subworkflow": definition.subworkflow_factory is not None,
+        "has_dynamic_ports": (
+            definition.port_resolver is not None or definition.instance_port_resolver is not None
+        ),
+    }
+
+
+def _port_to_dict(port: PortDefinition) -> dict[str, Any]:
+    """Serialize one named typed node endpoint."""
+    return {
+        "name": port.name,
+        "label": port.display_label,
+        "direction": port.direction.value,
+        "data_type_id": port.data_type.id,
+        "data_type_label": port.data_type.label,
+        "required": port.required,
+        "is_param": port.is_param,
+    }
+
+
+def _parameter_to_dict(parameter: ParameterDefinition) -> dict[str, Any]:
+    """Serialize one editable parameter schema without runtime type objects."""
+    return {
+        "name": parameter.name,
+        "kind_id": parameter.kind.id,
+        "kind_label": parameter.kind.label,
+        "label": parameter.label,
+        "default": deepcopy(parameter.default),
+        "placeholder": parameter.placeholder,
+        "options": [
+            {"value": deepcopy(option.value), "label": option.label} for option in parameter.options
+        ],
+        "file_patterns": list(parameter.file_patterns),
+        "port": parameter.port,
+    }
+
+
+def _assert_json_compatible(payload: Mapping[str, Any]) -> None:
+    """Raise a useful error if a catalog implementation adds non-JSON metadata."""
+    try:
+        json.dumps(payload)
+    except (TypeError, ValueError) as error:
+        raise ValueError(f"Workflow web catalog is not JSON-compatible: {error}") from error
+
+
+def main() -> None:
+    """Write the web-editor catalog to a command-line-selected JSON file."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("output", type=Path, help="Destination node-catalog.json path.")
+    args = parser.parse_args()
+    print(write_workflow_web_catalog(args.output))
+
+
+if __name__ == "__main__":
+    main()

flowgraph/application/workflows.py

@@ -0,0 +1,7 @@
+"""Compatibility exports for headless workflow composition."""
+
+from __future__ import annotations
+
+from flowgraph.application.node_registry import create_node_registry
+
+__all__ = ["create_node_registry"]

flowgraph/core_cli.py

@@ -0,0 +1,81 @@
+"""Headless command-line entry point for the binary FlowGraph core wheel."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from flowgraph.application.workflow_cli import (
+    WorkflowCliError,
+    execute_cli_workflow,
+    format_workflow_outputs,
+    inspect_workflow,
+    parse_inputs,
+    parse_overrides,
+    workflow_outputs,
+    write_json_output,
+)
+from flowgraph.application.workflow_core import WorkflowError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser for headless workflow execution."""
+    parser = argparse.ArgumentParser(description="Inspect or execute FlowGraph workflows.")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    inspect_parser = commands.add_parser(
+        "inspect", help="print workflow inputs, outputs, and its directed ASCII graph"
+    )
+    inspect_parser.add_argument("workflow", type=str, help="workflow JSON file")
+
+    run_parser = commands.add_parser("run", help="execute a workflow without opening the UI")
+    run_parser.add_argument("workflow", type=str, help="workflow JSON file")
+    run_parser.add_argument(
+        "--input",
+        action="append",
+        default=[],
+        metavar="NAME=VALUE",
+        help="set a published workflow input; JSON values are decoded when possible",
+    )
+    run_parser.add_argument(
+        "--override",
+        action="append",
+        default=[],
+        metavar="NODE-ID.PARAMETER=VALUE",
+        help="override a node parameter for this run",
+    )
+    run_parser.add_argument(
+        "--json-output",
+        type=str,
+        metavar="FILE",
+        help="write public workflow outputs as JSON to FILE",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Validate arguments and run a headless FlowGraph workflow command."""
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "inspect":
+            print(inspect_workflow(args.workflow))
+        else:
+            workflow, result = execute_cli_workflow(
+                args.workflow,
+                inputs=parse_inputs(args.input),
+                overrides=parse_overrides(args.override),
+            )
+            outputs = workflow_outputs(workflow, result)
+            if args.json_output:
+                write_json_output(outputs, args.json_output)
+            else:
+                print(format_workflow_outputs(outputs))
+    except (OSError, ValueError, KeyError, WorkflowError, WorkflowCliError) as error:
+        print(f"flowgraph: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowgraph/domain/__init__.py

@@ -0,0 +1,5 @@
+"""UI-independent mesh domain objects."""
+
+from flowgraph.domain.mesh_document import MeshDocument
+
+__all__ = ["MeshDocument"]

flowgraph/domain/mesh_document.py

@@ -0,0 +1,91 @@
+"""The canonical, editable mesh document."""
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from Muscat.MeshContainers.Mesh import Mesh
+from Muscat.Types import MuscatIndex
+
+
+@dataclass
+class MeshDocument:
+    """Own a Muscat mesh and application-level state without UI dependencies."""
+
+    mesh: Mesh  # type: ignore # this is only a type hint
+
+    _mesh: Mesh = field(init=False, repr=False)
+
+    def __str__(self):
+        return str(self._mesh)
+
+    @property
+    def mesh(self) -> Mesh:
+        return self._mesh
+
+    @mesh.setter
+    def mesh(self, mesh: Mesh):
+        self._mesh = mesh
+        # ensure we have the correct FlowGraph Fields
+        self.get_muscat_node_ids()
+        self.get_muscat_elements_ids()
+
+    def get_muscat_node_ids(self):
+
+        if "flowgraph_node_id" not in self.mesh.nodeFields:
+            res = np.arange(self.mesh.GetNumberOfNodes(), dtype=MuscatIndex)
+            self.mesh.nodeFields["flowgraph_node_id"] = res
+        else:
+            res = self.mesh.nodeFields["flowgraph_node_id"]
+
+        if len(res) != self.mesh.GetNumberOfNodes():
+            raise ValueError("MeshDocument node IDs do not match its Muscat mesh")
+        return res
+
+    def get_muscat_elements_ids(self):
+        if "flowgraph_element_id" not in self.mesh.elemFields:
+            res = np.arange(self.mesh.GetNumberOfElements(), dtype=MuscatIndex)
+            self.mesh.elemFields["flowgraph_element_id"] = res
+        else:
+            res = self.mesh.elemFields["flowgraph_element_id"]
+
+        if len(res) != self._mesh.GetNumberOfElements():
+            raise ValueError("MeshDocument element IDs do not match its Muscat mesh")
+        return res
+
+    def to_vtk_unstructured_grid(self):  # type: ignore[no-untyped-def]
+        """Create a VTK projection with stable Muscat node and element ID arrays."""
+        from Muscat.Bridges.vtkBridge import MeshToVtk
+
+        return MeshToVtk(self.mesh)
+
+    def __repr__(self):
+        mesh = self.mesh
+        res = f"""Mesh details       :
+Number Of Nodes    : {mesh.GetNumberOfNodes()}
+
+"""
+
+        if len(mesh.nodesTags):
+            res += " Nodes named selections (name: size):\n"
+            for x in mesh.nodesTags:
+                res += f"  {x.name}: {len(x)} \n"
+
+        res += f"Total Number Of Elements : {mesh.GetNumberOfElements()} \n"
+
+        for data in mesh.elements.values():
+            res += f" Element type: {data.elementType} \n"
+            res += f"  Number of elements: {data.GetNumberOfElements()}\n"
+            if len(data.tags):
+                res += "  Named selections (name: size):\n"
+                for x in data.tags:
+                    res += f"   {x.name}: {len(x)} \n"
+
+        if len(mesh.nodeFields.keys()) > 0:
+            res += "\n  Node Fields (name: type, shape):\n"
+            for k, v in mesh.nodeFields.items():
+                res += f"   {k}: {v.dtype}, {v.shape}\n"
+        if len(mesh.elemFields.keys()) > 0:
+            res += "\n  Element Fields (name: type, shape):\n"
+            for k, v in mesh.elemFields.items():
+                res += f"   {k}: {v.dtype}, {v.shape}\n"
+        return res

flowgraph/examples/AllFilters.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from flowgraph.application.node_registry import create_node_registry
+from flowgraph.application.workflow_io import execute_workflow, load_workflow
+
+registry = create_node_registry()
+my_workflow = load_workflow(Path(__file__).parent / ".." / "testdata" / "AllFilters.json", registry)
+
+print(my_workflow)
+
+for node in my_workflow.nodes:
+    node.pprint()
+
+
+parameter_overrides = {}
+
+result = execute_workflow(my_workflow, registry=registry, parameter_overrides=parameter_overrides)
+
+print(result)

flowgraph/examples/convert_format.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from flowgraph.application.node_registry import create_node_registry
+from flowgraph.application.workflow_io import execute_workflow, load_workflow
+
+registry = create_node_registry()
+my_workflow = load_workflow(
+    Path(__file__).parent / ".." / "testdata" / "workflowtest.json", registry
+)
+
+print(my_workflow)
+
+for node in my_workflow.nodes:
+    node.pprint()
+
+
+parameter_overrides = {"create-muscat-element-filter-2": {"dimensionality": [0]}}
+
+result = execute_workflow(my_workflow, registry=registry, parameter_overrides=parameter_overrides)
+
+print(result.node_outputs["filter-mesh-muscat-2"]["mesh"].mesh)

flowgraph/resources.py

@@ -0,0 +1,29 @@
+"""Current-working-directory-independent access to packaged FlowGraph resources."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import flowgraph
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+
+
+def package_resource_path(*parts: str, required: bool = True) -> Path:
+    """Return a path inside the installed package and optionally require it to exist.
+
+    PyInstaller gives bundled modules meaningful ``__file__`` paths inside its
+    collected application directory, so this works in source, wheel, and onedir
+    executions without depending on the process working directory.
+    """
+    candidates = [Path(root).joinpath(*parts) for root in flowgraph.__path__]
+    path = next(
+        (candidate for candidate in candidates if candidate.exists()), PACKAGE_ROOT.joinpath(*parts)
+    )
+    if required and not path.exists():
+        resource = "/".join(parts) or "."
+        raise FileNotFoundError(
+            f"Required FlowGraph resource {resource!r} was not included at {path}. "
+            "Install the matching FlowGraph core and desktop distributions, then rebuild the artifact."
+        )
+    return path