Merge branch 'main' of github.com:CodingThrust/problem-reductions

Author: GiggleLiu

.claude/CLAUDE.md

@@ -27,6 +27,8 @@ make diagrams      # Generate SVG diagrams from Typst (light + dark)
 make examples      # Generate example JSON for paper
 make compare       # Generate and compare Rust mapping exports
 make jl-testdata   # Regenerate Julia parity test data (requires julia)
+make cli           # Build the pred CLI tool (release mode)
+make cli-demo      # Run closed-loop CLI demo (exercises all commands)
 make run-plan      # Execute a plan with Claude autorun
 make release V=x.y.z  # Tag and push a new release (CI publishes to crates.io)
 ```
@@ -48,6 +50,7 @@ make test clippy  # Must pass before PR
 - `src/traits.rs` - `Problem`, `OptimizationProblem`, `SatisfactionProblem` traits
 - `src/rules/traits.rs` - `ReduceTo<T>`, `ReductionResult` traits
 - `src/registry/` - Compile-time reduction metadata collection
+- `problemreductions-cli/` - `pred` CLI tool (separate crate in workspace)
 - `src/unit_tests/` - Unit test files (mirroring `src/` structure, referenced via `#[path]`)
 - `tests/main.rs` - Integration tests (modules in `tests/suites/`); example tests use `include!` for direct invocation (no subprocess)
 - `tests/data/` - Ground truth JSON for integration tests
@@ -149,6 +152,13 @@ See Key Patterns above for solver API signatures. Follow the reference files for
 
 Unit tests in `src/unit_tests/` linked via `#[path]` (see Core Modules above). Integration tests in `tests/suites/`, consolidated through `tests/main.rs`. Example tests in `tests/suites/examples.rs` using `include!` for direct invocation.
 
+## Documentation Locations
+- `README.md` — Project overview and quickstart
+- `.claude/` — Claude Code instructions and skills
+- `docs/book/` — mdBook user documentation (built with `make doc`)
+- `docs/paper/reductions.typ` — Typst paper with problem definitions and reduction theorems
+- `examples/` — Reduction example code (also used in paper and tests)
+
 ## Documentation Requirements
 
 **Reference:** search `docs/paper/reductions.typ` for `MinimumVertexCover` `MaximumIndependentSet` to see a complete problem-def + reduction-rule example.

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
           components: clippy
       - uses: Swatinem/rust-cache@v2
       - name: Run clippy
-        run: cargo clippy --all-targets --all-features -- -D warnings
+        run: cargo clippy --all-targets --features ilp-highs -- -D warnings
 
   # Build and test
   test:
@@ -34,13 +34,13 @@ jobs:
       - uses: Swatinem/rust-cache@v2
 
       - name: Build
-        run: cargo build --all-features --verbose
+        run: cargo build --features ilp-highs --verbose
 
       - name: Run tests
-        run: cargo test --all-features --verbose
+        run: cargo test --features ilp-highs --verbose
 
       - name: Run doc tests
-        run: cargo test --doc --all-features --verbose
+        run: cargo test --doc --features ilp-highs --verbose
 
   # Code coverage
   coverage:
@@ -55,7 +55,7 @@ jobs:
       - name: Install cargo-llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
       - name: Generate coverage
-        run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
+        run: cargo llvm-cov --features ilp-highs --workspace --lcov --output-path lcov.info
       - name: Upload to codecov.io
         uses: codecov/codecov-action@v4
         with:

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "problemreductions-macros"]
+members = [".", "problemreductions-macros", "problemreductions-cli"]
 
 [package]
 name = "problemreductions"
@@ -12,8 +12,15 @@ keywords = ["np-hard", "optimization", "reduction", "sat", "graph"]
 categories = ["algorithms", "science"]
 
 [features]
-default = ["ilp"]
-ilp = ["good_lp"]
+default = ["ilp-highs"]
+ilp = ["ilp-highs"]  # backward compat shorthand
+ilp-solver = []      # marker: enables ILP solver code
+ilp-highs = ["ilp-solver", "dep:good_lp", "good_lp/highs"]
+ilp-coin-cbc = ["ilp-solver", "dep:good_lp", "good_lp/coin_cbc"]
+ilp-clarabel = ["ilp-solver", "dep:good_lp", "good_lp/clarabel"]
+ilp-scip = ["ilp-solver", "dep:good_lp", "good_lp/scip"]
+ilp-lpsolve = ["ilp-solver", "dep:good_lp", "good_lp/lpsolve"]
+ilp-microlp = ["ilp-solver", "dep:good_lp", "good_lp/microlp"]
 
 [dependencies]
 petgraph = { version = "0.8", features = ["serde-1"] }
@@ -22,7 +29,7 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 thiserror = "2.0"
 num-traits = "0.2"
-good_lp = { version = "1.8", default-features = false, features = ["highs"], optional = true }
+good_lp = { version = "1.8", default-features = false, optional = true }
 inventory = "0.3"
 ordered-float = "5.0"
 rand = "0.9"

Makefile

@@ -1,6 +1,6 @@
 # Makefile for problemreductions
 
-.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release run-plan diagrams jl-testdata
+.PHONY: help build test fmt clippy doc mdbook paper examples clean coverage rust-export compare qubo-testdata export-schemas release run-plan diagrams jl-testdata cli cli-demo
 
 # Default target
 help:
@@ -24,15 +24,17 @@ help:
 	@echo "  qubo-testdata - Regenerate QUBO test data (requires uv)"
 	@echo "  jl-testdata  - Regenerate Julia parity test data (requires julia)"
 	@echo "  release V=x.y.z - Tag and push a new release (triggers CI publish)"
+	@echo "  cli          - Build the pred CLI tool"
+	@echo "  cli-demo     - Run closed-loop CLI demo (build + exercise all commands)"
 	@echo "  run-plan   - Execute a plan with Claude autorun (latest plan in docs/plans/)"
 
 # Build the project
 build:
-	cargo build --all-features
+	cargo build --features ilp-highs
 
 # Run all tests (including ignored tests)
 test:
-	cargo test --all-features -- --include-ignored
+	cargo test --features ilp-highs -- --include-ignored
 
 # Format code
 fmt:
@@ -44,14 +46,14 @@ fmt-check:
 
 # Run clippy
 clippy:
-	cargo clippy --all-targets --all-features -- -D warnings
+	cargo clippy --all-targets --features ilp-highs -- -D warnings
 
 # Build mdBook documentation
 doc:
 	cargo run --example export_graph
 	cargo run --example export_schemas
 	mdbook build docs
-	RUSTDOCFLAGS="--default-theme=dark" cargo doc --all-features --no-deps
+	RUSTDOCFLAGS="--default-theme=dark" cargo doc --features ilp-highs --no-deps
 	rm -rf docs/book/api
 	cp -r target/doc docs/book/api
 
@@ -70,7 +72,7 @@ diagrams:
 mdbook:
 	cargo run --example export_graph
 	cargo run --example export_schemas
-	RUSTDOCFLAGS="--default-theme=dark" cargo doc --all-features --no-deps
+	RUSTDOCFLAGS="--default-theme=dark" cargo doc --features ilp-highs --no-deps
 	mdbook build
 	rm -rf book/api
 	cp -r target/doc book/api
@@ -85,9 +87,9 @@ examples:
 	@mkdir -p docs/paper/examples
 	@for example in $(REDUCTION_EXAMPLES); do \
 		echo "Running $$example..."; \
-		cargo run --all-features --example $$example || exit 1; \
+		cargo run --features ilp-highs --example $$example || exit 1; \
 	done
-	cargo run --all-features --example export_petersen_mapping
+	cargo run --features ilp-highs --example export_petersen_mapping
 
 # Export problem schemas to JSON
 export-schemas:
@@ -102,7 +104,7 @@ paper: examples
 # Generate coverage report (requires: cargo install cargo-llvm-cov)
 coverage:
 	@command -v cargo-llvm-cov >/dev/null 2>&1 || { echo "Installing cargo-llvm-cov..."; cargo install cargo-llvm-cov; }
-	cargo llvm-cov --all-features --workspace --html --open
+	cargo llvm-cov --features ilp-highs --workspace --html --open
 
 # Clean build artifacts
 clean:
@@ -135,6 +137,10 @@ endif
 	git push origin main --tags
 	@echo "v$(V) pushed — CI will publish to crates.io"
 
+# Build the pred CLI tool
+cli:
+	cargo build -p problemreductions-cli --release
+
 # Generate Rust mapping JSON exports for all graphs and modes
 GRAPHS := diamond bull house petersen
 MODES := unweighted weighted triangular
@@ -191,3 +197,140 @@ run-plan:
 		--verbose \
 		--max-turns 500 \
 		-p "$$PROMPT" 2>&1 | tee "$(OUTPUT)"
+
+# Closed-loop CLI demo: exercises all commands end-to-end
+PRED := cargo run -p problemreductions-cli --release --
+CLI_DEMO_DIR := /tmp/pred-cli-demo
+cli-demo: cli
+	@echo "=== pred CLI closed-loop demo ==="
+	@rm -rf $(CLI_DEMO_DIR) && mkdir -p $(CLI_DEMO_DIR)
+	@set -e; \
+	PRED="./target/release/pred"; \
+	\
+	echo ""; \
+	echo "--- 1. list: all registered problems ---"; \
+	$$PRED list; \
+	$$PRED list -o $(CLI_DEMO_DIR)/problems.json; \
+	\
+	echo ""; \
+	echo "--- 2. show: inspect MIS (variants, fields, reductions) ---"; \
+	$$PRED show MIS; \
+	$$PRED show MIS -o $(CLI_DEMO_DIR)/mis_info.json; \
+	\
+	echo ""; \
+	echo "--- 3. to: explore 2-hop outgoing neighborhood ---"; \
+	$$PRED to MIS --hops 2; \
+	$$PRED to MIS --hops 2 -o $(CLI_DEMO_DIR)/mis_hops.json; \
+	\
+	echo ""; \
+	echo "--- 4. from: incoming neighbors ---"; \
+	$$PRED from QUBO --hops 1; \
+	\
+	echo ""; \
+	echo "--- 5. path: find reduction paths ---"; \
+	$$PRED path MIS QUBO; \
+	$$PRED path MIS QUBO -o $(CLI_DEMO_DIR)/path_mis_qubo.json; \
+	$$PRED path Factoring SpinGlass; \
+	$$PRED path MIS QUBO --cost minimize:num_variables; \
+	\
+	echo ""; \
+	echo "--- 6. path --all: enumerate all paths ---"; \
+	$$PRED path MIS QUBO --all; \
+	$$PRED path MIS QUBO --all -o $(CLI_DEMO_DIR)/all_paths/; \
+	\
+	echo ""; \
+	echo "--- 7. export-graph: full reduction graph ---"; \
+	$$PRED export-graph -o $(CLI_DEMO_DIR)/graph.json; \
+	\
+	echo ""; \
+	echo "--- 8. create: build problem instances ---"; \
+	$$PRED create MIS --edges 0-1,1-2,2-3,3-4,4-0 -o $(CLI_DEMO_DIR)/mis.json; \
+	$$PRED create MIS --edges 0-1,1-2,2-3 --weights 2,1,3,1 -o $(CLI_DEMO_DIR)/mis_weighted.json; \
+	$$PRED create SAT --num-vars 3 --clauses "1,2;-1,3;2,-3" -o $(CLI_DEMO_DIR)/sat.json; \
+	$$PRED create 3SAT --num-vars 4 --clauses "1,2,3;-1,2,-3;1,-2,3" -o $(CLI_DEMO_DIR)/3sat.json; \
+	$$PRED create QUBO --matrix "1,-0.5;-0.5,2" -o $(CLI_DEMO_DIR)/qubo.json; \
+	$$PRED create KColoring --k 3 --edges 0-1,1-2,2-0 -o $(CLI_DEMO_DIR)/kcol.json; \
+	$$PRED create SpinGlass --edges 0-1,1-2 -o $(CLI_DEMO_DIR)/sg.json; \
+	$$PRED create MaxCut --edges 0-1,1-2,2-0 -o $(CLI_DEMO_DIR)/maxcut.json; \
+	$$PRED create MVC --edges 0-1,1-2,2-3 -o $(CLI_DEMO_DIR)/mvc.json; \
+	$$PRED create MaximumMatching --edges 0-1,1-2,2-3 -o $(CLI_DEMO_DIR)/matching.json; \
+	$$PRED create Factoring --target 15 --bits-m 4 --bits-n 4 -o $(CLI_DEMO_DIR)/factoring.json; \
+	$$PRED create Factoring --target 21 --bits-m 3 --bits-n 3 -o $(CLI_DEMO_DIR)/factoring2.json; \
+	\
+	echo ""; \
+	echo "--- 9. evaluate: test configurations ---"; \
+	$$PRED evaluate $(CLI_DEMO_DIR)/mis.json --config 1,0,1,0,0; \
+	$$PRED evaluate $(CLI_DEMO_DIR)/mis.json --config 1,1,0,0,0; \
+	$$PRED evaluate $(CLI_DEMO_DIR)/sat.json --config 0,1,1; \
+	$$PRED evaluate $(CLI_DEMO_DIR)/mis.json --config 1,0,1,0,0 -o $(CLI_DEMO_DIR)/eval.json; \
+	\
+	echo ""; \
+	echo "--- 10. solve: direct ILP (auto-reduces to ILP) ---"; \
+	$$PRED solve $(CLI_DEMO_DIR)/mis.json; \
+	$$PRED solve $(CLI_DEMO_DIR)/mis.json -o $(CLI_DEMO_DIR)/sol_ilp.json; \
+	\
+	echo ""; \
+	echo "--- 11. solve: brute-force ---"; \
+	$$PRED solve $(CLI_DEMO_DIR)/mis.json --solver brute-force; \
+	\
+	echo ""; \
+	echo "--- 12. solve: weighted MIS ---"; \
+	$$PRED solve $(CLI_DEMO_DIR)/mis_weighted.json; \
+	\
+	echo ""; \
+	echo "--- 13. reduce: MIS → QUBO (auto-discover path) ---"; \
+	$$PRED reduce $(CLI_DEMO_DIR)/mis.json --to QUBO -o $(CLI_DEMO_DIR)/bundle_qubo.json; \
+	\
+	echo ""; \
+	echo "--- 14. solve bundle: brute-force on reduced QUBO ---"; \
+	$$PRED solve $(CLI_DEMO_DIR)/bundle_qubo.json --solver brute-force; \
+	\
+	echo ""; \
+	echo "--- 15. reduce --via: use explicit path file ---"; \
+	$$PRED reduce $(CLI_DEMO_DIR)/mis.json --via $(CLI_DEMO_DIR)/path_mis_qubo.json -o $(CLI_DEMO_DIR)/bundle_via.json; \
+	\
+	echo ""; \
+	echo "--- 16. solve bundle with ILP: MIS → MVC → ILP ---"; \
+	$$PRED reduce $(CLI_DEMO_DIR)/mis.json --to MVC -o $(CLI_DEMO_DIR)/bundle_mvc.json; \
+	$$PRED solve $(CLI_DEMO_DIR)/bundle_mvc.json --solver ilp; \
+	\
+	echo ""; \
+	echo "--- 17. solve: other problem types ---"; \
+	$$PRED solve $(CLI_DEMO_DIR)/sat.json --solver brute-force; \
+	$$PRED solve $(CLI_DEMO_DIR)/kcol.json --solver brute-force; \
+	$$PRED solve $(CLI_DEMO_DIR)/maxcut.json --solver brute-force; \
+	$$PRED solve $(CLI_DEMO_DIR)/mvc.json; \
+	\
+	echo ""; \
+	echo "--- 18. closed-loop: create → reduce → solve → verify ---"; \
+	echo "Creating a 6-vertex graph..."; \
+	$$PRED create MIS --edges 0-1,1-2,2-3,3-4,4-5,0-5,1-4 -o $(CLI_DEMO_DIR)/big.json; \
+	echo "Solving with ILP..."; \
+	$$PRED solve $(CLI_DEMO_DIR)/big.json -o $(CLI_DEMO_DIR)/big_sol.json; \
+	echo "Reducing to QUBO and solving with brute-force..."; \
+	$$PRED reduce $(CLI_DEMO_DIR)/big.json --to QUBO -o $(CLI_DEMO_DIR)/big_qubo.json; \
+	$$PRED solve $(CLI_DEMO_DIR)/big_qubo.json --solver brute-force -o $(CLI_DEMO_DIR)/big_qubo_sol.json; \
+	echo "Verifying both solutions have the same evaluation..."; \
+	ILP_EVAL=$$(jq -r '.evaluation' $(CLI_DEMO_DIR)/big_sol.json); \
+	BF_EVAL=$$(jq -r '.evaluation' $(CLI_DEMO_DIR)/big_qubo_sol.json); \
+	echo "  ILP solution evaluation:         $$ILP_EVAL"; \
+	echo "  Brute-force (via QUBO) evaluation: $$BF_EVAL"; \
+	if [ "$$ILP_EVAL" = "$$BF_EVAL" ]; then \
+		echo "  ✅ Solutions agree!"; \
+	else \
+		echo "  ❌ Solutions disagree!" && exit 1; \
+	fi; \
+	\
+	echo ""; \
+	echo "--- 19. show with alias and variant slash syntax ---"; \
+	$$PRED show MIS/UnitDiskGraph; \
+	\
+	echo ""; \
+	echo "--- 20. completions: generate shell completions ---"; \
+	$$PRED completions bash > /dev/null && echo "bash completions: OK"; \
+	$$PRED completions zsh > /dev/null && echo "zsh completions:  OK"; \
+	$$PRED completions fish > /dev/null && echo "fish completions: OK"; \
+	\
+	echo ""; \
+	echo "=== Demo complete: $$(ls $(CLI_DEMO_DIR)/*.json | wc -l | tr -d ' ') JSON files in $(CLI_DEMO_DIR) ==="
+	@echo "=== All 20 steps passed ✅ ==="

README.md

@@ -15,14 +15,32 @@ Download [PDF manual](https://codingthrust.github.io/problem-reductions/reductio
 
 ## Installation
 
+### As a library
+
 Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
 problemreductions = "0.2"
 ```
 
-See the [Getting Started](https://codingthrust.github.io/problem-reductions/getting-started.html) guide for usage examples and the reduction workflow.
+### CLI tool
+
+Install the `pred` command-line tool for exploring the reduction graph from your terminal:
+
+```bash
+cargo install --git https://github.com/CodingThrust/problem-reductions problemreductions-cli
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/CodingThrust/problem-reductions
+cd problem-reductions
+make cli    # builds target/release/pred
+```
+
+See the [Getting Started](https://codingthrust.github.io/problem-reductions/getting-started.html) guide for usage examples, the reduction workflow, and [CLI usage](https://codingthrust.github.io/problem-reductions/cli.html).
 
 ## Contributing
 

codecov.yml

@@ -17,6 +17,10 @@ coverage:
         threshold: 2%
 
 # Exclude proc-macro crate from coverage since it runs at compile time
-# and traditional runtime coverage tools cannot measure it
+# and traditional runtime coverage tools cannot measure it.
+# Exclude CLI crate from patch coverage: it is a thin dispatch layer
+# with many boilerplate type-dispatch match arms that are tested
+# end-to-end via integration tests, not amenable to 95% line coverage.
 ignore:
   - "problemreductions-macros/**/*"
+  - "problemreductions-cli/**/*"