langgoap 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. langgoap/__init__.py +371 -0
  2. langgoap/_score_base.py +74 -0
  3. langgoap/_version.py +3 -0
  4. langgoap/actions.py +450 -0
  5. langgoap/callbacks.py +180 -0
  6. langgoap/cli/__init__.py +7 -0
  7. langgoap/cli/_loader.py +131 -0
  8. langgoap/cli/actions_cmd.py +104 -0
  9. langgoap/cli/deploy_init_cmd.py +116 -0
  10. langgoap/cli/explain_cmd.py +60 -0
  11. langgoap/cli/main.py +28 -0
  12. langgoap/cli/plan_cmd.py +165 -0
  13. langgoap/cli/visualize_cmd.py +69 -0
  14. langgoap/conditions.py +398 -0
  15. langgoap/constraints.py +306 -0
  16. langgoap/goals.py +358 -0
  17. langgoap/graph/__init__.py +1 -0
  18. langgoap/graph/builder.py +389 -0
  19. langgoap/graph/nodes/__init__.py +87 -0
  20. langgoap/graph/nodes/_execution.py +353 -0
  21. langgoap/graph/nodes/_helpers.py +133 -0
  22. langgoap/graph/nodes/executor.py +317 -0
  23. langgoap/graph/nodes/observer.py +440 -0
  24. langgoap/graph/nodes/parallel_executor.py +314 -0
  25. langgoap/graph/nodes/planner.py +667 -0
  26. langgoap/graph/state.py +117 -0
  27. langgoap/guards.py +277 -0
  28. langgoap/history.py +309 -0
  29. langgoap/integrations/__init__.py +42 -0
  30. langgoap/integrations/deepagents.py +249 -0
  31. langgoap/integrations/langgraph_deploy.py +230 -0
  32. langgoap/integrations/prebuilt.py +197 -0
  33. langgoap/integrations/subgraph.py +122 -0
  34. langgoap/integrations/tools.py +179 -0
  35. langgoap/interpreter.py +350 -0
  36. langgoap/planner/__init__.py +5 -0
  37. langgoap/planner/agents.py +99 -0
  38. langgoap/planner/astar.py +530 -0
  39. langgoap/planner/csp.py +944 -0
  40. langgoap/planner/explain.py +337 -0
  41. langgoap/planner/mcts.py +1144 -0
  42. langgoap/planner/metrics.py +126 -0
  43. langgoap/planner/pipeline.py +289 -0
  44. langgoap/planner/repair.py +229 -0
  45. langgoap/planner/router.py +206 -0
  46. langgoap/planner/strategy.py +341 -0
  47. langgoap/planner/transitions.py +210 -0
  48. langgoap/planner/types.py +262 -0
  49. langgoap/planner/utility.py +171 -0
  50. langgoap/qos.py +126 -0
  51. langgoap/reflexion.py +412 -0
  52. langgoap/score.py +159 -0
  53. langgoap/sensors.py +186 -0
  54. langgoap/serde.py +716 -0
  55. langgoap/state.py +147 -0
  56. langgoap/stuck.py +206 -0
  57. langgoap/termination.py +299 -0
  58. langgoap/testing.py +92 -0
  59. langgoap/tracing/__init__.py +34 -0
  60. langgoap/tracing/_helpers.py +105 -0
  61. langgoap/tracing/_protocol.py +160 -0
  62. langgoap/tracing/_safe_proxy.py +99 -0
  63. langgoap/tracing/_search_buffer.py +124 -0
  64. langgoap/tracing/langsmith.py +563 -0
  65. langgoap/tracing/logging.py +156 -0
  66. langgoap/tracing/multi.py +182 -0
  67. langgoap/tracing/null.py +127 -0
  68. langgoap/types.py +36 -0
  69. langgoap/viz/__init__.py +42 -0
  70. langgoap/viz/ascii.py +196 -0
  71. langgoap/viz/dot.py +145 -0
  72. langgoap/viz/jupyter.py +128 -0
  73. langgoap/viz/mermaid.py +273 -0
  74. langgoap/viz/save.py +78 -0
  75. langgoap-0.1.1.dist-info/METADATA +366 -0
  76. langgoap-0.1.1.dist-info/RECORD +79 -0
  77. langgoap-0.1.1.dist-info/WHEEL +4 -0
  78. langgoap-0.1.1.dist-info/entry_points.txt +2 -0
  79. langgoap-0.1.1.dist-info/licenses/LICENSE +21 -0
langgoap/__init__.py ADDED
@@ -0,0 +1,371 @@
1
+ """LangGOAP: Goal-Oriented Action Planning framework for LangGraph."""
2
+
3
+ import logging
4
+
5
+ from langgoap._version import __version__
6
+
7
+
8
+ def set_log_level(level: str | int) -> None:
9
+ """Set the log level for all langgoap loggers.
10
+
11
+ Convenience function replacing the common 2-line pattern::
12
+
13
+ import logging
14
+ logging.getLogger("langgoap").setLevel(logging.ERROR)
15
+
16
+ With::
17
+
18
+ import langgoap
19
+ langgoap.set_log_level("ERROR")
20
+
21
+ Args:
22
+ level: Log level as a string (e.g. ``"ERROR"``, ``"DEBUG"``)
23
+ or an ``int`` (e.g. ``logging.WARNING``).
24
+ """
25
+ logging.getLogger("langgoap").setLevel(level)
26
+
27
+
28
+ from langgoap.actions import ActionSpec, EffectFunction, GoapAction, goap_action
29
+ from langgoap.callbacks import DEFAULT_COST_PER_1K_TOKENS, CostAccumulator
30
+ from langgoap.conditions import (
31
+ AsyncConditionResolver,
32
+ ConditionResolver,
33
+ ConditionStatus,
34
+ FunctionalConditionResolver,
35
+ PromptConditionResolver,
36
+ aresolve_conditions,
37
+ resolve_conditions,
38
+ )
39
+ from langgoap.constraints import (
40
+ BuilderOutput,
41
+ ChainOutput,
42
+ ConstraintBuilder,
43
+ ConstraintChain,
44
+ )
45
+ from langgoap.goals import (
46
+ ConstraintSpec,
47
+ Goal,
48
+ GoalPolicy,
49
+ GoalSpec,
50
+ MultiGoal,
51
+ SoftGoal,
52
+ )
53
+ from langgoap.graph.builder import GoapGraph
54
+ from langgoap.graph.nodes import (
55
+ GoapExecutor,
56
+ GoapObserver,
57
+ GoapPlanner,
58
+ ParallelGoapExecutor,
59
+ )
60
+ from langgoap.graph.state import ActionResult, GoapState, successful_action_names
61
+ from langgoap.guards import (
62
+ ActionGuard,
63
+ AsyncActionGuard,
64
+ FunctionalGuard,
65
+ GuardResult,
66
+ GuardSeverity,
67
+ has_blocking_failure,
68
+ run_guards_async,
69
+ run_guards_sync,
70
+ )
71
+ from langgoap.history import (
72
+ ExecutionRecord,
73
+ StoreExecutionHistory,
74
+ compute_goal_hash,
75
+ )
76
+ from langgoap.integrations import (
77
+ GoapSubgraph,
78
+ add_goap_subgraph,
79
+ create_goap_agent,
80
+ create_goap_subagent,
81
+ create_goap_tool,
82
+ format_goap_result,
83
+ goapify_tool,
84
+ scaffold_deployment,
85
+ )
86
+ from langgoap.interpreter import (
87
+ GoalInterpreter,
88
+ InterpretedConstraint,
89
+ InterpretedGoal,
90
+ InterpretedObjective,
91
+ )
92
+ from langgoap.planner.astar import plan
93
+ from langgoap.planner.csp import (
94
+ CSPMetadata,
95
+ CSPStatus,
96
+ ResourceUsage,
97
+ ScheduleEntry,
98
+ pareto_plans,
99
+ )
100
+ from langgoap.planner.explain import (
101
+ InfeasibilityExplanation,
102
+ NoPlanExplanation,
103
+ ResourceShortfall,
104
+ explain_infeasibility,
105
+ explain_no_plan,
106
+ )
107
+ from langgoap.planner.mcts import (
108
+ MCTSExploration,
109
+ MCTSReuseConfig,
110
+ MCTSStrategy,
111
+ MCTSTracingConfig,
112
+ )
113
+ from langgoap.planner.pipeline import plan as pipeline_plan
114
+ from langgoap.planner.repair import RepairStrategy
115
+ from langgoap.planner.router import (
116
+ ProblemFeatures,
117
+ RuleBasedClassifier,
118
+ StrategyClassifier,
119
+ StrategyRouter,
120
+ extract_features,
121
+ )
122
+ from langgoap.planner.strategy import (
123
+ AnytimePlanningStrategy,
124
+ AStarStrategy,
125
+ CSPRefinementStrategy,
126
+ LazyDecompositionStrategy,
127
+ PlanningStrategy,
128
+ TwoPhasePipelineStrategy,
129
+ )
130
+ from langgoap.planner.transitions import (
131
+ DeterministicTransitionModel,
132
+ DivergencePolicy,
133
+ TransitionModel,
134
+ )
135
+ from langgoap.planner.types import Plan, PlanMetadata
136
+ from langgoap.planner.utility import (
137
+ NIRVANA_NAME,
138
+ NirvanaGoal,
139
+ UtilityStrategy,
140
+ is_nirvana,
141
+ )
142
+ from langgoap.qos import DEFAULT_RETRY_POLICY, FIRE_ONCE, ActionQos
143
+ from langgoap.reflexion import Reflection, ReflexionTracer
144
+ from langgoap.score import BendableScore, HardSoftScore, Score, SimpleScore
145
+ from langgoap.sensors import (
146
+ AsyncSensor,
147
+ FunctionalSensor,
148
+ Sensor,
149
+ run_sensors_async,
150
+ run_sensors_sync,
151
+ )
152
+ from langgoap.serde import (
153
+ LANGGOAP_ALLOWED_MSGPACK_TYPES,
154
+ LangGOAPSerializer,
155
+ install_langgoap_serde,
156
+ )
157
+ from langgoap.state import PlanningState, infer_start_state
158
+ from langgoap.stuck import (
159
+ FunctionalStuckHandler,
160
+ MulticastStuckHandler,
161
+ StuckHandler,
162
+ StuckHandlerResult,
163
+ StuckHandlingResultCode,
164
+ )
165
+ from langgoap.termination import (
166
+ AllOfPolicy,
167
+ EarlyTermination,
168
+ FirstOfPolicy,
169
+ MaxActionsPolicy,
170
+ MaxCostPolicy,
171
+ MaxLLMCallsPolicy,
172
+ MaxTokensPolicy,
173
+ MaxWallClockPolicy,
174
+ OnStuckPolicy,
175
+ TerminationPolicy,
176
+ )
177
+ from langgoap.tracing import (
178
+ LangSmithTracer,
179
+ LoggingTracer,
180
+ MultiTracer,
181
+ NullTracer,
182
+ PlanningTracer,
183
+ )
184
+ from langgoap.types import (
185
+ CostFunction,
186
+ Maximize,
187
+ Minimize,
188
+ ObjectiveDirection,
189
+ ReplanStrategy,
190
+ )
191
+ from langgoap.viz import (
192
+ render_ascii,
193
+ render_ascii_gantt,
194
+ render_dot,
195
+ render_mermaid,
196
+ render_mermaid_gantt,
197
+ visualize,
198
+ )
199
+
200
+ __all__ = [
201
+ "__version__",
202
+ "set_log_level",
203
+ # Actions
204
+ "ActionSpec",
205
+ "EffectFunction",
206
+ "GoapAction",
207
+ "goap_action",
208
+ # Conditions (three-valued logic + LLM-evaluated conditions)
209
+ "AsyncConditionResolver",
210
+ "ConditionResolver",
211
+ "ConditionStatus",
212
+ "FunctionalConditionResolver",
213
+ "PromptConditionResolver",
214
+ "aresolve_conditions",
215
+ "resolve_conditions",
216
+ # Goals
217
+ "ConstraintSpec",
218
+ "Goal",
219
+ "GoalSpec",
220
+ "GoalPolicy",
221
+ "MultiGoal",
222
+ "SoftGoal",
223
+ # Constraint builder
224
+ "BuilderOutput",
225
+ "ChainOutput",
226
+ "ConstraintBuilder",
227
+ "ConstraintChain",
228
+ # Integrations (low-code LangGraph on-ramp)
229
+ "create_goap_agent",
230
+ "create_goap_tool",
231
+ "create_goap_subagent",
232
+ "format_goap_result",
233
+ "goapify_tool",
234
+ "GoapSubgraph",
235
+ "add_goap_subgraph",
236
+ "scaffold_deployment",
237
+ # Interpreter
238
+ "GoalInterpreter",
239
+ "InterpretedConstraint",
240
+ "InterpretedGoal",
241
+ "InterpretedObjective",
242
+ # Graph
243
+ "GoapGraph",
244
+ "GoapPlanner",
245
+ "GoapExecutor",
246
+ "GoapObserver",
247
+ "ParallelGoapExecutor",
248
+ "GoapState",
249
+ "ActionResult",
250
+ "successful_action_names",
251
+ # Planning
252
+ "plan",
253
+ "pipeline_plan",
254
+ "Plan",
255
+ "PlanMetadata",
256
+ "PlanningState",
257
+ "infer_start_state",
258
+ # Planning strategies
259
+ "PlanningStrategy",
260
+ "AStarStrategy",
261
+ "AnytimePlanningStrategy",
262
+ "CSPRefinementStrategy",
263
+ "LazyDecompositionStrategy",
264
+ "MCTSStrategy",
265
+ "MCTSExploration",
266
+ "MCTSReuseConfig",
267
+ "MCTSTracingConfig",
268
+ "RepairStrategy",
269
+ "TwoPhasePipelineStrategy",
270
+ # Utility (greedy) planner
271
+ "NIRVANA_NAME",
272
+ "NirvanaGoal",
273
+ "UtilityStrategy",
274
+ "is_nirvana",
275
+ # Router
276
+ "ProblemFeatures",
277
+ "RuleBasedClassifier",
278
+ "StrategyClassifier",
279
+ "StrategyRouter",
280
+ "extract_features",
281
+ # Transition models
282
+ "DeterministicTransitionModel",
283
+ "DivergencePolicy",
284
+ "TransitionModel",
285
+ # Guards
286
+ "ActionGuard",
287
+ "AsyncActionGuard",
288
+ "FunctionalGuard",
289
+ "GuardResult",
290
+ "GuardSeverity",
291
+ "has_blocking_failure",
292
+ "run_guards_async",
293
+ "run_guards_sync",
294
+ # LLM cost / token accounting
295
+ "CostAccumulator",
296
+ "DEFAULT_COST_PER_1K_TOKENS",
297
+ # Action QoS / retry policy
298
+ "ActionQos",
299
+ "DEFAULT_RETRY_POLICY",
300
+ "FIRE_ONCE",
301
+ # Stuck-handler protocol
302
+ "FunctionalStuckHandler",
303
+ "MulticastStuckHandler",
304
+ "StuckHandler",
305
+ "StuckHandlerResult",
306
+ "StuckHandlingResultCode",
307
+ # Early-termination policies
308
+ "AllOfPolicy",
309
+ "EarlyTermination",
310
+ "FirstOfPolicy",
311
+ "MaxActionsPolicy",
312
+ "MaxCostPolicy",
313
+ "MaxLLMCallsPolicy",
314
+ "MaxTokensPolicy",
315
+ "MaxWallClockPolicy",
316
+ "OnStuckPolicy",
317
+ "TerminationPolicy",
318
+ # Scores
319
+ "Score",
320
+ "SimpleScore",
321
+ "HardSoftScore",
322
+ "BendableScore",
323
+ # CSP
324
+ "CSPMetadata",
325
+ "CSPStatus",
326
+ "ResourceUsage",
327
+ "ScheduleEntry",
328
+ "pareto_plans",
329
+ # Plan explanation
330
+ "InfeasibilityExplanation",
331
+ "NoPlanExplanation",
332
+ "ResourceShortfall",
333
+ "explain_infeasibility",
334
+ "explain_no_plan",
335
+ # Types
336
+ "CostFunction",
337
+ "Maximize",
338
+ "Minimize",
339
+ "ObjectiveDirection",
340
+ "ReplanStrategy",
341
+ # Visualization
342
+ "render_mermaid",
343
+ "render_mermaid_gantt",
344
+ "render_dot",
345
+ "render_ascii",
346
+ "render_ascii_gantt",
347
+ "visualize",
348
+ # Tracing
349
+ "PlanningTracer",
350
+ "NullTracer",
351
+ "LoggingTracer",
352
+ "MultiTracer",
353
+ "LangSmithTracer",
354
+ # Execution history
355
+ "ExecutionRecord",
356
+ "StoreExecutionHistory",
357
+ "compute_goal_hash",
358
+ # Sensors
359
+ "Sensor",
360
+ "AsyncSensor",
361
+ "FunctionalSensor",
362
+ "run_sensors_sync",
363
+ "run_sensors_async",
364
+ # Reflexion
365
+ "Reflection",
366
+ "ReflexionTracer",
367
+ # Serde
368
+ "LANGGOAP_ALLOWED_MSGPACK_TYPES",
369
+ "LangGOAPSerializer",
370
+ "install_langgoap_serde",
371
+ ]
@@ -0,0 +1,74 @@
1
+ """Internal base class for the :class:`~langgoap.score.Score` hierarchy.
2
+
3
+ Holds the comparison machinery (``__eq__`` from the dataclass plus a
4
+ single ``__lt__`` whose body is shared by every concrete subclass).
5
+ Subclasses opt into ordering by defining :meth:`Score._compare_payload`
6
+ \u2014 ``functools.total_ordering`` synthesises ``__le__`` / ``__gt__`` /
7
+ ``__ge__`` from ``__eq__`` + ``__lt__``.
8
+
9
+ Lives in a private module so the public ``score.py`` stays focused on
10
+ the concrete score types and their domain semantics.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import functools
16
+ from dataclasses import dataclass
17
+ from typing import Any
18
+
19
+
20
+ @functools.total_ordering
21
+ @dataclass(frozen=True, order=False, slots=True)
22
+ class Score:
23
+ """Abstract base for all score types.
24
+
25
+ Subclasses must implement :attr:`value`, :meth:`is_feasible`, and
26
+ :meth:`_compare_payload`. Cross-subclass comparison raises
27
+ ``TypeError`` so callers stay within a single score type per
28
+ planning run.
29
+ """
30
+
31
+ @property
32
+ def value(self) -> float:
33
+ """Return a scalar representation of this score.
34
+
35
+ Useful for logging and simple comparisons that do not require
36
+ lexicographic semantics. Different subclasses use different
37
+ definitions \u2014 read the subclass docstring.
38
+ """
39
+ raise NotImplementedError
40
+
41
+ def is_feasible(self) -> bool:
42
+ """Return True if this score represents a feasible plan."""
43
+ raise NotImplementedError
44
+
45
+ def _compare_payload(self) -> Any:
46
+ """Return the tuple/scalar used for ordering comparisons.
47
+
48
+ Concrete subclasses override this with their lexicographic
49
+ payload (e.g. ``(self.hard, self.soft)`` for
50
+ :class:`~langgoap.score.HardSoftScore`). The base class never
51
+ compares with itself so it raises rather than returning a
52
+ default.
53
+ """
54
+ raise NotImplementedError
55
+
56
+ def _compare_check(self, other: Score) -> None:
57
+ """Hook for subclass-specific pre-comparison validation.
58
+
59
+ Default is a no-op. :class:`~langgoap.score.BendableScore`
60
+ overrides this to assert matching hard/soft level shapes.
61
+ Called from :meth:`__lt__` after the type check passes; only
62
+ receives instances that already passed ``isinstance`` against
63
+ ``type(self)``.
64
+ """
65
+
66
+ def __lt__(self, other: Any) -> bool:
67
+ if not isinstance(other, type(self)):
68
+ raise TypeError(
69
+ f"Cannot compare {type(self).__name__} with "
70
+ f"{type(other).__name__}; scores must be of the same "
71
+ "concrete subclass."
72
+ )
73
+ self._compare_check(other)
74
+ return self._compare_payload() < other._compare_payload()
langgoap/_version.py ADDED
@@ -0,0 +1,3 @@
1
+ """Version information for LangGOAP."""
2
+
3
+ __version__ = "0.1.1"