API Reference

Every symbol listed below is part of the stable v0.1.0 public surface re-exported from the top-level langgoap package. Anything not listed here is internal and subject to change without notice.

Core

langgoap.GoapGraph	Builder that produces a compiled LangGraph for GOAP execution.
langgoap.ActionSpec	Specification of a GOAP action for planning.
langgoap.GoapAction	Base class for object-oriented GOAP action definitions.
langgoap.goap_action	Decorator that converts a function into an ActionSpec.
langgoap.GoalSpec	Specification of a GOAP goal.
langgoap.Goal
langgoap.MultiGoal	A composite goal made up of one or more GoalSpec children.
langgoap.ConstraintSpec	A resource/budget constraint for CSP optimization.
langgoap.PlanningState	Immutable, hashable representation of a GOAP world state.
langgoap.ActionResult	Result of executing a single GOAP action.
langgoap.GoapState	LangGraph state schema for the GOAP execution loop.

Planning

langgoap.planner.astar.plan	Find an optimal action sequence from start to goal using A*.
langgoap.pipeline_plan	Two-phase planning: A* finds sequences, CSP validates/optimizes.
langgoap.Plan	A sequence of actions that achieves a goal from a given start state.
langgoap.PlanMetadata	Metadata about how a plan was generated.
langgoap.PlanningStrategy	A pluggable planning strategy.
langgoap.AStarStrategy	Pure A* construction heuristic.
langgoap.CSPRefinementStrategy	Run CSP validation / optimization over an existing candidate plan.
langgoap.TwoPhasePipelineStrategy	A* construction + CSP refinement, composed as a single strategy.

Constraints, scoring, and CSP

langgoap.Score	Abstract base for all score types.
langgoap.SimpleScore	A single scalar score.
langgoap.HardSoftScore	A two-level score with hard and soft components.
langgoap.BendableScore	A variable-width score with any number of hard and soft levels.
langgoap.ConstraintBuilder	Factory and aggregator for ConstraintChain instances.
langgoap.ConstraintChain	A single in-progress fluent chain.
langgoap.ChainOutput	Output of a single terminated builder chain.
langgoap.BuilderOutput	Tagged bundle returned by ConstraintBuilder.build().
langgoap.CSPMetadata	Results from the CSP optimizer.
langgoap.CSPStatus	Status of a CSP solve attempt.
langgoap.ResourceUsage	Per-key resource breakdown for a plan.
langgoap.ScheduleEntry	Per-action temporal slot in a schedule.

Integrations (low-code LangGraph on-ramp)

langgoap.create_goap_agent	Create a compiled GOAP agent from a list of LangChain tools and a goal.
langgoap.goapify_tool	Wrap a LangChain BaseTool into a LangGOAP ActionSpec.
langgoap.GoapSubgraph	A GOAP planner packaged as a reusable sub-graph.
langgoap.add_goap_subgraph	Attach a GOAP sub-graph as a node inside a parent StateGraph.

Natural-language goal interpreter

langgoap.GoalInterpreter	Converts natural language requests into GoalSpec objects via LLM.
langgoap.InterpretedGoal	Structured goal extracted from a natural language request.
langgoap.InterpretedConstraint	A resource constraint extracted from natural language.
langgoap.InterpretedObjective	An optimization objective extracted from natural language.

Graph nodes

langgoap.GoapPlanner	LangGraph node that invokes the planner.
langgoap.GoapExecutor	LangGraph node that executes the current action in the plan.
langgoap.GoapObserver	LangGraph node that decides the next step via Command routing.

Tracing

langgoap.PlanningTracer	Sync + async observability hooks for the GOAP planning loop.
langgoap.NullTracer	No-op tracer — the default when no tracer is configured.
langgoap.LoggingTracer	Tracer that routes every event through stdlib logging.
langgoap.MultiTracer	Fan a single event out to multiple tracers.

Execution history

langgoap.ExecutionRecord	One planner → executor → observer loop outcome.
langgoap.StoreExecutionHistory	Execution history backed by a LangGraph BaseStore.
langgoap.compute_goal_hash	Return a stable short hash of a goal's conditions.

Types

langgoap.CostFunction	Protocol for dynamic action cost functions.
langgoap.Maximize	Direction for numeric optimization objectives.
langgoap.Minimize	Direction for numeric optimization objectives.
langgoap.ObjectiveDirection	Direction for numeric optimization objectives.
langgoap.ReplanStrategy	When to trigger replanning during execution.

Visualization

langgoap.render_mermaid	Render a Plan as a Mermaid flowchart TD diagram.
langgoap.render_mermaid_gantt	Render a Plan's schedule as a Mermaid gantt chart.
langgoap.render_dot	Render a Plan as a Graphviz DOT digraph.
langgoap.render_ascii	Render a Plan as a top-to-bottom ASCII tree.
langgoap.render_ascii_gantt	Render the plan's schedule as an ASCII Gantt chart.
langgoap.visualize	Render a Plan for display.