katalyst-engine 2.1.0__tar.gz

katalyst_engine-2.1.0/.gitignore

@@ -0,0 +1,104 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+*.local
+
+# Browser/Playwright state files
+browser-state-*.json
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/

katalyst_engine-2.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: katalyst-engine
+Version: 2.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
+License: Proprietary
+Keywords: declaration,engine,evolvable,graph,primitives,registry,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# katalyst-engine
+
+A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs.
+
+## Status
+
+**Alpha** — Engine Phase 1 (`core/` primitives) is implemented.
+
+## Install
+
+```bash
+pip install katalyst-engine
+```
+
+## Core Primitives
+
+- **Evolvable** — identity + version + lifecycle + compatibility contract
+- **Definitive** — describes the structure/constraints of other Evolvables
+- **Compositional** — groups/contains other Evolvables
+- **Relation** — typed, directed, versioned edge between two Evolvables
+
+```python
+from katalyst_engine.core import Identity, Version, Evolvable, Lifecycle
+
+node = Evolvable(
+    identity=Identity(kind="system", name="backend", namespace="org"),
+    version=Version(major=1),
+    lifecycle=Lifecycle.STABLE,
+)
+print(node.fqn)  # "org.backend"
+```

katalyst_engine-2.1.0/README.md

@@ -0,0 +1,31 @@
+# katalyst-engine
+
+A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs.
+
+## Status
+
+**Alpha** — Engine Phase 1 (`core/` primitives) is implemented.
+
+## Install
+
+```bash
+pip install katalyst-engine
+```
+
+## Core Primitives
+
+- **Evolvable** — identity + version + lifecycle + compatibility contract
+- **Definitive** — describes the structure/constraints of other Evolvables
+- **Compositional** — groups/contains other Evolvables
+- **Relation** — typed, directed, versioned edge between two Evolvables
+
+```python
+from katalyst_engine.core import Identity, Version, Evolvable, Lifecycle
+
+node = Evolvable(
+    identity=Identity(kind="system", name="backend", namespace="org"),
+    version=Version(major=1),
+    lifecycle=Lifecycle.STABLE,
+)
+print(node.fqn)  # "org.backend"
+```

katalyst_engine-2.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "katalyst-engine"
+version = "2.1.0"
+description = "A distributed declaration framework — primitives for schema-aware, multi-source, evolvable artifact graphs"
+readme = "README.md"
+license = { text = "Proprietary" }
+requires-python = ">=3.12"
+authors = [
+    { name = "eSimplicity" }
+]
+keywords = [
+    "engine", "primitives", "schema", "evolvable",
+    "declaration", "graph", "registry",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/esimplicityinc/katalyst-taxonomy"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/katalyst_engine"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.5",
+    "pyright>=1.1",
+]
+
+[tool.pytest.ini_options]
+addopts = ["-ra", "--cov-report=term-missing"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+
+[tool.coverage.run]
+branch = true
+source = ["src/katalyst_engine"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

katalyst_engine-2.1.0/src/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-2.1.0/src/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-2.1.0/src/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-2.1.0/src/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)