pencilmark 1.0.0rc1__tar.gz

pencilmark-1.0.0rc1/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 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.0rc1/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.0rc1/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.0rc1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: pencilmark
+Version: 1.0.0rc1
+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)](https://pypi.org/project/pencilmark/)
+[![Python](https://img.shields.io/pypi/pyversions/pencilmark)](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,
+f-puzzles, penpa-edit and Logic Masters links, and generates new puzzles to a target band or difficulty.
+
+The engine is written in C++ (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"]          # ('Medium', 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  Medium  -  difficulty 5.9  -  time 10.7 min (80% of players within 16.4 min)
+   contains: Naked Pair (or PPR/HPR), X-Wing (or KTE/SCL)
+
+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/FORMAT.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/FORMAT.md) section 11):
+
+| Field | Meaning |
+|---|---|
+| `difficulty` | how hard each step feels, continuous from 0 (one empty cell) with no ceiling; a typical newspaper medium is about 5 |
+| `time` | expected minutes for an average player (`time_p80` on request: 80% of players finish within it) |
+| `band`, `band_index` | Very Easy (0), Easy, Medium, Hard, Very Hard, Extreme (5); `"Unknown"` (null) only with `allow_guessing=True`, when the engine had to guess |
+| `contains` | techniques met going easy to hard: `code`, `chip`, `name`, `band`, `uses`, `alternatives`; with `contains_complete` and `contains_truncated` |
+| `issues`, `reject` | publishing checks such as a difficulty spike or an unused rule (`code`, `severity` reject / warning, `text`, and `rules`: the offending rules' indices in the exported puzzle); `reject` is true when any issue is a reject |
+| on request | `time_p80`, `steps` (technique, placement `r2c8=3` or eliminations `r4c5#7`; `explain="short"` / `"teach"` adds explanations), `se` / `se_diuf`, `describe`, `symmetry` |
+
+A chip like `XWG/KTE/SCL` means any one of those techniques gets you through at that point.
+
+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 `contains_complete: false`
+and `stopped_at_step`. With `max_seconds` set, the contents search is capped and the card
+may say `contains_truncated: true`. 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 packed strings, exports ipuz, and loads SudokuPad,
+f-puzzles, Penpa+ 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
+from pencilmark.gen import generate
+r = generate({"size": 9, "target_band": "Hard", "seed": 1})
+r["puzzle"], r["card"], r["info"]
+```
+
+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
+
+- 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 `contains_truncated: true`).
+- The Sudoku Explainer-style ratings (`se=True`) are approximate and meaningful for classic sudoku only.
+
+## License
+
+MIT, see [LICENSE](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE).
+
+pencilmark was written with [Claude](https://claude.ai).

pencilmark-1.0.0rc1/README.md

@@ -0,0 +1,162 @@
+# pencilmark
+
+[![PyPI](https://img.shields.io/pypi/v/pencilmark)](https://pypi.org/project/pencilmark/)
+[![Python](https://img.shields.io/pypi/pyversions/pencilmark)](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,
+f-puzzles, penpa-edit and Logic Masters links, and generates new puzzles to a target band or difficulty.
+
+The engine is written in C++ (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"]          # ('Medium', 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  Medium  -  difficulty 5.9  -  time 10.7 min (80% of players within 16.4 min)
+   contains: Naked Pair (or PPR/HPR), X-Wing (or KTE/SCL)
+
+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/FORMAT.md](https://github.com/silly-puppyy/pencilmark/blob/main/docs/FORMAT.md) section 11):
+
+| Field | Meaning |
+|---|---|
+| `difficulty` | how hard each step feels, continuous from 0 (one empty cell) with no ceiling; a typical newspaper medium is about 5 |
+| `time` | expected minutes for an average player (`time_p80` on request: 80% of players finish within it) |
+| `band`, `band_index` | Very Easy (0), Easy, Medium, Hard, Very Hard, Extreme (5); `"Unknown"` (null) only with `allow_guessing=True`, when the engine had to guess |
+| `contains` | techniques met going easy to hard: `code`, `chip`, `name`, `band`, `uses`, `alternatives`; with `contains_complete` and `contains_truncated` |
+| `issues`, `reject` | publishing checks such as a difficulty spike or an unused rule (`code`, `severity` reject / warning, `text`, and `rules`: the offending rules' indices in the exported puzzle); `reject` is true when any issue is a reject |
+| on request | `time_p80`, `steps` (technique, placement `r2c8=3` or eliminations `r4c5#7`; `explain="short"` / `"teach"` adds explanations), `se` / `se_diuf`, `describe`, `symmetry` |
+
+A chip like `XWG/KTE/SCL` means any one of those techniques gets you through at that point.
+
+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 `contains_complete: false`
+and `stopped_at_step`. With `max_seconds` set, the contents search is capped and the card
+may say `contains_truncated: true`. 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 packed strings, exports ipuz, and loads SudokuPad,
+f-puzzles, Penpa+ 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
+from pencilmark.gen import generate
+r = generate({"size": 9, "target_band": "Hard", "seed": 1})
+r["puzzle"], r["card"], r["info"]
+```
+
+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
+
+- 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 `contains_truncated: true`).
+- The Sudoku Explainer-style ratings (`se=True`) are approximate and meaningful for classic sudoku only.
+
+## License
+
+MIT, see [LICENSE](https://github.com/silly-puppyy/pencilmark/blob/main/LICENSE).
+
+pencilmark was written with [Claude](https://claude.ai).