lmdl 0.1.0__py3-none-any.whl

lmdl/__init__.py

@@ -0,0 +1,80 @@
+"""
+LMDL: Language-Model Domain Language.
+
+The base planning schema: sorts, predicates, actions, problem instances,
+PDDL compilation, and template-driven NL rendering. The pydantic models
+ignore unknown JSON fields and subclass cleanly, so downstream projects can
+extend the schema without changes here.
+"""
+
+from lmdl.schema import (
+    ActionParam,
+    ActionSpec,
+    AtomTemplate,
+    DomainSchema,
+    GroundAtom,
+    PredicateArg,
+    PredicateSpec,
+    PrimitiveRegistry,
+    ProblemSpec,
+    domain_profile_json_schema,
+    dumps_domain_schema,
+    load_domain_schema,
+    load_problem_spec,
+    save_domain_schema,
+    save_problem_spec,
+)
+from lmdl.nl import domain_nl, format_atom, problem_nl, render_atom
+from lmdl import prompts
+from lmdl.pddl import (
+    Atom,
+    action_from_pddl,
+    build_domain,
+    build_problem,
+    build_problem_from_spec,
+    domain_from_pddl,
+    domain_types_from_pddl,
+    extract_action_pddl,
+    load_problem,
+    minimal_problem,
+    predicates_from_pddl,
+    problem_from_pddl,
+)
+
+__all__ = [
+    # base planning schema
+    "ActionParam",
+    "ActionSpec",
+    "AtomTemplate",
+    "DomainSchema",
+    "GroundAtom",
+    "PredicateArg",
+    "PredicateSpec",
+    "PrimitiveRegistry",
+    "ProblemSpec",
+    "domain_profile_json_schema",
+    "dumps_domain_schema",
+    "load_domain_schema",
+    "load_problem_spec",
+    "save_domain_schema",
+    "save_problem_spec",
+    # natural-language rendering and prompt snippets
+    "prompts",
+    "domain_nl",
+    "format_atom",
+    "problem_nl",
+    "render_atom",
+    # PDDL compilation + ingestion
+    "Atom",
+    "action_from_pddl",
+    "build_domain",
+    "build_problem",
+    "build_problem_from_spec",
+    "domain_from_pddl",
+    "domain_types_from_pddl",
+    "extract_action_pddl",
+    "load_problem",
+    "minimal_problem",
+    "predicates_from_pddl",
+    "problem_from_pddl",
+]

lmdl/convert.py

@@ -0,0 +1,134 @@
+"""
+``lmdl-convert``: convert between PDDL files and canonical LMDL JSON.
+
+The input kind is detected from its content and converted to the other
+representation:
+
+  PDDL domain    (define (domain ...))              -> LMDL domain JSON
+  PDDL problem   (define (problem ...))             -> LMDL problem JSON
+  LMDL domain    JSON with sorts/predicates/actions -> PDDL domain
+  LMDL problem   JSON with objects/init/goal        -> PDDL problem
+
+PDDL -> LMDL is lossy upward: PDDL carries no NL, so the ``description`` and
+``template`` fields come out empty for authors to fill in. LMDL -> PDDL is
+the standard compilation path (``build_domain`` / ``build_problem_from_spec``).
+
+Usage:
+  lmdl-convert domain.pddl                          # LMDL JSON to stdout
+  lmdl-convert domain.lmdl.json --name blocksworld  # PDDL to stdout
+  lmdl-convert instance-0.pddl -o instance-0.problem.lmdl.json
+  python -m lmdl.convert ...                            # equivalent invocation
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from lmdl.pddl import (
+    build_domain,
+    build_problem_from_spec,
+    domain_from_pddl,
+    problem_from_pddl,
+)
+from lmdl.schema import ProblemSpec, dumps_domain_schema, load_domain_schema
+
+# (format, kind) pairs returned by _detect
+_PDDL_DOMAIN_RE = r"\(\s*define\s*\(\s*domain\b"
+_PDDL_PROBLEM_RE = r"\(\s*define\s*\(\s*problem\b"
+
+
+def _detect(text: str) -> Tuple[str, str]:
+    """Detect an input file's representation and kind from its content.
+
+    :param text: The file's full text.
+    :returns: ``(format, kind)`` with format ``"pddl"`` | ``"lmdl"`` and kind
+        ``"domain"`` | ``"problem"``.
+    :raises ValueError: If the content is neither recognizable PDDL nor
+        recognizable LMDL JSON.
+    """
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        if re.search(_PDDL_DOMAIN_RE, text, re.IGNORECASE):
+            return "pddl", "domain"
+        if re.search(_PDDL_PROBLEM_RE, text, re.IGNORECASE):
+            return "pddl", "problem"
+        raise ValueError(
+            "input is neither LMDL JSON nor a PDDL (define (domain|problem ...))"
+        )
+
+    if not isinstance(payload, dict):
+        raise ValueError("LMDL JSON input must be an object")
+    if {"init", "goal", "objects"} & set(payload):
+        return "lmdl", "problem"
+    if {"predicates", "actions", "sorts"} & set(payload):
+        return "lmdl", "domain"
+    raise ValueError(
+        "JSON input has neither problem keys (objects/init/goal) nor "
+        "domain keys (sorts/predicates/actions)"
+    )
+
+
+def convert(path: Path, name: str = "domain") -> str:
+    """Convert one file to the opposite representation.
+
+    :param path: The PDDL or LMDL JSON file to convert.
+    :param name: The domain name to write into compiled PDDL headers
+        (LMDL carries no domain name; ignored for other conversions).
+    :returns: The converted text.
+    :raises ValueError: If the input kind cannot be detected or parsed.
+    """
+    text = path.read_text()
+    fmt, kind = _detect(text)
+
+    if fmt == "pddl" and kind == "domain":
+        return dumps_domain_schema(domain_from_pddl(text))
+    if fmt == "pddl" and kind == "problem":
+        return problem_from_pddl(text).model_dump_json(indent=2)
+    if kind == "domain":
+        return build_domain(load_domain_schema(path), name)
+    return build_problem_from_spec(ProblemSpec.model_validate_json(text))
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Parse command-line arguments and run one conversion.
+
+    :param argv: Arguments to parse instead of ``sys.argv`` (for tests).
+    """
+    parser = argparse.ArgumentParser(
+        prog="lmdl-convert",
+        description="Convert a PDDL domain/problem file to LMDL JSON, or back.",
+    )
+    parser.add_argument("input", type=Path, help="PDDL or LMDL JSON file")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="Write here instead of stdout",
+    )
+    parser.add_argument(
+        "--name",
+        default="domain",
+        help="Domain name for compiled PDDL output (default: domain)",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        result = convert(args.input, name=args.name)
+    except (ValueError, FileNotFoundError) as e:
+        sys.exit(f"lmdl-convert: {e}")
+
+    if args.output is not None:
+        args.output.write_text(result + "\n")
+    else:
+        print(result)
+
+
+if __name__ == "__main__":
+    main()

lmdl/nl.py

@@ -0,0 +1,118 @@
+"""
+Natural-language rendering of domains, ground atoms, and problem instances.
+
+Each predicate in a domain profile carries an NL ``template`` with ``{arg}``
+placeholders (e.g. ``"block {x} is on top of block {y}"``); rendering a state
+or goal is placeholder substitution -- no LLM required. ``domain_nl`` is the
+domain-side counterpart: it renders the predicate and action vocabulary from
+the schema's authored ``description`` fields, with the formal signatures and
+pre/add/delete structure kept symbolic.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, List, Optional, Sequence
+
+from lmdl.schema import DomainSchema, ProblemSpec
+
+
+def format_atom(atom: Sequence[str]) -> str:
+    """Format an atom as compact ``pred(a, b)`` text (bare ``pred`` when
+    zero-arity).
+
+    Works on both ground atoms (object arguments) and atom templates
+    (variable arguments).
+
+    :param atom: The atom as ``(name, *args)``.
+    :returns: The atom as compact symbolic text.
+    """
+    name, args = atom[0], atom[1:]
+    return name if not args else f"{name}({', '.join(args)})"
+
+
+def render_atom(atom: Sequence[str], schema: DomainSchema) -> str:
+    """Render a ground atom ``(pred, obj1, obj2)`` as an NL sentence via its
+    predicate's template.
+
+    Falls back to the symbolic form ``pred(obj1, obj2)`` when the predicate is
+    unknown, has no template, or the atom's arity doesn't match.
+
+    :param atom: The ground atom as ``(predicate_name, *object_names)``.
+    :param schema: The domain schema supplying the predicate templates.
+    :returns: One NL sentence (or the symbolic fallback form).
+    """
+    name, objs = atom[0], list(atom[1:])
+    pred = schema.predicates.get(name)
+    if pred is None or not pred.template or len(pred.args) != len(objs):
+        return format_atom(atom)
+    # Substitute by whole placeholder token rather than str.format so that
+    # hyphenated arg names (illegal as format fields) still work.
+    text = pred.template
+    for arg, obj in zip(pred.args, objs):
+        text = text.replace("{" + arg.name + "}", obj)
+    return text
+
+
+def domain_nl(schema: DomainSchema, exclude_action: Optional[str] = None) -> str:
+    """Render a domain's vocabulary as text from its authored descriptions.
+
+    Predicates and actions are listed with their typed signatures and NL
+    ``description`` fields; each action's pre/add/delete atoms stay symbolic
+    (``clear(underob), holding(ob)``). No LLM required.
+
+    :param schema: The domain schema to render.
+    :param exclude_action: Optionally omit one action, e.g. so it can serve
+        as a held-out generation target.
+    :returns: The domain description, one predicate/action per block.
+    """
+    lines = ["Predicates:"]
+    for name, pred in schema.predicates.items():
+        sig = ", ".join(f"{a.name}: {a.type}" for a in pred.args) if pred.args else ""
+        desc = f" — {pred.description}" if pred.description else ""
+        lines.append(f"  {name}({sig}){desc}")
+
+    lines.append("")
+    lines.append("Actions:")
+    for name, action in schema.actions.items():
+        if name == exclude_action:
+            continue
+        sig = ", ".join(f"{p.name}: {p.type}" for p in action.params)
+        desc = f" — {action.description}" if action.description else ""
+        lines.append(f"  {name}({sig}){desc}")
+
+        pre_str = ", ".join(format_atom(t) for t in action.pre) or "—"
+        add_str = ", ".join(format_atom(t) for t in action.add) or "—"
+        del_str = ", ".join(format_atom(t) for t in action.delete) or "—"
+        lines.append(f"    preconditions: {pre_str}")
+        lines.append(f"    add: {add_str}")
+        lines.append(f"    delete: {del_str}")
+
+    return "\n".join(lines)
+
+
+def problem_nl(problem: ProblemSpec, schema: DomainSchema) -> str:
+    """Render a problem instance as NL: objects grouped by sort, then the
+    initial state and goal as one templated sentence per ground atom.
+
+    :param problem: The problem instance to render.
+    :param schema: The domain schema supplying the predicate templates.
+    :returns: The full NL problem statement (objects, initial state, goal).
+    """
+    by_sort: Dict[str, List[str]] = defaultdict(list)
+    for obj, sort in problem.objects.items():
+        by_sort[sort].append(obj)
+    obj_lines = [
+        f"  {sort}: {', '.join(sorted(objs))}" for sort, objs in sorted(by_sort.items())
+    ]
+    init_lines = [f"  - {render_atom(a, schema)}" for a in sorted(problem.init)]
+    goal_lines = [f"  - {render_atom(a, schema)}" for a in problem.goal]
+
+    return (
+        "Objects:\n"
+        + "\n".join(obj_lines)
+        + "\n\nInitial state:\n"
+        + "\n".join(init_lines)
+        + "\n\nGoal:\n"
+        + "\n".join(goal_lines)
+    )