Home

GraphK WIKI

GraphK is built around graph programming.

Execution is modeled as a graph of small units with clear responsibilities. Each unit does one thing. Pipelines define structure. Sessions carry runtime state. Policies and context define execution conditions and scoped values.

The result is a package for building process architectures that are:

• explicit
• composable
• state-aware
• easy to inspect

GraphK gives you a small execution model:

• a Node defines one executable unit of behavior
• a Pipeline turns nodes into an architecture
• a Session carries runtime state
• an Emitter or Runner executes the graph

The easiest way to understand that model is to follow one small story.

Illustrative Scenario

Consider a small processing service.

A request arrives with one value. The service must process that value through a few explicit steps, keep execution state visible, and return one final response. The architecture must remain readable in the code.

Suppose the request contains one input field:

• read value
• transform it step by step
• return one response

The story starts with one node.

import graphk


class IncrementNode(graphk.Node):

    def __init__(self, name: str, increment: int = 1, **kwargs) -> None:
        super().__init__(**kwargs)
        self._name = name
        self._increment = increment

    def ping(self) -> bool:
        return True

    def info(self) -> dict:
        return {"name": self._name}

    def step(self):
        current = self.session.get("value", 0)
        current += self._increment
        self.session.set("value", current)
        self.session.set("response", {"value": current})
        yield current

That node defines one unit of behavior. The next step is to give it an architecture.

import graphk


pipeline = graphk.SequencePipe(
    nodes=[
        IncrementNode("Prepare", increment=1),
        IncrementNode("Enrich", increment=2),
        IncrementNode("Finalize", increment=3),
    ]
)

Now the graph has shape. The pipeline says:

• start here
• then move here
• then finish here

To execute that graph, create the runtime state and send it through the pipeline.

import graphk


session = graphk.Session(value=10)
emitter = graphk.Emitter(pipeline, session=session)

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

print(emitter.response())
print(session.to_dict())

That is the first complete GraphK pattern:

1. define behavior with nodes
2. compose behavior into a pipeline
3. create a session
4. execute through an emitter or runner
5. inspect the final session and response

The package grows from this same structure. More advanced use cases do not replace this model. They extend it with richer context, policies, branching, and multi-route execution.

Where To Go Next

Two paths follow from this starting point.

The first path is for usage:

• start with one request/response flow
• then add more nodes
• then add scoped context and policies
• then add branching and multi-route execution

The second path is for extension:

• create your own nodes

• create your own pipelines

• learn how context, policy, branching, and emitters fit into custom architectures

• Learn By Example

• Extend GraphK