Skip to content

How To Use Context

Jump to bottom
Fernando Koch edited this page Mar 30, 2026 · 3 revisions

How To Use Context

Purpose

Use Context to carry scoped execution data that should be available to nodes, pipelines, and runners without storing that data as final runtime output.

Typical context values include:

  • stage names
  • route selectors
  • modes
  • configuration flags
  • environment-like execution settings

What Is Context?

graphk.Context is a scoped Store.

It behaves like hierarchical state, but its role is different from Session:

  • Context is configuration
  • Session is runtime result state

Use context for values that shape execution. Use session for values produced by execution.

The Context Chain

GraphK contexts can attach to each other through parent relationships. This creates a context chain.

Typical resolution chain during execution:

  1. Session
  2. Node
  3. Pipeline
  4. Runner
  5. Program

This means a node can access values coming from different levels with GraphK's scoped key syntax.

Examples:

  • mode Search upward through the chain.

  • @Node/stage Read the nearest node-level context value named stage.

  • @Pipeline/route Read the nearest pipeline-level context value named route.

  • @Runner/mode Read a runner-level execution setting.

  • @Program/mode Read a program-level shared execution setting.

Why Does The Context Chain Matter?

It lets you:

  • avoid passing the same parameters through many method calls
  • keep local configuration local
  • override higher-level values at lower levels when needed
  • route execution based on scoped state

Minimal Example

import graphk


node = graphk.demo.IncrementNode(
    "A",
    increment=1,
    target_key="counter",
    context=graphk.Context(stage="node-stage"),
)

pipeline = graphk.SequencePipe(
    nodes=[node],
    context=graphk.Context(route="alpha"),
)

program = graphk.Program({"main": pipeline}, context=graphk.Context(mode="strict"))
session = graphk.Session(counter=0)
emitter = graphk.Emitter(program)

emitter.request("main", session)

print(session.get("@Node/stage"))
print(session.get("@Pipeline/route"))
print(session.get("@Runner/mode"))
print(session.get("@Program/mode"))

How Attachment Works

GraphK attaches contexts when parent/child objects are connected.

Typical behavior:

  • a node context attaches to its pipeline context
  • a pipeline context attaches to its parent pipeline, runner, or program context
  • a session attaches to the current node or runner context during execution

This means context resolution is dynamic and execution-aware.

Common Use Cases

Stage Tagging

Give each node a local stage:

graphk.Context(stage="validate")

Route Selection

Give a pipeline a route name:

graphk.Context(route="alpha")

Execution Mode

Give a runner a high-level mode:

graphk.Context(mode="strict")

Common Mistakes

  • Do not store final results in Context when they belong in Session.
  • Do not use global variables for configuration that should be scoped.
  • Do not forget that unscoped get("value") resolves upward through the chain.

Learn More

Recommended references:

Clone this wiki locally