pipelantic 0.1.0__tar.gz

pipelantic-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+site/
+.venv/
+venv/
+.env
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store

pipelantic-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-16
+
+### Added
+
+- First public release as **Pipelantic** (PyPI package `pipelantic`)
+- Typed modeling kernel for authoring pipelines without an execution backend
+- `Transformation`, `Input`, `Output`, and `Parameter` port annotations
+- `Pipeline`, `Source`, `Step`, `Sink`, and subpipeline composition
+- Typed `OutputRef` wiring with stable node and port identities
+- Structural validation diagnostics (cycles, missing refs, incompatible ports)
+- Logical graph inspection and Mermaid diagram generation
+- ContractModel integration boundary via `DataContractModel` alias
+- uv + ruff toolchain, MkDocs documentation site, shared GitHub Actions
+  checks, and tag-triggered PyPI release
+
+[0.1.0]: https://github.com/eddiethedean/pipelantic/releases/tag/v0.1.0

pipelantic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Odo Matthews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pipelantic-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: pipelantic
+Version: 0.1.0
+Summary: Typed, contract-driven data pipeline modeling for Python.
+Project-URL: Homepage, https://github.com/eddiethedean/pipelantic
+Project-URL: Documentation, https://github.com/eddiethedean/pipelantic/tree/main/docs
+Project-URL: Repository, https://github.com/eddiethedean/pipelantic
+Project-URL: Issues, https://github.com/eddiethedean/pipelantic/issues
+Project-URL: Changelog, https://github.com/eddiethedean/pipelantic/blob/main/CHANGELOG.md
+Author-email: Odo Matthews <odosmatthews@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-contracts,etl,pipelines,pydantic,typed
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: contractmodel>=0.1.2
+Requires-Dist: packaging>=24
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+![Pipelantic banner](docs/theme/assets/pipelantic-banner.png)
+
+# Pipelantic
+
+[![Documentation Status](https://readthedocs.org/projects/pipelantic/badge/?version=latest)](https://pipelantic.readthedocs.io/en/latest/?badge=latest)
+
+Typed, contract-driven data pipeline modeling for Python.
+
+> Define data, transformations, and pipelines with typed Python classes.
+> Validate and plan them once. Execute them through interchangeable backends.
+
+## Status
+
+**0.1.0 — Typed Modeling Kernel**
+
+Pipelantic currently provides the authoring model, logical graph construction,
+topology and compatibility diagnostics, graph inspection, and Mermaid output.
+Planning, execution plugins, and contract serialization arrive in later
+milestones.
+
+See the [hosted documentation](https://pipelantic.readthedocs.io/) for the
+full design,
+[CHANGELOG.md](CHANGELOG.md) for release notes, and
+[Roadmap](docs/11_DEVELOPMENT/ROADMAP.md) for sequencing.
+
+## Install
+
+```bash
+pip install pipelantic
+# or
+uv add pipelantic
+```
+
+### Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+```
+
+`uv sync` creates `.venv`, installs the package in editable mode, and installs
+the `dev` dependency group (pytest, ruff, mkdocs) by default.
+
+## Release
+
+Tag a version that matches `src/pipelantic/_version.py`, then push the tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+GitHub Actions runs checks and publishes to PyPI using the `PYPI_API_TOKEN`
+repository secret.
+
+## Quick example
+
+```python
+from contractmodel import ContractModel as DataContractModel
+from pipelantic import Input, Output, Pipeline, Sink, Source, Transformation
+
+
+class RawCustomer(DataContractModel):
+    customer_id: int
+    first_name: str
+    last_name: str
+
+
+class Customer(DataContractModel):
+    customer_id: int
+    full_name: str
+
+
+class NormalizeCustomers(Transformation):
+    customers: Input[RawCustomer]
+    result: Output[Customer]
+
+
+class CustomerPipeline(Pipeline):
+    raw: Source[RawCustomer] = Source(binding="customer_source")
+    normalized = NormalizeCustomers.step(customers=raw)
+    curated: Sink[Customer] = Sink(
+        input=normalized.result,
+        binding="customer_sink",
+    )
+
+
+graph = CustomerPipeline.inspect()
+report = CustomerPipeline.validate()
+print(CustomerPipeline.to_mermaid())
+```
+
+## Documentation
+
+- [Documentation site](https://pipelantic.readthedocs.io/)
+- [Getting Started](docs/01_GETTING_STARTED/README.md)
+- [Core Concepts](docs/02_FOUNDATIONS/CORE_CONCEPTS.md)
+- [Architecture](docs/02_FOUNDATIONS/ARCHITECTURE.md)
+- [Roadmap](docs/11_DEVELOPMENT/ROADMAP.md)
+
+## License
+
+MIT

pipelantic-0.1.0/README.md

@@ -0,0 +1,107 @@
+![Pipelantic banner](docs/theme/assets/pipelantic-banner.png)
+
+# Pipelantic
+
+[![Documentation Status](https://readthedocs.org/projects/pipelantic/badge/?version=latest)](https://pipelantic.readthedocs.io/en/latest/?badge=latest)
+
+Typed, contract-driven data pipeline modeling for Python.
+
+> Define data, transformations, and pipelines with typed Python classes.
+> Validate and plan them once. Execute them through interchangeable backends.
+
+## Status
+
+**0.1.0 — Typed Modeling Kernel**
+
+Pipelantic currently provides the authoring model, logical graph construction,
+topology and compatibility diagnostics, graph inspection, and Mermaid output.
+Planning, execution plugins, and contract serialization arrive in later
+milestones.
+
+See the [hosted documentation](https://pipelantic.readthedocs.io/) for the
+full design,
+[CHANGELOG.md](CHANGELOG.md) for release notes, and
+[Roadmap](docs/11_DEVELOPMENT/ROADMAP.md) for sequencing.
+
+## Install
+
+```bash
+pip install pipelantic
+# or
+uv add pipelantic
+```
+
+### Development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+```
+
+`uv sync` creates `.venv`, installs the package in editable mode, and installs
+the `dev` dependency group (pytest, ruff, mkdocs) by default.
+
+## Release
+
+Tag a version that matches `src/pipelantic/_version.py`, then push the tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+GitHub Actions runs checks and publishes to PyPI using the `PYPI_API_TOKEN`
+repository secret.
+
+## Quick example
+
+```python
+from contractmodel import ContractModel as DataContractModel
+from pipelantic import Input, Output, Pipeline, Sink, Source, Transformation
+
+
+class RawCustomer(DataContractModel):
+    customer_id: int
+    first_name: str
+    last_name: str
+
+
+class Customer(DataContractModel):
+    customer_id: int
+    full_name: str
+
+
+class NormalizeCustomers(Transformation):
+    customers: Input[RawCustomer]
+    result: Output[Customer]
+
+
+class CustomerPipeline(Pipeline):
+    raw: Source[RawCustomer] = Source(binding="customer_source")
+    normalized = NormalizeCustomers.step(customers=raw)
+    curated: Sink[Customer] = Sink(
+        input=normalized.result,
+        binding="customer_sink",
+    )
+
+
+graph = CustomerPipeline.inspect()
+report = CustomerPipeline.validate()
+print(CustomerPipeline.to_mermaid())
+```
+
+## Documentation
+
+- [Documentation site](https://pipelantic.readthedocs.io/)
+- [Getting Started](docs/01_GETTING_STARTED/README.md)
+- [Core Concepts](docs/02_FOUNDATIONS/CORE_CONCEPTS.md)
+- [Architecture](docs/02_FOUNDATIONS/ARCHITECTURE.md)
+- [Roadmap](docs/11_DEVELOPMENT/ROADMAP.md)
+
+## License
+
+MIT

pipelantic-0.1.0/SECURITY.md

@@ -0,0 +1,57 @@
+# Security Policy
+
+Pipelantic 0.1 publishes the typed modeling kernel. Security reports
+concerning the published package, documentation, proposed APIs, repository
+automation, or later milestones are welcome.
+
+## Reporting a Vulnerability
+
+Do not open a public issue for:
+
+- credential exposure
+- arbitrary code execution
+- unsafe contract or configuration parsing
+- path traversal
+- server-side request forgery
+- plugin supply-chain vulnerabilities
+- injection vulnerabilities
+- cross-tenant artifact or cache exposure
+
+Until a private reporting address or GitHub private vulnerability reporting is
+configured, contact the repository owner privately through an available
+verified channel and include:
+
+- affected component
+- impact
+- reproduction steps
+- relevant configuration
+- suggested mitigation, when known
+
+Do not include production secrets, customer data, or regulated records.
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| 0.1.x | Best-effort while the modeling kernel is in alpha |
+| earlier | Not supported |
+
+A formal security patch policy will be published before 1.0.
+
+## Security Model
+
+The project threat model and production-readiness requirements are documented
+in [docs/02_FOUNDATIONS/SECURITY.md](docs/02_FOUNDATIONS/SECURITY.md).
+
+## Disclosure
+
+The project intends to use coordinated disclosure:
+
+1. Confirm receipt privately.
+2. Validate and assess severity.
+3. Develop and test a fix.
+4. Prepare an advisory and upgrade guidance.
+5. Release the fix before public technical details.
+
+Response targets and a formal private reporting mechanism must be established
+before Pipelantic is declared production-ready.

pipelantic-0.1.0/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "pipelantic"
+version = "0.1.0"
+description = "Typed, contract-driven data pipeline modeling for Python."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Odo Matthews", email = "odosmatthews@gmail.com" }]
+keywords = ["pipelines", "etl", "data-contracts", "typed", "pydantic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "contractmodel>=0.1.2",
+    "pydantic>=2.12,<3",
+    "packaging>=24",
+]
+
+[project.urls]
+Homepage = "https://github.com/eddiethedean/pipelantic"
+Documentation = "https://github.com/eddiethedean/pipelantic/tree/main/docs"
+Repository = "https://github.com/eddiethedean/pipelantic"
+Issues = "https://github.com/eddiethedean/pipelantic/issues"
+Changelog = "https://github.com/eddiethedean/pipelantic/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.6,<10",
+    "mkdocstrings[python]>=0.29,<1",
+    "pymdown-extensions>=10.14,<11",
+    "pytest>=8,<9",
+    "ruff>=0.9,<1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipelantic"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/pipelantic",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/CHANGELOG.md",
+    "/SECURITY.md",
+    "/pyproject.toml",
+]
+
+[tool.uv]
+package = true
+default-groups = ["dev"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+src = ["src", "tests"]
+exclude = [
+    ".git",
+    ".venv",
+    ".ruff_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+ignore = [
+    "E501",  # line length handled by formatter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pipelantic"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true

pipelantic-0.1.0/src/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-0.1.0/src/pipelantic/_version.py

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

pipelantic-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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."""