PlanForge SGD

PlanForge SGD synthesizes classical plans by optimizing a differentiable, horizon-wide transcription and accepting plans only after exact SAS+ replay. It is search-free: expanded, evaluated, generated, reopened, and dead-end counters are exactly zero.

The optimizer was extracted from PlanForge with its development history. PlanForge owns the task model, translator, exact replay, and shared configuration parser; this repository owns all SGD and Candle code.

Build and run

Rust 1.88 or newer is required. The default package excludes Candle so its transcription and reference semantics stay quick to build:

cargo test --locked
cargo test --locked --features candle
cargo build --release --locked -p planforge-sgd-cli

Run directly from PDDL:

cargo run --release --locked -p planforge-sgd-cli -- \
  --search 'sgd(horizon=12,particles=24,updates=8000,seed=7)' \
  tests/fixtures/blocks-4-0/domain.pddl \
  tests/fixtures/blocks-4-0/problem.pddl

One numeric SAS+ file may be supplied instead of the PDDL pair. A successful run writes an action-only sas_plan, replays it exactly, reports its cost and replay-state count, and keeps every search counter at zero.

Migration from PlanForge

Only the executable name changes. Replace:

planforge --search 'sgd(OPTIONS)' DOMAIN PROBLEM

with:

planforge-sgd --search 'sgd(OPTIONS)' DOMAIN PROBLEM

All existing sgd(...) option keys, the lr alias, strict error behavior, and fixed or dovetail horizon forms are retained. PlanForge's former top-level resource, portfolio, and grounding flags were properties of its process wrapper, not SGD configuration; apply equivalent limits with your runner when migrating. An old SGD specification passed to PlanForge is now rejected as an unknown search engine; it never selects a different planner.

Dependency policy

PlanForge crates are not yet published on crates.io. Cargo.toml therefore pins every PlanForge dependency to the same immutable public HTTPS Git revision, and Cargo.lock is committed. No sibling checkout or private patch is needed. Once compatible PlanForge crates are published, the next minor release will replace the Git pin with normal version requirements after the same differential and clean-clone gates.

See ARCHITECTURE.md for the mathematical dataflow and invariants, CONTRIBUTING.md for validation commands, and VALIDATION.md for extraction and release evidence.

PlanForge SGD is licensed under GPL-3.0.