How arbom/sharppddl works
1. SharpPDDL is a reusable C# class library, not a single application. The repository’s main deliverable is the SharpPDDL library, with several console-style example projects under Examples/ that demonstrate how to model and solve planning problems.
2. The architectural core is a PDDL/GOAP-style planner built directly in C# using expression trees and lambdas. Instead of parsing .pddl files, users define domains, actions, preconditions, effects, goals, and costs programmatically against their own domain classes.
3. The model layer is split across types that represent domain objects and their metadata: ObjectPDDL, TypesPDDL, SingleType, Value, Parametr, ElementInObjectPDDL, and related helpers. The README’s constraint that state values must be value types is important because the planner relies on equality/comparison over generated state representations.
4. Actions are the main public abstraction. The ActionPDDL and ActionPDDL/* files cover action definitions, parameter binding, action “sentences” for human-readable output, and action checking/visualization support. An action can carry both logical conditions and executable side effects.
5. Preconditions, effects, goals, and costs each have their own subsystem. The repository separates these into PreconditionPDDL, EffectPDDL, GoalsPDDP, and ActionCost, with lambda-based variants for user-supplied expressions. This keeps the planner generic while letting the user describe domain-specific logic in code.
6. Planning/search appears to be graph-based rather than a simple tree expansion. The CrisscrossesGenerate and Collections/Crisscross* files suggest state-space expansion, duplicate-state reduction, and goal checking over a cross-linked exploration structure. Supporting node types like TreeNode, ChainStruct, and comparers handle traversal, equality, and state deduplication.
7. The planner pipeline is centered around domain realization and search orchestration. DomainPDDLtaskRealization, DomainPlanner, DomeinPDDL, Executor, and PossibleState are the likely top-level coordination points: define domain, expand reachable states, reduce them, test against the goal, then emit an ordered plan.
8. Execution is a separate concern from planning. The Execution/ folder contains expression execution and action execution helpers, plus exception types for precondition failures. This suggests the library can both compute a plan and optionally replay it against live objects through user-provided callbacks.
9. Visualization and export are first-class utilities. DGML.cs, TypesPDDLVisualization.cs, ActionPDDL/ActionsVisualization.cs, and CrisscrossesGenerate/CrisscrossesVisualization.cs indicate support for inspecting domains, actions, and search graphs, likely for debugging or documentation.
10. The Thumbnails/ folder indicates an internal intermediate representation of object instances and types. The README’s Hanoi diagram shows these “thumbnail” objects being used to derive state-space nodes from user classes, which is a key boundary between the user’s domain model and the planner’s internal model.
11. The examples are separate consumer applications, each modeling a classic planning problem: 15-puzzle, Hanoi Tower, peg solitaire, river crossing, travelling salesman, and water pouring. They illustrate the same flow: define domain classes, declare actions with preconditions/effects/costs, invoke the planner, and print or execute the resulting plan.
12. One example, travelling salesman, also shows an external data dependency through CitiesAPI for distance lookup. That dependency exists only in the example layer; the core library itself is intended to be self-contained and uses only the C# standard library.
13. Build and delivery are straightforward: the solution contains a single library project plus example projects, with GitHub Actions workflows for .NET build validation and line-of-code reporting. The repo is therefore organized around a core planning engine with thin sample clients, not around a server, UI, or distributed system.
Main entry points: ActionPDDL.cs Actions · CrisscrossGenerator.cs Search graph · DomainPlanner.cs Planner · DGML.cs Visualization
Components 17
SharpPDDL core
Reusable planning library and its internal subsystems.
- Domain model · User domain objects, types, values, parameters, and member metadata.
SharpPDDL/ObjectPDDL.cs - Thumbnails · Intermediate object/type representations used to derive planner state from user classes.
SharpPDDL/Thumbnails/ThumbnailObject.cs - Actions · Action definitions, bindings, human-readable sentences, and action checking.
SharpPDDL/ActionPDDL/ActionPDDL.cs - Preconditions · Logical preconditions and lambda-based condition variants.
SharpPDDL/PreconditionPDDL/PreconditionPDDL.cs - Effects · Action effects, including lambda and pointer-based variants.
SharpPDDL/EffectPDDL/EffectPDDL.cs - Goals · Goal definitions and goal checking helpers.
SharpPDDL/GoalsPDDP/GoalPDDL.cs - Costs · Action cost definitions and lambda-based cost evaluation.
SharpPDDL/ActionCost/ActionCost.cs - Planner · Domain realization and top-level planning coordination.
SharpPDDL/DomainPlanner.cs - Search graph · Crisscross generation, reduction, goal checks, and duplicate-state management.
SharpPDDL/CrisscrossesGenerate/CrisscrossGenerator.cs - State collections · Tree and crisscross structures, comparers, and traversal helpers used by search.
SharpPDDL/Collections/Crisscross.cs - Executor · Expression execution and action replay helpers for applying plans.
SharpPDDL/Executor.cs - Execution helpers · Precondition failures, expression execution, and whole-action execution wrappers.
SharpPDDL/Execution/ExpressionExecution.cs - Visualization · DGML and visualization helpers for domains, actions, and search graphs.
SharpPDDL/DGML.cs - Possible state · Computed planner state representation used during expansion and comparison.
SharpPDDL/PossibleState.cs
Examples
Console-style consumer projects demonstrating the planner.
- Puzzle examples · Console examples for classic planning problems and external data integration.
Examples/README.md - Cities API · External distance lookup used by the travelling salesman example.
Examples/Travelling Salesman Problem/CitiesAPI.cs
Automation
Build and repository maintenance workflows.
- Build CI · Repository workflows for .NET build validation and line-of-code reporting.
.github/workflows/dotnet.yml
Connections 19
- Thumbnails → Domain model: derives · Turns user domain classes into planner-facing object/type metadata.
- Domain model → Actions: binds · Actions are declared against the user domain model and its parameters.
- Actions → Preconditions: uses · Each action may carry logical conditions that must hold before execution.
- Actions → Effects: applies · Actions define how state changes after preconditions succeed.
- Actions → Costs: prices · Actions can contribute search cost or heuristic weight.
- Goals → Planner: targets · The planner searches for states that satisfy goal definitions.
- Planner → Search graph: expands · Top-level orchestration delegates reachable-state exploration to search generation.
- Search graph → State collections: stores · Search uses graph/tree structures and comparers to manage explored states.
- Search graph → Possible state: materializes · Expansion produces candidate planner states for comparison and goal tests.
- Search graph → Goals: checks · Generated states are tested against the goal subsystem.
- Planner → Executor: returns plan to · A found plan can be replayed against live objects through execution.
- Executor → Execution helpers: invokes · Execution helpers run expressions and surface precondition failures.
- Actions → Execution helpers: supports · Action definitions include executable side-effect pathways.
- Visualization → Actions: renders · Action structures can be exported for inspection.
- Visualization → Search graph: renders · Search graphs and crisscross structures can be visualized.
- Visualization → Domain model: renders · Domain/type metadata can be exported as diagrams.
- Puzzle examples → Planner: consumes · Examples define domains and call into the core planner library.
- Puzzle examples → Cities API: uses · The travelling salesman sample depends on external distance data.
- Build CI → Puzzle examples: validates · Workflows build the library and example projects.