pddl-pyvalidator 0.1.0__py3-none-any.whl

pddl_pyvalidator-0.1.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: pddl-pyvalidator
+Version: 0.1.0
+Summary: Pure Python PDDL plan validator
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: unified-planning>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: copilot
+Requires-Dist: pddl-plus-parser; extra == "copilot"
+Dynamic: license-file

pddl_pyvalidator-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pddl_pyvalidator-0.1.0.dist-info/licenses/LICENSE,sha256=eppAqBLLzP6SKT_c_8v_9yvey-bVjR0iH1d8ZThQVxY,1064
+pyval/__init__.py,sha256=6W25DWrNGhTWSQeVnbuk1Jp5RRfHFfbO4ipepOhaGwc,403
+pyval/cli.py,sha256=Qksw3sBZnrxadzNV57KxE0c2JyD55_e_cajZWVMGt2k,2073
+pyval/diagnostics.py,sha256=phlJ8hNg_7j3qdgmbiJgyZlOfYqBLB1ErYC9ZZc4IPg,8552
+pyval/models.py,sha256=aMmk0AzFAcU1OTovqL-CwJJ3TAhZpiGXl1A6bXeElU0,1893
+pyval/numeric_tracker.py,sha256=uRM6NH9wfNwe1vxqW4EtlLrcriWRVBvSkVj8SjqduzQ,2711
+pyval/plan_simulator.py,sha256=_cJy_dtEM264JaxbpHC0OnK0FL_Z_-4fWDtrWua_DVg,4246
+pyval/report_formatter.py,sha256=Kyjy6IIdsg4zkRM_DjmhDOfNxZ-KgVDHXLQKN2rFvdQ,8990
+pyval/syntax_checker.py,sha256=htxMjaTq9uZk89tPi2_GwS7D_2bguCe7wT7Hc84RxHA,2246
+pyval/validator.py,sha256=7ri7fzkaJKE57gC5d-ZyByWMadR-gekTMs88ePqoFKQ,8265
+pddl_pyvalidator-0.1.0.dist-info/METADATA,sha256=-E8GO_mo8Rt3md4-bs6EYcs1acU4iI5gJs7H6FjT_7I,371
+pddl_pyvalidator-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pddl_pyvalidator-0.1.0.dist-info/entry_points.txt,sha256=XG6ZbaynFjtJwl48-nN-6xpzq06jbRo-sAClHw8Mi3A,41
+pddl_pyvalidator-0.1.0.dist-info/top_level.txt,sha256=FsnZuyQIfXng5Gjl4gTGgNfEJTAXVAEwyDKpZIVPaA0,6
+pddl_pyvalidator-0.1.0.dist-info/RECORD,,

pddl_pyvalidator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pddl_pyvalidator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyval = pyval.cli:main

pddl_pyvalidator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SPL@BGU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pddl_pyvalidator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyval

pyval/__init__.py

@@ -0,0 +1,21 @@
+"""PyVAL — Pure Python PDDL plan validator."""
+
+from pyval.models import (
+    GoalResult,
+    NumericChange,
+    PreconditionFailure,
+    StateSnapshot,
+    StepResult,
+    ValidationResult,
+)
+from pyval.validator import PDDLValidator
+
+__all__ = [
+    "PDDLValidator",
+    "ValidationResult",
+    "StepResult",
+    "NumericChange",
+    "PreconditionFailure",
+    "GoalResult",
+    "StateSnapshot",
+]

pyval/cli.py

@@ -0,0 +1,78 @@
+"""CLI entry point — mirrors VAL's Validate interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from pyval.report_formatter import format_json, format_plain_text, format_trajectory
+from pyval.validator import PDDLValidator
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pyval",
+        description="PyVAL — Pure Python PDDL plan validator",
+    )
+    parser.add_argument(
+        "files",
+        nargs="+",
+        metavar="FILE",
+        help="PDDL files: domain [problem [plan]]",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Verbose output"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="Output as structured JSON"
+    )
+    parser.add_argument(
+        "--trajectory", action="store_true", help="Output numeric fluent trajectory"
+    )
+    parser.add_argument(
+        "--track",
+        action="append",
+        metavar="FLUENT",
+        help="Track specific numeric fluent (repeatable)",
+    )
+    parser.add_argument(
+        "--version", action="version", version="pyval 0.1.0"
+    )
+
+    args = parser.parse_args()
+    files = args.files
+
+    if len(files) > 3:
+        parser.error("Expected 1-3 files: domain [problem [plan]]")
+
+    validator = PDDLValidator()
+
+    if len(files) == 1:
+        result = validator.validate_syntax(domain_path=files[0])
+    elif len(files) == 2:
+        result = validator.validate_syntax(
+            domain_path=files[0], problem_path=files[1]
+        )
+    else:
+        result = validator.validate(
+            domain_path=files[0],
+            problem_path=files[1],
+            plan_path=files[2],
+            tracked_fluents=args.track,
+        )
+
+    # Output
+    import json
+
+    if args.json:
+        print(json.dumps(format_json(result), indent=2))
+    elif args.trajectory:
+        print(format_trajectory(result, tracked=args.track))
+    else:
+        print(format_plain_text(result, verbose=args.verbose))
+
+    sys.exit(0 if result.is_valid else 1)
+
+
+if __name__ == "__main__":
+    main()

pyval/diagnostics.py

@@ -0,0 +1,253 @@
+"""Diagnostic message generation — precondition decomposition and goal checking."""
+
+from __future__ import annotations
+
+from unified_planning.model import FNode, OperatorKind
+
+from pyval.models import GoalResult, PreconditionFailure
+
+
+def decompose_preconditions(
+    action, parameters: tuple, state, problem
+) -> list[PreconditionFailure]:
+    """Walk action preconditions, evaluate each against state, return failures.
+
+    Parameters are the grounded objects substituted into the action schema.
+    """
+    failures: list[PreconditionFailure] = []
+    param_map = dict(zip(action.parameters, parameters))
+
+    for prec in action.preconditions:
+        _evaluate_expr(prec, state, param_map, failures)
+
+    return failures
+
+
+def check_goals(problem, state) -> list[GoalResult]:
+    """Evaluate all goals against a state, return results for each."""
+    results: list[GoalResult] = []
+    for goal in problem.goals:
+        _evaluate_goal(goal, state, results)
+    return results
+
+
+def _evaluate_expr(
+    expr: FNode,
+    state,
+    param_map: dict,
+    failures: list[PreconditionFailure],
+) -> None:
+    """Recursively evaluate a precondition expression, collecting failures."""
+    node_type = expr.node_type
+
+    if node_type == OperatorKind.AND:
+        for arg in expr.args:
+            _evaluate_expr(arg, state, param_map, failures)
+        return
+
+    if node_type == OperatorKind.OR:
+        # Check if any disjunct is satisfied
+        sub_failures: list[PreconditionFailure] = []
+        for arg in expr.args:
+            _evaluate_expr(arg, state, param_map, sub_failures)
+        if len(sub_failures) == len(expr.args):
+            # None satisfied — report the OR as failed
+            failures.append(PreconditionFailure(
+                expression=_expr_to_pddl(expr, param_map),
+                type="boolean",
+                current_values={},
+                explanation="None of the disjuncts are satisfied",
+            ))
+        return
+
+    if node_type == OperatorKind.NOT:
+        inner = expr.args[0]
+        grounded = _substitute(inner, param_map)
+        try:
+            val = state.get_value(grounded)
+            if val.is_true():
+                failures.append(PreconditionFailure(
+                    expression=_expr_to_pddl(expr, param_map),
+                    type="boolean",
+                    current_values={_expr_to_pddl(inner, param_map): True},
+                    explanation=f"{_expr_to_pddl(inner, param_map)} is true but should be false",
+                ))
+        except Exception:
+            pass
+        return
+
+    # Comparison operators: LE, LT, EQUALS (UPF normalizes >= to <= with swapped args)
+    if node_type in (OperatorKind.LE, OperatorKind.LT, OperatorKind.EQUALS):
+        _evaluate_comparison(expr, state, param_map, failures)
+        return
+
+    # Fluent expression (boolean)
+    if expr.is_fluent_exp():
+        grounded = _substitute(expr, param_map)
+        try:
+            val = state.get_value(grounded)
+            if val.is_false():
+                failures.append(PreconditionFailure(
+                    expression=_expr_to_pddl(expr, param_map),
+                    type="boolean",
+                    current_values={_expr_to_pddl(expr, param_map): False},
+                    explanation=f"{_expr_to_pddl(expr, param_map)} is not true in the current state",
+                ))
+        except Exception:
+            failures.append(PreconditionFailure(
+                expression=_expr_to_pddl(expr, param_map),
+                type="boolean",
+                current_values={},
+                explanation=f"Could not evaluate {_expr_to_pddl(expr, param_map)}",
+            ))
+        return
+
+
+def _evaluate_comparison(
+    expr: FNode,
+    state,
+    param_map: dict,
+    failures: list[PreconditionFailure],
+) -> None:
+    """Evaluate a numeric comparison, report failure with deficit."""
+    left_expr, right_expr = expr.args[0], expr.args[1]
+    left_grounded = _substitute(left_expr, param_map)
+    right_grounded = _substitute(right_expr, param_map)
+
+    try:
+        left_val = state.get_value(left_grounded).constant_value()
+        right_val = state.get_value(right_grounded).constant_value()
+    except Exception:
+        failures.append(PreconditionFailure(
+            expression=_expr_to_pddl(expr, param_map),
+            type="numeric",
+            current_values={},
+            explanation=f"Could not evaluate numeric comparison",
+        ))
+        return
+
+    op = expr.node_type
+    satisfied = _check_comparison(op, left_val, right_val)
+
+    if not satisfied:
+        current_values = {}
+        if left_expr.is_fluent_exp():
+            current_values[_expr_to_pddl(left_expr, param_map)] = left_val
+        if right_expr.is_fluent_exp():
+            current_values[_expr_to_pddl(right_expr, param_map)] = right_val
+
+        deficit = _compute_deficit(op, left_val, right_val)
+        op_symbol = _op_symbol(op)
+
+        failures.append(PreconditionFailure(
+            expression=_expr_to_pddl(expr, param_map),
+            type="numeric",
+            current_values=current_values,
+            explanation=(
+                f"Required: {_expr_to_pddl(left_expr, param_map)} "
+                f"{op_symbol} {_expr_to_pddl(right_expr, param_map)}"
+            ),
+            deficit=deficit,
+        ))
+
+
+def _check_comparison(op: OperatorKind, left: float, right: float) -> bool:
+    eps = 1e-6
+    if op == OperatorKind.LE:
+        return left <= right + eps
+    if op == OperatorKind.LT:
+        return left < right
+    if op == OperatorKind.EQUALS:
+        return abs(left - right) < eps
+    return False
+
+
+def _compute_deficit(op: OperatorKind, left: float, right: float) -> float:
+    if op == OperatorKind.LE:
+        return left - right
+    if op == OperatorKind.LT:
+        return left - right
+    if op == OperatorKind.EQUALS:
+        return abs(left - right)
+    return 0.0
+
+
+def _op_symbol(op: OperatorKind) -> str:
+    return {
+        OperatorKind.LE: "<=",
+        OperatorKind.LT: "<",
+        OperatorKind.EQUALS: "=",
+    }.get(op, "?")
+
+
+def _evaluate_goal(expr: FNode, state, results: list[GoalResult]) -> None:
+    """Evaluate a single goal expression, decomposing ANDs."""
+    if expr.node_type == OperatorKind.AND:
+        for arg in expr.args:
+            _evaluate_goal(arg, state, results)
+        return
+
+    try:
+        val = state.get_value(expr)
+        if val.is_bool_constant():
+            satisfied = val.is_true()
+            results.append(GoalResult(
+                expression=str(expr),
+                satisfied=satisfied,
+                current_values={str(expr): satisfied},
+            ))
+        else:
+            # Numeric goal (comparison)
+            satisfied = val.is_true() if val.is_bool_constant() else False
+            results.append(GoalResult(
+                expression=str(expr),
+                satisfied=satisfied,
+                current_values={str(expr): val.constant_value() if not val.is_bool_constant() else satisfied},
+            ))
+    except Exception:
+        # For complex expressions (comparisons), try to evaluate directly
+        satisfied = _evaluate_goal_expr(expr, state)
+        results.append(GoalResult(
+            expression=str(expr),
+            satisfied=satisfied,
+            current_values={},
+        ))
+
+
+def _evaluate_goal_expr(expr: FNode, state) -> bool:
+    """Evaluate a goal expression that may be a comparison."""
+    if expr.node_type in (OperatorKind.LE, OperatorKind.LT, OperatorKind.EQUALS):
+        try:
+            left_val = state.get_value(expr.args[0]).constant_value()
+            right_val = state.get_value(expr.args[1]).constant_value()
+            return _check_comparison(expr.node_type, left_val, right_val)
+        except Exception:
+            return False
+
+    if expr.node_type == OperatorKind.NOT:
+        inner = expr.args[0]
+        try:
+            val = state.get_value(inner)
+            return val.is_false()
+        except Exception:
+            return False
+
+    try:
+        val = state.get_value(expr)
+        return val.is_true()
+    except Exception:
+        return False
+
+
+def _substitute(expr: FNode, param_map: dict) -> FNode:
+    """Substitute action parameters with grounded objects in an expression."""
+    if not param_map:
+        return expr
+    return expr.substitute(param_map)
+
+
+def _expr_to_pddl(expr: FNode, param_map: dict | None = None) -> str:
+    """Convert an FNode expression to a PDDL-like string."""
+    if param_map:
+        expr = _substitute(expr, param_map)
+    return str(expr)

pyval/models.py

@@ -0,0 +1,67 @@
+"""Data models for PyVAL validation results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass
+class NumericChange:
+    before: float
+    after: float
+
+
+@dataclass
+class PreconditionFailure:
+    expression: str
+    type: Literal["boolean", "numeric"]
+    current_values: dict[str, Any]
+    explanation: str
+    deficit: float | None = None
+
+
+@dataclass
+class GoalResult:
+    expression: str
+    satisfied: bool
+    current_values: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StateSnapshot:
+    step: int
+    action: str | None
+    boolean_fluents: dict[str, bool] = field(default_factory=dict)
+    numeric_fluents: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass
+class StepResult:
+    index: int
+    action: str
+    status: Literal["OK", "FAILED"]
+    boolean_changes: dict[str, bool] = field(default_factory=dict)
+    numeric_changes: dict[str, NumericChange] = field(default_factory=dict)
+    unsatisfied: list[PreconditionFailure] = field(default_factory=list)
+
+
+@dataclass
+class ValidationResult:
+    status: Literal["VALID", "INVALID", "SYNTAX_ERROR", "STRUCTURE_ERROR"]
+    is_valid: bool
+    phases: dict = field(default_factory=dict)
+    steps: list[StepResult] = field(default_factory=list)
+    trajectory: list[StateSnapshot] = field(default_factory=list)
+    numeric_trajectory: dict[str, list] = field(default_factory=dict)
+    failed_step: int | None = None
+    unsatisfied_goals: list[GoalResult] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def report(self, verbose: bool = False) -> str:
+        from pyval.report_formatter import format_plain_text
+        return format_plain_text(self, verbose=verbose)
+
+    def to_json(self) -> dict:
+        from pyval.report_formatter import format_json
+        return format_json(self)

pyval/numeric_tracker.py

@@ -0,0 +1,77 @@
+"""Numeric fluent value tracking across plan steps."""
+
+from __future__ import annotations
+
+from unified_planning.model import Problem
+
+from pyval.models import StateSnapshot
+
+
+class NumericTracker:
+    """Tracks numeric (and boolean) fluent values across plan execution steps."""
+
+    def __init__(
+        self, problem: Problem, tracked_fluents: list[str] | None = None
+    ):
+        self._problem = problem
+        self._snapshots: list[StateSnapshot] = []
+
+        # Identify all fluent expressions from initial values
+        self._boolean_exprs = []
+        self._numeric_exprs = []
+        for fluent_expr, val in problem.initial_values.items():
+            if val.is_bool_constant():
+                self._boolean_exprs.append(fluent_expr)
+            else:
+                self._numeric_exprs.append(fluent_expr)
+
+        # Filter numeric fluents if tracking specific ones
+        if tracked_fluents is not None:
+            tracked_set = set(tracked_fluents)
+            self._numeric_exprs = [
+                e for e in self._numeric_exprs
+                if _fluent_display_name(e) in tracked_set
+            ]
+
+    def record(self, step: int, action: str | None, state) -> StateSnapshot:
+        """Record a state snapshot at a given step."""
+        boolean_fluents = {}
+        for expr in self._boolean_exprs:
+            val = state.get_value(expr)
+            boolean_fluents[str(expr)] = val.is_true()
+
+        numeric_fluents = {}
+        for expr in self._numeric_exprs:
+            val = state.get_value(expr)
+            numeric_fluents[str(expr)] = float(val.constant_value())
+
+        snapshot = StateSnapshot(
+            step=step,
+            action=action,
+            boolean_fluents=boolean_fluents,
+            numeric_fluents=numeric_fluents,
+        )
+        self._snapshots.append(snapshot)
+        return snapshot
+
+    def get_numeric_trajectory(self) -> dict[str, list[float]]:
+        """Return {fluent_name: [val_step0, val_step1, ...]}."""
+        if not self._snapshots:
+            return {}
+
+        # Use the first snapshot's numeric keys as the canonical set
+        keys = list(self._snapshots[0].numeric_fluents.keys())
+        trajectory: dict[str, list[float]] = {k: [] for k in keys}
+        for snap in self._snapshots:
+            for k in keys:
+                trajectory[k].append(snap.numeric_fluents.get(k, 0.0))
+        return trajectory
+
+
+def _fluent_display_name(expr) -> str:
+    """Extract a display name like 'fuel truck1' from a fluent expression."""
+    if expr.is_fluent_exp():
+        name = expr.fluent().name
+        args = " ".join(str(a) for a in expr.args)
+        return f"{name} {args}".strip() if args else name
+    return str(expr)

pyval/plan_simulator.py

@@ -0,0 +1,121 @@
+"""Phase 3: Step-by-step plan execution with diagnostics."""
+
+from __future__ import annotations
+
+import warnings
+
+from unified_planning.engines import UPSequentialSimulator
+from unified_planning.model import Problem
+from unified_planning.plans import ActionInstance
+
+from pyval.diagnostics import check_goals, decompose_preconditions
+from pyval.models import GoalResult, NumericChange, StateSnapshot, StepResult
+from pyval.numeric_tracker import NumericTracker
+
+
+def simulate(
+    problem: Problem,
+    action_instances: list[ActionInstance],
+    original_names: dict[str, str],
+    tracked_fluents: list[str] | None = None,
+) -> tuple[list[StepResult], list[StateSnapshot], list[GoalResult], dict[str, list]]:
+    """Simulate plan execution step-by-step.
+
+    Returns (steps, trajectory, goal_results, numeric_trajectory).
+    """
+    # Suppress UPF warnings about unsupported problem kinds
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        sim = UPSequentialSimulator(problem=problem, error_on_failed_checks=False)
+
+    state = sim.get_initial_state()
+    tracker = NumericTracker(problem, tracked_fluents)
+    tracker.record(0, None, state)
+
+    steps: list[StepResult] = []
+
+    for idx, ai in enumerate(action_instances, start=1):
+        action_display = _format_action(ai, original_names)
+
+        if sim.is_applicable(state, ai):
+            new_state = sim.apply(state, ai)
+            if new_state is None:
+                # apply() returned None — treat as inapplicable (per upf-gotchas.md)
+                failures = decompose_preconditions(
+                    ai.action, ai.actual_parameters, state, problem
+                )
+                steps.append(StepResult(
+                    index=idx,
+                    action=action_display,
+                    status="FAILED",
+                    unsatisfied=failures,
+                ))
+                break
+
+            boolean_changes, numeric_changes = _compute_changes(
+                problem, state, new_state
+            )
+            steps.append(StepResult(
+                index=idx,
+                action=action_display,
+                status="OK",
+                boolean_changes=boolean_changes,
+                numeric_changes=numeric_changes,
+            ))
+            state = new_state
+            tracker.record(idx, action_display, state)
+        else:
+            failures = decompose_preconditions(
+                ai.action, ai.actual_parameters, state, problem
+            )
+            steps.append(StepResult(
+                index=idx,
+                action=action_display,
+                status="FAILED",
+                unsatisfied=failures,
+            ))
+            # Record snapshot at failure point too
+            tracker.record(idx, action_display, state)
+            break
+
+    goal_results = check_goals(problem, state)
+
+    return (
+        steps,
+        tracker._snapshots,
+        goal_results,
+        tracker.get_numeric_trajectory(),
+    )
+
+
+def _compute_changes(
+    problem: Problem, old_state, new_state
+) -> tuple[dict[str, bool], dict[str, NumericChange]]:
+    """Compute fluent changes between two states."""
+    boolean_changes: dict[str, bool] = {}
+    numeric_changes: dict[str, NumericChange] = {}
+
+    for fluent_expr in problem.initial_values:
+        old_val = old_state.get_value(fluent_expr)
+        new_val = new_state.get_value(fluent_expr)
+
+        if str(old_val) != str(new_val):
+            name = str(fluent_expr)
+            if old_val.is_bool_constant():
+                boolean_changes[name] = new_val.is_true()
+            else:
+                numeric_changes[name] = NumericChange(
+                    before=float(old_val.constant_value()),
+                    after=float(new_val.constant_value()),
+                )
+
+    return boolean_changes, numeric_changes
+
+
+def _format_action(ai: ActionInstance, original_names: dict[str, str]) -> str:
+    """Format an ActionInstance as a PDDL plan line using original names."""
+    action_name = original_names.get(ai.action.name, ai.action.name)
+    params = " ".join(
+        original_names.get(str(p), str(p)) for p in ai.actual_parameters
+    )
+    return f"({action_name} {params})" if params else f"({action_name})"

pyval/report_formatter.py

@@ -0,0 +1,249 @@
+"""Output formatting: plain text, structured JSON, and trajectory table."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyval.models import ValidationResult
+
+
+def format_plain_text(result: ValidationResult, verbose: bool = False) -> str:
+    """Format validation result as human-readable plain text."""
+    lines: list[str] = []
+
+    # Phase 1: Syntax
+    if "syntax" in result.phases:
+        phase = result.phases["syntax"]
+        if phase["errors"] or phase["warnings"] or verbose:
+            lines.append("=== Syntax & Semantic Validation ===")
+            for err in phase["errors"]:
+                lines.append(f"[ERROR] {err}")
+            for warn in phase["warnings"]:
+                lines.append(f"[WARNING] {warn}")
+            if not phase["errors"] and not phase["warnings"]:
+                lines.append("All checks passed.")
+            lines.append("")
+
+    if result.status == "SYNTAX_ERROR":
+        lines.append(f"Validation halted: {result.status}")
+        return "\n".join(lines)
+
+    # Phase 2: Structure
+    if "structure" in result.phases:
+        phase = result.phases["structure"]
+        if phase["errors"] or phase["warnings"] or verbose:
+            lines.append("=== Plan Structure Validation ===")
+            for err in phase["errors"]:
+                lines.append(f"[ERROR] {err}")
+            for warn in phase["warnings"]:
+                lines.append(f"[WARNING] {warn}")
+            if not phase["errors"] and not phase["warnings"]:
+                lines.append("All checks passed.")
+            lines.append("")
+
+    if result.status == "STRUCTURE_ERROR":
+        lines.append(f"Validation halted: {result.status}")
+        return "\n".join(lines)
+
+    # Phase 3: Execution
+    if result.steps:
+        lines.append("=== Plan Execution ===")
+        for step in result.steps:
+            if step.status == "OK":
+                lines.append(f"Step {step.index}: {step.action} \u2713")
+                changes = _format_changes(step)
+                if changes:
+                    lines.append(f"  Changed: {changes}")
+            else:
+                lines.append(f"Step {step.index}: {step.action} \u2717 PRECONDITION FAILURE")
+                for failure in step.unsatisfied:
+                    lines.append(f"  Unsatisfied: {failure.expression}")
+                    for k, v in failure.current_values.items():
+                        lines.append(f"    Current value: {k} = {v}")
+                    if failure.explanation:
+                        lines.append(f"    {failure.explanation}")
+                    if failure.deficit is not None and failure.deficit > 0:
+                        lines.append(f"    Deficit: {failure.deficit} units")
+        lines.append("")
+
+    # Goal check
+    lines.append("=== Goal Check ===")
+    if result.is_valid:
+        lines.append("All goals satisfied. Plan is VALID.")
+    else:
+        if result.failed_step is not None:
+            total = result.phases.get("execution", {}).get("total_steps", "?")
+            lines.append(
+                f"Plan is INVALID. Failed at step {result.failed_step} of {total}."
+            )
+            remaining = int(total) - result.failed_step if isinstance(total, int) else "?"
+            lines.append(f"Remaining actions not executed: {remaining}")
+        elif result.unsatisfied_goals:
+            lines.append("Plan executed but goals are NOT satisfied.")
+            for goal in result.unsatisfied_goals:
+                lines.append(f"  Unmet goal: {goal.expression}")
+                for k, v in goal.current_values.items():
+                    lines.append(f"    Current value: {v}")
+        else:
+            lines.append(f"Plan is {result.status}.")
+
+    # Summary
+    if result.steps:
+        lines.append(f"Plan length: {len(result.steps)} actions")
+
+    # Numeric summary
+    if result.numeric_trajectory:
+        numeric_finals = {}
+        for fluent, values in result.numeric_trajectory.items():
+            if values:
+                numeric_finals[fluent] = values[-1]
+        if numeric_finals:
+            parts = [f"{k} = {v}" for k, v in numeric_finals.items()]
+            lines.append(f"Final state numeric values: {', '.join(parts)}")
+
+    return "\n".join(lines)
+
+
+def format_json(result: ValidationResult) -> dict:
+    """Format validation result as structured JSON dict."""
+    output: dict = {
+        "status": result.status,
+        "phases": {},
+    }
+
+    # Syntax phase
+    if "syntax" in result.phases:
+        output["phases"]["syntax"] = result.phases["syntax"]
+
+    # Structure phase
+    if "structure" in result.phases:
+        output["phases"]["structure"] = result.phases["structure"]
+
+    # Execution phase
+    if "execution" in result.phases:
+        exec_phase: dict = {
+            "status": result.phases["execution"]["status"],
+            "failed_step": result.failed_step,
+            "total_steps": result.phases["execution"].get("total_steps"),
+            "steps": [],
+        }
+
+        for step in result.steps:
+            step_dict: dict = {
+                "index": step.index,
+                "action": step.action,
+                "status": step.status,
+            }
+
+            if step.status == "OK":
+                step_dict["changes"] = {
+                    "boolean": step.boolean_changes,
+                    "numeric": {
+                        k: {"before": v.before, "after": v.after}
+                        for k, v in step.numeric_changes.items()
+                    },
+                }
+            else:
+                step_dict["unsatisfied_preconditions"] = [
+                    {
+                        "expression": f.expression,
+                        "type": f.type,
+                        "current_values": f.current_values,
+                        "explanation": f.explanation,
+                        **({"deficit": f.deficit} if f.deficit is not None else {}),
+                    }
+                    for f in step.unsatisfied
+                ]
+
+            exec_phase["steps"].append(step_dict)
+        output["phases"]["execution"] = exec_phase
+
+    # Goals
+    if result.unsatisfied_goals is not None:
+        goals = [
+            {
+                "expression": g.expression,
+                "satisfied": g.satisfied,
+                "current_values": g.current_values,
+            }
+            for g in result.unsatisfied_goals
+        ]
+        output["phases"]["goals"] = goals if goals else None
+    else:
+        output["phases"]["goals"] = None
+
+    return output
+
+
+def _format_changes(step) -> str:
+    """Format boolean and numeric changes for a step as a compact string."""
+    parts: list[str] = []
+    for name, val in step.boolean_changes.items():
+        parts.append(f"{name} = {str(val).lower()}")
+    for name, change in step.numeric_changes.items():
+        parts.append(f"{name} = {change.after} (was {change.before})")
+    return ", ".join(parts)
+
+
+def format_trajectory(
+    result: ValidationResult, tracked: list[str] | None = None
+) -> str:
+    """Format numeric fluent trajectory as a table."""
+    traj = result.numeric_trajectory
+    if not traj:
+        return "No numeric fluents to display."
+
+    # Filter if specific fluents requested
+    if tracked:
+        tracked_set = set(tracked)
+        traj = {k: v for k, v in traj.items() if k in tracked_set}
+        if not traj:
+            return "No matching numeric fluents found."
+
+    fluent_names = list(traj.keys())
+    num_steps = max(len(v) for v in traj.values()) if traj else 0
+
+    # Build action labels from trajectory snapshots
+    action_labels = []
+    for snap in result.trajectory:
+        action_labels.append(snap.action or "[initial state]")
+
+    # Column widths
+    step_width = max(4, len(str(num_steps)))
+    action_width = max(6, max((len(a) for a in action_labels), default=6))
+    col_widths = {
+        name: max(len(name), max((len(str(v)) for v in vals), default=1))
+        for name, vals in traj.items()
+    }
+
+    lines: list[str] = []
+    lines.append("=== Numeric Fluent Trajectory ===")
+
+    # Header
+    header = (
+        f"{'Step':>{step_width}} | {'Action':<{action_width}}"
+    )
+    for name in fluent_names:
+        header += f" | {name:>{col_widths[name]}}"
+    lines.append(header)
+
+    # Separator
+    sep = "-" * (step_width + 1) + "|" + "-" * (action_width + 2)
+    for name in fluent_names:
+        sep += "|" + "-" * (col_widths[name] + 1) + ":"
+    lines.append(sep)
+
+    # Data rows
+    for i in range(num_steps):
+        action = action_labels[i] if i < len(action_labels) else ""
+        row = f"{i:>{step_width}} | {action:<{action_width}}"
+        for name in fluent_names:
+            vals = traj[name]
+            val = vals[i] if i < len(vals) else ""
+            val_str = str(int(val)) if isinstance(val, float) and val == int(val) else str(val)
+            row += f" | {val_str:>{col_widths[name]}}"
+        lines.append(row)
+
+    return "\n".join(lines)

pyval/syntax_checker.py

@@ -0,0 +1,63 @@
+"""Phase 1: PDDL syntax and semantic validation via UPF's PDDLReader."""
+
+from __future__ import annotations
+
+from unified_planning.io import PDDLReader
+from unified_planning.model import Problem
+
+
+def check_syntax(
+    domain_path: str, problem_path: str | None = None
+) -> tuple[dict, Problem | None]:
+    """Parse and validate PDDL domain (and optionally problem).
+
+    Returns a tuple of (phase_result, parsed_problem).
+    phase_result has keys: status ("PASS"|"FAIL"), errors (list[str]), warnings (list[str]).
+    parsed_problem is None if parsing failed.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    reader = PDDLReader()
+    try:
+        problem = reader.parse_problem(domain_path, problem_path)
+    except Exception as exc:
+        errors.append(_format_parse_error(exc, domain_path, problem_path))
+        return {"status": "FAIL", "errors": errors, "warnings": warnings}, None
+
+    # Post-parse checks: warn on uninitialized numeric functions
+    warnings.extend(_check_numeric_initialization(problem))
+
+    return {"status": "PASS", "errors": errors, "warnings": warnings}, problem
+
+
+def _format_parse_error(
+    exc: Exception, domain_path: str, problem_path: str | None
+) -> str:
+    """Format a UPF parse exception into a readable error message."""
+    msg = str(exc).strip()
+    if problem_path:
+        return f"Failed to parse domain '{domain_path}' with problem '{problem_path}': {msg}"
+    return f"Failed to parse domain '{domain_path}': {msg}"
+
+
+def _check_numeric_initialization(problem: Problem) -> list[str]:
+    """Warn about numeric fluents with no explicit initial value (default 0)."""
+    warnings = []
+    declared_numeric_fluents = set()
+    initialized_fluents = set()
+
+    for fluent in problem.fluents:
+        if fluent.type.is_int_type() or fluent.type.is_real_type():
+            declared_numeric_fluents.add(fluent.name)
+
+    for fluent_expr in problem.initial_values:
+        if fluent_expr.is_fluent_exp():
+            initialized_fluents.add(fluent_expr.fluent().name)
+
+    for name in declared_numeric_fluents - initialized_fluents:
+        warnings.append(
+            f"Numeric function '{name}' has no initial value assigned — defaults to 0"
+        )
+
+    return warnings

pyval/validator.py

@@ -0,0 +1,250 @@
+"""Main validation orchestrator — coordinates the 3-phase pipeline."""
+
+from __future__ import annotations
+
+from unified_planning.model import Problem
+from unified_planning.plans import ActionInstance
+
+from pyval.models import ValidationResult
+from pyval.syntax_checker import check_syntax
+
+
+class PDDLValidator:
+    """Pure-Python PDDL plan validator."""
+
+    def validate_syntax(
+        self, domain_path: str, problem_path: str | None = None
+    ) -> ValidationResult:
+        """Run Phase 1 only: syntax and semantic validation."""
+        phase_result, problem = check_syntax(domain_path, problem_path)
+
+        if phase_result["status"] == "FAIL":
+            return ValidationResult(
+                status="SYNTAX_ERROR",
+                is_valid=False,
+                phases={"syntax": phase_result},
+                warnings=phase_result["warnings"],
+            )
+
+        return ValidationResult(
+            status="VALID",
+            is_valid=True,
+            phases={"syntax": phase_result},
+            warnings=phase_result["warnings"],
+        )
+
+    def validate(
+        self,
+        domain_path: str,
+        problem_path: str,
+        plan_path: str,
+        tracked_fluents: list[str] | None = None,
+    ) -> ValidationResult:
+        """Run full 3-phase validation pipeline."""
+        # Phase 1: Syntax & Semantic
+        phase1_result, problem = check_syntax(domain_path, problem_path)
+        phases: dict = {"syntax": phase1_result}
+
+        if phase1_result["status"] == "FAIL":
+            return ValidationResult(
+                status="SYNTAX_ERROR",
+                is_valid=False,
+                phases=phases,
+                warnings=phase1_result["warnings"],
+            )
+
+        assert problem is not None
+
+        # Phase 2: Plan Structure
+        phase2_result, action_instances, original_names = _validate_plan_structure(
+            problem, plan_path
+        )
+        phases["structure"] = phase2_result
+
+        if phase2_result["status"] == "FAIL":
+            return ValidationResult(
+                status="STRUCTURE_ERROR",
+                is_valid=False,
+                phases=phases,
+                warnings=phase1_result["warnings"] + phase2_result["warnings"],
+            )
+
+        # Phase 3: Plan Execution
+        from pyval.plan_simulator import simulate
+
+        steps, trajectory, goal_results, numeric_traj = simulate(
+            problem, action_instances, original_names, tracked_fluents
+        )
+
+        failed_step = next(
+            (s.index for s in steps if s.status == "FAILED"), None
+        )
+        unsatisfied_goals = [g for g in goal_results if not g.satisfied]
+        is_valid = failed_step is None and len(unsatisfied_goals) == 0
+
+        exec_status = "PASS" if is_valid else "FAIL"
+        phases["execution"] = {
+            "status": exec_status,
+            "failed_step": failed_step,
+            "total_steps": len(action_instances),
+        }
+
+        all_warnings = phase1_result["warnings"] + phase2_result["warnings"]
+
+        return ValidationResult(
+            status="VALID" if is_valid else "INVALID",
+            is_valid=is_valid,
+            phases=phases,
+            steps=steps,
+            trajectory=trajectory,
+            numeric_trajectory=numeric_traj,
+            failed_step=failed_step,
+            unsatisfied_goals=unsatisfied_goals,
+            warnings=all_warnings,
+        )
+
+
+def _validate_plan_structure(
+    problem: Problem, plan_path: str
+) -> tuple[dict, list[ActionInstance], dict[str, str]]:
+    """Phase 2: parse plan file and validate action/object/type references.
+
+    Returns (phase_result, action_instances, original_names).
+    original_names maps normalized (underscore) names to original PDDL names.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+    action_instances: list[ActionInstance] = []
+    original_names: dict[str, str] = {}
+
+    lines = _read_plan_lines(plan_path)
+
+    if not lines:
+        # Empty plan — valid only if goals already satisfied
+        # (goal checking is Phase 3's job, so we pass it through)
+        return (
+            {"status": "PASS", "errors": errors, "warnings": warnings},
+            action_instances,
+            original_names,
+        )
+
+    for step_idx, line in enumerate(lines, start=1):
+        tokens = _parse_plan_line(line)
+        if tokens is None:
+            continue
+
+        action_name_raw = tokens[0]
+        param_names_raw = tokens[1:]
+
+        # Look up action schema — try original name, then normalized
+        action_schema = _lookup_action(problem, action_name_raw)
+        if action_schema is None:
+            errors.append(
+                f"Step {step_idx}: Action '{action_name_raw}' is not declared in domain"
+            )
+            continue
+        original_names[action_schema.name] = action_name_raw
+
+        # Check parameter count
+        expected_count = len(action_schema.parameters)
+        if len(param_names_raw) != expected_count:
+            errors.append(
+                f"Step {step_idx}: Action '{action_name_raw}' expects "
+                f"{expected_count} parameters, got {len(param_names_raw)}"
+            )
+            continue
+
+        # Look up each parameter object and check types
+        objects = []
+        step_ok = True
+        for i, param_name_raw in enumerate(param_names_raw):
+            obj = _lookup_object(problem, param_name_raw)
+            if obj is None:
+                errors.append(
+                    f"Step {step_idx}: Action '{action_name_raw}' — "
+                    f"object '{param_name_raw}' is not declared in problem"
+                )
+                step_ok = False
+                continue
+            original_names[obj.name] = param_name_raw
+
+            expected_type = action_schema.parameters[i].type
+            if not obj.type.is_compatible(expected_type):
+                errors.append(
+                    f"Step {step_idx}: Action '{action_name_raw}' — "
+                    f"parameter {i + 1} expects type '{expected_type}', "
+                    f"got '{obj.type}' (object '{param_name_raw}')"
+                )
+                step_ok = False
+                continue
+
+            objects.append(obj)
+
+        if step_ok:
+            action_instances.append(ActionInstance(action_schema, tuple(objects)))
+
+    status = "FAIL" if errors else "PASS"
+    return (
+        {"status": status, "errors": errors, "warnings": warnings},
+        action_instances,
+        original_names,
+    )
+
+
+def _read_plan_lines(plan_path: str) -> list[str]:
+    """Read plan file, strip comments and blank lines."""
+    with open(plan_path) as f:
+        lines = []
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith(";"):
+                continue
+            # Strip inline cost comments
+            if ";" in line:
+                line = line[: line.index(";")].strip()
+            if line:
+                lines.append(line)
+        return lines
+
+
+def _parse_plan_line(line: str) -> list[str] | None:
+    """Parse a plan line into [action_name, param1, param2, ...].
+
+    Handles both `(action p1 p2)` and `action p1 p2` formats.
+    """
+    line = line.strip()
+    if line.startswith("(") and line.endswith(")"):
+        line = line[1:-1]
+    tokens = line.split()
+    if not tokens:
+        return None
+    return tokens
+
+
+def _lookup_action(problem: Problem, raw_name: str):
+    """Look up an action schema, trying original name then hyphen-normalized."""
+    for candidate in _name_candidates(raw_name):
+        try:
+            return problem.action(candidate)
+        except Exception:
+            continue
+    return None
+
+
+def _lookup_object(problem: Problem, raw_name: str):
+    """Look up a problem object, trying original name then hyphen-normalized."""
+    for candidate in _name_candidates(raw_name):
+        try:
+            return problem.object(candidate)
+        except Exception:
+            continue
+    return None
+
+
+def _name_candidates(name: str) -> list[str]:
+    """Return lookup candidates: original, then normalized (if different)."""
+    candidates = [name]
+    normalized = name.replace("-", "_")
+    if normalized != name:
+        candidates.append(normalized)
+    return candidates