pencilmark 1.0.0__tar.gz

pencilmark-1.0.0/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+## 1.0.0
+
+First stable release: the `sudoku-puzzle`, `sudoku-grade` and `sudoku-spec` formats are format_version 1, and the card's
+meaning is set out in docs/PHILOSOPHY.md. Changes since 1.0.0rc2:
+
+- Grade card simplified (one meaning per key, docs/PHILOSOPHY.md): `contains_complete` removed (it was band != Unknown;
+  `stopped_at_step` still marks where human logic ran out); `time_dist.median` removed (it repeated `time`); steps use
+  the same keys as `contains` (`code`, `name`, `band`; `technique` renamed `name`); `alternatives` is `null` when the
+  search was skipped (`alternatives=False`) and omitted only when there are none.
+- More text formats: text grids with separators (Simple Sudoku / SadMan / forum style; `to_string(puzzle, "grid")`
+  writes them), a trailing `# comment` after a plain string, pencil-mark grids and 729-character candidate strings
+  (Sukaku). `rate()` and every entry point accept them as one string.
+- ipuz import: `from_ipuz` reads ipuz 1 / 2 sudoku (boxes, jigsaw zones, diagonals, windows, cages); `to_ipuz` now refuses
+  given candidates instead of dropping them.
+- `max_seconds` is now also checked inside the forcing-chain fallback (Easter Monster at `max_seconds=2` returned after
+  4.3 s, now 2.0 s); grades without a limit are unchanged.
+- Windows / macOS: `pencilmark rate -j N` hung under the spawn start method (the workers looked for their function in
+  pencilmark's `__main__`, which spawn does not re-import); it now passes them from the importable module and reads all
+  input first and reads / writes UTF-8 on every platform; the test suite runs on Windows and macOS too.
+- HoDoKu library lines (`:0901:4:<puzzle>:<removed candidates>:...`) are read by `from_string`.
+- `band_index` is no longer a default field (ask for it with `fields=[...]`); `se_diuf` removed (`se` gives the classic
+  Sudoku Explainer scale).
+- Rules keep the file's order: `to_export` writes a puzzle file's rules back in the order given, with their `id`, `label`
+  and `style` (it used to reorder them and drop those keys), and `issues` count rules in the graded file (`rules`), plus
+  their `ids` where present.
+- Quality checks: every entry of `quality` is an object, `{"limit": n, "severity": "reject" | "warning" | "off"}`
+  (CLI `--quality trivial.limit=0.5,trial.severity=reject`), so a check's severity can be changed as well as its limit;
+  bare numbers and `true` / `false` are no longer accepted. New optional field `warning` (true when any issue is a
+  warning), next to `reject`.
+- Format: `ext` removed; data for one program goes in `meta` under a reverse-DNS key, next to the suggested common keys
+  (the generator's own knobs too). Reserved items (`"type": "custom"`, `digits` as an object) are refused with a
+  message naming them as future work. `neighbours` kinds are documented as exact shortcuts for an operator on a pair
+  pattern.
+- Pair operators take their parameter under its own key, as the rest of the format: `{"op": "difference", "value": 3}`,
+  `{"op": "sum", "sum": 10}`, `any_of` a list of objects; positional `params` lists are refused. Writing an
+  `any_of` relation back no longer crashes.
+- `"type": "table"` and the `allowed` operator are reserved: explicit digit tables made files large and could not be
+  drawn; a custom rule type is planned to replace them. Mechanics without a rule family cannot be written in
+  format_version 1. The Rossini test puzzle now uses `rossini` rules and `negative` instead of edges and tables.
+- Generator: one vocabulary. `pencilmark.generate(spec)` (also `pencilmark.gen.generate`) takes a `sudoku-spec` request and
+  returns a `sudoku-puzzle` (with `meta.generated_from`), honouring the spec's `fields`; the internal Spec dicts
+  (`target_band`, `max_givens`, ...) and `spec_from_gen` / `spec_to_gen` are no longer public. `SPEC.md` version 1
+  describes exactly what the generator runs; the rest is listed as reserved and refused with a message naming it.
+  Example specs that use reserved parts moved to `docs/examples/specs/reserved/`.
+- **Seven bands**: Very Easy (scanning: full house, hidden singles) / Easy (naked singles, pointing / claiming, one rule's
+  combinations) / Medium (pairs, triples, quads; variant implications) / Hard (the first learned patterns: X-Wing,
+  Skyscraper, 2-String Kite, Turbot Fish, simple colouring) / Very Hard (Empty Rectangle, finned and larger fish, wings,
+  uniqueness) / **Expert** (new: XY-Chain, AIC, Medusa, ALS) / Extreme (forcing, trial). The steps common curricula
+  take (docs/PHILOSOPHY.md). `band_index` runs 0..6. Difficulty and time are unchanged
+  (all 7,427 graded puzzles of the frozen benchmark identical).
+- Step explanations at three levels: `notation` (the solvers' shared form, `X-Wing: 3 r58 c68 => r679c6<>3`), `short`,
+  `teach`; `pencilmark rate --report -v / -vv / -vvv` lists the steps at those levels. The report shows time percentiles
+  only when asked for (`--fields ...,time_p80`) and names alternatives in full.
+- Singles never carry `uses`; alternatives inside a chip are ordered deterministically (the order depended on Python's
+  per-process hashing); `max_seconds` also checked in the generalised fish search.
+- Difficulty below 2: the score map turns gentler there (about the square root of effort, the same value and slope at 2)
+  instead of bending into 0, so very easy puzzles keep apart (an easy 4x4 about 0.1-0.4, a nearly finished grid about
+  0.2; most used to read 0.0). Scores of 2 and above, every ranking and every time are unchanged.
+- Docs: philosophy page (goals, exact meaning of band / difficulty / time, format rules); README known issues.
+
+## 1.0.0rc2
+
+- `max_seconds` bounds the whole `rate()` call (uniqueness proof, card, technique list). The band and difficulty route
+  runs first, the technique list in the time left. If the limit passes in the route, the card says band `Unknown` with
+  `difficulty` / `time` null and the techniques found so far; if uniqueness is not proven in time, `rate` raises
+  `Undecided`. New `completed` field whenever `max_seconds` is set.
+- `contains_truncated` removed: `completed: false` already says the limit passed (when it passed only while the technique
+  list was being minimised, the grade stands and the list may not be minimal).
+- Optional `elapsed` field (wall-clock seconds for the call); `solve(puzzle, info=True)` returns the solution with its
+  seconds; the generator's `info` has `seconds` and `attempts`.
+- Optional `time_dist` field (`{"type": "lognormal", "median", "sigma_players", "sigma_model"}`); `time_p50` accepted.
+- Three variant techniques from how people solve on video: clue facts (`CFX`, Very Easy: what a clue rules out on an
+  empty grid, e.g. no 5 on a whisper), clue shape (`CSH`, Easy: a line's shape inside one house, e.g. a whisper 4
+  between two 9s) and high/low & odd/even colouring (`CCL`, Medium). Accuracy on human data is unchanged on average
+  (kropki ranks better); solving routes are shorter and closer to human ones.
+- Time spread: `time_mean` and any percentile `time_pNN` (e.g. `time_p20`, `time_p80`) on request, over today's players
+  (log-normal; sigma 0.79 for classics and multi-grid layouts, 0.62 with any other rule, from two sources' per-player times). `time_p80` was a one-player spread (1.53x) and is now
+  the population one (about 1.85x). `time` is the median player.
+- Generator: element varieties (kropki colour, XV letter, odd/even) with counts, ranges and caps; the information-budget
+  check uses per-class maximums.
+- `spike` check: a Medium+ puzzle whose 3 hardest steps carry more than 60% of its effort (adjustable, `quality`), as a
+  warning; replaces the old "few band moves in an all-singles solve" rule.
+- Cards without `contains` / `issues` skip the technique-list search: about 3x faster for the same band, difficulty and
+  time; the generator screens candidates this way.
+- `alternatives=False` / `--no-alternatives`: skip the search for interchangeable techniques (faster; band, difficulty and
+  time unchanged). The generator screens candidates this way.
+- Faster cards: the search-effort profile stops trials past the shortest refutation and skips unchanged rules; the
+  solution is found once per card.
+- Publishing checks (`issues`, `reject`) are no longer default card fields; ask for them with `fields=[...]`.
+- Docs: the puzzle format (`FORMAT.md`), grade card (`GRADE.md`) and generator spec (`SPEC.md`) are separate
+  documents, each saying how to implement a subset; drawing conventions moved out of the format into `STYLE.md`, variant
+  naming into `NAMING.md`.
+- Drawing: `docs/palette.json` with the default sizes, light and dark themes and the community line colours; reference
+  SVG renderer `tools/render_svg.py`.
+
+## 1.0.0rc1
+
+First public release.
+
+- `rate`, `rate_many`, `solve`, `to_export`, `load`: the "sudoku-grade" card (difficulty, time, band, contents, issues /
+  reject; on request time_p80, steps with two explanation levels, Sudoku Explainer-style ratings, describe, symmetry;
+  `fields=[...]` computes only the requested fields) for classic and variant sudoku.
+- Publishing checks (`issues`) with adjustable limits: `quality={"trivial": 0.5, "trial": False}` / `--quality`, the same
+  object the generator spec's `quality` takes.
+- Command line: `pencilmark rate | solve | json | export | fingerprint | describe` (also `python -m pencilmark`).
+- Exchange format: `sudoku-puzzle` format_version 1, read and written, specified in `docs/FORMAT.md` with a JSON Schema (`docs/sudoku-puzzle.schema.json`):
+  every constraint is a rule (houses as `grid` / `box_grid` / `box`, explicit `row` / `column` for bent ones; nothing
+  implied), cells named `r1c1`, a rule
+  vocabulary of families and kinds with exact semantics and default drawings, outside clues anchored by `side`,
+  explicit `negative` rules, strict reading (unknown keys or rule types are refused).
+- `sudoku-spec` generator requests (givens, locked rules and templates, symmetry, `where` card targets, quality,
+  limits); `spec_to_gen` runs what the generator supports and refuses the rest with the reason; showcase specs in
+  `docs/examples/specs/`.
+- Format functions: `dumps` (canonical text), `fingerprint` (content hash), `validate`, `describe` / `rules_text` (variant
+  name and rules from a registry of placement variants and rule families), optional `to_ipuz`, `from_string` / `to_string`
+  (plain and sudokuwiki.org strings), `spec_from_gen` / `spec_to_gen` (the `sudoku-spec` generator request).
+- Cards carry `"format_version": 1` and `"grader": {"name": "pencilmark", "version": ...}`.
+- One engine form per mechanic: renban / between / zipper / region-sum constraints as lines, jigsaw pieces as boxes,
+  numbered pair clues (difference / sum / product / ratio, mathrax) as 2-cell tables, duplicated houses merged, global entropy and quadruple clues as named rules for
+  every importer (docs/ENGINE.md).
+- Puzzle generator (`pencilmark.gen`) with band, difficulty, technique and rule-element targets.
+- Puzzle importers (`pencilmark.sources`) for SudokuPad, f-puzzles, penpa-edit and Logic Masters links.
+- C++ engine built with pybind11; OR-Tools is optional (`pencilmark[verify]`).
+- No guessing by default: where no technique applies, the engine proves an elimination by full search (Trial and error,
+  band Extreme), so every uniquely solvable puzzle gets a band; `allow_guessing=True` / `--allow-guessing` guesses there
+  instead (band Unknown).
+- Bands: forcing chains / nets, Nishio, pattern overlay and trial and error are Extreme; bounded case splits (either
+  way, what if, short trial) and ALS chains / Death Blossom are Very Hard.

pencilmark-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pencilmark contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pencilmark-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE README.md CHANGELOG.md setup.py
+recursive-include csrc *.cpp *.hpp
+recursive-include src/pencilmark/data *.json *.csv
+recursive-include docs *.md *.json
+recursive-include tests *.py *.json
+global-exclude __pycache__ *.py[cod] *.so

pencilmark-1.0.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: pencilmark
+Version: 1.0.0
+Summary: Human-like difficulty grader, solver and generator for classic and variant sudoku
+Author: pencilmark contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/silly-puppyy/pencilmark
+Project-URL: Documentation, https://silly-puppyy.github.io/pencilmark/
+Project-URL: Source, https://github.com/silly-puppyy/pencilmark
+Project-URL: Issues, https://github.com/silly-puppyy/pencilmark/issues
+Project-URL: Changelog, https://github.com/silly-puppyy/pencilmark/blob/main/CHANGELOG.md
+Keywords: sudoku,puzzle,difficulty,grader,solver,generator
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: C++
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lzstring>=1.0.4
+Provides-Extra: verify
+Requires-Dist: ortools>=9.8; extra == "verify"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: jsonschema>=4.18; extra == "test"
+Dynamic: license-file
+
+# pencilmark
+
+[![PyPI](https://img.shields.io/pypi/v/pencilmark?include_prereleases)](https://pypi.org/project/pencilmark/)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)](https://pypi.org/project/pencilmark/)
+[![Wheels](https://github.com/silly-puppyy/pencilmark/actions/workflows/wheels.yml/badge.svg)](https://github.com/silly-puppyy/pencilmark/actions/workflows/wheels.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-silly--puppyy.github.io-blue)](https://silly-puppyy.github.io/pencilmark/)
+
+pencilmark rates sudoku puzzles the way a human solver experiences them. It solves a puzzle step by step with human
+techniques, easiest first, and reports how hard it is, how long it takes, which band it belongs to and which techniques
+you need. It works for classic sudoku of any standard size and for many variants (killer, thermo, arrow, kropki, XV,
+sandwich, multi-grid boards and more). It also solves puzzles, checks uniqueness, imports puzzles from [SudokuPad](https://sudokupad.app/),
+[f-puzzles](https://www.f-puzzles.com/), [penpa-edit](https://swaroopg92.github.io/penpa-edit/) and [Logic Masters](https://logic-masters.de/) links, and generates new puzzles to a target band or difficulty.
+
+The engine is written in C++ ([pybind11](https://github.com/pybind/pybind11)). Results are deterministic: the same puzzle always gets the same card.
+
+## Install
+
+```
+pip install pencilmark
+pip install "pencilmark[verify]"      # optional: OR-Tools CP-SAT as a fallback uniqueness checker
+```
+
+Python 3.10 or newer. Building from source needs a C++17 compiler.
+
+## Quick start
+
+```python
+import pencilmark
+
+card = pencilmark.rate("....4.8.3.6...8..29.86.5..1235.........7..2.........96..2......8.12..7...9.......")
+card["band"], card["difficulty"], card["time"]          # ('Hard', 5.9, 10.7)
+
+card  = pencilmark.rate(puzzle, steps=True)             # add the step-by-step solve with explanations
+cards = pencilmark.rate_many(puzzles, jobs=4)           # several puzzles in parallel, input order kept
+sol   = pencilmark.solve(puzzle)                        # list of digits; raises NotUnique / NoSolution
+exp   = pencilmark.to_export(puzzle, title="My puzzle") # "sudoku-puzzle" exchange format (docs/FORMAT.md)
+```
+
+A puzzle can be a classic string (`.` or `0` for blanks), a `sudoku-puzzle` dict, a puzzle JSON dict or string, or a
+path to a `.json` file.
+
+Command line:
+
+```
+$ echo '....4.8.3.6...8..29.86.5..1235.........7..2.........96..2......8.12..7...9.......' | pencilmark rate - --report
+#1  Hard  -  difficulty 5.9  -  time 10.7 min
+   contains: Naked Pair (or Hidden Pair), X-Wing (or 2-String Kite / Simple Colouring / Short chain in the head)
+
+pencilmark rate puzzles.txt --json        # full card per line (python -m pencilmark works too)
+pencilmark solve puzzles.txt              # the solution, or 'not unique' / 'no solution'
+```
+
+More in [docs/USAGE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/USAGE.md).
+
+## The card
+
+`rate` returns a dict (format `"sudoku-grade"`) with these fields by default (`grader`, `format`, `format_version` are
+always there); `rate(puzzle, fields=[...])` / `--fields` asks for others by their key names, and only requested fields
+are computed ([docs/GRADE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/GRADE.md)):
+
+| Field | Meaning |
+|---|---|
+| `difficulty` | how hard each step feels, continuous, above 0 (a nearly finished grid is about 0.2), no ceiling; a typical newspaper medium is about 5 |
+| `time` | expected minutes for the median player (on request `time_mean` or any percentile `time_pNN`, e.g. `time_p80`: 80% of players finish within it) |
+| `band` | Very Easy, Easy, Medium, Hard, Very Hard, Expert, Extreme; `"Unknown"` when guessing was allowed and used, or `max_seconds` passed (on request `band_index` 0..6) |
+| `contains` | techniques met going easy to hard: `code`, `chip`, `name`, `band`, `uses`, `alternatives`; with `stopped_at_step` when human logic ran out |
+| on request | `issues` / `reject` (publishing checks, below), `time_mean` / `time_pNN`, `steps` (technique, placement `r2c8=3` or eliminations `r4c5#7`; `explain="notation"` / `"short"` / `"teach"` adds explanations, from `X-Wing: 3 r58 c68 => r679c6<>3` to a short lesson), `se`, `band_index`, `describe`, `symmetry` |
+
+A chip like `XWG/KTE/SCL` means any one of those techniques gets you through at that point.
+
+Publishing checks are off unless you ask for them. They flag puzzles a publisher would usually not pick: a difficulty
+spike, a rule that is never used, too many givens, ... (`code`, `severity` reject / warning, `text`, and `rules`: the
+offending rules' indices in the exported puzzle); `reject` is true when any issue is a reject. Each check's limit is
+adjustable:
+
+```python
+card = pencilmark.rate(puzzle, fields=["difficulty", "band", "issues", "reject"], quality={"trivial": {"limit": 0.4}, "trial": {"severity": "off"}})
+```
+
+Guessing is off by default: where no technique applies, the engine proves an elimination by full search (Trial and
+error, band Extreme), so every uniquely solvable puzzle gets a band. `allow_guessing=True` (CLI `--allow-guessing`) lets it
+guess there instead, which is faster on the hardest puzzles; the card then says Unknown, with
+`stopped_at_step`. With `max_seconds` set, the whole call is capped and the card
+says `completed: false` if the limit passed. A puzzle without exactly one solution has no card: `rate` raises `NotUnique` /
+`NoSolution`.
+
+## Exchange format
+
+`to_export` writes, and every entry point reads, the `"sudoku-puzzle"` format, **format_version 1**, specified in
+[docs/FORMAT.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/FORMAT.md) (JSON Schema: [docs/sudoku-puzzle.schema.json](https://github.com/silly-puppyy/pencilmark/blob/main/docs/sudoku-puzzle.schema.json)):
+
+```json
+{"format": "sudoku-puzzle", "format_version": 1,
+ "meta": {"title": "Heartstring", "author": "...", "source": "example.org", "type": "Killer Sudoku"},
+ "board": {"rows": 9, "cols": 9},
+ "digits": 9,
+ "givens":   [0, 0, 5, 4, 0, ...],
+ "solution": [6, 1, 5, 4, 2, ...],
+ "rules": [
+  {"type": "box_grid", "origin": "r1c1", "box": [3, 3]},
+  {"type": "cage", "sum": 15, "cells": ["r1c4", "r1c5", "r2c4"]},
+  {"type": "edge", "kind": "kropki", "color": "white", "cells": ["r5c5", "r5c6"]}]}
+```
+
+- Every constraint is a rule, houses included: a `grid` gives a sudoku grid's rows and columns, a `box_grid` adds its
+  regular boxes, so a classic is one `box_grid` and a jigsaw is a `grid` plus `box` rules. Nothing is implied. Cells are
+  named `r{row}c{col}`, 1-based.
+  `givens`: `0` = empty, `null` = no cell (multi-grid gaps).
+- Each rule has one exact meaning and a default drawing, so a renderer needs nothing else; `style` and `decorations`
+  are cosmetic only. `meta` is free-form information that never changes solving.
+- Strict reading: an unknown key or rule type makes the reader refuse the file (`FormatError`) instead of dropping a
+  rule.
+- `pencilmark.dumps` writes the canonical text (one grid row per line, one rule per line); `pencilmark.fingerprint`
+  gives a content hash that ignores metadata and styling; `pencilmark.describe` names the variant and lists its rules.
+
+### Other formats
+
+For convenience pencilmark also reads and writes [sudokuwiki.org](https://www.sudokuwiki.org/) packed strings, text grids and [ipuz](http://www.ipuz.org/), reads pencil-mark grids, and loads SudokuPad,
+f-puzzles, [Penpa](https://swaroopg92.github.io/penpa-edit/)+ and Logic Masters links. None of these is needed to use the `sudoku-puzzle` format; see
+[docs/INTEROP.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/INTEROP.md). How rules map onto the engine, and how to add one, is in
+[docs/ENGINE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/ENGINE.md).
+
+## Supported rules
+
+Classic sudoku from 4x4 to 25x25, irregular (jigsaw) regions, diagonals and extra regions, multi-grid layouts (samurai,
+twodoku, butterfly, windmill and more), killer cages, little killers, sandwich, X-sums, skyscrapers, frame sums,
+arrows, thermometers (normal and slow), German and Dutch whispers, renban, region-sum, palindrome, zipper, between,
+entropic, modular and parity lines, kropki, XV, greater-than, difference / ratio dots, anti-knight, anti-king,
+non-consecutive, odd / even, low / high, Rossini, Vudoku, equal sums, counting rules, and given candidates (Sukaku).
+Rules that cannot be translated exactly are refused, never dropped silently.
+
+## Generator
+
+```python
+r = pencilmark.generate({"format": "sudoku-spec", "format_version": 1,
+                         "board": {"rows": 9, "cols": 9}, "digits": 9,
+                         "rules": [{"type": "box_grid", "origin": "r1c1", "box": [3, 3]}],
+                         "where": {"band": "Hard"}})
+r["puzzle"], r["card"], r["info"]       # sudoku-puzzle, its card, run details
+```
+
+The request is a `sudoku-spec` ([docs/SPEC.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/SPEC.md)).
+
+Targets: band, difficulty range, required techniques, symmetry, given counts, and rule elements (cages, thermos,
+whispers, renban, between lines, arrows, kropki, XV, parity). Every result is checked for uniqueness. Multi-grid boards
+are not generated.
+
+## Puzzle sources
+
+```python
+from pencilmark import sources
+pj = sources.load("https://sudokupad.app/...")      # SudokuPad, f-puzzles, penpa-edit, Logic Masters, short links
+card = pencilmark.rate(pj)
+```
+
+Loaders that fetch pages identify themselves, obey robots.txt and pause between requests. Override the user agent with
+the `PENCILMARK_UA` environment variable.
+
+## Limitations
+
+- Bands and difficulty measure different things. The band is the hardest technique a puzzle needs; difficulty is how
+  hard it is overall. A puzzle that needs one X-Wing (Hard) is often easier than a long Medium one, and solvers agree
+  (docs/PHILOSOPHY.md). This is by design, not an error.
+- Difficulty and time are models fitted to human solving data. Differences under one point of difficulty are not
+  meaningful, and a single solve can vary a lot from the predicted time.
+- Bands depend on the technique catalogue; a puzzle that needs a technique the engine does not have is solved with
+  Trial and error at that point and rated Extreme.
+- Very hard puzzles with many-cell rules (killers, arrows, palindromes, thermos) can take minutes while the contents list
+  is minimised; use `max_seconds` to cap it (the card then says `completed: false`).
+- The Sudoku Explainer-style ratings (`se=True`) are approximate and meaningful for classic sudoku only.
+
+## Benchmark
+
+On a frozen held-out set of 7,623 puzzles with real human solve data from seven sources, pencilmark's difficulty ranks
+puzzles by human solve time at Spearman 0.61 to 0.80 within each group, closer than four established graders on the same
+classics. Details: [docs/BENCHMARK.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/BENCHMARK.md).
+
+## Known issues
+
+Being worked on after 1.0:
+
+- **Speed.** Grading takes a median 0.5 s per puzzle, but the slowest few percent take 10 s to minutes. On the
+  benchmark's classics: pencilmark 0.04 s, Rangsk's solver 0.09 s, Sudoku Explainer and HoDoKu under a millisecond (they do
+  not model human solving); on variants: pencilmark 0.49 s, Rangsk's solver 0.13 s. Use `max_seconds` to bound a call.
+- **Generator speed and range.** About 20-70 s per puzzle that meets a spec (HoDoKu: 0.05-1 s), and classic Extreme puzzles
+  are not reached within the default 120 s. A maximum on the givens count is not always enforced.
+- **Variants on one scale.** On classics, difficulty matches established ratings of the same puzzles; across variant
+  types the same difficulty does not yet mean the same experience (puzzle types differ by about 2 points on average, and
+  variants often score above the classic range of their band). Time is most off for the same reason (about 1.4x per
+  puzzle type).
+- **The ends of the scale.** Between about 2 and 8, each point of difficulty means about 20-40% more solving time per
+  cell. Above about 8 a point is worth less time (5-15% on three sources). Below 2 the scale is gentler (about the square root of
+  effort, so it never goes negative); there it predicts solve times about 1.5% worse than a pure log scale would.
+- **Uniqueness on some killers.** A few large killers can raise `Undecided` without OR-Tools (`pip install
+  "pencilmark[verify]"`) although human logic solves them.
+
+## License
+
+MIT, see [LICENSE](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE).
+
+pencilmark was written with [Claude](https://claude.ai).

pencilmark-1.0.0/README.md

@@ -0,0 +1,202 @@
+# pencilmark
+
+[![PyPI](https://img.shields.io/pypi/v/pencilmark?include_prereleases)](https://pypi.org/project/pencilmark/)
+[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)](https://pypi.org/project/pencilmark/)
+[![Wheels](https://github.com/silly-puppyy/pencilmark/actions/workflows/wheels.yml/badge.svg)](https://github.com/silly-puppyy/pencilmark/actions/workflows/wheels.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-silly--puppyy.github.io-blue)](https://silly-puppyy.github.io/pencilmark/)
+
+pencilmark rates sudoku puzzles the way a human solver experiences them. It solves a puzzle step by step with human
+techniques, easiest first, and reports how hard it is, how long it takes, which band it belongs to and which techniques
+you need. It works for classic sudoku of any standard size and for many variants (killer, thermo, arrow, kropki, XV,
+sandwich, multi-grid boards and more). It also solves puzzles, checks uniqueness, imports puzzles from [SudokuPad](https://sudokupad.app/),
+[f-puzzles](https://www.f-puzzles.com/), [penpa-edit](https://swaroopg92.github.io/penpa-edit/) and [Logic Masters](https://logic-masters.de/) links, and generates new puzzles to a target band or difficulty.
+
+The engine is written in C++ ([pybind11](https://github.com/pybind/pybind11)). Results are deterministic: the same puzzle always gets the same card.
+
+## Install
+
+```
+pip install pencilmark
+pip install "pencilmark[verify]"      # optional: OR-Tools CP-SAT as a fallback uniqueness checker
+```
+
+Python 3.10 or newer. Building from source needs a C++17 compiler.
+
+## Quick start
+
+```python
+import pencilmark
+
+card = pencilmark.rate("....4.8.3.6...8..29.86.5..1235.........7..2.........96..2......8.12..7...9.......")
+card["band"], card["difficulty"], card["time"]          # ('Hard', 5.9, 10.7)
+
+card  = pencilmark.rate(puzzle, steps=True)             # add the step-by-step solve with explanations
+cards = pencilmark.rate_many(puzzles, jobs=4)           # several puzzles in parallel, input order kept
+sol   = pencilmark.solve(puzzle)                        # list of digits; raises NotUnique / NoSolution
+exp   = pencilmark.to_export(puzzle, title="My puzzle") # "sudoku-puzzle" exchange format (docs/FORMAT.md)
+```
+
+A puzzle can be a classic string (`.` or `0` for blanks), a `sudoku-puzzle` dict, a puzzle JSON dict or string, or a
+path to a `.json` file.
+
+Command line:
+
+```
+$ echo '....4.8.3.6...8..29.86.5..1235.........7..2.........96..2......8.12..7...9.......' | pencilmark rate - --report
+#1  Hard  -  difficulty 5.9  -  time 10.7 min
+   contains: Naked Pair (or Hidden Pair), X-Wing (or 2-String Kite / Simple Colouring / Short chain in the head)
+
+pencilmark rate puzzles.txt --json        # full card per line (python -m pencilmark works too)
+pencilmark solve puzzles.txt              # the solution, or 'not unique' / 'no solution'
+```
+
+More in [docs/USAGE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/USAGE.md).
+
+## The card
+
+`rate` returns a dict (format `"sudoku-grade"`) with these fields by default (`grader`, `format`, `format_version` are
+always there); `rate(puzzle, fields=[...])` / `--fields` asks for others by their key names, and only requested fields
+are computed ([docs/GRADE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/GRADE.md)):
+
+| Field | Meaning |
+|---|---|
+| `difficulty` | how hard each step feels, continuous, above 0 (a nearly finished grid is about 0.2), no ceiling; a typical newspaper medium is about 5 |
+| `time` | expected minutes for the median player (on request `time_mean` or any percentile `time_pNN`, e.g. `time_p80`: 80% of players finish within it) |
+| `band` | Very Easy, Easy, Medium, Hard, Very Hard, Expert, Extreme; `"Unknown"` when guessing was allowed and used, or `max_seconds` passed (on request `band_index` 0..6) |
+| `contains` | techniques met going easy to hard: `code`, `chip`, `name`, `band`, `uses`, `alternatives`; with `stopped_at_step` when human logic ran out |
+| on request | `issues` / `reject` (publishing checks, below), `time_mean` / `time_pNN`, `steps` (technique, placement `r2c8=3` or eliminations `r4c5#7`; `explain="notation"` / `"short"` / `"teach"` adds explanations, from `X-Wing: 3 r58 c68 => r679c6<>3` to a short lesson), `se`, `band_index`, `describe`, `symmetry` |
+
+A chip like `XWG/KTE/SCL` means any one of those techniques gets you through at that point.
+
+Publishing checks are off unless you ask for them. They flag puzzles a publisher would usually not pick: a difficulty
+spike, a rule that is never used, too many givens, ... (`code`, `severity` reject / warning, `text`, and `rules`: the
+offending rules' indices in the exported puzzle); `reject` is true when any issue is a reject. Each check's limit is
+adjustable:
+
+```python
+card = pencilmark.rate(puzzle, fields=["difficulty", "band", "issues", "reject"], quality={"trivial": {"limit": 0.4}, "trial": {"severity": "off"}})
+```
+
+Guessing is off by default: where no technique applies, the engine proves an elimination by full search (Trial and
+error, band Extreme), so every uniquely solvable puzzle gets a band. `allow_guessing=True` (CLI `--allow-guessing`) lets it
+guess there instead, which is faster on the hardest puzzles; the card then says Unknown, with
+`stopped_at_step`. With `max_seconds` set, the whole call is capped and the card
+says `completed: false` if the limit passed. A puzzle without exactly one solution has no card: `rate` raises `NotUnique` /
+`NoSolution`.
+
+## Exchange format
+
+`to_export` writes, and every entry point reads, the `"sudoku-puzzle"` format, **format_version 1**, specified in
+[docs/FORMAT.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/FORMAT.md) (JSON Schema: [docs/sudoku-puzzle.schema.json](https://github.com/silly-puppyy/pencilmark/blob/main/docs/sudoku-puzzle.schema.json)):
+
+```json
+{"format": "sudoku-puzzle", "format_version": 1,
+ "meta": {"title": "Heartstring", "author": "...", "source": "example.org", "type": "Killer Sudoku"},
+ "board": {"rows": 9, "cols": 9},
+ "digits": 9,
+ "givens":   [0, 0, 5, 4, 0, ...],
+ "solution": [6, 1, 5, 4, 2, ...],
+ "rules": [
+  {"type": "box_grid", "origin": "r1c1", "box": [3, 3]},
+  {"type": "cage", "sum": 15, "cells": ["r1c4", "r1c5", "r2c4"]},
+  {"type": "edge", "kind": "kropki", "color": "white", "cells": ["r5c5", "r5c6"]}]}
+```
+
+- Every constraint is a rule, houses included: a `grid` gives a sudoku grid's rows and columns, a `box_grid` adds its
+  regular boxes, so a classic is one `box_grid` and a jigsaw is a `grid` plus `box` rules. Nothing is implied. Cells are
+  named `r{row}c{col}`, 1-based.
+  `givens`: `0` = empty, `null` = no cell (multi-grid gaps).
+- Each rule has one exact meaning and a default drawing, so a renderer needs nothing else; `style` and `decorations`
+  are cosmetic only. `meta` is free-form information that never changes solving.
+- Strict reading: an unknown key or rule type makes the reader refuse the file (`FormatError`) instead of dropping a
+  rule.
+- `pencilmark.dumps` writes the canonical text (one grid row per line, one rule per line); `pencilmark.fingerprint`
+  gives a content hash that ignores metadata and styling; `pencilmark.describe` names the variant and lists its rules.
+
+### Other formats
+
+For convenience pencilmark also reads and writes [sudokuwiki.org](https://www.sudokuwiki.org/) packed strings, text grids and [ipuz](http://www.ipuz.org/), reads pencil-mark grids, and loads SudokuPad,
+f-puzzles, [Penpa](https://swaroopg92.github.io/penpa-edit/)+ and Logic Masters links. None of these is needed to use the `sudoku-puzzle` format; see
+[docs/INTEROP.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/INTEROP.md). How rules map onto the engine, and how to add one, is in
+[docs/ENGINE.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/ENGINE.md).
+
+## Supported rules
+
+Classic sudoku from 4x4 to 25x25, irregular (jigsaw) regions, diagonals and extra regions, multi-grid layouts (samurai,
+twodoku, butterfly, windmill and more), killer cages, little killers, sandwich, X-sums, skyscrapers, frame sums,
+arrows, thermometers (normal and slow), German and Dutch whispers, renban, region-sum, palindrome, zipper, between,
+entropic, modular and parity lines, kropki, XV, greater-than, difference / ratio dots, anti-knight, anti-king,
+non-consecutive, odd / even, low / high, Rossini, Vudoku, equal sums, counting rules, and given candidates (Sukaku).
+Rules that cannot be translated exactly are refused, never dropped silently.
+
+## Generator
+
+```python
+r = pencilmark.generate({"format": "sudoku-spec", "format_version": 1,
+                         "board": {"rows": 9, "cols": 9}, "digits": 9,
+                         "rules": [{"type": "box_grid", "origin": "r1c1", "box": [3, 3]}],
+                         "where": {"band": "Hard"}})
+r["puzzle"], r["card"], r["info"]       # sudoku-puzzle, its card, run details
+```
+
+The request is a `sudoku-spec` ([docs/SPEC.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/SPEC.md)).
+
+Targets: band, difficulty range, required techniques, symmetry, given counts, and rule elements (cages, thermos,
+whispers, renban, between lines, arrows, kropki, XV, parity). Every result is checked for uniqueness. Multi-grid boards
+are not generated.
+
+## Puzzle sources
+
+```python
+from pencilmark import sources
+pj = sources.load("https://sudokupad.app/...")      # SudokuPad, f-puzzles, penpa-edit, Logic Masters, short links
+card = pencilmark.rate(pj)
+```
+
+Loaders that fetch pages identify themselves, obey robots.txt and pause between requests. Override the user agent with
+the `PENCILMARK_UA` environment variable.
+
+## Limitations
+
+- Bands and difficulty measure different things. The band is the hardest technique a puzzle needs; difficulty is how
+  hard it is overall. A puzzle that needs one X-Wing (Hard) is often easier than a long Medium one, and solvers agree
+  (docs/PHILOSOPHY.md). This is by design, not an error.
+- Difficulty and time are models fitted to human solving data. Differences under one point of difficulty are not
+  meaningful, and a single solve can vary a lot from the predicted time.
+- Bands depend on the technique catalogue; a puzzle that needs a technique the engine does not have is solved with
+  Trial and error at that point and rated Extreme.
+- Very hard puzzles with many-cell rules (killers, arrows, palindromes, thermos) can take minutes while the contents list
+  is minimised; use `max_seconds` to cap it (the card then says `completed: false`).
+- The Sudoku Explainer-style ratings (`se=True`) are approximate and meaningful for classic sudoku only.
+
+## Benchmark
+
+On a frozen held-out set of 7,623 puzzles with real human solve data from seven sources, pencilmark's difficulty ranks
+puzzles by human solve time at Spearman 0.61 to 0.80 within each group, closer than four established graders on the same
+classics. Details: [docs/BENCHMARK.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/BENCHMARK.md).
+
+## Known issues
+
+Being worked on after 1.0:
+
+- **Speed.** Grading takes a median 0.5 s per puzzle, but the slowest few percent take 10 s to minutes. On the
+  benchmark's classics: pencilmark 0.04 s, Rangsk's solver 0.09 s, Sudoku Explainer and HoDoKu under a millisecond (they do
+  not model human solving); on variants: pencilmark 0.49 s, Rangsk's solver 0.13 s. Use `max_seconds` to bound a call.
+- **Generator speed and range.** About 20-70 s per puzzle that meets a spec (HoDoKu: 0.05-1 s), and classic Extreme puzzles
+  are not reached within the default 120 s. A maximum on the givens count is not always enforced.
+- **Variants on one scale.** On classics, difficulty matches established ratings of the same puzzles; across variant
+  types the same difficulty does not yet mean the same experience (puzzle types differ by about 2 points on average, and
+  variants often score above the classic range of their band). Time is most off for the same reason (about 1.4x per
+  puzzle type).
+- **The ends of the scale.** Between about 2 and 8, each point of difficulty means about 20-40% more solving time per
+  cell. Above about 8 a point is worth less time (5-15% on three sources). Below 2 the scale is gentler (about the square root of
+  effort, so it never goes negative); there it predicts solve times about 1.5% worse than a pure log scale would.
+- **Uniqueness on some killers.** A few large killers can raise `Undecided` without OR-Tools (`pip install
+  "pencilmark[verify]"`) although human logic solves them.
+
+## License
+
+MIT, see [LICENSE](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE).
+
+pencilmark was written with [Claude](https://claude.ai).