graphk 1.0.2__py3-none-any.whl

graphk/__init__.py

@@ -0,0 +1,69 @@
+"""
+GraphK - Framework for Graph-based execution and pipeline programming.
+"""
+
+from .common.store import Store
+from .common.matcher import Matcher
+from .common.logger import Logger
+from .common.persistence import Persistence
+from .core.session import Session
+from .core.context import Context
+from .core.policy import Policy
+from .core.node import Node
+from .core.pipeline import Pipeline
+from .core.runner import Runner
+from .core.emitter import Emitter
+from .pipes.branch import BranchPipe
+from .pipes.demos import (
+    AccumulateNode,
+    ApplyNode,
+    ConcatNode,
+    EchoNode,
+    IncrementNode,
+    RouteNode,
+    TextConcatNode,
+)
+from .pipes.multi import MultiPipe
+from .pipes.sequence import SequencePipe
+
+__all__ = [
+    "Store",
+    "Matcher",
+    "Logger",
+    "Session",
+    "Context",
+    "Policy",
+    "Node",
+    "Pipeline",
+    "Runner",
+    "Emitter",
+    "Persistence",
+    "EchoNode",
+    "ApplyNode",
+    "AccumulateNode",
+    "IncrementNode",
+    "ConcatNode",
+    "TextConcatNode",
+    "RouteNode",
+    "BranchPipe",
+    "MultiPipe",
+    "SequencePipe"
+]
+
+__title__ = "graphk"
+__version__ = "1.0.2"
+__description__ = "Framework for Graph-based execution and pipeline programming"
+__github__ = "https://github.com/kochf1/graphk"
+__license__ = "MIT"
+__about__ = """
+GraphK provides the core execution model for graph-based programming. It defines 
+pipelines as executable graphs composed of nodes, branches, and nested pipelines, 
+with explicit control flow and runtime semantics.
+"""
+__disclaimer__= """
+This codebase was developed with the assistance of agentic AI tools as part of a 
+vibe coding workflow. Multiple AI models and development tools were used while 
+following established code style guidelines and testing practices. Certain components 
+required manual intervention, and human-in-the-loop review  was applied throughout 
+the development process to ensure correctness, consistency, and code quality.
+"""

graphk/common/logger.py

@@ -0,0 +1,82 @@
+##
+## GraphK - Framework for Graph-based execution and pipeline programming.
+## common/logger.py — Shared logging configuration and levels.
+##
+# Copyright (c) 2026, Dr. Fernando Koch
+#    http://github.com/kochf1/graphk
+#
+# Check 'About', 'License' and 'Disclaimer' at BASE_DIR/__init__.py
+#
+
+import logging
+import sys
+from typing import Any
+
+
+class Logger:
+    """Central logging contract for GraphK components."""
+
+    LOGGER_INSTANCE = logging.getLogger("graphk")
+    NAME = "graphk"
+
+    SILENT = logging.CRITICAL + 10
+    ERROR = logging.ERROR
+    BASIC = logging.INFO
+    DETAIL = 15
+    DEBUG = logging.DEBUG
+
+    INSTANCE = LOGGER_INSTANCE
+    LOG_SILENT = SILENT
+    LOG_ERROR = ERROR
+    LOG_BASIC = BASIC
+    LOG_DETAIL = DETAIL
+    LOG_DEBUG = DEBUG
+
+    logging.addLevelName(DETAIL, "DETAIL")
+
+    @classmethod
+    def enable(cls, level: int = BASIC) -> bool:
+        """Enable package logging at the requested level."""
+        valid_levels = {cls.SILENT, cls.ERROR, cls.BASIC, cls.DETAIL, cls.DEBUG}
+
+        if level not in valid_levels:
+            raise ValueError(f"invalid log level: {level}")
+
+        if len(cls.LOGGER_INSTANCE.handlers) == 0:
+            handler = logging.StreamHandler(stream=sys.stdout)
+            handler.setFormatter(logging.Formatter("%(message)s"))
+            cls.LOGGER_INSTANCE.addHandler(handler)
+            cls.LOGGER_INSTANCE.propagate = False
+
+        cls.LOGGER_INSTANCE.setLevel(level)
+        return True
+
+    @classmethod
+    def format_event(
+        cls,
+        index: int,
+        level: int,
+        component: str,
+        action: str,
+        **kwargs: Any,
+    ) -> str:
+        """Format one structured package log line."""
+        parts = [f"action={action}"]
+        for key, value in kwargs.items():
+            parts.append(f"{key}={value!r}")
+
+        fields = "; ".join(parts)
+        return f"{index:03d} [{logging.getLevelName(level)}] {component}; {fields}"
+
+    @classmethod
+    def log(
+        cls,
+        index: int,
+        level: int,
+        component: str,
+        action: str,
+        **kwargs: Any,
+    ) -> None:
+        """Format and emit one structured package log line."""
+        cls.LOGGER_INSTANCE.log(level, cls.format_event(index, level, component, action, **kwargs))
+        return

graphk/common/matcher.py

@@ -0,0 +1,342 @@
+##
+## GraphK - Framework for Graph-based execution and pipeline programming.
+## common/matcher.py — Hierarchical Store for Set of Tests.
+##
+# Copyright (c) 2025, Dr. Fernando Koch
+#    http://github.com/kochf1/graphk
+#
+# Check 'About', 'License' and 'Disclaimer' at BASE_DIR/__init__.py
+#
+
+import re
+from typing import Any, Optional
+from .store import Store
+
+class Matcher(Store):
+    """Matcher evaluates rules against a store."""
+
+    # Rule Matching strategy
+    MATCH_ALL: int = 1
+    MATCH_ANY: int = 2
+
+    # Policy resolver strategy
+    """
+    RESOLVER_BOTTOMUP        - Rules are resolved from the current matcher upward through the hierarchy.
+                                Local policies may specialize or override higher-level policies while still inheriting them.
+
+    RESOLVER_TOPDOWN         - Rules are resolved from the root matcher downward through the hierarchy.
+                                Global policies take precedence and cannot be overridden by lower policy layers.
+
+    RESOLVER_ROOT            - Only the root matcher rules are resolved.
+                                The top-level policy acts as the supreme authority and all lower policy layers are ignored.
+
+    RESOLVER_BOTTOM          - Only the current matcher rules are resolved.
+                                The local context defines policy independently without inheriting higher-level policies.
+
+    RESOLVER_FLAT_BOTTOMUP   - The matcher hierarchy is flattened using bottom-up precedence before resolving.
+                                The effective policy is derived by allowing lower policy layers to override higher ones.
+
+    RESOLVER_FLAT_TOPDOWN    - The matcher hierarchy is flattened using top-down precedence before resolving.
+                                The effective policy is derived by enforcing root-level policies as authoritative baselines.
+    """
+
+    RESOLVER_BOTTOMUP = 1
+    RESOLVER_TOPDOWN = 2
+    RESOLVER_ROOT = 3
+    RESOLVER_BOTTOM = 4
+    RESOLVER_FLAT_BOTTOMUP = 5
+    RESOLVER_FLAT_TOPDOWN = 6
+   
+    # ===================================================================
+    # Initialization
+    # ===================================================================
+
+    def __init__(
+        self,
+        eval_strategy: int = MATCH_ALL,
+        resolve_strategy: int = RESOLVER_FLAT_BOTTOMUP,
+        case_sensitive: bool = False,
+        scope: Optional[str] = None,
+        parent: Optional[Store] = None,
+        **kwargs
+    ) -> None:
+        
+        """
+        Initializes a Matcher with matching strategy and rules.
+
+        Example:
+            m = Matcher(role="admin", age=">=18")
+        """
+
+        self._eval: int = eval_strategy
+        self._resolver: int = resolve_strategy
+        self._sensitive: bool = case_sensitive
+
+        Store.__init__(self, scope=scope, parent=parent, **kwargs)
+        return
+
+    # ===================================================================
+    # Private Methods
+    # ===================================================================
+
+    OPERATORS = (">=", "<=", "==", "!=", ">", "<")
+
+    @staticmethod
+    def _operator(a: float, b: float, op: str) -> bool:
+        """Apply a numeric comparison operator to two values."""
+        """Execute a numeric comparison operator."""
+
+        # fail-fast guards
+
+        # deliberation
+
+        res: bool = False
+
+        if op == ">":
+            res = a > b
+        elif op == "<":
+            res = a < b
+        elif op == ">=":
+            res = a >= b
+        elif op == "<=":
+            res = a <= b
+        elif op == "==":
+            res = a == b
+        elif op == "!=":
+            res = a != b
+
+        return res
+
+    @staticmethod
+    def _match_exp(case: Any, expression: Any, case_sensitive: bool = False) -> bool:
+        """Evaluate one case value against one matcher expression."""
+        """
+        Evaluate a field value against an expression.
+        """
+
+        # fail-fast guards
+        if case is None or expression is None:
+            return False
+
+        # deliberation
+        res: bool = False
+
+        if callable(expression):
+            value = expression(case)
+            if isinstance(value, bool):
+                res = value
+
+        elif isinstance(expression, (int, float)):
+            try:
+                res = float(case) == float(expression)
+            except (TypeError, ValueError):
+                res = False
+
+        elif not isinstance(expression, str):
+            res = case == expression
+
+        else:
+            case_str = str(case)
+            exp = expression
+
+            if not case_sensitive:
+                case_str = case_str.lower()
+                exp = exp.lower()
+
+            if exp.startswith("r/") and exp.endswith("/"):
+                pattern = exp[2:-1]
+                try:
+                    res = re.search(pattern, case_str) is not None
+                except re.error:
+                    pass
+
+            elif any(exp.startswith(op) for op in Matcher.OPERATORS):
+                for op in Matcher.OPERATORS:
+                    if exp.startswith(op):
+                        value = exp[len(op):]
+                        try:
+                            case_val = float(case)
+                            exp_val = float(value)
+                            res = Matcher._operator(case_val, exp_val, op)
+                        except (TypeError, ValueError):
+                            res = False
+                        break
+
+            elif "*" in exp:
+                pattern = "^" + re.escape(exp).replace(r"\*", ".*") + "$"
+                try:
+                    compiled = re.compile(pattern)
+                    res = compiled.match(case_str) is not None
+                except re.error:
+                    pass
+
+            else:
+                res = case_str == exp
+
+        return res
+
+
+    @staticmethod
+    def _match_lambdas(funcs: list[Any], state: Store, eval_strategy: int) -> bool:
+        """Evaluate global predicate functions against the given state."""
+        """Evaluate one or more global lambda predicates."""
+
+        # deliberation
+
+        res: bool = (eval_strategy == Matcher.MATCH_ALL)
+
+        for fn in funcs:
+            local = False
+
+            if callable(fn):
+                value = fn(state)
+                if isinstance(value, bool):
+                    local = value
+
+            if eval_strategy == Matcher.MATCH_ALL and not local:
+                res = False
+                break
+
+            if eval_strategy == Matcher.MATCH_ANY and local:
+                res = True
+                break
+
+        return res
+
+    @staticmethod
+    def _resolve(matcher: "Matcher", resolve_strategy: int) -> Optional[list[Any]]:
+        """Resolve matcher layers according to the selected strategy."""
+        """
+        Resolves rule sources according to the matching resolve strategy.
+
+        Example:
+            root = Matcher(role="admin", age=">=18")
+            pipeline = Matcher(parent=root, role="user")
+            session = Matcher(parent=pipeline, region="US")
+
+            ctx = Store(role="user", age=21, region="US")
+
+            # bottom-up layered evaluation
+            layers = Matcher._resolve(session, Matcher.RESOLVER_BOTTOMUP)
+            # -> [session, pipeline, root]
+
+            # top-down layered evaluation
+            layers = Matcher._resolve(session, Matcher.RESOLVER_TOPDOWN)
+            # -> [root, pipeline, session]
+
+            # flattened rule resolution
+            rules = Matcher._resolve(session, Matcher.RESOLVER_FLAT_BOTTOMUP)
+            # -> [{'role': 'user', 'age': '>=18', 'region': 'US'}]
+        """
+
+        # fail-fast guards
+
+        # deliberation
+
+        res: Optional[list[Any]] = None
+        if resolve_strategy == Matcher.RESOLVER_FLAT_BOTTOMUP:
+            res = [matcher.flatten()]
+
+        elif resolve_strategy == Matcher.RESOLVER_FLAT_TOPDOWN:
+            res = [matcher.flatten(top_down=True)]
+
+        else:
+            chain = matcher._chain()
+
+            if resolve_strategy == Matcher.RESOLVER_BOTTOMUP:
+                res = chain
+
+            elif resolve_strategy == Matcher.RESOLVER_TOPDOWN:
+                res = list(reversed(chain))
+
+            elif resolve_strategy == Matcher.RESOLVER_ROOT:
+                res = [chain[-1]]
+
+            elif resolve_strategy == Matcher.RESOLVER_BOTTOM:
+                res = [chain[0]]
+
+        return res
+
+    # ===================================================================
+    # Public Interface
+    # ===================================================================
+
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Return the effective rule set.
+
+        Example:
+            matcher = Matcher(role="admin")
+            matcher.to_dict()
+        """
+
+        # deliberation
+
+        layers = Matcher._resolve(self, self._resolver)
+
+        if isinstance(layers[0], dict):
+            res = dict(layers[0])
+        else:
+            merged: dict[str, Any] = {}
+
+            for layer in layers:
+                merged.update(dict(layer))
+
+            res = merged
+
+        return res
+    
+    def match(self, state: Store) -> bool:
+        """
+        Match the current rules against a store.
+
+        Example:
+            matcher = Matcher(role="admin")
+            state = Store(role="admin")
+            matcher.match(state)
+        """
+
+        # fail-fast guards
+
+        # deliberation
+
+        res: bool = (self._eval == Matcher.MATCH_ALL)
+        layers = Matcher._resolve(self, self._resolver)
+        done: bool = False
+
+        for layer in layers:
+            items = layer.items()
+
+            for key, expression in items:
+
+                if key == "_":
+                    funcs = expression if isinstance(expression, list) else [expression]
+                    valid = all(callable(fn) for fn in funcs)
+                    local: bool = False
+
+                    if valid:
+                        local = Matcher._match_lambdas(funcs, state, self._eval)
+
+                else:
+                    case = state.get(key, None)
+                    local = Matcher._match_exp(
+                        case=case,
+                        expression=expression,
+                        case_sensitive=self._sensitive,
+                    )
+
+                if self._eval == Matcher.MATCH_ALL and not local:
+                    res = False
+                    done = True
+                    break
+
+                if self._eval == Matcher.MATCH_ANY and local:
+                    res = True
+                    done = True
+                    break
+
+            if done:
+                break
+
+        return res

graphk/common/persistence.py

@@ -0,0 +1,83 @@
+##
+## GraphK - Framework for Graph-based execution and pipeline programming.
+## common/persistence.py — File persistence helpers for Session objects.
+##
+# Copyright (c) 2026, Dr. Fernando Koch
+#    http://github.com/kochf1/graphk
+#
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+from uuid import uuid4
+
+from ..core.session import Session
+
+
+class Persistence:
+    """Save and load Session snapshots from disk."""
+
+    DEFAULT_PREFIX = "session"
+    DEFAULT_ID_KEY = "id"
+
+    @staticmethod
+    def _ensure_id(session: Session, id_key: str = DEFAULT_ID_KEY) -> str:
+        """Resolve or create a stable session id for file naming."""
+        session_id = session.get(id_key)
+
+        if session_id is None:
+            session_id = uuid4().hex
+            session.set(id_key, session_id)
+
+        return str(session_id)
+
+    @staticmethod
+    def _payload(session: Session) -> Dict[str, Any]:
+        """Build a JSON-safe snapshot payload for one session."""
+        return {
+            "session": session.save(),
+            "code": session.code,
+            "message": session.message,
+        }
+
+    @staticmethod
+    def _resolve_path(session: Session, target: str | Path) -> Path:
+        """Resolve the final save path from a filename or folder target."""
+        path = Path(target)
+
+        if path.exists() and path.is_dir():
+            session_id = Persistence._ensure_id(session)
+            return path / f"{Persistence.DEFAULT_PREFIX}-{session_id}.json"
+
+        if path.suffix == "":
+            path.mkdir(parents=True, exist_ok=True)
+            session_id = Persistence._ensure_id(session)
+            return path / f"{Persistence.DEFAULT_PREFIX}-{session_id}.json"
+
+        parent = path.parent
+        if str(parent) not in ("", "."):
+            parent.mkdir(parents=True, exist_ok=True)
+
+        return path
+
+    @staticmethod
+    def save(session: Session, target: str | Path) -> str:
+        """Save a session snapshot to a file path or folder."""
+        if not isinstance(session, Session):
+            raise TypeError("session must be a Session")
+
+        path = Persistence._resolve_path(session, target)
+        payload = Persistence._payload(session)
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+        return str(path)
+
+    @staticmethod
+    def load(source: str | Path) -> Session:
+        """Load a session snapshot from disk."""
+        path = Path(source)
+        payload = json.loads(path.read_text(encoding="utf-8"))
+
+        session = Session()
+        session.restore(payload["session"])
+        session._restore_status(payload.get("code"), payload.get("message"))
+        return session