pgn-postmortem 0.1.0__tar.gz → 2.0.0__tar.gz

{pgn_postmortem-0.1.0 → pgn_postmortem-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgn-postmortem
-Version: 0.1.0
+Version: 2.0.0
 Summary: Turn a folder of PGN chess games into browsable Markdown post-mortems of every blunder, analyzed locally with Stockfish.
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -22,8 +22,18 @@ should have been punished, and an opening-theory breakdown showing where the gam
 Everything runs locally with [Stockfish](https://stockfishchess.org/), and the output is plain Markdown
 and SVG. There's no account and no server, and the site lives in git.
 
-**[→ Live demo](https://diegoami.github.io/pgn-postmortem/)**: five classic games, from Chigorin–Steinitz
-(1892) to Carlsen–Anand (2014). The same pages are also [browsable on GitHub](examples/docs/index.md).
+**[→ Live demo](https://diegoami.github.io/pgn-postmortem/)**: the library's Wikipedia-style site of five
+classic games, from Chigorin–Steinitz (1892) to Carlsen–Anand (2014), with a "what would you play?"
+question at each critical moment. The Markdown pages this README describes are at the demo's
+[`/markdown/`](https://diegoami.github.io/pgn-postmortem/markdown/), and are also
+[browsable on GitHub](examples/docs/index.md).
+
+**[→ A real collection](https://diegoami.github.io/chessgamescollection/)**: the author's own games, built with
+this library as three separate collections (source in
+[diegoami/chessgamescollection](https://github.com/diegoami/chessgamescollection)):
+[over-the-board games](https://diegoami.github.io/chessgamescollection/otb/) (148),
+[correspondence games](https://diegoami.github.io/chessgamescollection/correspondence/) (1,068) and
+[standard games](https://diegoami.github.io/chessgamescollection/standard/) (264, played online).
 
 <table>
 <tr>
@@ -176,6 +186,25 @@ analyzed.build_site("site/", title="Games of Ada Example")  # the quiz is for th
 
 Quote a `**` pattern so the library, not the shell, expands it. The scripts above are unchanged by it.
 
+### F-1.3 book demo
+
+`examples/book_demo/source/capablanca.pgn` is a five-game Capablanca subset from
+[PGN Mentor's Capablanca collection](https://www.pgnmentor.com/players/Capablanca.zip),
+listed on its [free PGN downloads page](https://www.pgnmentor.com/files.html). The files are
+available for download completely free; the source page does not publish a separate open-source
+license, so the README does not claim one. The checked-in subset is the 1906 Raubitschek game and
+Marshall rounds 1, 2, 5 and 6 from 1909. The Stockfish 19, depth-22 files under
+`examples/book_demo/analyzed/` are derived/analyzed data from that source. This repository's
+distribution policy limits this demo data to non-commercial use. The originally selected Caissabase source remains documented in
+`ROADMAP.md`; its archived page is readable but its 630 MB download was not captured by Wayback.
+
+Build the separate local book demo from the committed analysis without running Stockfish:
+
+```bash
+pgn-postmortem site examples/book_demo/analyzed --player "Capablanca, Jose Raul" \
+  --title "José Raúl Capablanca" --out examples/book_demo/site
+```
+
 Every game the library writes is named `<date>-<id>.pgn` and carries two headers of its own:
 
 - `PostmortemId`, the game's content id;
@@ -282,6 +311,62 @@ The site of the test fixture is committed in [`tests/golden/site/`](tests/golden
 the same site without the reading history in
 [`tests/golden/site-no-history/`](tests/golden/site-no-history/index.html).
 
+### Correcting recorded results
+
+**Optional: nothing is corrected unless you ask.** Reading, `analyze`, `site` and `workspace` never touch
+a result by default.
+
+A source's `Result` is sometimes wrong, a residue of computer analysis: the side with the won position
+recorded as the loser, a draw as a defeat. For games the library analyzed, `correct-results` reads the
+final position (the board first: checkmate, stalemate, insufficient material; else the final `[%eval]`,
+a win for a side with at least 70% winning chances, a draw otherwise) and writes the result it gives into
+the game's `Result` header, keeping the source's value in an `OriginalResult` header. No engine runs.
+
+**The caveat, honestly:** a decisive result in a level position can be genuine (a time forfeit, a
+resignation, an adjudication), and the library cannot tell. So you choose how far it may go and which
+games it must leave alone, every change is listed with its reason, and the original is always kept.
+
+| policy | what it writes |
+|---|---|
+| `all` (default) | the final position's result whenever there is one: a recorded win in a level position becomes a draw |
+| `contradictions` | only a recorded win or loss reversed, or a recorded draw made decisive; never a decisive result made a draw because the position is level, and `*` is left alone |
+| `unrecorded` | only a missing or `*` result (the rule above, written to the file) |
+| `board` | only what the board itself decides (checkmate, stalemate, insufficient material) |
+
+```console tested
+$ pgn-postmortem correct-results analyzed --policy contradictions --dry-run --explain
+Policy: contradictions, threshold 70.
+2013-01-01-30390dba02.pgn: 0-1 -> 1-0 (Ada Example vs. Bert Sample, corrected)
+2013-01-02-545b079385.pgn: kept: policy (1-0, the final position says 1/2-1/2)
+```
+
+`--threshold` (55 to 95, one value) sets the winning chances that make a win, and `--skip-header
+NAME=REGEX` (repeatable) leaves alone the games whose header matches, for example
+`--skip-header 'Termination=(?i)forfeit|time'`. `--dry-run` lists and writes nothing; `--explain` also
+says why each game was kept (`kept: agrees`, `kept: policy`, `kept: skipped`, `kept: no verdict`).
+Running again changes nothing; a narrower policy restores what it would not correct. The game's id and
+file name do not change (the id is computed from the source's result), so analysis is not redone and the
+analyzed copy still matches its source. For new games, `pgn-postmortem analyze ... --correct-results`
+(with `--result-policy`, `--result-threshold`, `--result-skip-header`) does it as each game is analyzed.
+In Python, `correct_results("analyzed/", policy="contradictions", skip=...)`,
+`Collection.correct_results(policy=...)` (in memory) and `analyze(..., correct_results=True)`. In a
+workspace manifest, per collection, in memory only (no file is rewritten):
+
+```toml tested
+[[collection]]
+slug = "otb"
+title = "Over-the-board games"
+inputs = ["analyzed"]
+correct_results = "contradictions"
+```
+
+**For anyone scripting against the output:** `correct-results` and `analyze --correct-results` now
+print a `Policy: NAME, threshold T.` line first (the change lines and the summary are as before).
+
+An article of a corrected game shows a "Source result" row and says the source recorded something else.
+The full reference, with a worked example of each policy, the skip rules, undoing a correction and the
+library API, is in [`docs/result-correction.md`](docs/result-correction.md).
+
 ## Claude Code skill
 
 [`.claude/skills/publish-games`](.claude/skills/publish-games/SKILL.md) is a

{pgn_postmortem-0.1.0 → pgn_postmortem-2.0.0}/README.md

@@ -11,8 +11,18 @@ should have been punished, and an opening-theory breakdown showing where the gam
 Everything runs locally with [Stockfish](https://stockfishchess.org/), and the output is plain Markdown
 and SVG. There's no account and no server, and the site lives in git.
 
-**[→ Live demo](https://diegoami.github.io/pgn-postmortem/)**: five classic games, from Chigorin–Steinitz
-(1892) to Carlsen–Anand (2014). The same pages are also [browsable on GitHub](examples/docs/index.md).
+**[→ Live demo](https://diegoami.github.io/pgn-postmortem/)**: the library's Wikipedia-style site of five
+classic games, from Chigorin–Steinitz (1892) to Carlsen–Anand (2014), with a "what would you play?"
+question at each critical moment. The Markdown pages this README describes are at the demo's
+[`/markdown/`](https://diegoami.github.io/pgn-postmortem/markdown/), and are also
+[browsable on GitHub](examples/docs/index.md).
+
+**[→ A real collection](https://diegoami.github.io/chessgamescollection/)**: the author's own games, built with
+this library as three separate collections (source in
+[diegoami/chessgamescollection](https://github.com/diegoami/chessgamescollection)):
+[over-the-board games](https://diegoami.github.io/chessgamescollection/otb/) (148),
+[correspondence games](https://diegoami.github.io/chessgamescollection/correspondence/) (1,068) and
+[standard games](https://diegoami.github.io/chessgamescollection/standard/) (264, played online).
 
 <table>
 <tr>
@@ -165,6 +175,25 @@ analyzed.build_site("site/", title="Games of Ada Example")  # the quiz is for th
 
 Quote a `**` pattern so the library, not the shell, expands it. The scripts above are unchanged by it.
 
+### F-1.3 book demo
+
+`examples/book_demo/source/capablanca.pgn` is a five-game Capablanca subset from
+[PGN Mentor's Capablanca collection](https://www.pgnmentor.com/players/Capablanca.zip),
+listed on its [free PGN downloads page](https://www.pgnmentor.com/files.html). The files are
+available for download completely free; the source page does not publish a separate open-source
+license, so the README does not claim one. The checked-in subset is the 1906 Raubitschek game and
+Marshall rounds 1, 2, 5 and 6 from 1909. The Stockfish 19, depth-22 files under
+`examples/book_demo/analyzed/` are derived/analyzed data from that source. This repository's
+distribution policy limits this demo data to non-commercial use. The originally selected Caissabase source remains documented in
+`ROADMAP.md`; its archived page is readable but its 630 MB download was not captured by Wayback.
+
+Build the separate local book demo from the committed analysis without running Stockfish:
+
+```bash
+pgn-postmortem site examples/book_demo/analyzed --player "Capablanca, Jose Raul" \
+  --title "José Raúl Capablanca" --out examples/book_demo/site
+```
+
 Every game the library writes is named `<date>-<id>.pgn` and carries two headers of its own:
 
 - `PostmortemId`, the game's content id;
@@ -271,6 +300,62 @@ The site of the test fixture is committed in [`tests/golden/site/`](tests/golden
 the same site without the reading history in
 [`tests/golden/site-no-history/`](tests/golden/site-no-history/index.html).
 
+### Correcting recorded results
+
+**Optional: nothing is corrected unless you ask.** Reading, `analyze`, `site` and `workspace` never touch
+a result by default.
+
+A source's `Result` is sometimes wrong, a residue of computer analysis: the side with the won position
+recorded as the loser, a draw as a defeat. For games the library analyzed, `correct-results` reads the
+final position (the board first: checkmate, stalemate, insufficient material; else the final `[%eval]`,
+a win for a side with at least 70% winning chances, a draw otherwise) and writes the result it gives into
+the game's `Result` header, keeping the source's value in an `OriginalResult` header. No engine runs.
+
+**The caveat, honestly:** a decisive result in a level position can be genuine (a time forfeit, a
+resignation, an adjudication), and the library cannot tell. So you choose how far it may go and which
+games it must leave alone, every change is listed with its reason, and the original is always kept.
+
+| policy | what it writes |
+|---|---|
+| `all` (default) | the final position's result whenever there is one: a recorded win in a level position becomes a draw |
+| `contradictions` | only a recorded win or loss reversed, or a recorded draw made decisive; never a decisive result made a draw because the position is level, and `*` is left alone |
+| `unrecorded` | only a missing or `*` result (the rule above, written to the file) |
+| `board` | only what the board itself decides (checkmate, stalemate, insufficient material) |
+
+```console tested
+$ pgn-postmortem correct-results analyzed --policy contradictions --dry-run --explain
+Policy: contradictions, threshold 70.
+2013-01-01-30390dba02.pgn: 0-1 -> 1-0 (Ada Example vs. Bert Sample, corrected)
+2013-01-02-545b079385.pgn: kept: policy (1-0, the final position says 1/2-1/2)
+```
+
+`--threshold` (55 to 95, one value) sets the winning chances that make a win, and `--skip-header
+NAME=REGEX` (repeatable) leaves alone the games whose header matches, for example
+`--skip-header 'Termination=(?i)forfeit|time'`. `--dry-run` lists and writes nothing; `--explain` also
+says why each game was kept (`kept: agrees`, `kept: policy`, `kept: skipped`, `kept: no verdict`).
+Running again changes nothing; a narrower policy restores what it would not correct. The game's id and
+file name do not change (the id is computed from the source's result), so analysis is not redone and the
+analyzed copy still matches its source. For new games, `pgn-postmortem analyze ... --correct-results`
+(with `--result-policy`, `--result-threshold`, `--result-skip-header`) does it as each game is analyzed.
+In Python, `correct_results("analyzed/", policy="contradictions", skip=...)`,
+`Collection.correct_results(policy=...)` (in memory) and `analyze(..., correct_results=True)`. In a
+workspace manifest, per collection, in memory only (no file is rewritten):
+
+```toml tested
+[[collection]]
+slug = "otb"
+title = "Over-the-board games"
+inputs = ["analyzed"]
+correct_results = "contradictions"
+```
+
+**For anyone scripting against the output:** `correct-results` and `analyze --correct-results` now
+print a `Policy: NAME, threshold T.` line first (the change lines and the summary are as before).
+
+An article of a corrected game shows a "Source result" row and says the source recorded something else.
+The full reference, with a worked example of each policy, the skip rules, undoing a correction and the
+library API, is in [`docs/result-correction.md`](docs/result-correction.md).
+
 ## Claude Code skill
 
 [`.claude/skills/publish-games`](.claude/skills/publish-games/SKILL.md) is a

{pgn_postmortem-0.1.0 → pgn_postmortem-2.0.0}/pgn_postmortem/__init__.py

@@ -18,16 +18,54 @@ The same steps from the command line are ``pgn-postmortem read``,
 
 from pgn_postmortem.analysis import AnalysisReport, EngineFailure, Thresholds, analyze_games
 from pgn_postmortem.collection import CollectedGame, Collection, ReadReport, find_pgn_files
+from pgn_postmortem.results import (
+    POLICIES,
+    CorrectionReport,
+    GameDecision,
+    ResultChange,
+    check_policy,
+    correct_game,
+    correct_results,
+    decided_result,
+    header_skip,
+)
+from pgn_postmortem.selection import (
+    ChapterWeights,
+    SelectionFeatures,
+    SelectionOptions,
+    SelectionWeights,
+    select_chapters,
+)
 from pgn_postmortem.site import SiteReport, build_site, critical_moments, shown_result
+from pgn_postmortem.workspace import (
+    CollectionProfile,
+    Workspace,
+    WorkspaceBuildError,
+    WorkspaceConfigError,
+    WorkspaceReport,
+)
 
-__version__ = "0.1.0"
+__version__ = "2.0.0"
 
 __all__ = [
     "AnalysisReport",
     "CollectedGame",
     "Collection",
+    "CorrectionReport",
+    "ResultChange",
+    "GameDecision",
+    "POLICIES",
+    "check_policy",
+    "header_skip",
+    "correct_game",
+    "correct_results",
+    "decided_result",
     "EngineFailure",
     "ReadReport",
+    "ChapterWeights",
+    "SelectionFeatures",
+    "SelectionOptions",
+    "SelectionWeights",
     "Thresholds",
     "__version__",
     "SiteReport",
@@ -36,4 +74,10 @@ __all__ = [
     "critical_moments",
     "find_pgn_files",
     "shown_result",
+    "select_chapters",
+    "CollectionProfile",
+    "Workspace",
+    "WorkspaceBuildError",
+    "WorkspaceConfigError",
+    "WorkspaceReport",
 ]

{pgn_postmortem-0.1.0 → pgn_postmortem-2.0.0}/pgn_postmortem/analysis.py

@@ -45,7 +45,7 @@ from collections.abc import Callable, Iterable
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 import chess
 import chess.engine
@@ -53,6 +53,9 @@ import chess.pgn
 
 from pgn_postmortem.collection import ANALYSIS_HEADER, CollectedGame, analyzed_ids, format_game
 
+if TYPE_CHECKING:
+    from pgn_postmortem.results import ResultChange
+
 FALLBACK_ENGINE_PATH = "/usr/games/stockfish"  # where Debian and Ubuntu install it, off the default PATH
 
 MATE_SCORE = 100000
@@ -86,6 +89,7 @@ class AnalysisReport:
     analyzed: int = 0
     skipped: int = 0
     written: list[Path] = field(default_factory=list)
+    corrections: list[ResultChange] = field(default_factory=list)  # with ``correct_results``: each result rewritten
 
 
 def default_engine_path() -> str:
@@ -216,6 +220,10 @@ def analyze_games(
     engine_path: str | None = None,
     pv_plies: int = DEFAULT_PV_PLIES,
     thresholds: Thresholds = LICHESS_THRESHOLDS,
+    correct_results: bool = False,
+    presume_threshold: float | None = None,
+    result_policy: str | None = None,
+    result_skip: Callable[[chess.pgn.Game], bool] | None = None,
     progress: Callable[[int, int, CollectedGame], None] | None = None,
 ) -> AnalysisReport:
     """Analyze every game not yet in ``out_dir`` into ``out_dir/<date>-<id>.pgn``.
@@ -225,7 +233,35 @@ def analyze_games(
     processes run side by side (0: one per CPU). No engine is started when
     there is nothing to analyze. ``progress(done, total, game)`` is called
     after each game.
+
+    With ``correct_results``, each game analyzed now has its ``Result``
+    corrected from its final position before it is written
+    (``pgn_postmortem.results``, ROADMAP.md F-14; ``presume_threshold`` is the
+    winning chances in percent, 70 by default, 55 to 95, checked before
+    anything is written or any engine started). ``result_policy`` (one of
+    ``pgn_postmortem.results.POLICIES``, ``all`` by default) says which
+    corrections are made and ``result_skip(game) -> bool`` leaves a game's
+    result as it is (see ``pgn_postmortem.results``); giving either without
+    ``correct_results`` raises ``ValueError``. A game already analyzed
+    into ``out_dir`` is not touched: ``pgn_postmortem.results.correct_results``
+    corrects those without an engine.
     """
+    from pgn_postmortem.results import (
+        DEFAULT_POLICY,
+        PRESUME_THRESHOLD,
+        check_policy,
+        check_presume_threshold,
+        correct_game,
+    )
+
+    result_threshold = PRESUME_THRESHOLD if presume_threshold is None else presume_threshold
+    if correct_results or presume_threshold is not None:
+        check_presume_threshold(result_threshold)
+    if result_policy is not None:
+        check_policy(result_policy)
+    if not correct_results and (result_policy is not None or result_skip is not None):
+        raise ValueError("result_policy and result_skip only apply with correct_results=True")
+    policy = result_policy or DEFAULT_POLICY
     out_dir = Path(out_dir)
     out_dir.mkdir(parents=True, exist_ok=True)
     done_ids = analyzed_ids(out_dir)
@@ -239,7 +275,7 @@ def analyze_games(
     workers = max(1, min(workers or os.cpu_count() or 1, len(todo)))
     engines: queue.Queue[chess.engine.SimpleEngine] = queue.Queue()
 
-    def run(item: CollectedGame) -> Path:
+    def run(item: CollectedGame) -> tuple[Path, ResultChange | None]:
         engine = engines.get()
         try:
             analyzed = analyze_game(engine, limit, item.game, item.id, pv_plies, thresholds)
@@ -247,11 +283,14 @@ def analyze_games(
             raise EngineFailure(f"the engine failed on {item.origin}: {err}") from err
         finally:
             engines.put(engine)
+        change = None
+        if correct_results:
+            change = correct_game(analyzed, result_threshold, item.filename, policy=policy, skip=result_skip)
         path = out_dir / item.filename
         partial = path.with_name(path.name + ".partial")
         partial.write_text(format_game(analyzed), encoding="utf-8")
         os.replace(partial, path)  # a run that is interrupted never leaves a half-written game behind
-        return path
+        return path, change
 
     engine_path = engine_path or default_engine_path()
     try:
@@ -269,7 +308,10 @@ def analyze_games(
             futures = {pool.submit(run, item): item for item in todo}
             try:
                 for done, future in enumerate(as_completed(futures), start=1):
-                    report.written.append(future.result())
+                    path, change = future.result()
+                    report.written.append(path)
+                    if change:
+                        report.corrections.append(change)
                     report.analyzed += 1
                     if progress:
                         progress(done, len(todo), futures[future])
@@ -285,4 +327,5 @@ def analyze_games(
             except ENGINE_ERRORS:
                 pass  # it already died
     report.written.sort()
+    report.corrections.sort(key=lambda change: change.path)
     return report