langgoap.GoapGraph

langgoap.GoapGraph#

class GoapGraph(actions, *, strategy=None, tracer=None, history=None, sensors=None, guards=None, resolvers=None, record_expansions=False, transition_model=None, rng=None, stuck_handlers=None, max_stuck_iterations=3, termination_policies=None)[source]#

Builder that produces a compiled LangGraph for GOAP execution.

Supports two usage styles:

Explicit compile + invoke (for power users who need the compiled graph):

graph = GoapGraph(actions=[action1, action2, ...])
compiled = graph.compile(checkpointer=saver)
result = compiled.invoke({
    "goal": GoalSpec(conditions={"done": True}),
    "world_state": {"a": True},
})

Convenience invoke (single-shot, no persistence):

graph = GoapGraph(actions=[action1, action2, ...])
result = graph.invoke(
    goal=GoalSpec(conditions={"done": True}),
    world_state={"a": True},
)

Custom planning strategy:

from langgoap.planner.strategy import LazyDecompositionStrategy
graph = GoapGraph(
    actions=[action1, action2, ...],
    strategy=LazyDecompositionStrategy(lookahead=2),
)
result = graph.invoke(goal=goal, world_state={})

The graph structure is:

START → planner → executor → observer ──→ END
          ↑                     │
          └─────────────────────┘
Parameters:

  • actions (list[ActionSpec]) – The action library available to the planner and executor.

  • strategy (PlanningStrategy | None) – Optional PlanningStrategy. Defaults to the A* strategy wired inside GoapPlanner.

  • tracer (PlanningTracer | None) – Optional PlanningTracer for planning/execution observability.

  • history (StoreExecutionHistory | None) – Optional StoreExecutionHistory for persisting execution traces.

  • sensors (list[Sensor | AsyncSensor] | None) – Optional list of Sensor / AsyncSensor run before planning.

  • guards (list[ActionGuard | AsyncActionGuard] | None) – Optional list of ActionGuard / AsyncActionGuard evaluated before each action executes.

  • resolvers (list[ConditionResolver | AsyncConditionResolver] | None) – Optional list of dynamic condition resolvers applied to precondition evaluation.

  • record_expansions (bool) – Forwarded to GoapPlanner; enables node expansion trace recording for post-hoc analysis.

  • transition_model (TransitionModel | None) – Optional TransitionModel threaded into GoapExecutor. When provided, actions with no execute callable (or those returning None) have their runtime effects drawn from transition_model.sample. Use the same model you passed to MCTSStrategy so plan-time and runtime share one noise distribution.

  • rng (random.Random | None) – Optional random.Random forwarded to the executor for reproducible sampling.

  • stuck_handlers (list[StuckHandler] | None)

  • max_stuck_iterations (int)

  • termination_policies (list[TerminationPolicy] | None)

__init__(actions, *, strategy=None, tracer=None, history=None, sensors=None, guards=None, resolvers=None, record_expansions=False, transition_model=None, rng=None, stuck_handlers=None, max_stuck_iterations=3, termination_policies=None)[source]#
Parameters:

  • actions (list[ActionSpec])

  • strategy (PlanningStrategy | None)

  • tracer (PlanningTracer | None)

  • history (StoreExecutionHistory | None)

  • sensors (list[Sensor | AsyncSensor] | None)

  • guards (list[ActionGuard | AsyncActionGuard] | None)

  • resolvers (list[ConditionResolver | AsyncConditionResolver] | None)

  • record_expansions (bool)

  • transition_model (TransitionModel | None)

  • rng (random.Random | None)

  • stuck_handlers (list[StuckHandler] | None)

  • max_stuck_iterations (int)

  • termination_policies (list[TerminationPolicy] | None)

Return type:

None

Methods

__init__(actions, *[, strategy, tracer, ...])

ainvoke(goal[, world_state, config])

Async convenience method: compile and invoke the graph.

ainvoke_nl(request[, world_state, config, ...])

Async variant of invoke_nl().

compile([checkpointer, store, ...])

Build and compile the GOAP StateGraph.

invoke(goal[, world_state, config])

Convenience method: compile and invoke the graph in one call.

invoke_nl(request[, world_state, config, ...])

Interpret a natural language request and execute the GOAP loop.