Metadata-Version: 2.4
Name: graphk
Version: 1.0.4
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 is a Python framework for graph-based execution and pipeline programming. It models execution as explicit nodes, pipelines, runtime sessions, scoped context, and policy checks. The objective is a small execution kernel for graph-based workflows. GraphK provides composition and runtime control. 

- `Store` and `Matcher`
- `Session`, `Context`, and `Policy`
- `Node`
- `Pipeline`, `SequencePipe`, `BranchPipe`, and `MultiPipe`
- `Runner`
- `Emitter`

Report issues at [GraphK Issues](https://github.com/kochf1/graphk/issues).

## Getting Started

Install from PyPI when published:

```bash
pip install graphk
```

All examples use the public import form:

```python
import graphk
```

### Experiment 1: First Request And Response

What is being presented?

The smallest useful GraphK flow: one pipeline, one emitter, one request, one response.

What does it mean?

This example shows the public execution surface with no custom code.

```python
import graphk


pipeline = graphk.SequencePipe(nodes=[graphk.demo.EchoNode()])
emitter = graphk.Emitter(pipeline)

emitter.request({"value": 5})

print(emitter.response())
```

Expected result:

```python
{"value": 5, "double": 10}
```

### Experiment 2: Sequential Pipeline

What is being presented?

Several nodes running in a fixed order inside one pipeline.

What does it mean?

The pipeline is the execution architecture. Every node reads and writes the same session.

```python
import graphk


pipeline = graphk.SequencePipe(
    nodes=[
        graphk.demo.IncrementNode("A", increment=1, target_key="counter", order_key="order", response=True),
        graphk.demo.IncrementNode("B", increment=2, target_key="counter", order_key="order", response=True),
        graphk.demo.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"]}
```

### Experiment 3: Context And Policy

What is being presented?

Scoped runtime values and rule-based execution checks.

What does it mean?

`Context` carries scoped execution data. `Policy` checks entry and exit conditions against the active state.

```python
import graphk


allow_entry = graphk.Policy(task="go", **{"@Node/stage": "work"})

pipeline = graphk.SequencePipe(
    nodes=[
        graphk.demo.IncrementNode(
            "Prepare",
            increment=2,
            target_key="counter",
            response=True,
            context=graphk.Context(stage="work"),
            entry_policy=allow_entry,
            exit_policy=graphk.Policy(counter=">=2"),
        )
    ]
)

emitter = graphk.Emitter(pipeline, context=graphk.Context(mode="strict"))
emitter.request({"task": "go", "counter": 0})

print(emitter.response())
```

### Experiment 4: Managed Execution With Runner

What is being presented?

The explicit execution engine for pipelines.

What does it mean?

`Runner` is the main execution API when session lifecycle and pipeline control need to remain visible.

```python
import graphk


pipeline = graphk.SequencePipe(
    nodes=[
        graphk.demo.IncrementNode("A", increment=1, target_key="counter"),
        graphk.demo.IncrementNode("B", increment=2, target_key="counter"),
    ]
)

session = graphk.Session(counter=0)
runner = graphk.Runner(pipeline, session)

runner.start()
runner.run()

print(session.to_dict())
```

### Experiment 5: Branching And Fan-Out

What is being presented?

Two advanced routing forms: exclusive routing with `BranchPipe` and cumulative routing with `MultiPipe`.

What does it mean?

`BranchPipe` selects one matching branch. `MultiPipe` executes every matching branch.

```python
import graphk


branch = graphk.BranchPipe(
    nodes=[
        (graphk.Matcher(task="route-a"), graphk.SequencePipe(nodes=[graphk.demo.RouteNode("A")])),
        (graphk.Matcher(task="route-b"), graphk.SequencePipe(nodes=[graphk.demo.RouteNode("B")])),
    ]
)

multi = graphk.MultiPipe(
    nodes=[
        (graphk.Matcher(group="alpha"), graphk.SequencePipe(nodes=[graphk.demo.RouteNode("A")])),
        (graphk.Matcher(group="alpha"), graphk.SequencePipe(nodes=[graphk.demo.RouteNode("B")])),
    ]
)

route_emitter = graphk.Emitter(graphk.SequencePipe(nodes=[branch]))
route_emitter.request({"task": "route-b"})
print(route_emitter.response())

multi_emitter = graphk.Emitter(graphk.SequencePipe(nodes=[multi]))
multi_emitter.request({"group": "alpha"})
print(multi_emitter.response())
```

## Learn More

The repository examples and tests work as learn-by-example material.

Examples:

- [`examples/example_1.py`](https://github.com/kochf1/graphk/blob/main/examples/example_1.py)
- [`examples/example_4.py`](https://github.com/kochf1/graphk/blob/main/examples/example_4.py)
- [`examples/example_5.py`](https://github.com/kochf1/graphk/blob/main/examples/example_5.py)
- [`examples/example_6.py`](https://github.com/kochf1/graphk/blob/main/examples/example_6.py)
- [`examples/example_7.py`](https://github.com/kochf1/graphk/blob/main/examples/example_7.py)

Tests:

- [`tests/common/`](https://github.com/kochf1/graphk/tree/main/tests/common)
- [`tests/core/`](https://github.com/kochf1/graphk/tree/main/tests/core)
- [`tests/pipes/`](https://github.com/kochf1/graphk/tree/main/tests/pipes)

Wiki:

- [GraphK Wiki](https://github.com/kochf1/graphk/wiki)
