graphk 1.0.2__tar.gz

graphk-1.0.2/.gitignore

@@ -0,0 +1,39 @@
+# --- Python Environment & Caches ---
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+ENV/
+.env
+.pypirc
+.DS_Store
+.DS_Store/
+/*.txt
+
+# --- Embedded development packages ---
+#graphk/
+
+# --- Build & Distribution ---
+# These are generated by 'python -m build'
+dist/
+build/
+*.egg-info
+*.egg-info/
+*.egg
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# --- macOS System Files ---
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# --- IDEs & Editors ---
+.vscode/
+.idea/
+*.swp
+*.swo
+

graphk-1.0.2/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dr. Fernando Koch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

graphk-1.0.2/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: graphk
+Version: 1.0.2
+Summary: Framework for Graph-based execution and pipeline programming
+Project-URL: Homepage, https://github.com/kochf1/graphk
+Project-URL: Repository, https://github.com/kochf1/graphk
+Project-URL: Documentation, https://github.com/kochf1/graphk/wiki
+Project-URL: Issues, https://github.com/kochf1/graphk/issues
+Author-email: Fernando Koch <kochf@fau.edu>
+License: MIT
+License-File: LICENSE.txt
+Keywords: execution,graph,pipeline,runtime,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# GraphK
+
+<div align="left">
+  <a href="https://github.com/kochf1/graphk"><img src="https://img.shields.io/badge/GraphK-Toolkit-blueviolet?style=for-the-badge&logo=openai&logoColor=white" alt="GraphK Toolkit" /></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License" />
+</div>
+
+---
+
+## Overview
+
+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. 
+
+GraphK treats execution as an explicit graph providing representation for 
+state, policy, scope, and control flow. The goal is to keep execution
+understandable, inspectable, and composable.
+
+### Why This Project Exists
+
+Many workflow systems, agent systems, and orchestration layers
+accumulate implicit behavior over time: hidden state propagation,
+scattered branching logic, and unclear lifecycle boundaries.
+GraphK exists to provide a small reusable execution kernel where:
+
+- flow control is modeled explicitly
+- state resolution follows clear hierarchical rules
+- validation is attached to execution boundaries
+- complex orchestration can be built from simple, inspectable parts
+
+GraphK gives you a small set of composable primitives for building
+executable graphs:
+
+- `Store` and `Matcher` for hierarchical state and rule evaluation
+- `Session`, `Context`, and `Policy` for runtime state, scoped
+  configuration, and validation
+- `Node` as the executable unit
+- `Pipeline`, `SequencePipe`, `BranchPipe`, and `MultiPipe` for
+  orchestration
+- `Runner` for managed end-to-end execution
+- `Emitter` for request/response-style execution on top of
+  `Runner` and `Session`
+
+Learn more about the core architecture on the Wiki pages:
+[GraphK Wiki](https://github.com/kochf1/graphk/wiki)
+
+## Getting Started
+
+Install from PyPI when published:
+
+```bash
+pip install graphk
+```
+
+The examples below assume the package is installed and imported as
+`graphk`.
+
+### Shared Demo Nodes
+
+GraphK includes a small set of reusable basic nodes for common
+pipeline operations. These are not test-only helpers. They are
+general-purpose building blocks for simple executable graphs.
+
+- `graphk.EchoNode` for minimal request/response flows
+- `graphk.ApplyNode` for applying a callable to the active session
+- `graphk.IncrementNode` for incrementing numeric session fields
+- `graphk.ConcatNode` for string accumulation
+- `graphk.RouteNode` for branch-routing flows
+
+Learn more about the built-in node helpers on the Wiki pages:
+[Demo Nodes](https://github.com/kochf1/graphk/wiki)
+
+### Example 1: A Simple Sequence
+
+This is the smallest useful GraphK workflow: a sequence pipeline
+executed through an `Emitter`.
+
+```python
+import graphk
+
+
+pipeline = graphk.SequencePipe(
+    nodes=[
+        graphk.IncrementNode(
+            "A",
+            increment=1,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+        graphk.IncrementNode(
+            "B",
+            increment=2,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+        graphk.IncrementNode(
+            "C",
+            increment=3,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+    ]
+)
+
+emitter = graphk.Emitter(pipeline)
+emitter.request({"counter": 0})
+
+print(emitter.response())
+```
+
+Expected result:
+
+```python
+{"counter": 6, "order": ["A", "B", "C"]}
+```
+
+### Example 2: A Branched Sequence
+
+This example shows how GraphK routes execution through one branch
+selected from runtime state.
+
+```python
+import graphk
+
+
+branch = graphk.BranchPipe(
+    nodes=[
+        (
+            graphk.Matcher(task="route-a"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("A")]),
+        ),
+        (
+            graphk.Matcher(task="route-b"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("B")]),
+        ),
+        (
+            graphk.Matcher(task="route-c"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("C")]),
+        ),
+    ]
+)
+
+pipeline = graphk.SequencePipe(nodes=[branch])
+emitter = graphk.Emitter(pipeline)
+
+emitter.request({"task": "route-b"})
+print(emitter.response())
+```
+
+Expected result:
+
+```python
+{"route": "B"}
+```
+
+
+## Learn by Examples
+
+All runnable examples are available in
+[`examples`](examples), and they can be executed together with:
+
+```bash
+bash examples/example.sh
+```
+
+- [`examples/example_1.py`](examples/example_1.py) - Simple
+  emitter request and response
+- [`examples/example_2.py`](examples/example_2.py) - Multi-step
+  sequence execution
+- [`examples/example_3.py`](examples/example_3.py) - Context-driven
+  sequence
+- [`examples/example_4.py`](examples/example_4.py) - Nested
+  sequence pipelines
+- [`examples/example_5.py`](examples/example_5.py) - Branch routing
+  with `BranchPipe`
+- [`examples/example_6.py`](examples/example_6.py) - `MultiPipe`
+  fan-out
+- [`examples/example_7.py`](examples/example_7.py) - Policy-governed
+  execution
+- [`examples/example_8.py`](examples/example_8.py) - Hierarchical
+  memory resolution
+- [`examples/example_9.py`](examples/example_9.py) - Graceful early
+  stop with `CUT`
+- [`examples/example_10.py`](examples/example_10.py) - Error
+  rollback during execution
+
+Learn more about each area on the Wiki pages:
+[GraphK Wiki](https://github.com/kochf1/graphk/wiki)

graphk-1.0.2/README.md

@@ -0,0 +1,194 @@
+# GraphK
+
+<div align="left">
+  <a href="https://github.com/kochf1/graphk"><img src="https://img.shields.io/badge/GraphK-Toolkit-blueviolet?style=for-the-badge&logo=openai&logoColor=white" alt="GraphK Toolkit" /></a>
+  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License" />
+</div>
+
+---
+
+## Overview
+
+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. 
+
+GraphK treats execution as an explicit graph providing representation for 
+state, policy, scope, and control flow. The goal is to keep execution
+understandable, inspectable, and composable.
+
+### Why This Project Exists
+
+Many workflow systems, agent systems, and orchestration layers
+accumulate implicit behavior over time: hidden state propagation,
+scattered branching logic, and unclear lifecycle boundaries.
+GraphK exists to provide a small reusable execution kernel where:
+
+- flow control is modeled explicitly
+- state resolution follows clear hierarchical rules
+- validation is attached to execution boundaries
+- complex orchestration can be built from simple, inspectable parts
+
+GraphK gives you a small set of composable primitives for building
+executable graphs:
+
+- `Store` and `Matcher` for hierarchical state and rule evaluation
+- `Session`, `Context`, and `Policy` for runtime state, scoped
+  configuration, and validation
+- `Node` as the executable unit
+- `Pipeline`, `SequencePipe`, `BranchPipe`, and `MultiPipe` for
+  orchestration
+- `Runner` for managed end-to-end execution
+- `Emitter` for request/response-style execution on top of
+  `Runner` and `Session`
+
+Learn more about the core architecture on the Wiki pages:
+[GraphK Wiki](https://github.com/kochf1/graphk/wiki)
+
+## Getting Started
+
+Install from PyPI when published:
+
+```bash
+pip install graphk
+```
+
+The examples below assume the package is installed and imported as
+`graphk`.
+
+### Shared Demo Nodes
+
+GraphK includes a small set of reusable basic nodes for common
+pipeline operations. These are not test-only helpers. They are
+general-purpose building blocks for simple executable graphs.
+
+- `graphk.EchoNode` for minimal request/response flows
+- `graphk.ApplyNode` for applying a callable to the active session
+- `graphk.IncrementNode` for incrementing numeric session fields
+- `graphk.ConcatNode` for string accumulation
+- `graphk.RouteNode` for branch-routing flows
+
+Learn more about the built-in node helpers on the Wiki pages:
+[Demo Nodes](https://github.com/kochf1/graphk/wiki)
+
+### Example 1: A Simple Sequence
+
+This is the smallest useful GraphK workflow: a sequence pipeline
+executed through an `Emitter`.
+
+```python
+import graphk
+
+
+pipeline = graphk.SequencePipe(
+    nodes=[
+        graphk.IncrementNode(
+            "A",
+            increment=1,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+        graphk.IncrementNode(
+            "B",
+            increment=2,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+        graphk.IncrementNode(
+            "C",
+            increment=3,
+            target_key="counter",
+            order_key="order",
+            response=True,
+        ),
+    ]
+)
+
+emitter = graphk.Emitter(pipeline)
+emitter.request({"counter": 0})
+
+print(emitter.response())
+```
+
+Expected result:
+
+```python
+{"counter": 6, "order": ["A", "B", "C"]}
+```
+
+### Example 2: A Branched Sequence
+
+This example shows how GraphK routes execution through one branch
+selected from runtime state.
+
+```python
+import graphk
+
+
+branch = graphk.BranchPipe(
+    nodes=[
+        (
+            graphk.Matcher(task="route-a"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("A")]),
+        ),
+        (
+            graphk.Matcher(task="route-b"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("B")]),
+        ),
+        (
+            graphk.Matcher(task="route-c"),
+            graphk.SequencePipe(nodes=[graphk.RouteNode("C")]),
+        ),
+    ]
+)
+
+pipeline = graphk.SequencePipe(nodes=[branch])
+emitter = graphk.Emitter(pipeline)
+
+emitter.request({"task": "route-b"})
+print(emitter.response())
+```
+
+Expected result:
+
+```python
+{"route": "B"}
+```
+
+
+## Learn by Examples
+
+All runnable examples are available in
+[`examples`](examples), and they can be executed together with:
+
+```bash
+bash examples/example.sh
+```
+
+- [`examples/example_1.py`](examples/example_1.py) - Simple
+  emitter request and response
+- [`examples/example_2.py`](examples/example_2.py) - Multi-step
+  sequence execution
+- [`examples/example_3.py`](examples/example_3.py) - Context-driven
+  sequence
+- [`examples/example_4.py`](examples/example_4.py) - Nested
+  sequence pipelines
+- [`examples/example_5.py`](examples/example_5.py) - Branch routing
+  with `BranchPipe`
+- [`examples/example_6.py`](examples/example_6.py) - `MultiPipe`
+  fan-out
+- [`examples/example_7.py`](examples/example_7.py) - Policy-governed
+  execution
+- [`examples/example_8.py`](examples/example_8.py) - Hierarchical
+  memory resolution
+- [`examples/example_9.py`](examples/example_9.py) - Graceful early
+  stop with `CUT`
+- [`examples/example_10.py`](examples/example_10.py) - Error
+  rollback during execution
+
+Learn more about each area on the Wiki pages:
+[GraphK Wiki](https://github.com/kochf1/graphk/wiki)

graphk-1.0.2/pyproject.toml

@@ -0,0 +1,83 @@
+# =================================================================
+# Project Configuration
+# pip install -e .
+# =================================================================
+
+# =================================================================
+# Build System
+# =================================================================
+[build-system]
+requires = [
+    "hatchling"
+]
+build-backend = "hatchling.build"
+
+# =================================================================
+# Project Metadata
+# =================================================================
+[project]
+name = "graphk"
+dynamic = ["version"]
+description = "Framework for Graph-based execution and pipeline programming"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["graph", "pipeline", "workflow", "execution", "runtime"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+authors = [
+    { name = "Fernando Koch", email = "kochf@fau.edu" }
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/kochf1/graphk"
+Repository = "https://github.com/kochf1/graphk"
+Documentation = "https://github.com/kochf1/graphk/wiki"
+Issues = "https://github.com/kochf1/graphk/issues"
+
+
+# =================================================================
+# CLI (only enable if CLI exists)
+# =================================================================
+# [project.scripts]
+# PACKAGE = "PACKAGE.ui.cli:main"
+
+# =================================================================
+# Build targets
+# =================================================================
+[tool.hatch.build.targets.wheel]
+packages = ["src/graphk"]
+
+[tool.hatch.version]
+path = "src/graphk/__init__.py"
+
+# =================================================================
+# Source distribution contents
+# =================================================================
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/graphk",
+    "README.md",
+    "LICENSE.txt",
+    "pyproject.toml",
+]
+
+# =================================================================
+# Build data
+# =================================================================
+[tool.hatch.build]
+artifacts = []

graphk-1.0.2/src/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.
+"""