katalyst-engine 2.0.0__py3-none-any.whl

katalyst_engine/extensions/capability.py

@@ -0,0 +1,45 @@
+"""Capabilities and extensions — what plugins can do.
+
+A Capability describes a named ability. An Extension is the base
+Evolvable for plugins, declaring what capabilities it provides.
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.core.evolvable import Evolvable
+
+
+class Capability(Evolvable, frozen=True):
+    """Describes what an extension can do.
+
+    Capabilities are named abilities that extensions declare.
+    The ExtensionRegistry indexes extensions by their capabilities,
+    enabling lookup like "find all extensions that can export data".
+    """
+
+    description: str = ""
+    """Human-readable description of this capability."""
+
+    category: str = ""
+    """Grouping category (e.g. "discovery", "export", "validation")."""
+
+
+class Extension(Evolvable, frozen=True):
+    """Base Evolvable for plugins/extensions.
+
+    An Extension declares its capabilities and provides metadata
+    about itself. Concrete extension types (Provider, Effector)
+    add behavior via ABCs.
+    """
+
+    capabilities: tuple[str, ...] = ()
+    """Capability names this extension provides."""
+
+    description: str = ""
+    """Human-readable description of this extension."""
+
+    entry_point: str = ""
+    """Opaque reference to the extension's entry point (module path, URI, etc.)."""
+
+    enabled: bool = True
+    """Whether this extension is active."""

katalyst_engine/extensions/discovery.py

@@ -0,0 +1,85 @@
+"""Extension discovery — find extensions from entry points and directories.
+
+Pure model for representing discovered extension locations. Actual
+I/O (scanning entry points, reading directories) is done by adapters.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ExtensionSourceKind(str, Enum):
+    """Where an extension was discovered from."""
+
+    ENTRY_POINT = "entry_point"
+    DIRECTORY = "directory"
+    INLINE = "inline"
+
+
+class DiscoveredExtension(BaseModel, frozen=True):
+    """Metadata about a discovered (but not yet loaded) extension.
+
+    Represents the location and kind of an extension found during
+    scanning. Loading and instantiation happens in the adapter layer.
+    """
+
+    name: str
+    """Human-readable name of the extension."""
+
+    source_kind: ExtensionSourceKind
+    """How the extension was found."""
+
+    location: str
+    """Path, module path, or entry point string."""
+
+    group: str = ""
+    """Entry point group, if applicable."""
+
+    metadata: dict[str, str] = {}
+    """Additional metadata about the extension."""
+
+
+class ExtensionDiscovery:
+    """Collects and deduplicates discovered extension descriptors.
+
+    This is an in-memory collector. Adapters push DiscoveredExtension
+    instances into it; the ExtensionRegistry uses the results to
+    load and register actual Extensions.
+
+    Usage:
+        discovery = ExtensionDiscovery()
+        discovery.add(DiscoveredExtension(name="neo4j-export", ...))
+        for ext in discovery.all():
+            # load and register
+    """
+
+    def __init__(self) -> None:
+        self._discovered: dict[str, DiscoveredExtension] = {}  # keyed by name
+
+    def add(self, ext: DiscoveredExtension) -> None:
+        """Add a discovered extension. Last-write-wins on name collision."""
+        self._discovered[ext.name] = ext
+
+    def get(self, name: str) -> DiscoveredExtension | None:
+        """Look up a discovered extension by name."""
+        return self._discovered.get(name)
+
+    def all(self) -> list[DiscoveredExtension]:
+        """Return all discovered extensions, sorted by name."""
+        return sorted(self._discovered.values(), key=lambda e: e.name)
+
+    def by_source_kind(self, kind: ExtensionSourceKind) -> list[DiscoveredExtension]:
+        """Return extensions discovered from a specific source kind."""
+        return [e for e in self._discovered.values() if e.source_kind == kind]
+
+    @property
+    def count(self) -> int:
+        """Number of discovered extensions."""
+        return len(self._discovered)
+
+    def clear(self) -> None:
+        """Remove all discovered extensions."""
+        self._discovered.clear()

katalyst_engine/extensions/effector.py

@@ -0,0 +1,54 @@
+"""Effector — abstract base for extensions that produce side effects.
+
+Effectors are triggered by events and execute actions such as
+exporting data, sending notifications, or running validations.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+from katalyst_engine.extensions.capability import Extension
+
+
+class EffectResult(BaseModel, frozen=True):
+    """Result of an effector execution.
+
+    Captures whether the effect succeeded, any error message,
+    and optional output data.
+    """
+
+    success: bool = True
+    """Whether the effect executed successfully."""
+
+    error: str = ""
+    """Error message if the effect failed."""
+
+    output: dict[str, Any] = {}
+    """Optional output data from the effect."""
+
+
+class Effector(Extension, ABC, frozen=True):
+    """Abstract base for extensions that produce side effects.
+
+    Effectors are triggered by events or explicit invocations.
+    They perform actions like exporting data, sending notifications,
+    or writing to external systems.
+
+    The execute method is abstract — concrete effectors must
+    implement it.
+    """
+
+    @abstractmethod
+    def execute(self, context: dict[str, Any]) -> EffectResult:
+        """Execute this effector's side effect.
+
+        Args:
+            context: Key-value data providing context for the effect.
+
+        Returns:
+            An EffectResult describing the outcome.
+        """

katalyst_engine/extensions/provider.py

@@ -0,0 +1,33 @@
+"""Provider — abstract base for extensions that bring data in.
+
+Providers are the discovery side of the extension system. They
+know how to find declarations from a specific kind of source.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from katalyst_engine.discovery.declaration import Declaration
+from katalyst_engine.extensions.capability import Extension
+
+
+class Provider(Extension, ABC, frozen=True):
+    """Abstract base for extensions that bring data into the engine.
+
+    Providers discover declarations from external sources. Each
+    Provider implementation knows how to read from one kind of
+    source (filesystem, API, database, etc.).
+
+    The discover method is abstract — concrete providers must
+    implement it. The engine never does I/O directly; Providers
+    encapsulate all I/O.
+    """
+
+    @abstractmethod
+    def discover(self) -> list[Declaration]:
+        """Discover declarations from this provider's source.
+
+        Returns:
+            List of discovered Declarations.
+        """

katalyst_engine/extensions/registry.py

@@ -0,0 +1,77 @@
+"""Extension registry — register and look up extensions by capability.
+
+Central index for discovering extensions that provide specific
+capabilities.
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.extensions.capability import Extension
+
+
+class ExtensionRegistry:
+    """Registry of extensions indexed by capability.
+
+    Provides registration, lookup by capability name, and
+    iteration over all registered extensions.
+
+    Usage:
+        registry = ExtensionRegistry()
+        registry.register(my_provider)
+        providers = registry.by_capability("discover")
+    """
+
+    def __init__(self) -> None:
+        self._extensions: dict[str, Extension] = {}  # keyed by fqn
+        self._by_capability: dict[str, list[Extension]] = {}
+
+    def register(self, extension: Extension) -> None:
+        """Register an extension, indexing it by its declared capabilities."""
+        fqn = extension.identity.fqn
+        self._extensions[fqn] = extension
+
+        for cap in extension.capabilities:
+            if cap not in self._by_capability:
+                self._by_capability[cap] = []
+            self._by_capability[cap].append(extension)
+
+    def unregister(self, extension: Extension) -> bool:
+        """Remove an extension. Returns True if it existed."""
+        fqn = extension.identity.fqn
+        if fqn not in self._extensions:
+            return False
+
+        del self._extensions[fqn]
+
+        for cap in extension.capabilities:
+            cap_list = self._by_capability.get(cap)
+            if cap_list is not None:
+                cap_list[:] = [e for e in cap_list if e.identity.fqn != fqn]
+
+        return True
+
+    def get(self, fqn: str) -> Extension | None:
+        """Look up an extension by FQN."""
+        return self._extensions.get(fqn)
+
+    def by_capability(self, capability: str) -> list[Extension]:
+        """Return all extensions providing a given capability."""
+        return list(self._by_capability.get(capability, []))
+
+    def all_extensions(self) -> list[Extension]:
+        """Return all registered extensions, ordered by FQN."""
+        return sorted(self._extensions.values(), key=lambda e: e.identity.fqn)
+
+    def all_capabilities(self) -> list[str]:
+        """Return all known capability names, sorted."""
+        return sorted(self._by_capability.keys())
+
+    @property
+    def count(self) -> int:
+        """Number of registered extensions."""
+        return len(self._extensions)
+
+    def clear(self) -> None:
+        """Remove all extensions."""
+        self._extensions.clear()
+        self._by_capability.clear()

katalyst_engine/extensions/trigger.py

@@ -0,0 +1,64 @@
+"""Triggers — event patterns and conditions for effector activation.
+
+A Trigger matches events by type pattern and optional conditions.
+TriggerContext carries the data passed to effectors when triggered.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from katalyst_engine.events.event import Event
+
+
+class Trigger(BaseModel, frozen=True):
+    """Describes when an effector should fire.
+
+    Matches events by type pattern (glob) and optional conditions
+    on event properties.
+    """
+
+    event_type_pattern: str
+    """Glob pattern matching event type strings (e.g. "model.node.*")."""
+
+    conditions: dict[str, str] = {}
+    """Key-value conditions on event properties. All must match."""
+
+    description: str = ""
+    """Human-readable description of when this trigger fires."""
+
+    def matches(self, event: Event) -> bool:
+        """Check if an event matches this trigger's pattern and conditions.
+
+        Uses fnmatch for the event type pattern and exact matching
+        for property conditions.
+        """
+        from fnmatch import fnmatch
+
+        if not fnmatch(event.type.value, self.event_type_pattern):
+            return False
+
+        for key, value in self.conditions.items():
+            if str(event.properties.get(key, "")) != value:
+                return False
+
+        return True
+
+
+class TriggerContext(BaseModel, frozen=True):
+    """Data passed to effectors when a trigger fires.
+
+    Carries the triggering event plus any additional contextual
+    data the engine wants to provide.
+    """
+
+    event: Event
+    """The event that caused the trigger to fire."""
+
+    trigger: Trigger
+    """The trigger that matched."""
+
+    extra: dict[str, Any] = {}
+    """Additional context data."""

katalyst_engine/model/__init__.py

@@ -0,0 +1,25 @@
+"""Model — nodes, store, materialization, and queries."""
+
+from katalyst_engine.model.manager import ModelManager
+from katalyst_engine.model.materializer import RelationshipMaterializer
+from katalyst_engine.model.node import Node
+from katalyst_engine.model.query import (
+    QueryEngine,
+    QueryFilter,
+    QueryResult,
+    SortField,
+    SortOrder,
+)
+from katalyst_engine.model.store import ModelStore
+
+__all__ = [
+    "ModelManager",
+    "ModelStore",
+    "Node",
+    "QueryEngine",
+    "QueryFilter",
+    "QueryResult",
+    "RelationshipMaterializer",
+    "SortField",
+    "SortOrder",
+]

katalyst_engine/model/manager.py

@@ -0,0 +1,85 @@
+"""Model manager — orchestrates store, materializer, and queries.
+
+High-level interface for adding nodes, materializing relationships,
+and querying the model.
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.core.relation import Relation, RelationshipClaim
+from katalyst_engine.model.materializer import RelationshipMaterializer
+from katalyst_engine.model.node import Node
+from katalyst_engine.model.query import QueryEngine, QueryFilter, QueryResult, SortField, SortOrder
+from katalyst_engine.model.store import ModelStore
+
+
+class ModelManager:
+    """Orchestrator for the model layer.
+
+    Coordinates the ModelStore (storage), RelationshipMaterializer
+    (edge creation), and QueryEngine (retrieval).
+
+    Usage:
+        manager = ModelManager()
+        manager.add_node(my_node)
+        relations = manager.materialize(claims)
+        result = manager.query(QueryFilter(kind="layer"))
+    """
+
+    def __init__(self) -> None:
+        self._store = ModelStore()
+        self._materializer = RelationshipMaterializer()
+        self._query_engine = QueryEngine(self._store)
+        self._relations: list[Relation] = []
+
+    @property
+    def store(self) -> ModelStore:
+        """Access the underlying ModelStore."""
+        return self._store
+
+    @property
+    def relations(self) -> list[Relation]:
+        """All materialized relations."""
+        return list(self._relations)
+
+    def add_node(self, node: Node) -> None:
+        """Add a node to the model."""
+        self._store.add(node)
+
+    def remove_node(self, node: Node) -> bool:
+        """Remove a node from the model. Returns True if it existed."""
+        return self._store.remove(node.identity)
+
+    def materialize(self, claims: list[RelationshipClaim]) -> list[Relation]:
+        """Materialize relationship claims against the current store.
+
+        Replaces any previously materialized relations.
+
+        Returns:
+            The list of materialized Relations.
+        """
+        all_nodes = self._store.all_nodes()
+        self._relations = self._materializer.materialize(claims, all_nodes)
+        return list(self._relations)
+
+    def query(
+        self,
+        filter: QueryFilter | None = None,
+        sort_by: SortField = SortField.FQN,
+        sort_order: SortOrder = SortOrder.ASC,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> QueryResult:
+        """Query nodes in the model."""
+        return self._query_engine.query(
+            filter=filter,
+            sort_by=sort_by,
+            sort_order=sort_order,
+            offset=offset,
+            limit=limit,
+        )
+
+    def clear(self) -> None:
+        """Remove all nodes and relations."""
+        self._store.clear()
+        self._relations.clear()

katalyst_engine/model/materializer.py

@@ -0,0 +1,78 @@
+"""Relationship materializer — turns claims into concrete Relations.
+
+Takes Nodes and their RelationshipClaims, matches targets via
+NodeSelectors, and produces materialized Relation edges.
+"""
+
+from __future__ import annotations
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.relation import Relation, RelationshipClaim
+from katalyst_engine.core.version import Version
+from katalyst_engine.model.node import Node
+
+
+class RelationshipMaterializer:
+    """Materializes RelationshipClaims into concrete Relations.
+
+    Given a set of nodes and their claims, finds matching targets
+    using NodeSelectors and produces Relation edges.
+
+    Usage:
+        materializer = RelationshipMaterializer()
+        relations = materializer.materialize(claims, nodes)
+    """
+
+    def materialize(
+        self,
+        claims: list[RelationshipClaim],
+        nodes: list[Node],
+    ) -> list[Relation]:
+        """Materialize claims against a set of available nodes.
+
+        For each claim, evaluates the selector against all nodes
+        (excluding the source node) and produces a Relation for
+        each match.
+
+        Args:
+            claims: Relationship claims to materialize.
+            nodes: Available nodes to match against.
+
+        Returns:
+            List of materialized Relations.
+        """
+        relations: list[Relation] = []
+
+        for claim in claims:
+            matches = self._find_matches(claim, nodes)
+            for target in matches:
+                relation = self._build_relation(claim, target)
+                relations.append(relation)
+
+        return relations
+
+    def _find_matches(self, claim: RelationshipClaim, nodes: list[Node]) -> list[Node]:
+        """Find nodes matching a claim's selector, excluding the source."""
+        return [
+            node
+            for node in nodes
+            if node.identity != claim.source_identity and claim.selector.matches(node)
+        ]
+
+    def _build_relation(self, claim: RelationshipClaim, target: Node) -> Relation:
+        """Build a Relation from a claim and a matched target."""
+        rel_identity = Identity(
+            kind="relation",
+            name=f"{claim.source_identity.fqn}--{claim.kind}-->{target.identity.fqn}",
+            namespace=claim.source_identity.namespace,
+        )
+
+        return Relation(
+            identity=rel_identity,
+            version=Version(),
+            source=claim.source_identity,
+            target=target.identity,
+            relation_kind=claim.kind,
+            cardinality=claim.cardinality,
+            materialized_from=claim,
+        )

katalyst_engine/model/node.py

@@ -0,0 +1,49 @@
+"""Node — concrete Evolvable instances with spec data and parent references.
+
+A Node is the runtime representation of a declared artifact. It carries
+a spec dict (arbitrary key-value data), a source FQN indicating where
+it was discovered, and an optional parent identity reference.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from katalyst_engine.core.evolvable import Evolvable
+from katalyst_engine.core.identity import Identity
+
+
+class Node(Evolvable, frozen=True):
+    """A concrete artifact instance in the model.
+
+    Nodes are the primary inhabitants of the ModelStore. Each Node
+    has an identity (kind, name, namespace), a spec dict carrying
+    its domain-specific data, and references to its source and parent.
+
+    Nodes are immutable — updates produce new Node instances.
+    """
+
+    spec: dict[str, Any] = {}
+    """Domain-specific data for this node (field values from the declaration)."""
+
+    source_fqn: str = ""
+    """FQN of the source that produced this node."""
+
+    parent: Identity | None = None
+    """Identity of this node's parent, if any."""
+
+    description: str = ""
+    """Human-readable description of this node."""
+
+    def with_spec(self, **updates: Any) -> Node:
+        """Return a new Node with updated spec fields."""
+        merged: dict[str, Any] = {**self.spec, **updates}
+        return self.model_copy(update={"spec": merged})
+
+    def with_parent(self, parent: Identity) -> Node:
+        """Return a new Node with the given parent identity."""
+        return self.model_copy(update={"parent": parent})
+
+    def spec_value(self, key: str, default: Any = None) -> Any:
+        """Get a value from the spec dict with an optional default."""
+        return self.spec.get(key, default)