katalyst-engine 3.0.0__tar.gz → 3.1.0__tar.gz

katalyst_engine-3.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog — katalyst-engine
+
+All notable changes to the **katalyst-engine** modeling core are 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).
+
+This package is released independently from `katalyst-taxonomy` and the other
+workspace packages. Tags use the `engine-vX.Y.Z` prefix.
+
+---
+
+## [3.1.0] -- 2026-06-11
+
+### Added
+- **Path-based bundle loading** (`katalyst_engine.bundle.path_loader`) — load a `Bundle` from an arbitrary filesystem path via `importlib.util.spec_from_file_location`, with an engine-only dependency gate (`enforce_engine_only_deps`) that rejects any declared dependency other than `katalyst-engine` before importing. Supports remote/on-demand bundles installed without modifying the environment.
+
+## [3.0.0] -- 2026-06-10
+
+### Changed
+- Baseline for independent per-package releases. No engine source changes since the lockstep `v3.0.0` release; this entry establishes the engine package's own version line going forward.
+
+---
+
+> Versions prior to 3.0.0 were released in lockstep with `katalyst-taxonomy`
+> under the umbrella `vX.Y.Z` tags. See the root `CHANGELOG.md` for that history.

{katalyst_engine-3.0.0 → katalyst_engine-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-engine
-Version: 3.0.0
+Version: 3.1.0
 Summary: A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs
 Project-URL: Repository, https://github.com/esimplicityinc/katalyst-taxonomy
 Author: eSimplicity

{katalyst_engine-3.0.0 → katalyst_engine-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-engine"
-version = "3.0.0"
+version = "3.1.0"
 description = "A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs"
 readme = "README.md"
 license = { text = "Proprietary" }

katalyst_engine-3.1.0/src/katalyst_engine/bundle/path_loader.py

@@ -0,0 +1,180 @@
+"""Path-based bundle loading + dependency gating.
+
+This module is the ONLY place in the engine that imports a bundle from an
+arbitrary filesystem path (via ``importlib.util.spec_from_file_location``)
+rather than from an installed, ``sys.path``-importable distribution.
+
+It supports loading "remote" bundles that have been fetched to a local
+directory (PyPI wheel, git checkout, URL tarball) WITHOUT installing them
+into the active environment. Two guardrails apply before any of the
+bundle's own code executes:
+
+1. **Declared-dependency gate** (:func:`enforce_engine_only_deps`): the
+   fetched artifact's declared dependencies must contain nothing other
+   than ``katalyst-engine``. This is checked *before* import.
+2. **Import-time backstop**: an undeclared third-party import surfaces as
+   an :class:`ImportError` at load time with a clear message.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from katalyst_engine.bundle.protocol import Bundle
+
+#: The only distribution a remote bundle may depend on.
+ALLOWED_DEPENDENCIES: frozenset[str] = frozenset({"katalyst-engine"})
+
+
+class BundleDependencyError(ValueError):
+    """Raised when a fetched bundle declares disallowed dependencies."""
+
+
+class BundleLoadError(ValueError):
+    """Raised when a fetched bundle cannot be path-imported or is not a Bundle."""
+
+
+def _normalize_dist_name(requirement: str) -> str:
+    """Extract the bare distribution name from a requirement string.
+
+    Handles forms like ``"katalyst-engine>=3.0,<4"``, ``"foo[extra]>=1"``,
+    ``"bar ; python_version>='3.10'"``, and normalizes underscores/case.
+    Returns "" for entries that are not real runtime requirements (e.g.
+    blank lines or extras-only markers we can't attribute to a dist).
+    """
+    req = requirement.strip()
+    if not req:
+        return ""
+    # Drop environment markers (after ';')
+    req = req.split(";", 1)[0].strip()
+    # Cut at the first version/extras/space specifier character.
+    for sep in ("[", "(", "<", ">", "=", "!", "~", " "):
+        idx = req.find(sep)
+        if idx != -1:
+            req = req[:idx]
+    return req.strip().replace("_", "-").lower()
+
+
+def enforce_engine_only_deps(declared_dependencies: list[str]) -> None:
+    """Reject a bundle whose declared deps include anything but the allow-list.
+
+    Args:
+        declared_dependencies: Requirement strings parsed from the fetched
+            artifact's metadata (wheel ``Requires-Dist`` or pyproject
+            ``[project.dependencies]``).
+
+    Raises:
+        BundleDependencyError: If any declared dependency names a
+            distribution other than ``katalyst-engine``.
+    """
+    allowed = {name.replace("_", "-").lower() for name in ALLOWED_DEPENDENCIES}
+    disallowed: list[str] = []
+    for raw in declared_dependencies:
+        name = _normalize_dist_name(raw)
+        if not name:
+            continue
+        if name not in allowed:
+            disallowed.append(raw.strip())
+    if disallowed:
+        raise BundleDependencyError(
+            "Remote bundle declares disallowed dependencies "
+            f"{disallowed!r}; bundles may depend only on {sorted(allowed)!r}."
+        )
+
+
+def _instantiate(factory: object) -> object:
+    """Apply the DiscoveredBundle.load() instantiation contract.
+
+    If the attribute is a class or callable, call it with no args; if it is
+    already a Bundle instance, return it. Returns ``object`` so the caller's
+    ``isinstance(..., Bundle)`` check is meaningful.
+    """
+    if isinstance(factory, type):
+        return factory()
+    if callable(factory):
+        return factory()
+    return factory
+
+
+@dataclass(frozen=True, slots=True)
+class PathImportTarget:
+    """Where to find a bundle within a fetched directory.
+
+    ``module_file`` is the absolute path to the Python file that defines
+    (or re-exports) the bundle. ``attr`` is the attribute name to read from
+    the imported module (the Bundle class or factory). If ``attr`` is empty,
+    the module object itself is treated as the bundle factory.
+    """
+
+    module_file: Path
+    attr: str = ""
+
+    @classmethod
+    def parse(cls, spec: str, *, base_dir: Path) -> PathImportTarget:
+        """Parse an ``import_target`` string ("rel/mod.py:Attr") against base_dir."""
+        rel, _, attr = spec.partition(":")
+        module_file = (base_dir / rel).resolve()
+        return cls(module_file=module_file, attr=attr)
+
+    def to_spec(self, *, base_dir: Path) -> str:
+        """Render this target back to a relative ``import_target`` string."""
+        rel = self.module_file.resolve().relative_to(base_dir.resolve())
+        return f"{rel}:{self.attr}" if self.attr else str(rel)
+
+
+def load_bundle_from_path(target: PathImportTarget) -> Bundle:
+    """Path-import a module and return its Bundle instance.
+
+    This is the engine's only use of ``spec_from_file_location``. The
+    module's parent directory is temporarily placed on ``sys.path`` so the
+    bundle's intra-package imports (``import my_bundle.wings``) resolve.
+
+    Raises:
+        BundleLoadError: If the file cannot be imported or the resulting
+            object does not satisfy the :class:`Bundle` protocol.
+    """
+    module_file = target.module_file
+    if not module_file.is_file():
+        raise BundleLoadError(f"Bundle module file not found: {module_file}")
+
+    # Derive a stable, unique module name from the file path.
+    module_name = f"_katalyst_remote_bundle_{abs(hash(str(module_file)))}"
+    package_root = module_file.parent.parent  # so "pkg.module" imports work
+    added_to_path = False
+    if str(package_root) not in sys.path:
+        sys.path.insert(0, str(package_root))
+        added_to_path = True
+    try:
+        spec = importlib.util.spec_from_file_location(module_name, module_file)
+        if spec is None or spec.loader is None:
+            raise BundleLoadError(f"Could not create import spec for {module_file}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        try:
+            spec.loader.exec_module(module)
+        except ImportError as exc:
+            raise BundleLoadError(
+                f"Failed to import bundle from {module_file}: {exc}. "
+                "Remote bundles may depend only on katalyst-engine."
+            ) from exc
+        if target.attr:
+            if not hasattr(module, target.attr):
+                raise BundleLoadError(
+                    f"Bundle module {module_file} has no attribute {target.attr!r}"
+                )
+            factory = getattr(module, target.attr)
+        else:
+            factory = module
+        bundle = _instantiate(factory)
+        if not isinstance(bundle, Bundle):
+            raise BundleLoadError(
+                f"Object loaded from {module_file} (attr={target.attr!r}) "
+                "does not satisfy the Bundle protocol."
+            )
+        return bundle
+    finally:
+        if added_to_path and str(package_root) in sys.path:
+            sys.path.remove(str(package_root))

katalyst_engine-3.1.0/tests/bundle/test_path_loader.py

@@ -0,0 +1,136 @@
+"""Tests for path-based bundle loading and the engine-only dependency gate."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from katalyst_engine.bundle.path_loader import (
+    BundleDependencyError,
+    BundleLoadError,
+    PathImportTarget,
+    enforce_engine_only_deps,
+    load_bundle_from_path,
+)
+
+
+class TestDependencyGate:
+    def test_allows_engine_only(self) -> None:
+        enforce_engine_only_deps(["katalyst-engine>=3.0,<4"])
+
+    def test_allows_empty(self) -> None:
+        enforce_engine_only_deps([])
+
+    def test_normalizes_underscores_and_case(self) -> None:
+        enforce_engine_only_deps(["Katalyst_Engine >= 3.0"])
+
+    def test_rejects_third_party(self) -> None:
+        with pytest.raises(BundleDependencyError) as exc:
+            enforce_engine_only_deps(["katalyst-engine>=3.0", "pandas>=2.0"])
+        assert "pandas" in str(exc.value)
+
+    def test_ignores_marker_only_extras(self) -> None:
+        # A requirement gated entirely by an environment marker still names a
+        # disallowed dist, so it should be rejected.
+        with pytest.raises(BundleDependencyError):
+            enforce_engine_only_deps(["requests; python_version >= '3.10'"])
+
+
+def _write_bundle(root: Path, *, deps: str = '"katalyst-engine>=3.0,<4"') -> PathImportTarget:
+    pkg = root / "src" / "demo_bundle"
+    pkg.mkdir(parents=True)
+    (pkg / "__init__.py").write_text("")
+    (pkg / "bundle.py").write_text(
+        textwrap.dedent(
+            """
+            from katalyst_engine.bundle.protocol import BundleManifest
+            from katalyst_engine.core.identity import Identity
+            from katalyst_engine.core.version import Version
+            from katalyst_engine.schema.definition import (
+                NodeDefinition, SchemaDefinition, WingDefinition,
+            )
+            from katalyst_engine.schema.manager import SchemaManager
+
+            NODE = NodeDefinition(
+                identity=Identity(kind="node_definition", name="demo_thing"),
+                describes_kind="demo_thing",
+                wing="demo",
+                display_order=900,
+                directory_name="demo_things",
+                is_root=True,
+                is_leaf=True,
+                is_extension=False,
+                scaffoldable=False,
+                clonable=False,
+                display_label="Demo Thing",
+                display_label_plural="Demo Things",
+            )
+            WING = WingDefinition(
+                identity=Identity(kind="wing", name="demo"),
+                describes_kind="demo",
+                display_order=900,
+            )
+
+            class DemoBundle:
+                @property
+                def manifest(self) -> BundleManifest:
+                    return BundleManifest(
+                        identity=Identity(kind="bundle", name="demo"),
+                        version=Version(major=1),
+                        provided_kinds=frozenset({"demo_thing"}),
+                        wing_names=frozenset({"demo"}),
+                    )
+                def node_definitions(self): return [NODE]
+                def wing_definitions(self): return [WING]
+                def schema_definition(self):
+                    return SchemaDefinition(
+                        identity=Identity(kind="schema", name="demo"),
+                        describes_kind="taxonomy",
+                        api_version="v2alpha",
+                        schema_version=Version(major=1),
+                        node_definitions=(NODE.identity,),
+                        wing_definitions=(WING.identity,),
+                    )
+                def register(self, manager: SchemaManager) -> None:
+                    manager.register_schema(
+                        self.schema_definition(),
+                        node_definitions=self.node_definitions(),
+                        wing_definitions=self.wing_definitions(),
+                    )
+            """
+        )
+    )
+    return PathImportTarget(module_file=pkg / "bundle.py", attr="DemoBundle")
+
+
+class TestPathImport:
+    def test_loads_valid_bundle(self, tmp_path: Path) -> None:
+        target = _write_bundle(tmp_path)
+        bundle = load_bundle_from_path(target)
+        assert bundle.manifest.identity.name == "demo"
+        assert "demo_thing" in bundle.manifest.provided_kinds
+
+    def test_missing_file_raises(self, tmp_path: Path) -> None:
+        with pytest.raises(BundleLoadError):
+            load_bundle_from_path(PathImportTarget(module_file=tmp_path / "nope.py", attr="X"))
+
+    def test_missing_attr_raises(self, tmp_path: Path) -> None:
+        target = _write_bundle(tmp_path)
+        with pytest.raises(BundleLoadError):
+            load_bundle_from_path(PathImportTarget(module_file=target.module_file, attr="Nope"))
+
+    def test_non_bundle_object_raises(self, tmp_path: Path) -> None:
+        mod = tmp_path / "plain.py"
+        mod.parent.mkdir(parents=True, exist_ok=True)
+        mod.write_text("VALUE = 42\n")
+        with pytest.raises(BundleLoadError):
+            load_bundle_from_path(PathImportTarget(module_file=mod, attr="VALUE"))
+
+    def test_import_target_round_trip(self, tmp_path: Path) -> None:
+        target = _write_bundle(tmp_path)
+        spec = target.to_spec(base_dir=tmp_path)
+        parsed = PathImportTarget.parse(spec, base_dir=tmp_path)
+        assert parsed.module_file == target.module_file
+        assert parsed.attr == target.attr