Skip to main content

​
Gates

Gate nodes control execution flow in graphs. They make routing decisions but do not produce data outputs.

​
Gate Decorators

​
@route

from hypergraph import route, END

@route(targets=["process_a", "process_b", END])
def decide(x: int) -> str:
    if x == 0:
        return END
    return "process_a" if x > 0 else "process_b"
Decorator to create a RouteNode from a routing function.
​
targets
list[str | type[END]] | dict[str | type[END], str]
required
Valid target names. Can be a list or dict with descriptions for visualization
​
fallback
str | type[END] | None
Default target if function returns None (incompatible with multi_target)
​
multi_target
bool
default:"False"
If True, function returns list of targets to run in parallel
​
cache
bool
default:"False"
Cache the routing function’s return value. On cache hit, the runner restores the routing decision without calling the function
​
hide
bool
default:"False"
Whether to hide from visualization
​
default_open
bool
default:"True"
If True, targets may execute before the gate runs the first time. If False, targets are blocked until the gate executes and records a decision
​
name
str | None
Node name (default: func.__name__)
​
rename_inputs
dict[str, str] | None
Mapping to rename inputs {old: new}
​
emit
str | tuple[str, ...] | None
Ordering-only output name(s)
​
wait_for
str | tuple[str, ...] | None
Ordering-only input name(s)
​
RouteNode
Returns a RouteNode instance

​
Return Value

The decorated function should return:
  • A target name (str) to activate that node
  • END to terminate execution along this path
  • None to use fallback (if set) or do nothing
  • A list of targets if multi_target=True

​
@ifelse

from hypergraph import ifelse, END

@ifelse(when_true="process", when_false="skip")
def is_valid(data: dict) -> bool:
    return data.get("valid", False)
Decorator to create an IfElseNode from a boolean function. Syntactic sugar for the common if/else branching pattern.
​
when_true
str | type[END]
required
Target to activate when function returns True
​
when_false
str | type[END]
required
Target to activate when function returns False
​
cache
bool
default:"False"
Cache the routing function’s return value
​
hide
bool
default:"False"
Whether to hide from visualization
​
default_open
bool
default:"True"
If True, targets may execute before the gate runs the first time. If False, targets are blocked until the gate executes
​
name
str | None
Node name (default: func.__name__)
​
rename_inputs
dict[str, str] | None
Mapping to rename inputs {old: new}
​
emit
str | tuple[str, ...] | None
Ordering-only output name(s)
​
wait_for
str | tuple[str, ...] | None
Ordering-only input name(s)
​
IfElseNode
Returns an IfElseNode instance

​
Return Value

The decorated function should return:
  • True: Routes to when_true target
  • False: Routes to when_false target

​
Gate Classes

​
GateNode

Abstract base class for routing/control flow nodes. Gate nodes make routing decisions but do not produce data outputs.
​
name
str
Node name
​
inputs
tuple[str, ...]
Input parameter names from function signature
​
outputs
tuple[str, ...]
Always empty tuple or emit-only outputs (gates produce no data)
​
targets
list[str | type[END]]
List of valid target names (or END)
​
descriptions
dict[str | type[END] | bool, str]
Optional descriptions for visualization
​
func
Callable
The routing function

​
Properties

​
cache
bool
Whether routing function results should be cached
​
hide
bool
Whether this node is hidden from visualization
​
wait_for
tuple[str, ...]
Ordering-only inputs this gate waits for
​
data_outputs
tuple[str, ...]
Gates produce no data outputs (always empty tuple)
​
is_async
bool
Route functions must be sync, so always False
​
is_generator
bool
Route functions must not be generators, so always False

​
RouteNode

Routes execution to target nodes based on a routing function’s return value. 
from hypergraph import RouteNode, END

def decide(x: int) -> str:
    if x == 0:
        return END
    return "process_a" if x > 0 else "process_b"

node = RouteNode(decide, targets=["process_a", "process_b", END])
​
func
Callable[..., str | type[END] | list[str | type[END]] | None]
required
Function that returns target name(s) or END
​
targets
list[str | type[END]] | dict[str | type[END], str]
required
Valid targets (list or dict with descriptions)
​
fallback
str | type[END] | None
Default target if func returns None (incompatible with multi_target)
​
multi_target
bool
default:"False"
If True, func returns list of targets to run in parallel
​
cache
bool
default:"False"
Whether to cache routing decisions
​
hide
bool
default:"False"
Whether to hide from visualization
​
default_open
bool
default:"True"
If True, targets may execute before the gate runs the first time
​
name
str | None
Node name (default: func.__name__)
​
rename_inputs
dict[str, str] | None
Mapping to rename inputs {old: new}
​
emit
str | tuple[str, ...] | None
Ordering-only output name(s)
​
wait_for
str | tuple[str, ...] | None
Ordering-only input name(s)

​
Properties

​
fallback
str | type[END] | None
Default target if function returns None
​
multi_target
bool
Whether function returns list of targets

​
IfElseNode

Binary gate that routes based on boolean decision. 
from hypergraph import IfElseNode

def is_valid(data: dict) -> bool:
    return data.get("valid", False)

node = IfElseNode(is_valid, when_true="process", when_false="skip")
​
func
Callable[..., bool]
required
Function that returns True or False
​
when_true
str | type[END]
required
Target to activate when func returns True
​
when_false
str | type[END]
required
Target to activate when func returns False
​
cache
bool
default:"False"
Whether to cache routing decisions
​
hide
bool
default:"False"
Whether to hide from visualization
​
default_open
bool
default:"True"
If True, targets may execute before the gate runs the first time
​
name
str | None
Node name (default: func.__name__)
​
rename_inputs
dict[str, str] | None
Mapping to rename inputs {old: new}
​
emit
str | tuple[str, ...] | None
Ordering-only output name(s)
​
wait_for
str | tuple[str, ...] | None
Ordering-only input name(s)

​
Properties

​
when_true
str | type[END]
Target when function returns True
​
when_false
str | type[END]
Target when function returns False

​
END Sentinel

​
END

Sentinel class indicating execution should terminate along this path. 
from hypergraph import route, END

@route(targets=["process", END])
def decide(x: int) -> str:
    return END if x == 0 else "process"
END is a class, not an instance. Use it directly (END, not END()).

Build docs developers (and LLMs) love

Get started for freeTalk to us