Add analysis API and CLI check command

Author: SaridakisStamatisChristos

README.md

@@ -57,6 +57,9 @@ sudoku-dlx dedupe --in puzzles.txt --out unique.txt
 # Generate a unique puzzle (deterministic with seed)
 sudoku-dlx gen   --seed 123 --givens 30           # ~target clue count (approx)
 sudoku-dlx gen   --seed 123 --givens 30 --pretty
+# Analyze (valid/solvable/unique/difficulty/stats/canonical)
+sudoku-dlx check --grid "<81chars>"
+sudoku-dlx check --grid "<81chars>" --json > report.json
 # Advanced generator flags:
 sudoku-dlx gen   --seed 123 --givens 28 --minimal
 sudoku-dlx gen   --seed 123 --givens 28 --symmetry rot180

src/sudoku_dlx/__init__.py

@@ -7,6 +7,7 @@
     count_solutions,
     from_string,
     is_valid,
+    analyze,
     solve,
     to_string,
 )
@@ -34,6 +35,7 @@
     "to_string",
     "is_valid",
     "solve",
+    "analyze",
     "count_solutions",
     "rate",
     "canonical_form",

src/sudoku_dlx/api.py

@@ -2,10 +2,12 @@
 
 from dataclasses import dataclass
 from time import perf_counter
-from typing import List, Optional
+from typing import List, Optional, Dict, Any
 
 Grid = List[List[int]]
 
+ANALYZE_VERSION = "1"
+
 
 @dataclass
 class Stats:
@@ -88,6 +90,50 @@ def count_solutions(grid: Grid, limit: int = 2) -> int:
     engine = DLXEngine()
     return engine.count(rows, limit=limit)
 
+
+def analyze(grid: Grid) -> Dict[str, Any]:
+    """
+    Return a compact analysis dict for a Sudoku grid. Keys:
+      - version: schema version string
+      - valid: bool (no row/col/box duplicates among givens)
+      - givens: int
+      - solvable: bool
+      - unique: bool (exactly one solution determined via limit=2)
+      - difficulty: float in [0,10] (heuristic)
+      - canonical: str (81-char canonical form)
+      - solution: str | None (81-char solution if solvable)
+      - stats: {ms, nodes, backtracks} (0s if unsolvable)
+    """
+    from .rating import rate
+    from .canonical import canonical_form
+
+    givens = sum(1 for r in range(9) for c in range(9) if grid[r][c] != 0)
+    valid = is_valid(grid)
+    uniq = False
+    solv: Optional[SolveResult] = None
+    if valid:
+        # Uniqueness and solvability
+        uniq = count_solutions(grid, limit=2) == 1
+        solv = solve(grid)
+    solution = None
+    ms = nodes = backs = 0
+    if solv is not None:
+        solution = to_string(solv.grid)
+        ms = int(round(solv.stats.ms))
+        nodes = int(solv.stats.nodes)
+        backs = int(solv.stats.backtracks)
+    return {
+        "version": ANALYZE_VERSION,
+        "valid": valid,
+        "givens": givens,
+        "solvable": solv is not None,
+        "unique": uniq,
+        "difficulty": float(rate(grid)),
+        "canonical": canonical_form(grid),
+        "solution": solution,
+        "stats": {"ms": ms, "nodes": nodes, "backtracks": backs},
+    }
+
 __all__ = [
     "Grid",
     "Stats",
@@ -97,4 +143,5 @@ def count_solutions(grid: Grid, limit: int = 2) -> int:
     "is_valid",
     "solve",
     "count_solutions",
+    "analyze",
 ]

src/sudoku_dlx/cli.py

@@ -2,12 +2,13 @@
 
 import argparse
 import csv
+import json
 import pathlib
 import random
 import sys
 from typing import Optional
 
-from .api import from_string, is_valid, solve, to_string
+from .api import analyze, from_string, is_valid, solve, to_string
 from .canonical import canonical_form
 from .generate import generate
 from .rating import rate
@@ -27,6 +28,23 @@ def _print_grid(grid) -> None:
         print(" ".join(str(x) for x in row))
 
 
+def _print_analysis(data: dict) -> None:
+    def yes(b: bool) -> str:
+        return "yes" if b else "no"
+
+    print("== sudoku-dlx check ==")
+    print(f"valid:     {yes(data['valid'])}   givens: {data['givens']}")
+    print(f"solvable:  {yes(data['solvable'])}   unique: {yes(data['unique'])}")
+    print(f"difficulty:{data['difficulty']:.1f}")
+    stats = data["stats"]
+    print(
+        f"stats:     {stats['ms']} ms · nodes {stats['nodes']} · backtracks {stats['backtracks']}"
+    )
+    print(f"canonical: {data['canonical']}")
+    if data["solution"]:
+        print(f"solution:  {data['solution']}")
+
+
 def cmd_solve(ns: argparse.Namespace) -> int:
     grid = from_string(_read_grid_arg(ns))
     if not is_valid(grid):
@@ -54,6 +72,16 @@ def cmd_rate(ns: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_check(ns: argparse.Namespace) -> int:
+    grid = from_string(_read_grid_arg(ns))
+    data = analyze(grid)
+    if ns.json:
+        print(json.dumps(data, separators=(",", ":"), sort_keys=True))
+    else:
+        _print_analysis(data)
+    return 0
+
+
 def cmd_gen(ns: argparse.Namespace) -> int:
     grid = generate(
         seed=ns.seed,
@@ -165,6 +193,14 @@ def main(argv: Optional[list[str]] = None) -> int:
     rate_parser.add_argument("--file", help="path to a file with 9 lines of 9 chars")
     rate_parser.set_defaults(func=cmd_rate)
 
+    check_parser = sub.add_parser(
+        "check", help="validate/score a puzzle and show stats/canonical form"
+    )
+    check_parser.add_argument("--grid", help="81-char string; 0/./- for blanks")
+    check_parser.add_argument("--file", help="path to a file with 9 lines of 9 chars")
+    check_parser.add_argument("--json", action="store_true", help="output JSON")
+    check_parser.set_defaults(func=cmd_check)
+
     canon_parser = sub.add_parser(
         "canon",
         help=(

tests/test_check.py

@@ -0,0 +1,41 @@
+from textwrap import dedent
+import json
+from sudoku_dlx import analyze, from_string
+from sudoku_dlx import cli
+
+PUZ = dedent(
+    """
+    53..7....
+    6..195...
+    .98....6.
+    8...6...3
+    4..8.3..1
+    7...2...6
+    .6....28.
+    ...419..5
+    ....8..79
+    """
+).strip()
+
+def test_analyze_api_keys():
+    g = from_string(PUZ)
+    data = analyze(g)
+    for k in ["version","valid","givens","solvable","unique","difficulty","canonical","solution","stats"]:
+        assert k in data
+    st = data["stats"]
+    for k in ["ms","nodes","backtracks"]:
+        assert k in st
+
+def test_cli_check_pretty_and_json(capsys):
+    rc = cli.main(["check", "--grid", PUZ])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "valid:" in out and "difficulty:" in out and "canonical:" in out
+
+    rc = cli.main(["check", "--grid", PUZ, "--json"])
+    assert rc == 0
+    out = capsys.readouterr().out.strip()
+    data = json.loads(out)
+    assert data["valid"] is True
+    assert "canonical" in data and len(data["canonical"]) == 81
+    assert isinstance(data["difficulty"], float)