Skip to content

Make the command line safe to script, and the charts survive a dead end - #167

Merged
guilyx merged 9 commits into
mainfrom
feat/zen-gates-g3lolk
Nov 3, 2026
Merged

Make the command line safe to script, and the charts survive a dead end#167
guilyx merged 9 commits into
mainfrom
feat/zen-gates-g3lolk

Conversation

@guilyx

@guilyx guilyx commented Nov 3, 2026

Copy link
Copy Markdown
Member

What and why

Fixes from the CLI / viz / web / packaging review. An outside user meets the CLI first. Before this PR it hung on two documented commands, exited 1 for every kind of failure, and printed tracebacks for typos.

Command line

Before After
Unsolvable, out of budget and a crash all exited 1 0 solved · 1 no plan · 2 bad input · 3 stopped by a budget · 4 a plan that failed validation. Documented in --help, the module docstring and the README
A missing file, a parse error, an unknown planner or --sizes abc printed a traceback One line: jupyddl: error: …. JUPYDDL_DEBUG=1 restores the traceback
jupyddl demo and the README's jupyddl benchmark demos never finished Both stop each search after 10 s by default (--time-limit 0 for no limit). animate and demo accept the same budget flags as solve
--planners astar,nosuch reported nosuch 0/13 and exited 0 Planners, heuristic and --metric are checked before anything runs
Without the viz extra, chart options failed after the whole search, or silently wrote nothing and exited 0 Checked before searching; exits 2 with "install jupyddl[viz]"
No --version jupyddl --version

Charts and workbench

  • Dead ends broke charts. A dead end has h = inf. The progress chart crashed (Axis limits cannot be NaN or Inf), and the wavefront chart coloured those nodes NaN. Infinite values are now filtered out, and dead ends take the end of the colour scale.
  • The workbench aborted on a dead end. It streamed Infinity for h/f, which JSON.parse rejects, so the run aborted. Both values are now sanitised.
  • Bookkeeping in traces. A trace's plan showed compiler steps such as __observe-1#1 and disjunct tags. It now records the plan the user actually reads.

Packaging and CI

  • The sdist's own test suite failed. It excluded all of .github/, while a test checks that CONTRIBUTING.md is there. Only .github/workflows/** is excluded now. I built the sdist and ran its suite: 341 passed, 0 failed (submodule tests skip).
  • build now runs twine check --strict, like release already does.
  • black is pinned to one major version (>=26,<27) in both the dev extra and format.yml. format.yml used to install whatever was newest.
  • Renovate's helpers:pinGitHubActionDigests pins third-party actions to commit SHAs. Some of them run with contents: write.

How it was checked

  • New tests/test_cli_contract.py:
    • each exit code
    • each bad-input path gives one line and no traceback
    • debug mode keeps the traceback
    • --version
    • a chart option without matplotlib fails before a search that would take minutes
    • a trace's plan has no bookkeeping steps
    • the workbench observer emits valid JSON for h = f = inf
  • Two new viz tests: a dead-end run writes both charts; an empty benchmark gives a clear error.
  • Full suite: 513 passed, 1 skipped. flake8 and black are clean, and web/dist is rebuilt.

Behaviour changes to note

  • Exit-code changes. A run stopped by a budget now exits 3 (it was 1). An invalid plan now exits 4 (it was 2). Bad-input paths that exited 1 now exit 2.
  • New default limit. benchmark and demo now have a default 10 s per-search limit. Coverage numbers from those commands therefore depend on the machine unless you pass --time-limit 0.

Checklist

  • flake8 jupyddl tests tools and pytest pass locally
  • python tools/build_web.py re-run; web/dist committed
  • No planner or heuristic guarantee changes
  • CHANGELOG.md updated

The history has a merge -s ours of the already-merged #166 tip so the push fast-forwards. Squash-merge.

Generated by Claude Code

claude added 9 commits November 2, 2026 21:26
@claude
State the intent to publish, and get ready for outside contributors
ff7dcde 
Write down where and why we mean to publish jupyddl as citable research
software (.docs/PUBLISHING.md): a Zenodo DOI per release, a JOSS paper,
ICAPS workshops for the research results, with a readiness checklist, the
paper outline, the AI-usage disclosure JOSS requires, and how contributors
can be considered for authorship. The README states the project's aim and
its Cite section now says which version the 2021 preprint describes.

Add the community files an outside contributor expects: a security policy,
a pull-request template, a "Propose an algorithm" issue template, and an
"Adding an algorithm" section in CONTRIBUTING.md.

Run tests and build on pull requests. They were `on: [push]`, which never
fires for a fork, so a contributor's PR showed no checks at all.

Fix AGENTS.md drift: the Python floor is 3.10 and Mergify is retired.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RbGtRHF8XhkiPQCDVHtV2
@claude
Let other packages plug in, and write the guide to building on jupyddl
770b41a 
A package can now add planners, heuristics and generators by declaring
`jupyddl.planners`, `jupyddl.heuristics` or `jupyddl.generators` entry
points. Once installed, they work from the CLI, the benchmark harness and
`jupyddl.solve` by name, without anyone importing the package.

Discovery is lazy and defensive (jupyddl/plugins.py): the CLI runs it
before building its parser, the library only on a registry miss, so
importing jupyddl never scans installed packages. A built-in name always
wins, a plugin that fails to import is skipped with a warning, and
JUPYDDL_NO_PLUGINS=1 turns it off. `jupyddl plugins` lists what was found.
The CLI now reads `requires_heuristic` from the registry at call time,
since INFORMED_PLANNERS is fixed at import and cannot know about plugins.

.docs/EXTENDING.md walks through a heuristic, a planner from a priority
function, a planner from scratch with the budget/observer contract, a
generator, testing the guarantees you claim, and shipping as a plugin.
tests/test_extending.py runs every Python block in it, so it cannot drift.

best_first now accepts a tuple priority for tie-breaking; observers get
its first element as `f`, so traces stay numeric.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RbGtRHF8XhkiPQCDVHtV2
@claude
Merge the already-merged #163 branch tip so this push fast-forwards
e1d4f83 
# Conflicts:
#	.docs/PUBLISHING.md
#	AGENTS.md
#	CHANGELOG.md
@claude
Fix wrong answers in the task model and heuristics
a5ef363 
Each of these returned a plan, a cost or a value without complaint, and
validate_plan accepted the plans because it replays them through the same
Task.apply. tests/test_semantics.py now pins them on tiny hand-written
tasks; 16 of its cases fail on the previous code.

- Derived facts were never retracted, and (not <derived>) held from the
  start. close() now recomputes axioms from scratch and maintains negated
  derived facts; negation inside a rule body (needs stratification) is
  refused. The relaxation gets the complement for free, so it never calls
  a solvable state a dead end.
- An atom both added and deleted left its complement true too; a `when`
  re-adding a deleted atom did the same. Complements: the delete wins.
- Under a (total-cost) metric an action without a cost effect is free, as
  in IPC planners (pegsol/sokoban optimised the wrong objective). Cost
  inside `when` was charged unconditionally: refused, as are negative costs.
- A never-defined numeric fluent read as 0; conditions reading one fail.
- blind skipped zero-cost actions and overestimated.
- h1/h2/hm crashed on numeric states; LM-cut crashed on an empty goal.
- lmcut and h2 clear `admissible` on tasks with conditional effects.
- Optimal planners default to lmcut, not hff; `-H none` means blind.
- make_heuristic builds a heuristic class or partial instead of passing it
  through unbuilt.
- Fact ids and id sets are built in sorted order, so LM-cut tie-breaks,
  expansions and plans no longer change with PYTHONHASHSEED.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RbGtRHF8XhkiPQCDVHtV2
@claude
Record the already-merged #164 branch tip so this push fast-forwards
76c970b
@claude
Make every planner honour its budget and claim only what it guarantees
0333b0d 
- iddfs, idastar and ehc never read their budget, so --time-limit was
  ignored. They poll per expansion now; the recursive ones unwind with
  BudgetExhausted. beam polls per node, not per layer, and bnb stops
  evaluating siblings once the budget fires.
- Hitting a depth cap (iddfs max_depth, bnb max_depth) or Python's
  recursion limit sets stats.truncated: it is not a proof of
  unsolvability, nor of optimality.
- bfs and iddfs leave OPTIMAL_PLANNERS: they minimise plan length, and on
  errands return cost 16 where 10 is optimal.
- Live dashboard: a budget stop no longer reads "no plan found"; lines are
  clipped to the stream's terminal width so repaints do not smear; the
  non-tty log writes at most every two seconds.
- idastar/ehc/hc/beam without a heuristic raise a clear ValueError;
  MultiObserver forwards positional arguments; the SearchObserver and
  best_first docstrings say what actually happens.

tests/test_search_contract.py runs every planner where the budget is the
only thing that stops it, checks OPTIMAL_PLANNERS against dijkstra under
action costs, and pins the dashboard behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RbGtRHF8XhkiPQCDVHtV2
@claude
Record the already-merged #165 branch tip so this push fast-forwards
5353db4
@claude
Make the command line safe to script, and the charts survive a dead end
f7d7334 
- Exit codes say what happened: 0 solved, 1 no plan, 2 bad input, 3
  stopped by a budget, 4 a plan that failed validation. Unsolvable, out of
  budget and a crash all used to exit 1.
- Bad input (missing file, parse error, unknown planner or heuristic, a
  malformed --sizes) is one line on stderr, not a traceback;
  JUPYDDL_DEBUG=1 restores the traceback. --version exists.
- `demo` and `benchmark demos` never finished. Both stop each search after
  10 s by default (--time-limit 0 for none); animate and demo take the
  same budget flags as solve.
- benchmark validates --planners/--heuristic/--metric up front, and chart
  options check for the viz extra before searching rather than after.
- Dead ends (h = inf) crashed the progress chart and coloured the
  wavefront NaN; in the workbench they made the progress message invalid
  JSON and aborted the run.
- A trace's plan is the visible plan, without compiler bookkeeping.
- Packaging: the sdist's own suite failed because .github/ was dropped
  wholesale; only workflows are excluded now. build runs twine --strict.
  black is pinned to one major in dev and format.yml; Renovate pins
  third-party actions to digests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RbGtRHF8XhkiPQCDVHtV2
@claude
Record the already-merged #166 branch tip so this push fast-forwards
0f83777
@guilyx
guilyx marked this pull request as ready for review November 3, 2026 08:18
@guilyx
guilyx merged commit f583fc7 into main Nov 3, 2026
10 checks passed
guilyx pushed a commit that referenced this pull request Nov 3, 2026
@claude
chore: record the already-merged #167 branch tip so this push fast-fo…
7af289e 
…rwards
@guilyx guilyx mentioned this pull request Nov 3, 2026
Merged
3 of 6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@guilyx @claude