pipelantic 0.1.0__py3-none-any.whl

pipelantic/__init__.py

@@ -0,0 +1,49 @@
+"""Pipelantic — typed, contract-driven data pipeline modeling.
+
+0.1 provides the authoring model, logical graph construction, topology and
+compatibility diagnostics, inspection, and Mermaid output.
+
+Data contracts are provided by ContractModel. This package re-exports
+``DataContractModel`` as an alias of ``contractmodel.ContractModel`` for
+documentation-aligned imports.
+"""
+
+from pipelantic._version import __version__
+from pipelantic.contracts import DataContractModel
+from pipelantic.diagnostics import Diagnostic, Severity, ValidationReport
+from pipelantic.exceptions import (
+    ModelDefinitionError,
+    PipelanticError,
+    PipelineValidationError,
+)
+from pipelantic.model import Edge, LogicalGraph, Node, NodeKind
+from pipelantic.pipeline import Pipeline, Sink, Source, SubpipelineInstance
+from pipelantic.ports import Input, Output, Parameter
+from pipelantic.refs import OutputRef
+from pipelantic.transformation import ImplementationRecord, Step, Transformation
+
+__all__ = [
+    "DataContractModel",
+    "Diagnostic",
+    "Edge",
+    "ImplementationRecord",
+    "Input",
+    "LogicalGraph",
+    "ModelDefinitionError",
+    "Node",
+    "NodeKind",
+    "Output",
+    "OutputRef",
+    "Parameter",
+    "PipelanticError",
+    "Pipeline",
+    "PipelineValidationError",
+    "Severity",
+    "Sink",
+    "Source",
+    "Step",
+    "SubpipelineInstance",
+    "Transformation",
+    "ValidationReport",
+    "__version__",
+]

pipelantic/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"

pipelantic/contracts.py

@@ -0,0 +1,42 @@
+"""Data-contract integration boundary for ContractModel.
+
+Pipelantic docs refer to ``DataContractModel``. The published ContractModel
+package exposes ``ContractModel`` as the Pydantic authoring base. This module
+aliases that type and provides helpers for identity and compatibility checks.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeAlias
+
+from contractmodel import ContractModel
+
+# Docs-aligned alias for the ContractModel Pydantic authoring base.
+DataContractModel: TypeAlias = ContractModel
+
+__all__ = [
+    "ContractModel",
+    "DataContractModel",
+    "is_data_contract_type",
+    "resolve_contract_type",
+]
+
+
+def is_data_contract_type(obj: Any) -> bool:
+    """Return True when ``obj`` is a ContractModel-compatible data-contract class."""
+    return isinstance(obj, type) and issubclass(obj, ContractModel)
+
+
+def resolve_contract_type(annotation: Any) -> type[Any] | None:
+    """Extract a data-contract class from a type annotation when possible.
+
+    Returns ``None`` when the annotation is not a concrete ContractModel subclass.
+    """
+    if is_data_contract_type(annotation):
+        return annotation
+    origin = getattr(annotation, "__origin__", None)
+    if origin is not None:
+        args = getattr(annotation, "__args__", ())
+        if len(args) == 1 and is_data_contract_type(args[0]):
+            return args[0]
+    return None

pipelantic/diagnostics.py

@@ -0,0 +1,89 @@
+"""Structured diagnostics and validation reports."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from pipelantic.exceptions import PipelineValidationError
+
+
+class Severity(StrEnum):
+    """Diagnostic severity levels."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    HINT = "hint"
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """A structured finding from loading, inspection, or validation."""
+
+    code: str
+    severity: Severity
+    message: str
+    path: tuple[str, ...] = ()
+    help: str | None = None
+    related: tuple[tuple[str, ...], ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationReport:
+    """Immutable collection of diagnostics for a validation pass."""
+
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    @property
+    def valid(self) -> bool:
+        """Return True when no error-severity diagnostics are present."""
+        return not any(d.severity is Severity.ERROR for d in self.diagnostics)
+
+    @property
+    def errors(self) -> tuple[Diagnostic, ...]:
+        """Return error-severity diagnostics."""
+        return tuple(d for d in self.diagnostics if d.severity is Severity.ERROR)
+
+    @property
+    def warnings(self) -> tuple[Diagnostic, ...]:
+        """Return warning-severity diagnostics."""
+        return tuple(d for d in self.diagnostics if d.severity is Severity.WARNING)
+
+    def filter(
+        self,
+        *,
+        severity: Severity | None = None,
+        code: str | None = None,
+    ) -> ValidationReport:
+        """Return a report containing only matching diagnostics."""
+        items = self.diagnostics
+        if severity is not None:
+            items = tuple(d for d in items if d.severity is severity)
+        if code is not None:
+            items = tuple(d for d in items if d.code == code)
+        return ValidationReport(diagnostics=items)
+
+    def raise_for_errors(self) -> None:
+        """Raise :class:`PipelineValidationError` if the report is invalid."""
+        if self.valid:
+            return
+        count = len(self.errors)
+        message = f"Pipeline validation failed with {count} error(s)."
+        raise PipelineValidationError(message, report=self)
+
+    def merge(self, other: ValidationReport) -> ValidationReport:
+        """Combine two reports, preserving order and uniqueness by identity."""
+        return ValidationReport(diagnostics=self.diagnostics + other.diagnostics)
+
+    @classmethod
+    def from_diagnostics(cls, diagnostics: Iterable[Diagnostic]) -> ValidationReport:
+        """Build a report from an iterable of diagnostics."""
+        return cls(diagnostics=tuple(diagnostics))
+
+    def codes(self) -> Sequence[str]:
+        """Return diagnostic codes in report order."""
+        return tuple(d.code for d in self.diagnostics)

pipelantic/exceptions.py

@@ -0,0 +1,28 @@
+"""Public exception hierarchy for Pipelantic."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pipelantic.diagnostics import ValidationReport
+
+
+class PipelanticError(Exception):
+    """Base class for public Pipelantic exceptions."""
+
+
+class ModelDefinitionError(PipelanticError):
+    """Raised when a class definition cannot form a usable model."""
+
+
+class PipelineValidationError(PipelanticError):
+    """Raised when validation fails and the caller requested an exception."""
+
+    def __init__(self, message: str, *, report: ValidationReport) -> None:
+        super().__init__(message)
+        self.report = report
+
+
+class InternalPipelanticError(PipelanticError):
+    """Raised when an internal invariant is violated."""

pipelantic/identity.py

@@ -0,0 +1,47 @@
+"""Stable identity helpers for pipelines, nodes, ports, and contracts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def qualified_type_id(obj: type[Any] | Any) -> str:
+    """Return a stable identity for a class or object type.
+
+    Format: ``{module}:{qualname}``. Never uses memory addresses.
+    """
+    if not isinstance(obj, type):
+        obj = type(obj)
+    module = getattr(obj, "__module__", None) or "<unknown>"
+    qualname = getattr(obj, "__qualname__", None) or getattr(obj, "__name__", "?")
+    return f"{module}:{qualname}"
+
+
+def pipeline_id(pipeline_cls: type[Any]) -> str:
+    """Stable identity for a pipeline class."""
+    return qualified_type_id(pipeline_cls)
+
+
+def transformation_id(transformation_cls: type[Any]) -> str:
+    """Stable identity for a transformation class."""
+    return qualified_type_id(transformation_cls)
+
+
+def contract_id(contract_type: type[Any]) -> str:
+    """Stable identity for a data-contract type."""
+    return qualified_type_id(contract_type)
+
+
+def node_id(pipeline: str, node_name: str) -> str:
+    """Stable identity for a node within a pipeline."""
+    return f"{pipeline}/{node_name}"
+
+
+def port_id(node: str, port_name: str) -> str:
+    """Stable identity for a port on a node."""
+    return f"{node}:{port_name}"
+
+
+def implementation_id(transform: str, engine: str) -> str:
+    """Stable identity for a registered transformation implementation."""
+    return f"{transform}/{engine}"

pipelantic/inspection.py

@@ -0,0 +1,18 @@
+"""Pipeline inspection helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pipelantic.model import LogicalGraph
+
+if TYPE_CHECKING:
+    from pipelantic.pipeline import Pipeline
+
+
+def inspect_pipeline(pipeline_cls: type[Pipeline]) -> LogicalGraph:
+    """Return the immutable logical graph for a pipeline class.
+
+    Repeated calls return an equivalent graph (cached on the class).
+    """
+    return pipeline_cls.build_graph()

pipelantic/mermaid.py

@@ -0,0 +1,44 @@
+"""Mermaid diagram generation from logical graphs."""
+
+from __future__ import annotations
+
+from pipelantic.model import LogicalGraph, NodeKind
+
+
+def graph_to_mermaid(graph: LogicalGraph) -> str:
+    """Render a logical pipeline graph as a Mermaid flowchart.
+
+    Output is deterministic for a given graph.
+    """
+    lines: list[str] = ["flowchart LR"]
+    node_ids: dict[str, str] = {}
+
+    for index, node in enumerate(graph.nodes):
+        safe_id = f"n{index}"
+        node_ids[node.name] = safe_id
+        label = _node_label(node.name, node.kind, node.transformation_name)
+        lines.append(f'    {safe_id}["{label}"]')
+
+    for edge in graph.edges:
+        src = node_ids.get(edge.producer_node)
+        dst = node_ids.get(edge.consumer_node)
+        if src is None or dst is None:
+            continue
+        edge_label = edge.producer_port
+        if edge.producer_port != edge.consumer_port:
+            edge_label = f"{edge.producer_port}->{edge.consumer_port}"
+        lines.append(f"    {src} -- {edge_label} --> {dst}")
+
+    return "\n".join(lines) + "\n"
+
+
+def _node_label(name: str, kind: NodeKind, transformation_name: str | None) -> str:
+    if kind is NodeKind.SOURCE:
+        return f"Source: {name}"
+    if kind is NodeKind.SINK:
+        return f"Sink: {name}"
+    if kind is NodeKind.SUBPIPELINE:
+        return f"Subpipeline: {name}"
+    if transformation_name:
+        return f"{name}\\n({transformation_name})"
+    return name

pipelantic/model.py

@@ -0,0 +1,105 @@
+"""Immutable logical graph intermediate representation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+
+class NodeKind(StrEnum):
+    """Kinds of nodes in a logical pipeline graph."""
+
+    SOURCE = "source"
+    STEP = "step"
+    SINK = "sink"
+    SUBPIPELINE = "subpipeline"
+
+
+@dataclass(frozen=True, slots=True)
+class PortSpec:
+    """A typed port on a logical node."""
+
+    name: str
+    direction: str  # "input" | "output"
+    contract_type: type[Any] | None
+    contract_id: str | None
+    required: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class ParameterSpec:
+    """A typed parameter on a transformation step."""
+
+    name: str
+    value_type: type[Any] | None
+    default: Any = ...
+    has_default: bool = False
+    value: Any = ...
+    has_value: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    """A data-flow edge from a producer port to a consumer port."""
+
+    producer_node: str
+    producer_port: str
+    consumer_node: str
+    consumer_port: str
+    producer_contract_id: str | None = None
+    consumer_contract_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """A node in the logical pipeline graph."""
+
+    name: str
+    kind: NodeKind
+    identity: str
+    contract_type: type[Any] | None = None
+    contract_id: str | None = None
+    binding: str | None = None
+    transformation_id: str | None = None
+    transformation_name: str | None = None
+    inputs: tuple[PortSpec, ...] = ()
+    outputs: tuple[PortSpec, ...] = ()
+    parameters: tuple[ParameterSpec, ...] = ()
+    # For subpipelines: nested graph identity and public port names
+    nested_pipeline_id: str | None = None
+    nested_graph: LogicalGraph | None = None
+    metadata: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+
+
+@dataclass(frozen=True, slots=True)
+class LogicalGraph:
+    """Immutable, deterministic logical pipeline graph."""
+
+    pipeline_id: str
+    pipeline_name: str
+    nodes: tuple[Node, ...] = ()
+    edges: tuple[Edge, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+
+    def node_map(self) -> dict[str, Node]:
+        """Return nodes keyed by name in declaration order."""
+        return {node.name: node for node in self.nodes}
+
+    def node_names(self) -> tuple[str, ...]:
+        """Return node names in declaration order."""
+        return tuple(node.name for node in self.nodes)
+
+    def edges_from(self, node_name: str) -> tuple[Edge, ...]:
+        """Return edges whose producer is ``node_name``."""
+        return tuple(e for e in self.edges if e.producer_node == node_name)
+
+    def edges_to(self, node_name: str) -> tuple[Edge, ...]:
+        """Return edges whose consumer is ``node_name``."""
+        return tuple(e for e in self.edges if e.consumer_node == node_name)
+
+
+# Forward reference resolution for Node.nested_graph
+Node.__annotations__["nested_graph"] = LogicalGraph | None