clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/model/workflow.py

@@ -0,0 +1,274 @@
+"""Declarative Workflow Manifest Domain Models (Sprint 395 / DEL-395-01).
+
+Implements Pydantic V2 domain models for canonical CLM Workflow specifications (clm.workflow.v1).
+A Workflow represents a Category-Theoretic Monadic Composition (Kleisli Category)
+chaining multiple Actions algebraically across the Pocket Flow Scheduler.
+
+Zero dependencies on Layer 1 through Layer 5.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from clm.layer0.exceptions import CLMError
+
+
+class CyclicDependencyError(CLMError):
+    """Raised when a workflow contains a circular dependency between steps."""
+    pass
+
+
+class WorkflowValidationError(CLMError):
+    """Raised when static validation of a workflow manifest fails (e.g. dangling reference)."""
+    pass
+
+
+class WorkflowMetadata(BaseModel):
+    """Metadata block identifying the workflow and its role in CLM."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    type: Literal["workflow", "pocketflow_dag"] = "workflow"
+    name: str = Field(..., pattern=r"^[a-z0-9_\-]+$")
+    description: str | None = None
+    author: str = "did:clm:system"
+
+
+class WorkflowInput(BaseModel):
+    """Specification of an input parameter to the workflow."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    format: str | None = None
+    description: str | None = None
+
+
+class WorkflowStep(BaseModel):
+    """A discrete Action step in the workflow DAG."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str = Field(..., pattern=r"^[a-z0-9_\-]+$")
+    action: str
+    inputs: dict[str, str] = Field(default_factory=dict)
+    depends_on: list[str] = Field(default_factory=list)
+
+    def extract_implicit_dependencies(self) -> set[str]:
+        """Extract referenced step IDs from input binding expressions ($step_id.output...)."""
+        deps: set[str] = set()
+        step_ref_pattern = re.compile(r"^\$([a-z0-9_\-]+)\.output")
+        for val in self.inputs.values():
+            if isinstance(val, str):
+                match = step_ref_pattern.match(val.strip())
+                if match:
+                    ref = match.group(1)
+                    if ref != "workflow":
+                        deps.add(ref)
+        return deps
+
+    def all_dependencies(self) -> set[str]:
+        """Return combined explicit and implicit dependencies for this step."""
+        return set(self.depends_on).union(self.extract_implicit_dependencies())
+
+
+class WorkflowOutput(BaseModel):
+    """Specification of an output produced by the workflow."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    source: str
+    format: str | None = None
+    description: str | None = None
+
+
+class WorkflowManifest(BaseModel):
+    """Canonical CLM Workflow specification (clm.workflow.v1).
+
+    Orchestrates multiple Actions in a directed acyclic graph (DAG) with
+    strict Kleisli monadic composition (>>>), parallel tensor branching (⊗),
+    and Merkle causal lineage.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    version: Literal["1.0", "1.0.0"] = "1.0"
+    clm: WorkflowMetadata
+    inputs: list[WorkflowInput] = Field(default_factory=list)
+    steps: list[WorkflowStep] = Field(..., min_length=1)
+    outputs: list[WorkflowOutput] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_dag_and_references(self) -> WorkflowManifest:
+        """Validate step uniqueness, references, and assert acyclicity."""
+        # 1. Step uniqueness
+        step_ids: set[str] = set()
+        step_map: dict[str, WorkflowStep] = {}
+        for s in self.steps:
+            if s.id in step_ids:
+                raise WorkflowValidationError(f"Duplicate step id '{s.id}' in workflow '{self.clm.name}'")
+            step_ids.add(s.id)
+            step_map[s.id] = s
+
+        # Known input names
+        input_names = {inp.name for inp in self.inputs}
+
+        # 2. Dependency & Reference validation
+        adj: dict[str, set[str]] = {sid: set() for sid in step_ids}
+
+        workflow_inp_pattern = re.compile(r"^\$workflow\.input(?:\.([a-z0-9_\-]+))?$")
+        step_out_pattern = re.compile(r"^\$([a-z0-9_\-]+)\.output")
+
+        for s in self.steps:
+            all_deps = s.all_dependencies()
+            for dep in all_deps:
+                if dep not in step_ids:
+                    raise WorkflowValidationError(
+                        f"Step '{s.id}' references unknown dependency or step '{dep}'"
+                    )
+                if dep == s.id:
+                    raise CyclicDependencyError(f"Step '{s.id}' has self-referential dependency")
+                adj[dep].add(s.id)
+
+            # Check workflow inputs
+            for in_key, in_val in s.inputs.items():
+                if isinstance(in_val, str):
+                    wf_match = workflow_inp_pattern.match(in_val.strip())
+                    if wf_match:
+                        inp_field = wf_match.group(1)
+                        if inp_field and input_names and inp_field not in input_names:
+                            raise WorkflowValidationError(
+                                f"Step '{s.id}' references undeclared workflow input '{inp_field}'"
+                            )
+
+        # 3. Output source validation
+        for out in self.outputs:
+            match = step_out_pattern.match(out.source.strip())
+            if match:
+                ref_step = match.group(1)
+                if ref_step not in step_ids and ref_step != "workflow":
+                    raise WorkflowValidationError(
+                        f"Workflow output '{out.name}' references unknown step '{ref_step}'"
+                    )
+
+        # 4. Topological sort & cycle detection (Kahn's algorithm)
+        # Compute in-degree from adj (dep -> dependent)
+        calc_in_degree: dict[str, int] = dict.fromkeys(step_ids, 0)
+        for dep, dependents in adj.items():
+            for target in dependents:
+                calc_in_degree[target] += 1
+
+        queue = [sid for sid, deg in calc_in_degree.items() if deg == 0]
+        sorted_order: list[str] = []
+
+        while queue:
+            curr = queue.pop(0)
+            sorted_order.append(curr)
+            for neighbor in adj[curr]:
+                calc_in_degree[neighbor] -= 1
+                if calc_in_degree[neighbor] == 0:
+                    queue.append(neighbor)
+
+        if len(sorted_order) != len(step_ids):
+            cycle_nodes = [sid for sid, deg in calc_in_degree.items() if deg > 0]
+            raise CyclicDependencyError(
+                f"Workflow '{self.clm.name}' contains a circular dependency involving steps: {cycle_nodes}"
+            )
+
+        return self
+
+    def get_step(self, step_id: str) -> WorkflowStep:
+        """Find a step by its identifier."""
+        for s in self.steps:
+            if s.id == step_id:
+                return s
+        raise KeyError(f"Step '{step_id}' not found in workflow")
+
+    def get_topological_order(self) -> list[str]:
+        """Compute valid linear execution order of steps."""
+        adj: dict[str, set[str]] = {s.id: set() for s in self.steps}
+        in_degree: dict[str, int] = {s.id: 0 for s in self.steps}
+
+        for s in self.steps:
+            for dep in s.all_dependencies():
+                adj[dep].add(s.id)
+                in_degree[s.id] += 1
+
+        queue = [sid for sid, deg in in_degree.items() if deg == 0]
+        order: list[str] = []
+
+        while queue:
+            curr = queue.pop(0)
+            order.append(curr)
+            for neighbor in adj[curr]:
+                in_degree[neighbor] -= 1
+                if in_degree[neighbor] == 0:
+                    queue.append(neighbor)
+
+        return order
+
+    def get_execution_stages(self) -> list[list[str]]:
+        """Group steps into parallel execution stages based on dependency depth.
+
+        Steps in the same stage have no mutual dependencies and their
+        ancestor dependencies are fulfilled by preceding stages.
+        """
+        top_order = self.get_topological_order()
+        depths: dict[str, int] = {}
+        for sid in top_order:
+            step = self.get_step(sid)
+            deps = step.all_dependencies()
+            if not deps:
+                depths[sid] = 0
+            else:
+                depths[sid] = max(depths[d] for d in deps) + 1
+
+        max_depth = max(depths.values()) if depths else 0
+        stages: list[list[str]] = [[] for _ in range(max_depth + 1)]
+        for sid in top_order:
+            stages[depths[sid]].append(sid)
+
+        return stages
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> WorkflowManifest:
+        """Instantiate from a raw Python dictionary."""
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_yaml(cls, source: str | Path) -> WorkflowManifest:
+        """Parse from YAML string or file path."""
+        p = Path(source) if isinstance(source, (str, Path)) else None
+        if p and p.exists() and p.is_file():
+            content = p.read_text(encoding="utf-8")
+        else:
+            content = str(source)
+        data = yaml.safe_load(content)
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_json(cls, source: str | Path) -> WorkflowManifest:
+        """Parse from JSON string or file path."""
+        p = Path(source) if isinstance(source, (str, Path)) else None
+        if p and p.exists() and p.is_file():
+            content = p.read_text(encoding="utf-8")
+        else:
+            content = str(source)
+        data = json.loads(content)
+        return cls.from_dict(data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert manifest to Python dictionary."""
+        return self.model_dump(exclude_none=True)
+
+    def to_yaml(self) -> str:
+        """Convert manifest to YAML string."""
+        return yaml.dump(self.to_dict(), sort_keys=False)

clm/layer0/narrative.py

@@ -0,0 +1,431 @@
+"""CLM Monadic Template & Narrative Spacetime Monad (Layer 0).
+
+Part of Phase 7 (Sprint 383: Layer 0 Kenotic Core & Parser Unification).
+Provides the pure, stateless monadic substrate for chapter-based narrative transformations:
+- Monad Archetype
+- Narrative Threads: Reader, State, Writer, IO, Either (Left, Right), Maybe (Just, Nothing)
+- CLMConfiguration: Abstract (VCard/Why), Concrete (PCard/How), Balanced (MCard/What)
+- NarrativeMonad: Composition of Reader, State, Writer, and IO
+- Chapter: Encapsulates individual narrative transformation steps
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+# Type Variables
+T = TypeVar("T")  # Result Type
+U = TypeVar("U")  # Transformed Result Type
+R = TypeVar("R")  # Reader Context Type
+S = TypeVar("S")  # State Type
+W = TypeVar("W")  # Writer Log Type
+E = TypeVar("E")  # Error Type
+
+
+# =============================================================================
+# 1. The Monad Archetype
+# =============================================================================
+
+
+class Monad(Generic[T], ABC):
+    """The Archetype of the Function.
+    Encapsulates Purity, Manages Impurity, Enables Composition.
+    """
+
+    @abstractmethod
+    def bind(self, func: Callable[[T], Monad[U]]) -> Monad[U]:
+        pass
+
+    def map(self, func: Callable[[T], U]) -> Monad[U]:
+        """Standard map operation."""
+        return self.bind(lambda x: self.pure(func(x)))
+
+    @classmethod
+    def pure(cls, value: T) -> Monad[T]:
+        return cls.unit(value)
+
+    @classmethod
+    @abstractmethod
+    def unit(cls, value: T) -> Monad[T]:
+        pass
+
+
+# =============================================================================
+# 2. The Narrative Threads (Specific Monads)
+# =============================================================================
+
+
+@dataclass
+class Reader(Monad[T], Generic[R, T]):
+    """The Reader Monad: Carries the Cultural Context and Configuration.
+    Immutable and accessible everywhere.
+    """
+
+    run: Callable[[R], T]
+
+    def bind(self, func: Callable[[T], Reader[R, U]]) -> Reader[R, U]:
+        return Reader(lambda r: func(self.run(r)).run(r))
+
+    @classmethod
+    def unit(cls, value: T) -> Reader[R, T]:
+        return Reader(lambda _: value)
+
+    @classmethod
+    def pure(cls, value: T) -> Reader[R, T]:
+        return cls.unit(value)
+
+    @staticmethod
+    def ask() -> Reader[R, R]:
+        return Reader(lambda env: env)
+
+
+@dataclass
+class State(Monad[T], Generic[S, T]):
+    """The State Monad: Carries the evolving World State.
+    (Village Prosperity, Network Topology, User Progress).
+    """
+
+    run: Callable[[S], tuple[T, S]]
+
+    def bind(self, func: Callable[[T], State[S, U]]) -> State[S, U]:
+        def new_run(s: S) -> tuple[U, S]:
+            val, new_s = self.run(s)
+            return func(val).run(new_s)
+
+        return State(new_run)
+
+    @classmethod
+    def unit(cls, value: T) -> State[S, T]:
+        return State(lambda s: (value, s))
+
+    @classmethod
+    def pure(cls, value: T) -> State[S, T]:
+        return cls.unit(value)
+
+    @staticmethod
+    def get() -> State[S, S]:
+        return State(lambda s: (s, s))
+
+    @staticmethod
+    def put(new_state: S) -> State[S, None]:
+        return State(lambda _: (None, new_state))
+
+
+class CallableTuple(tuple):
+    """A tuple subclass that is callable, returning itself."""
+
+    def __call__(self) -> tuple:
+        return self
+
+
+class Writer(Monad[T], Generic[W, T]):
+    """The Writer Monad: Accumulates the Log of the journey.
+    (The Story Text, The Audit Trail).
+    """
+
+    def __init__(self, run: Any):
+        if callable(run) and not isinstance(run, tuple):
+            res = run()
+            self.run = CallableTuple(res)
+        elif isinstance(run, tuple):
+            self.run = CallableTuple(run)
+        else:
+            self.run = CallableTuple((run, []))
+
+    def bind(self, func: Callable[[T], Writer[W, U]]) -> Writer[W, U]:
+        val, log = self.run
+        new_writer = func(val)
+        new_val, new_log = new_writer.run
+        return Writer((new_val, list(log) + list(new_log)))
+
+    @classmethod
+    def unit(cls, value: T) -> Writer[W, T]:
+        return cls((value, []))
+
+    @classmethod
+    def pure(cls, value: T) -> Writer[W, T]:
+        return cls((value, []))
+
+    @staticmethod
+    def tell(log: list[W]) -> Writer[W, None]:
+        return Writer((None, log))
+
+
+@dataclass
+class IO(Monad[T]):
+    """The IO Monad: Handles Effects at the boundaries.
+    (User Interaction, System Deployment).
+    """
+
+    effect: Callable[[], T]
+
+    def unsafe_run(self) -> T:
+        """Execute the side effect."""
+        return self.effect()
+
+    def __call__(self) -> T:
+        return self.effect()
+
+    def bind(self, func: Callable[[T], IO[U]]) -> IO[U]:
+        return IO(lambda: func(self.effect()).effect())
+
+    @classmethod
+    def unit(cls, value: T) -> IO[T]:
+        return IO(lambda: value)
+
+    @classmethod
+    def pure(cls, value: T) -> IO[T]:
+        return IO(lambda: value)
+
+
+class CallableBool(int):
+    """An int subclass representing a bool that is callable, returning itself."""
+
+    def __call__(self) -> bool:
+        return bool(self)
+
+    def __bool__(self) -> bool:
+        return self != 0
+
+
+class Either(Monad[T], Generic[E, T]):
+    """The Either Monad: Represents a value that can be one of two types.
+    Used for Error Handling (Left=Error, Right=Success) or Branching Logic.
+    Supports both Either[T] and Either[E, T] typing specializations.
+    """
+
+    def __init__(self, value: Any, is_left: bool = False):
+        self.value = value
+        self._is_left = CallableBool(1 if is_left else 0)
+
+    def __class_getitem__(cls, item: Any) -> Any:
+        if not isinstance(item, tuple):
+            item = (Any, item)
+        return super().__class_getitem__(item)
+
+    @property
+    def is_left(self) -> CallableBool:
+        return self._is_left
+
+    @property
+    def is_right(self) -> CallableBool:
+        return CallableBool(0 if self._is_left else 1)
+
+    def bind(self, func: Callable[[T], Either[Any, U]]) -> Either[Any, U]:
+        if self._is_left:
+            return self  # Propagate failure/left value
+        return func(self.value)
+
+    @classmethod
+    def unit(cls, value: T) -> Either[Any, T]:
+        return Right(value)
+
+    @classmethod
+    def pure(cls, value: T) -> Either[Any, T]:
+        return Right(value)
+
+    @classmethod
+    def left(cls, value: Any) -> Left[Any]:
+        return Left(value)
+
+    @classmethod
+    def right(cls, value: T) -> Right[T]:
+        return Right(value)
+
+
+class Left(Either[E, Any], Generic[E]):
+    def __init__(self, value: E):
+        super().__init__(value, is_left=True)
+
+
+class Right(Either[Any, T], Generic[T]):
+    def __init__(self, value: T):
+        super().__init__(value, is_left=False)
+
+
+class Maybe(Monad[T], Generic[T]):
+    """The Maybe Monad: Represents an optional value (Just val or Nothing).
+    Used for handling absence of value without null checks.
+    """
+
+    def __init__(self, value: T | None, is_nothing: bool = False):
+        self.value = value
+        self._is_nothing = CallableBool(1 if is_nothing else 0)
+
+    @property
+    def is_nothing(self) -> CallableBool:
+        return self._is_nothing
+
+    @property
+    def is_just(self) -> CallableBool:
+        return CallableBool(0 if self._is_nothing else 1)
+
+    def bind(self, func: Callable[[T], Maybe[U]]) -> Maybe[U]:
+        if self._is_nothing:
+            return self  # Propagate Nothing
+        return func(self.value)  # type: ignore
+
+    @classmethod
+    def unit(cls, value: T) -> Maybe[T]:
+        return Just(value)
+
+    @classmethod
+    def pure(cls, value: T) -> Maybe[T]:
+        return Just(value)
+
+    @classmethod
+    def nothing(cls) -> Nothing:
+        return Nothing()
+
+    @classmethod
+    def just(cls, value: T) -> Just:
+        return Just(value)
+
+
+class Nothing(Maybe[Any]):
+    def __init__(self):
+        super().__init__(None, is_nothing=True)
+
+
+class Just(Maybe[T]):
+    def __init__(self, value: T):
+        super().__init__(value, is_nothing=False)
+
+
+# =============================================================================
+# 3. The Cubical Logic Model (CLM)
+# =============================================================================
+
+
+@dataclass
+class CLMConfiguration:
+    """Defines the three orthogonal dimensions of any well-formed concept."""
+
+    abstract: str  # VCard (Value/Type): The Principle ("Why")
+    concrete: str  # PCard (Process/Instance): The Character ("How")
+    balanced: str  # MCard (Memory/Property): The Evidence ("What")
+
+    def __repr__(self) -> str:
+        return (
+            f"🧊 CLM Cube:\n"
+            f"  - Abstract (Why): {self.abstract}\n"
+            f"  - Concrete (How): {self.concrete}\n"
+            f"  - Balanced (What): {self.balanced}"
+        )
+
+
+# =============================================================================
+# 4. The Narrative Monad (Composition)
+# =============================================================================
+
+
+class NarrativeMonad(Generic[R, S, W, T]):
+    """The 'Spacetime' Monad.
+    A composition of Reader, State, Writer, and IO.
+
+    Signature: Context -> State -> IO(Result, NewState, Log)
+    """
+
+    def __init__(self, run: Callable[[R, S], IO[tuple[T, S, list[W]]]]):
+        self.run = run
+
+    def bind(
+        self, func: Callable[[T], NarrativeMonad[R, S, W, U]]
+    ) -> NarrativeMonad[R, S, W, U]:
+        def new_run(r: R, s: S) -> IO[tuple[U, S, list[W]]]:
+            # Execute first step
+            io_result = self.run(r, s)
+
+            # Define continuation inside IO to handle effects sequentially
+            def continuation() -> tuple[U, S, list[W]]:
+                val, s_prime, log1 = io_result.effect()
+
+                # Execute second step
+                next_monad = func(val)
+                io_result2 = next_monad.run(r, s_prime)
+                val2, s_double_prime, log2 = io_result2.effect()
+
+                return (val2, s_double_prime, log1 + log2)
+
+            return IO(continuation)
+
+        return NarrativeMonad(new_run)
+
+    @classmethod
+    def unit(cls, value: T) -> NarrativeMonad[R, S, W, T]:
+        return NarrativeMonad(lambda r, s: IO.unit((value, s, [])))
+
+    @classmethod
+    def lift_io(cls, io_action: IO[T]) -> NarrativeMonad[R, S, W, T]:
+        """Lift a pure IO action into the Narrative Monad"""
+        return NarrativeMonad(lambda r, s: IO(lambda: (io_action.effect(), s, [])))
+
+    @classmethod
+    def log(cls, message: W) -> NarrativeMonad[R, S, W, None]:
+        """Log a message (Writer effect)"""
+        return NarrativeMonad(lambda r, s: IO.unit((None, s, [message])))
+
+    @classmethod
+    def get_context(cls) -> NarrativeMonad[R, S, W, R]:
+        """Read the context (Reader effect)"""
+        return NarrativeMonad(lambda r, s: IO.unit((r, s, [])))
+
+    @classmethod
+    def get_state(cls) -> NarrativeMonad[R, S, W, S]:
+        """Read the state (State effect)"""
+        return NarrativeMonad(lambda r, s: IO.unit((s, s, [])))
+
+    @classmethod
+    def put_state(cls, new_state: S) -> NarrativeMonad[R, S, W, None]:
+        """Update the state (State effect)"""
+        return NarrativeMonad(lambda r, s: IO.unit((None, new_state, [])))
+
+    def execute(self, context: R, initial_state: S) -> tuple[T, S, list[W]]:
+        """Run the monadic chain"""
+        return self.run(context, initial_state).effect()
+
+
+# =============================================================================
+# 5. Chapter Template
+# =============================================================================
+
+
+@dataclass
+class Chapter:
+    """A Chapter in the Prologue of Spacetime."""
+
+    id: int
+    title: str
+    clm: CLMConfiguration
+    mvp_card: str  # The Archetype Name
+    pkc_task: str  # The Container Task
+    action: NarrativeMonad[dict, dict, str, Any]
+
+    def run(self, context: dict, state: dict) -> tuple[Any, dict, list[str]]:
+        print(f"\n--- Executing {self.title} ---")
+        print(self.clm)
+        result, new_state, log = self.action.execute(context, state)
+        print(f"Result: {result}")
+        print(f"Log: {log}")
+        return result, new_state, log
+
+
+__all__ = [
+    "CLMConfiguration",
+    "Chapter",
+    "Either",
+    "IO",
+    "Just",
+    "Left",
+    "Maybe",
+    "Monad",
+    "NarrativeMonad",
+    "Nothing",
+    "Reader",
+    "Right",
+    "State",
+    "Writer",
+]