Home

Getting Started With GraphK

Imagine you are building a very small processing service.

A request arrives with one value. You want to process that value through a few explicit steps, keep the execution state visible, and produce one final response. You do not want hidden orchestration. You want the architecture to be readable.

That is the problem GraphK solves.

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 best way to understand GraphK is to follow one small story.

A First Story

Suppose you want to process a request with one input field:

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

The story begins 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

Now that one unit of behavior exists, you can 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 architecture says:

• start here
• then move here
• then finish here

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

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

Two Ways To Continue

From here, there are two natural learning paths.

The first path is to learn by running complete examples from simple to advanced:

• 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 to extend GraphK itself:

• create your own nodes
• create your own pipelines
• learn how context, policy, branching, and emitters fit into custom architectures

Those two paths are documented separately:

• Learn By Example
• Extend GraphK