Skip to content

How To Use Policy

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

How To Use Policy

Purpose

Use Policy to govern whether execution is allowed to start or complete at a given boundary.

In GraphK, policies are usually attached to:

  • nodes
  • pipelines
  • runners

The most common uses are:

  • entry validation
  • exit validation
  • stop-or-skip decisions after policy failures

What Is Policy?

graphk.Policy is an execution-aware Matcher.

It inherits all matcher rule behavior and adds an execution strategy.

Important constants:

  • Policy.EXECUTION_STOP
  • Policy.EXECUTION_SKIP
  • Policy.EXECUTION_RECONSIDER

In current practical usage, the main strategies are:

  • EXECUTION_STOP
  • EXECUTION_SKIP

How Policies Are Used

Each node already carries:

  • entry_policy
  • exit_policy

During runner-managed execution:

  1. entry policy is checked before the node executes
  2. exit policy is checked after the node finishes
  3. the execution strategy decides whether to stop or skip on failure

Minimal Example

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"),
        )
    ]
)

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

runner.start()
runner.run()

print(session.to_dict())

Entry Policy Use Cases

Use entry policies when a node should only begin under specific conditions.

Examples:

  • allow a node only when task="go"
  • allow a node only in a given stage
  • allow a node only when runner mode is strict

Exit Policy Use Cases

Use exit policies when a node must prove that it completed successfully.

Examples:

  • counter must be at least a threshold
  • response must exist
  • route must have been selected

STOP vs SKIP

EXECUTION_STOP

Use when:

  • the pipeline must terminate if the rule fails
  • the failure means the workflow is invalid

Typical effect:

  • execution stops
  • session is marked as error

EXECUTION_SKIP

Use when:

  • a node is optional
  • failure should discard the node result and continue

Typical effect:

  • runner rolls back the node effect
  • execution continues with later nodes

Common Mistakes

  • Do not reimplement policy checks manually inside every node when entry/exit policies already express the rule.
  • Do not confuse matching rules with execution strategy; the rule decides pass/fail, the strategy decides what to do after failure.
  • Do not attach user-facing validation logic only to internals if it should be part of the public execution contract.

Learn More

Recommended references:

Clone this wiki locally