flowgraph 0.1.2__py3-none-any.whl

flowgraph/adapters/user_code.py

@@ -0,0 +1,196 @@
+"""Workflow node for executing user-provided Python code."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from collections.abc import Mapping
+from typing import Any
+
+from flowgraph.application.workflow_core import (
+    NodeDefinition,
+    NodeInstance,
+    ParameterDefinition,
+    PortDefinition,
+    PortDirection,
+)
+
+from .data_types import ANY, BOOLEAN, FLOAT, INTEGER, LIST_FLOAT, LIST_INT, LIST_STR, STRING
+
+DEFAULT_CODE = """def Execute(input1, input2, input3) -> tuple[Any, Any, Any]:
+    return (input1, input2, input3)
+"""
+
+_ANNOTATION_TYPES = {
+    "Any": ANY,
+    "bool": BOOLEAN,
+    "float": FLOAT,
+    "int": INTEGER,
+    "list[float]": LIST_FLOAT,
+    "list[int]": LIST_INT,
+    "list[str]": LIST_STR,
+    "str": STRING,
+}
+
+
+def _annotation_name(annotation: ast.expr | None) -> str:
+    """Return the supported source spelling for one function annotation."""
+    if annotation is None:
+        return "Any"
+    if isinstance(annotation, ast.Name):
+        return annotation.id
+    if (
+        isinstance(annotation, ast.Subscript)
+        and isinstance(annotation.value, ast.Name)
+        and annotation.value.id == "list"
+        and isinstance(annotation.slice, ast.Name)
+    ):
+        return f"list[{annotation.slice.id}]"
+    return ast.unparse(annotation)
+
+
+def _execute_function(source: str) -> ast.FunctionDef:
+    """Parse *source* and return its top-level ``Execute`` function declaration."""
+    if not isinstance(source, str) or not source.strip():
+        raise ValueError("The user function code must be non-empty Python source")
+    try:
+        module = ast.parse(source, filename="<flowgraph user-function>", mode="exec")
+    except SyntaxError as error:
+        raise ValueError(f"The user function code is invalid Python: {error.msg}") from error
+    functions = [
+        statement
+        for statement in module.body
+        if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and statement.name == "Execute"
+    ]
+    if len(functions) != 1:
+        raise ValueError(
+            "The user function code must define exactly one top-level Execute function"
+        )
+    function = functions[0]
+    if isinstance(function, ast.AsyncFunctionDef):
+        raise TypeError("Execute must be a regular function, not an async function")
+    return function
+
+
+def _input_ports(source: str) -> tuple[PortDefinition, ...]:
+    """Extract validated typed input ports from a user ``Execute`` declaration."""
+    function = _execute_function(source)
+    arguments = function.args
+    if arguments.vararg is not None or arguments.kwarg is not None or arguments.kwonlyargs:
+        raise ValueError(
+            "Execute may use only positional parameters; *args and keyword-only parameters are unsupported"
+        )
+    inputs = [*arguments.posonlyargs, *arguments.args]
+    ports: list[PortDefinition] = []
+    for argument in inputs:
+        annotation_name = _annotation_name(argument.annotation)
+        data_type = _ANNOTATION_TYPES.get(annotation_name)
+        if data_type is None:
+            supported = ", ".join(_ANNOTATION_TYPES)
+            raise ValueError(
+                f"Unsupported annotation for Execute parameter {argument.arg!r}: "
+                f"{annotation_name!r}. Supported annotations are {supported}."
+            )
+        ports.append(
+            PortDefinition(
+                argument.arg, PortDirection.INPUT, data_type, argument.arg, required=False
+            )
+        )
+    return tuple(ports)
+
+
+def _output_ports(source: str) -> tuple[PortDefinition, ...]:
+    """Extract validated typed output ports from a user ``Execute`` return annotation."""
+    annotation = _execute_function(source).returns
+    if not (
+        isinstance(annotation, ast.Subscript)
+        and isinstance(annotation.value, ast.Name)
+        and annotation.value.id == "tuple"
+    ):
+        raise ValueError("Execute must declare a fixed-length tuple return annotation")
+    elements = (
+        list(annotation.slice.elts)
+        if isinstance(annotation.slice, ast.Tuple)
+        else [annotation.slice]
+    )
+    ports: list[PortDefinition] = []
+    for index, element in enumerate(elements, start=1):
+        annotation_name = _annotation_name(element)
+        data_type = _ANNOTATION_TYPES.get(annotation_name)
+        if data_type is None:
+            supported = ", ".join(_ANNOTATION_TYPES)
+            raise ValueError(
+                f"Unsupported annotation for Execute output {index}: {annotation_name!r}. "
+                f"Supported annotations are {supported}."
+            )
+        ports.append(
+            PortDefinition(f"output{index}", PortDirection.OUTPUT, data_type, f"Output {index}")
+        )
+    return tuple(ports)
+
+
+def _ports_for_instance(instance: NodeInstance) -> tuple[PortDefinition, ...]:
+    """Resolve User Function inputs and outputs from an instance's source code."""
+    source = instance.parameters.get("code", DEFAULT_CODE)
+    return _input_ports(source) + _output_ports(source)
+
+
+def _execute_user_code(
+    inputs: Mapping[str, Any], parameters: Mapping[str, Any]
+) -> Mapping[str, Any]:
+    """Compile and run the user's ``Execute`` function in a trusted local namespace."""
+    code = parameters.get("code", DEFAULT_CODE)
+    input_ports = _input_ports(code)
+    output_ports = _output_ports(code)
+
+    namespace: dict[str, Any] = {"__builtins__": __builtins__, "Any": Any}
+    compiled = compile(code, "<flowgraph user-function>", "exec")
+    exec(compiled, namespace)  # noqa: S102 - this node intentionally runs trusted user code
+    function = namespace.get("Execute")
+    if not callable(function):
+        raise TypeError("The user function code must define callable Execute")
+
+    signature = inspect.signature(function)
+    function_parameters = list(signature.parameters.values())
+    if [parameter.name for parameter in function_parameters] != [
+        port.name for port in input_ports
+    ] or any(
+        parameter.kind
+        not in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+        for parameter in function_parameters
+    ):
+        raise ValueError("Execute must not be reassigned after its validated function declaration")
+
+    result = function(*(inputs.get(port.name) for port in input_ports))
+    if not isinstance(result, tuple) or len(result) != len(output_ports):
+        raise TypeError(
+            f"Execute must return a tuple containing exactly {len(output_ports)} outputs"
+        )
+    return {port.name: value for port, value in zip(output_ports, result, strict=True)}
+
+
+USER_FUNCTION = NodeDefinition(
+    id="user-function",
+    icon="mdi-code-braces",
+    label="User Function",
+    description="Runs trusted local Python code defining a typed Execute function.",
+    ports=(),
+    executor=_execute_user_code,
+    instance_port_resolver=_ports_for_instance,
+    parameters=(
+        ParameterDefinition(
+            "code",
+            STRING,
+            "Execute code",
+            DEFAULT_CODE,
+            "def Execute(value: float): ...",
+            port=False,
+        ),
+    ),
+    presentation="code",
+)
+
+AVAILABLE_NODES = (USER_FUNCTION,)
+
+__all__ = ["AVAILABLE_NODES", "DEFAULT_CODE", "USER_FUNCTION"]

flowgraph/adapters/workflow.py

@@ -0,0 +1,176 @@
+"""Composite node that executes an editable nested workflow graph."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from flowgraph.application.workflow_core import (
+    NodeDefinition,
+    NodeInstance,
+    NodeRegistry,
+    PortDefinition,
+    PortDirection,
+    WorkflowExecutor,
+    WorkflowGraph,
+    WorkflowRunResult,
+)
+
+from .data_types import ANY, FLOAT, INTEGER, LIST_ANY, LIST_FLOAT, LIST_INT, LIST_STR, STRING
+
+RUN_WORKFLOW_PORTS = (PortDefinition("result", PortDirection.OUTPUT, ANY, "Result"),)
+BATCH_WORKFLOW_PORTS = (PortDefinition("result", PortDirection.OUTPUT, LIST_ANY, "Results"),)
+
+_BATCH_LIST_TYPES = {
+    STRING.id: LIST_STR,
+    INTEGER.id: LIST_INT,
+    FLOAT.id: LIST_FLOAT,
+}
+
+
+def _nested_ports(instance: NodeInstance) -> tuple[PortDefinition, ...]:
+    """Return ports exported by a composite node's child workflow."""
+    graph = instance.subworkflow
+    if graph is None:
+        return RUN_WORKFLOW_PORTS
+    exported = tuple(
+        PortDefinition(port.name, port.direction, port.data_type, port.display_label)
+        for port in (*graph.inputs, *graph.outputs)
+    )
+    names = {(port.direction, port.name) for port in RUN_WORKFLOW_PORTS}
+    return RUN_WORKFLOW_PORTS + tuple(
+        port for port in exported if (port.direction, port.name) not in names
+    )
+
+
+def _execute_workflow(
+    instance: NodeInstance,
+    inputs: Mapping[str, Any],
+    _parameters: Mapping[str, Any],
+    registry: NodeRegistry,
+) -> Mapping[str, Any]:
+    """Execute the child graph with values supplied to its public inputs."""
+    graph = instance.subworkflow
+    if graph is None:
+        raise ValueError("The nested workflow is not initialized")
+    graph.sync_boundary_nodes(registry)
+    injected = {port.node_id: {port.node_port: inputs[port.name]} for port in graph.inputs}
+    nested_result: WorkflowRunResult = WorkflowExecutor(registry).run(
+        graph, initial_inputs=injected
+    )
+    outputs = {
+        port.name: nested_result.node_outputs[port.node_id][port.node_port]
+        for port in graph.outputs
+    }
+    return {"result": nested_result, **outputs}
+
+
+def _batch_ports(instance: NodeInstance) -> tuple[PortDefinition, ...]:
+    """Return broadcasting inputs and aggregated outputs of a child workflow."""
+    graph = instance.subworkflow
+    if graph is None:
+        return BATCH_WORKFLOW_PORTS
+    inputs = tuple(
+        PortDefinition(
+            port.name,
+            PortDirection.INPUT,
+            port.data_type,
+            port.display_label,
+            accepted_data_types=(list_type,)
+            if (list_type := _BATCH_LIST_TYPES.get(port.data_type.id))
+            else (),
+        )
+        for port in graph.inputs
+    )
+    outputs = tuple(
+        PortDefinition(
+            port.name,
+            PortDirection.OUTPUT,
+            _BATCH_LIST_TYPES.get(port.data_type.id, LIST_ANY),
+            port.display_label,
+        )
+        for port in graph.outputs
+    )
+    names = {(port.direction, port.name) for port in BATCH_WORKFLOW_PORTS}
+    return BATCH_WORKFLOW_PORTS + tuple(
+        port for port in (*inputs, *outputs) if (port.direction, port.name) not in names
+    )
+
+
+def _execute_batch_workflow(
+    instance: NodeInstance,
+    inputs: Mapping[str, Any],
+    _parameters: Mapping[str, Any],
+    registry: NodeRegistry,
+) -> Mapping[str, Any]:
+    """Execute a child graph for each list entry and aggregate its public outputs.
+
+    Lists define the batch dimension and must all have the same length. Scalar
+    inputs broadcast to every child execution.
+    """
+    graph = instance.subworkflow
+    if graph is None:
+        raise ValueError("The nested workflow is not initialized")
+    graph.sync_boundary_nodes(registry)
+    list_inputs = {name: value for name, value in inputs.items() if isinstance(value, list)}
+    if not list_inputs:
+        raise ValueError("Batch Workflow requires at least one list input")
+    lengths = {len(value) for value in list_inputs.values()}
+    if len(lengths) != 1:
+        details = ", ".join(f"{name}={len(value)}" for name, value in list_inputs.items())
+        raise ValueError(f"Batch Workflow list inputs must have equal lengths: {details}")
+
+    batch_size = lengths.pop()
+    results: list[WorkflowRunResult] = []
+    outputs = {port.name: [] for port in graph.outputs}
+    executor = WorkflowExecutor(registry)
+    for index in range(batch_size):
+        injected = {
+            port.node_id: {
+                port.node_port: inputs[port.name][index]
+                if isinstance(inputs[port.name], list)
+                else inputs[port.name]
+            }
+            for port in graph.inputs
+        }
+        result = executor.run(graph, initial_inputs=injected)
+        results.append(result)
+        for port in graph.outputs:
+            outputs[port.name].append(result.node_outputs[port.node_id][port.node_port])
+    return {"result": results, **outputs}
+
+
+def _empty_workflow() -> WorkflowGraph:
+    """Create an independent empty graph for one composite node instance."""
+    return WorkflowGraph()
+
+
+RUN_WORKFLOW = NodeDefinition(
+    id="run-workflow",
+    icon="mdi-play-network-outline",
+    label="Run Full Workflow",
+    description="Executes and exports the inputs and outputs of an editable nested workflow.",
+    ports=(RUN_WORKFLOW_PORTS),
+    executor=lambda _inputs, _parameters: {},
+    instance_port_resolver=_nested_ports,
+    instance_executor=_execute_workflow,
+    subworkflow_factory=_empty_workflow,
+    presentation="workflow",
+)
+
+BATCH_WORKFLOW = NodeDefinition(
+    id="batch-workflow",
+    icon="mdi-format-list-numbered",
+    label="Batch Workflow",
+    description="Executes an editable nested workflow once for each list entry.",
+    ports=(BATCH_WORKFLOW_PORTS),
+    executor=lambda _inputs, _parameters: {},
+    instance_port_resolver=_batch_ports,
+    instance_executor=_execute_batch_workflow,
+    subworkflow_factory=_empty_workflow,
+    presentation="workflow",
+)
+
+AVAILABLE_NODES = (RUN_WORKFLOW, BATCH_WORKFLOW)
+
+__all__ = ["AVAILABLE_NODES", "BATCH_WORKFLOW", "RUN_WORKFLOW"]

flowgraph/adapters/workflow_interfaces.py

@@ -0,0 +1,78 @@
+"""Workflow boundary nodes that define public inputs and outputs."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from flowgraph.application.workflow_core import (
+    NodeDefinition,
+    ParameterDefinition,
+    PortDefinition,
+    PortDirection,
+)
+
+from .data_types import ANY, ParameterKind
+
+
+def _workflow_input(inputs: Mapping[str, Any], _parameters: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Pass a supplied workflow input through to downstream nodes."""
+    return {"value": inputs["value"]}
+
+
+WORKFLOW_INPUT = NodeDefinition(
+    id="workflow-input",
+    icon="mdi-import",
+    label="Workflow Input",
+    description="Defines a named public input for the workflow.",
+    ports=(
+        PortDefinition("value", PortDirection.INPUT, ANY, "Value"),
+        PortDefinition("value", PortDirection.OUTPUT, ANY, "Value"),
+    ),
+    executor=_workflow_input,
+    parameters=(
+        ParameterDefinition(
+            "name",
+            ParameterKind.TEXT,
+            "Input name",
+            "input",
+            "Public workflow input name",
+            port=False,
+        ),
+    ),
+    color="orange",
+)
+
+
+def _workflow_output(
+    _inputs: Mapping[str, Any], _parameters: Mapping[str, Any]
+) -> Mapping[str, Any]:
+    """Pass a value through to the public workflow output."""
+    return {"value": _inputs["value"]}
+
+
+WORKFLOW_OUTPUT = NodeDefinition(
+    id="workflow-output",
+    icon="mdi-export",
+    label="Workflow Output",
+    description="Defines a named public output for the workflow.",
+    ports=(
+        PortDefinition("value", PortDirection.INPUT, ANY, "Value"),
+        PortDefinition("value", PortDirection.OUTPUT, ANY, "Value"),
+    ),
+    executor=_workflow_output,
+    parameters=(
+        ParameterDefinition(
+            "name",
+            ParameterKind.TEXT,
+            "Output name",
+            "output",
+            "Public workflow output name",
+            port=False,
+        ),
+    ),
+    color="orange",
+)
+
+
+AVAILABLE_NODES = (WORKFLOW_INPUT, WORKFLOW_OUTPUT)
+
+__all__ = ["AVAILABLE_NODES", "WORKFLOW_INPUT", "WORKFLOW_OUTPUT"]

flowgraph/adapters/writers.py

@@ -0,0 +1,159 @@
+"""Workflow nodes that write FlowGraph domain objects to external files."""
+
+import logging
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from flowgraph.adapters.readers import MESH_DOCUMENT
+from flowgraph.application.workflow_core import (
+    NodeDefinition,
+    ParameterDefinition,
+    PortDefinition,
+    PortDirection,
+)
+from flowgraph.domain.mesh_document import MeshDocument
+
+from .data_types import ParameterKind
+
+LOGGER = logging.getLogger(__name__)
+
+
+class MeshWriteError(RuntimeError):
+    """Raised when a mesh document cannot be written by a writer adapter."""
+
+
+def _validate_destination(
+    inputs: Mapping[str, Any], parameters: Mapping[str, Any], writer_name: str
+) -> Path:
+    """Return a usable destination or raise a writer-specific error."""
+    configured_path = inputs.get("path", parameters.get("path", ""))
+    destination = Path(configured_path).expanduser()
+
+    if not destination.name:
+        raise MeshWriteError("Mesh filename must not be empty")
+    if not destination.suffix:
+        raise MeshWriteError(
+            f"Mesh filename has no extension; {writer_name} cannot select a writer: {destination}"
+        )
+    if not destination.parent.is_dir():
+        raise MeshWriteError(
+            f"Mesh output directory does not exist or is not a directory: {destination.parent}"
+        )
+    return destination
+
+
+def _write_muscat(inputs: Mapping[str, Any], parameters: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Write a mesh document using Muscat's extension-aware universal writer."""
+
+    destination = _validate_destination(inputs, parameters, "Muscat")
+    document: MeshDocument = inputs["mesh"]
+
+    try:
+        from Muscat.IO.UniversalWriter import InitAllWriters, WriteMesh
+
+        LOGGER.debug("Initialising Muscat writers for %s", destination)
+        InitAllWriters()
+        LOGGER.info("Writing mesh document with Muscat: %s", destination)
+        WriteMesh(destination, document.mesh)
+    except Exception as error:
+        LOGGER.exception("Muscat failed while writing %s", destination)
+        raise MeshWriteError(f"Muscat could not write '{destination}': {error}") from error
+
+    LOGGER.info("Muscat wrote mesh document to %s", destination.resolve())
+    return {}
+
+
+def _write_meshio(inputs: Mapping[str, Any], parameters: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Convert a Muscat mesh through its meshio bridge and write it with meshio."""
+    destination = _validate_destination(inputs, parameters, "meshio")
+    document: MeshDocument = inputs["mesh"]
+
+    try:
+        import meshio
+        from Muscat.Bridges.MeshIOBridge import MeshToMeshIO
+
+        LOGGER.info("Writing mesh document with meshio: %s", destination)
+        meshio.write(destination, MeshToMeshIO(document.mesh))
+    except Exception as error:
+        LOGGER.exception("meshio failed while writing %s", destination)
+        raise MeshWriteError(f"meshio could not write '{destination}': {error}") from error
+
+    LOGGER.info("meshio wrote mesh document to %s", destination.resolve())
+    return {}
+
+
+def _write_meshlane(inputs: Mapping[str, Any], parameters: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Convert a Muscat mesh and write it with the optional MeshLane adapter."""
+    destination = _validate_destination(inputs, parameters, "MeshLane")
+    document: MeshDocument = inputs["mesh"]
+
+    try:
+        import meshlane
+    except ImportError as error:
+        raise MeshWriteError(
+            "MeshLane is not installed; install FlowGraph with the 'meshlane' extra"
+        ) from error
+
+    try:
+        from Muscat.Bridges.MeshlaneBridge import MeshToMeshlane
+    except ImportError as error:
+        raise MeshWriteError(
+            "This Muscat installation has no MeshLane bridge; install FlowGraph with "
+            "the 'meshlane' extra"
+        ) from error
+
+    try:
+        LOGGER.info("Writing mesh document with MeshLane: %s", destination)
+        meshlane.write(destination, MeshToMeshlane(document.mesh))
+    except Exception as error:
+        LOGGER.exception("MeshLane failed while writing %s", destination)
+        raise MeshWriteError(f"MeshLane could not write '{destination}': {error}") from error
+
+    LOGGER.info("MeshLane wrote mesh document to %s", destination.resolve())
+    return {}
+
+
+WRITE_MUSCAT = NodeDefinition(
+    id="write-muscat",
+    icon="mdi-file-export-outline",
+    label="Write Mesh (Muscat)",
+    description="Writes the canonical mesh document to a filename selected by extension.",
+    ports=(PortDefinition("mesh", PortDirection.INPUT, MESH_DOCUMENT, "Mesh"),),
+    executor=_write_muscat,
+    parameters=(
+        ParameterDefinition(
+            "path", ParameterKind.FILE, "File path", "", "/path/to/mesh", port=True
+        ),
+    ),
+)
+
+
+WRITE_MESHIO = NodeDefinition(
+    id="write-meshio",
+    icon="mdi-file-swap-outline",
+    label="Write Mesh (MeshIO)",
+    description="Writes the canonical mesh document with meshio through Muscat's bridge.",
+    ports=(PortDefinition("mesh", PortDirection.INPUT, MESH_DOCUMENT, "Mesh"),),
+    executor=_write_meshio,
+    parameters=(
+        ParameterDefinition(
+            "path", ParameterKind.FILE, "File path", "", "/path/to/mesh", port=True
+        ),
+    ),
+)
+
+
+WRITE_MESHLANE = NodeDefinition(
+    id="write-meshlane",
+    icon="mdi-file-swap-outline",
+    label="Write Mesh (MeshLane)",
+    description="Writes the canonical mesh document with the optional MeshLane adapter.",
+    ports=(PortDefinition("mesh", PortDirection.INPUT, MESH_DOCUMENT, "Mesh"),),
+    executor=_write_meshlane,
+    parameters=(
+        ParameterDefinition(
+            "path", ParameterKind.FILE, "File path", "", "/path/to/mesh", port=True
+        ),
+    ),
+)

flowgraph/application/__init__.py

@@ -0,0 +1 @@
+"""Application commands, history, validation, and workflow services."""

flowgraph/application/node_registry.py

@@ -0,0 +1,14 @@
+"""Headless built-in workflow node catalog and starter graph."""
+
+from flowgraph.adapters import ADAPTERS
+from flowgraph.application.workflow_core import NodeRegistry
+
+__all__ = ["create_node_registry"]
+
+
+def create_node_registry() -> NodeRegistry:
+    """Return all built-in nodes whose executors are safe for headless use."""
+    registry = NodeRegistry()
+    for definition in ADAPTERS.node_definitions:
+        registry.register(definition)
+    return registry

flowgraph/application/port_conversions.py

@@ -0,0 +1,63 @@
+"""Explicit automatic conversions permitted between workflow port types."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from flowgraph.application.workflow_core import DataType
+
+
+@dataclass(frozen=True)
+class PortConversion:
+    """A directed value conversion between two stable workflow type IDs."""
+
+    source_type_id: str
+    target_type_id: str
+    label: str
+    convert: Callable[[Any], Any]
+
+
+INTEGER_TO_FLOAT = PortConversion("integer", "float", "Integer → Float", float)
+INTEGER_TO_STRING = PortConversion("integer", "string", "Integer → string", str)
+INTEGER_TO_LIST_INT = PortConversion(
+    "integer", "list[int]", "Integer → list[int]", lambda value: [value]
+)
+
+FLOAT_TO_INTEGER = PortConversion("float", "integer", "Float -> Integer", round)
+FLOAT_TO_STRING = PortConversion("float", "string", "Float → Text", str)
+FLOAT_TO_LIST_FLOAT = PortConversion(
+    "float", "list[float]", "Float → list[float]", lambda value: [value]
+)
+
+PATH_TO_STR = PortConversion("filename", "string", "filename → Text", str)
+STR_TO_PATH = PortConversion("string", "filename", "Text → filename", str)
+
+VEC3D_TO_LIST = PortConversion(
+    "VEC3D", "list[float]", "Tex3D Vector → list[float]", lambda x: list(x)
+)
+
+
+PORT_CONVERSIONS = (
+    INTEGER_TO_FLOAT,
+    INTEGER_TO_STRING,
+    INTEGER_TO_LIST_INT,
+    FLOAT_TO_INTEGER,
+    FLOAT_TO_STRING,
+    FLOAT_TO_LIST_FLOAT,
+    PATH_TO_STR,
+    STR_TO_PATH,
+    VEC3D_TO_LIST,
+)
+
+
+_CONVERSIONS_BY_TYPE_IDS = {
+    (conversion.source_type_id, conversion.target_type_id): conversion
+    for conversion in PORT_CONVERSIONS
+}
+
+
+def resolve_port_conversion(source: DataType[Any], target: DataType[Any]) -> PortConversion | None:
+    """Return the explicitly registered conversion from *source* to *target*, if any."""
+    return _CONVERSIONS_BY_TYPE_IDS.get((source.id, target.id))