katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/__init__.py

@@ -0,0 +1,6 @@
+"""katalyst-engine — A distributed declaration framework.
+
+Primitives for schema-aware, multi-source, evolvable artifact graphs.
+"""
+
+__version__ = "0.1.0"

katalyst_engine/bundle/__init__.py

@@ -0,0 +1,30 @@
+"""Bundle — standard packaging for node type registration.
+
+A Bundle is a self-describing unit that contributes node types, wing
+definitions, and schema metadata to the engine. Bundles are discovered
+via Python entry points and registered with a SchemaManager.
+"""
+
+from katalyst_engine.bundle.discovery import (
+    BUNDLE_ENTRY_POINT_GROUP,
+    BundleDiscovery,
+    DiscoveredBundle,
+)
+from katalyst_engine.bundle.loader import BundleLoader
+from katalyst_engine.bundle.protocol import (
+    Bundle,
+    BundleManifest,
+    get_creation_templates,
+    get_scaffold_templates,
+)
+
+__all__ = [
+    "BUNDLE_ENTRY_POINT_GROUP",
+    "Bundle",
+    "BundleDiscovery",
+    "BundleLoader",
+    "BundleManifest",
+    "DiscoveredBundle",
+    "get_creation_templates",
+    "get_scaffold_templates",
+]

katalyst_engine/bundle/discovery.py

@@ -0,0 +1,158 @@
+"""Bundle discovery — find bundles via Python entry points.
+
+Scans ``importlib.metadata`` entry points in the
+``katalyst_engine.bundles`` group to discover installed bundles.
+Each entry point should point to a callable that returns a Bundle
+instance (typically the Bundle class itself).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from dataclasses import dataclass, field
+
+from katalyst_engine.bundle.protocol import Bundle
+
+logger = logging.getLogger(__name__)
+
+#: Default entry point group for bundle discovery.
+BUNDLE_ENTRY_POINT_GROUP = "katalyst_engine.bundles"
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredBundle:
+    """Metadata about a discovered (but not yet loaded) bundle.
+
+    Represents the location of a bundle found during entry point
+    scanning. The ``load()`` method instantiates the actual Bundle.
+    """
+
+    name: str
+    """Entry point name (e.g. "forge")."""
+
+    entry_point: str
+    """Dotted module path (e.g. "katalyst_taxonomy.bundles.forge:ForgeBundle")."""
+
+    group: str = BUNDLE_ENTRY_POINT_GROUP
+    """Entry point group this was discovered from."""
+
+    def load(self) -> Bundle:
+        """Load and instantiate the bundle from its entry point.
+
+        The entry point must be a callable that returns a Bundle
+        instance. If it's a class, it will be instantiated with
+        no arguments.
+
+        Raises:
+            ImportError: If the module cannot be imported.
+            TypeError: If the loaded object is not a valid Bundle.
+        """
+        module_path, _, attr_name = self.entry_point.rpartition(":")
+        if not attr_name:
+            # Entry point format is "module.path" (no colon)
+            module_path = self.entry_point
+            attr_name = ""
+
+        module = importlib.import_module(module_path)
+        if attr_name:
+            factory = getattr(module, attr_name)
+        else:
+            factory = module
+
+        # If it's a class, instantiate it; if callable, call it
+        if isinstance(factory, type):
+            return factory()  # type: ignore[return-value]
+        if callable(factory):
+            return factory()  # type: ignore[return-value]
+        # If it's already a Bundle instance, return it
+        return factory  # type: ignore[return-value]
+
+
+@dataclass(slots=True)
+class BundleDiscovery:
+    """Discovers bundles from Python entry points.
+
+    Scans the ``katalyst_engine.bundles`` entry point group to find
+    installed bundle packages. Results are cached after first scan.
+
+    Usage::
+
+        discovery = BundleDiscovery()
+        discovery.scan()  # or scan happens lazily on first access
+        for db in discovery.all():
+            bundle = db.load()
+            bundle.register(schema_manager)
+    """
+
+    _discovered: dict[str, DiscoveredBundle] = field(
+        default_factory=lambda: dict[str, DiscoveredBundle]()
+    )
+    _scanned: bool = False
+    group: str = BUNDLE_ENTRY_POINT_GROUP
+
+    def scan(self) -> None:
+        """Scan entry points for bundles.
+
+        Clears any previous results and re-scans. Uses
+        ``importlib.metadata.entry_points()`` to discover bundles.
+        """
+        self._discovered.clear()
+
+        try:
+            eps = importlib.metadata.entry_points(group=self.group)
+        except Exception:
+            logger.warning("Failed to scan entry points for group %s", self.group)
+            self._scanned = True
+            return
+
+        for ep in eps:
+            db = DiscoveredBundle(
+                name=ep.name,
+                entry_point=ep.value,
+                group=self.group,
+            )
+            self._discovered[ep.name] = db
+            logger.debug("Discovered bundle: %s -> %s", ep.name, ep.value)
+
+        self._scanned = True
+
+    def all(self) -> list[DiscoveredBundle]:
+        """Return all discovered bundles, sorted by name.
+
+        Triggers a scan if one hasn't happened yet.
+        """
+        if not self._scanned:
+            self.scan()
+        return sorted(self._discovered.values(), key=lambda db: db.name)
+
+    def get(self, name: str) -> DiscoveredBundle | None:
+        """Look up a discovered bundle by name.
+
+        Triggers a scan if one hasn't happened yet.
+        """
+        if not self._scanned:
+            self.scan()
+        return self._discovered.get(name)
+
+    @property
+    def count(self) -> int:
+        """Number of discovered bundles."""
+        if not self._scanned:
+            self.scan()
+        return len(self._discovered)
+
+    def add(self, bundle: DiscoveredBundle) -> None:
+        """Manually add a discovered bundle (for testing or explicit registration).
+
+        If no scan has happened yet, marks as scanned to prevent a
+        lazy scan from clearing manually-added entries.
+        """
+        if not self._scanned:
+            self._scanned = True
+        self._discovered[bundle.name] = bundle
+
+    def clear(self) -> None:
+        """Remove all discovered bundles and reset scan state."""
+        self._discovered.clear()
+        self._scanned = False

katalyst_engine/bundle/loader.py

@@ -0,0 +1,134 @@
+"""Bundle loader — discover and register all installed bundles.
+
+Provides a high-level ``load_bundles()`` function that discovers
+bundles via entry points, loads them, and registers them with
+a SchemaManager. This is the standard startup path for any
+application using the engine.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from katalyst_engine.bundle.discovery import BundleDiscovery, DiscoveredBundle
+from katalyst_engine.bundle.protocol import Bundle, BundleManifest
+from katalyst_engine.schema.manager import SchemaManager
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class BundleLoader:
+    """Loads and registers bundles with a SchemaManager.
+
+    Manages the lifecycle of bundle discovery → loading → registration.
+    Tracks which bundles have been loaded and their manifests.
+
+    Usage::
+
+        loader = BundleLoader(schema_manager)
+        loader.discover_and_register()
+        # Or manually:
+        loader.register(my_bundle)
+    """
+
+    manager: SchemaManager
+    """The SchemaManager to register bundles with."""
+
+    _loaded: dict[str, Bundle] = field(default_factory=lambda: dict[str, Bundle]())
+    _manifests: dict[str, BundleManifest] = field(
+        default_factory=lambda: dict[str, BundleManifest]()
+    )
+
+    def register(self, bundle: Bundle) -> BundleManifest:
+        """Register a single bundle with the SchemaManager.
+
+        Args:
+            bundle: A Bundle instance to register.
+
+        Returns:
+            The bundle's manifest.
+
+        Raises:
+            ValueError: If a bundle with the same identity is already loaded.
+        """
+        manifest = bundle.manifest
+        fqn = manifest.identity.fqn
+
+        if fqn in self._loaded:
+            raise ValueError(
+                f"Bundle already registered: {fqn!r}. "
+                f"Unregister it first or use a different identity."
+            )
+
+        bundle.register(self.manager)
+        self._loaded[fqn] = bundle
+        self._manifests[fqn] = manifest
+
+        logger.info(
+            "Registered bundle %r: %d kinds, %d wings",
+            fqn,
+            len(manifest.provided_kinds),
+            len(manifest.wing_names),
+        )
+
+        return manifest
+
+    def discover_and_register(
+        self,
+        discovery: BundleDiscovery | None = None,
+    ) -> list[BundleManifest]:
+        """Discover bundles via entry points and register them all.
+
+        Args:
+            discovery: Optional pre-configured BundleDiscovery.
+                If None, creates a new one and scans entry points.
+
+        Returns:
+            List of manifests for all successfully registered bundles.
+        """
+        if discovery is None:
+            discovery = BundleDiscovery()
+            discovery.scan()
+
+        manifests: list[BundleManifest] = []
+
+        for discovered in discovery.all():
+            try:
+                bundle = discovered.load()
+                manifest = self.register(bundle)
+                manifests.append(manifest)
+            except Exception:
+                logger.exception("Failed to load bundle %r", discovered.name)
+
+        return manifests
+
+    def register_discovered(self, discovered: DiscoveredBundle) -> BundleManifest:
+        """Load a single DiscoveredBundle and register it.
+
+        Args:
+            discovered: A discovered bundle to load and register.
+
+        Returns:
+            The bundle's manifest.
+        """
+        bundle = discovered.load()
+        return self.register(bundle)
+
+    def get_manifest(self, fqn: str) -> BundleManifest | None:
+        """Look up a loaded bundle's manifest by FQN."""
+        return self._manifests.get(fqn)
+
+    def all_manifests(self) -> list[BundleManifest]:
+        """Return all loaded bundle manifests, sorted by FQN."""
+        return sorted(self._manifests.values(), key=lambda m: m.identity.fqn)
+
+    def is_loaded(self, fqn: str) -> bool:
+        """Check if a bundle with the given FQN is loaded."""
+        return fqn in self._loaded
+
+    @property
+    def loaded_count(self) -> int:
+        """Number of loaded bundles."""
+        return len(self._loaded)

katalyst_engine/bundle/protocol.py

@@ -0,0 +1,209 @@
+"""Bundle protocol — the standard unit of schema packaging.
+
+A Bundle is a self-describing package of node types, wing definitions,
+and schema metadata that can be discovered and registered with the
+engine. Bundles are the mechanism by which different domains contribute
+their types to a shared engine.
+
+The Forge bundle for software delivery is one bundle. A security
+compliance package could be another. Each defines a ``Bundle`` class
+that the engine discovers via Python entry points.
+
+Bundles may optionally declare templates:
+
+- **Creation templates** — Jinja2-rendered YAML templates that produce the
+  taxonomy YAML document when a node of a given kind is created.
+- **Scaffold templates** — directory paths containing file trees that a
+  scaffolding plugin copies when a node with a scaffold variant is created.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, cast, runtime_checkable
+
+from pydantic import BaseModel
+
+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
+
+
+class BundleManifest(BaseModel, frozen=True):
+    """Immutable manifest describing what a bundle provides.
+
+    This is the metadata about a bundle — its identity, version,
+    what kinds it supplies, and what wings it defines. Used for
+    querying what's installed without loading the full definitions.
+    """
+
+    identity: Identity
+    """Unique identity of this bundle (kind="bundle", name="forge")."""
+
+    version: Version = Version()
+    """Version of this bundle."""
+
+    provided_kinds: frozenset[str] = frozenset()
+    """All node kinds this bundle registers."""
+
+    wing_names: frozenset[str] = frozenset()
+    """All wing names this bundle defines."""
+
+    description: str = ""
+    """Human-readable description of what this bundle provides."""
+
+    entry_point: str = ""
+    """The entry point string that loaded this bundle (if discovered)."""
+
+
+@runtime_checkable
+class Bundle(Protocol):
+    """Protocol for a registerable bundle of node types.
+
+    Any class that implements this protocol can be discovered and
+    registered with the engine. The engine discovers bundles via
+    Python entry points (``katalyst_engine.bundles`` group) or
+    explicit registration.
+
+    Minimal implementation::
+
+        class MyBundle:
+            @property
+            def manifest(self) -> BundleManifest:
+                return BundleManifest(
+                    identity=Identity(kind="bundle", name="my-bundle"),
+                    provided_kinds=frozenset({"widget", "gadget"}),
+                )
+
+            def node_definitions(self) -> list[NodeDefinition]:
+                return [WIDGET_DEF, GADGET_DEF]
+
+            def wing_definitions(self) -> list[WingDefinition]:
+                return [MY_WING_DEF]
+
+            def schema_definition(self) -> SchemaDefinition:
+                return SchemaDefinition(...)
+
+            def register(self, manager: SchemaManager) -> None:
+                manager.register_schema(
+                    self.schema_definition(),
+                    node_definitions=self.node_definitions(),
+                    wing_definitions=self.wing_definitions(),
+                )
+
+    Bundles may also provide ``relationship_definitions()`` for
+    relationship type classification::
+
+            def relationship_definitions(self) -> list[RelationshipDefinition]:
+                return [PARENT_REL, DEPENDS_ON_REL, ...]
+
+            def register(self, manager: SchemaManager) -> None:
+                manager.register_schema(
+                    self.schema_definition(),
+                    node_definitions=self.node_definitions(),
+                    wing_definitions=self.wing_definitions(),
+                    relationship_definitions=self.relationship_definitions(),
+                )
+
+    Bundles may optionally declare templates for creation and scaffolding::
+
+            def creation_templates(self) -> dict[str, str]:
+                return {"system": "<yaml template content>", ...}
+
+            def scaffold_templates(self) -> dict[str, Path]:
+                return {"layer:app-docker": Path("/path/to/scaffold/dir"), ...}
+    """
+
+    @property
+    def manifest(self) -> BundleManifest:
+        """Return the bundle's manifest describing what it provides."""
+        ...
+
+    def node_definitions(self) -> list[NodeDefinition]:
+        """Return all NodeDefinitions this bundle provides."""
+        ...
+
+    def wing_definitions(self) -> list[WingDefinition]:
+        """Return all WingDefinitions this bundle provides."""
+        ...
+
+    def schema_definition(self) -> SchemaDefinition:
+        """Return the SchemaDefinition for this bundle."""
+        ...
+
+    def register(self, manager: SchemaManager) -> None:
+        """Register this bundle's types with the given SchemaManager.
+
+        The default pattern is::
+
+            manager.register_schema(
+                self.schema_definition(),
+                node_definitions=self.node_definitions(),
+                wing_definitions=self.wing_definitions(),
+            )
+
+        Implementations may customize registration (e.g. conditional
+        registration, logging, event emission).
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Optional template accessors
+#
+# These are NOT part of the Bundle Protocol (adding them would make
+# isinstance(b, Bundle) fail for any bundle that does not implement them).
+# Instead, bundles that wish to declare templates do so by adding the
+# methods as duck-typed extras, and consumers use the helpers below.
+# ---------------------------------------------------------------------------
+
+
+def get_creation_templates(bundle: Any) -> dict[str, str]:
+    """Safely extract creation templates from a bundle.
+
+    Bundles that wish to provide creation templates implement a
+    ``creation_templates() -> dict[str, str]`` method. This helper
+    safely calls that method if present, returning an empty dict
+    otherwise.
+
+    Creation templates are Jinja2-rendered YAML templates that produce
+    the taxonomy YAML document when a node of a given kind is created.
+    The ``_base`` key is reserved for a fallback template.
+
+    Returns:
+        Mapping of node kind (or ``"_base"``) to Jinja2 template
+        content as a string. Empty dict if the bundle has no templates.
+    """
+    fn = getattr(bundle, "creation_templates", None)
+    if fn is not None and callable(fn):
+        return cast(dict[str, str], fn())
+    return {}
+
+
+def get_scaffold_templates(bundle: Any) -> dict[str, Path]:
+    """Safely extract scaffold templates from a bundle.
+
+    Bundles that wish to provide scaffold templates implement a
+    ``scaffold_templates() -> dict[str, Path]`` method. This helper
+    safely calls that method if present, returning an empty dict
+    otherwise.
+
+    Scaffold templates are directory paths containing file trees that
+    a scaffolding plugin copies when a node with a scaffold variant is
+    created. Keys use the format ``{kind}:{variant}`` — e.g.,
+    ``"layer:app-docker"``. For kind-only templates, use just the kind.
+
+    Returns:
+        Mapping of ``kind:variant`` (or just ``kind``) to the directory
+        ``Path`` containing the scaffold file tree. Empty dict if the
+        bundle has no scaffold templates.
+    """
+    fn = getattr(bundle, "scaffold_templates", None)
+    if fn is not None and callable(fn):
+        return cast(dict[str, Path], fn())
+    return {}

katalyst_engine/core/__init__.py

@@ -0,0 +1,62 @@
+"""katalyst-engine core primitives.
+
+This is the foundation of the engine. Every design decision here
+cascades through the entire library.
+
+The four root primitives:
+- Evolvable: identity + version + lifecycle + compatibility
+- Definitive: describes structure/constraints of OTHER things
+- Compositional: groups/contains other Evolvables
+- Relation: typed, directed, versioned edge between two Evolvables
+"""
+
+from katalyst_engine.core.compatibility import CompatibilityContract, MigrationPath
+from katalyst_engine.core.compositional import Compositional, MemberConstraint
+from katalyst_engine.core.definitive import (
+    Constraint,
+    ConstraintSeverity,
+    ConstraintViolation,
+    Definitive,
+    ValidationResult,
+)
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.lifecycle import Lifecycle, LifecyclePolicy
+from katalyst_engine.core.relation import (
+    Cardinality,
+    NodeSelector,
+    Relation,
+    RelationshipClaim,
+)
+from katalyst_engine.core.version import Version, VersionConstraint, VersionRange
+
+__all__ = [
+    # identity
+    "Identity",
+    # version
+    "Version",
+    "VersionRange",
+    "VersionConstraint",
+    # lifecycle
+    "Lifecycle",
+    "LifecyclePolicy",
+    # compatibility
+    "CompatibilityContract",
+    "MigrationPath",
+    # evolvable
+    "Evolvable",
+    # definitive
+    "Constraint",
+    "ConstraintSeverity",
+    "ConstraintViolation",
+    "Definitive",
+    "ValidationResult",
+    # compositional
+    "Compositional",
+    "MemberConstraint",
+    # relation
+    "Cardinality",
+    "NodeSelector",
+    "Relation",
+    "RelationshipClaim",
+]

katalyst_engine/core/compatibility.py

@@ -0,0 +1,58 @@
+"""Compatibility contracts and migration paths.
+
+Describes what guarantees a version makes about interoperability
+with other versions, and how to transform data between versions.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from katalyst_engine.core.version import Version
+
+
+class CompatibilityContract(BaseModel, frozen=True):
+    """Compatibility guarantees of a version.
+
+    Attached to every Evolvable. Describes whether old consumers
+    can work with this version and whether this version can
+    handle older data.
+
+    - backward_compatible: old consumers can read new data
+    - forward_compatible: new consumers can read old data
+    - breaking_changes: list of human-readable descriptions
+    """
+
+    backward_compatible: bool = True
+    forward_compatible: bool = False
+    breaking_changes: tuple[str, ...] = ()
+    notes: str = ""
+
+
+class MigrationPath(BaseModel, frozen=True):
+    """Links version N to version N+1 of an Evolvable.
+
+    The transform field is a string reference to a callable,
+    script, or module. The engine does not execute transforms —
+    consumers provide the runtime.
+
+    MigrationPaths form a directed graph that the schema versioning
+    layer uses to plan multi-step migrations (e.g. v1 → v2 → v3).
+    """
+
+    from_version: Version
+    to_version: Version
+    subject_kind: str
+    """The kind of Evolvable this migration applies to."""
+
+    transform: str
+    """Opaque reference to a callable/script that performs the migration."""
+
+    reversible: bool = False
+    """If True, the transform can be applied in reverse."""
+
+    compatibility: CompatibilityContract = CompatibilityContract()
+    """Compatibility guarantees of the target version after migration."""
+
+    validation_steps: tuple[str, ...] = ()
+    """Opaque references to validation callables run after migration."""