puzzlekit 0.3.2__tar.gz → 0.3.3__tar.gz

{puzzlekit-0.3.2 → puzzlekit-0.3.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: puzzlekit
-Version: 0.3.2
-Summary: A comprehensive logic puzzle solver (100+) based on Google OR-Tools. e.g., solvers for Nonogram, Slitherlink, Akari, Yajilin, Hitori and Sudoku-variants.
+Version: 0.3.3
+Summary: 100+ logic puzzle solvers on Google OR-Tools (e.g., yajilin, slitherlink, nonogram), with bidirectional conversion between puzz.link and Penpa+ URLs for supported genres (shared IR).
 Author-email: SmilingWayne <xiaoxiaowayne@gmail.com>
 License: MIT License
         
@@ -28,7 +28,7 @@ License: MIT License
 Project-URL: Homepage, https://github.com/SmilingWayne/PuzzleSolver
 Project-URL: Repository, https://github.com/SmilingWayne/PuzzleSolver
 Project-URL: Issues, https://github.com/SmilingWayne/PuzzleSolver/issues
-Keywords: puzzle,solver,logic,cp-sat,efficient,python,nonogram,slitherlink,yajilin,hitori,sudoku,akari
+Keywords: puzzle,solver,logic,cp-sat,python,nonogram,slitherlink,yajilin,sudoku,puzzlink,penpa,url-conversion
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -55,7 +55,7 @@ This repository provides **100+ useful, efficient and problem‑specific solvers
 
 For simplicity, the dataset is removed to [puzzlekit-dataset](https://github.com/SmilingWayne/puzzlekit-dataset) repo. The structured dataset contains 41k+ instances covering 130+ specific and popular puzzle types (e.g. Nonogram, Slitherlink, Akari, Fillomino, Hitori, Kakuro, Kakuro), mostly from [Raetsel's Janko](https://www.janko.at/Raetsel/index.htm) and [puzz.link](https://puzz.link). The details are listed in the table below. 
 
-
+This repo also provides **bidirectional conversion between [puzz.link](https://puzz.link) and [Penpa+](https://swaroopg92.github.io/penpa-edit/) puzzle URLs** for supported genres (19 for now) via a shared intermediate representation. puzz.link-like links from common mirrors (e.g., `pzplus.tck.mn`, `pzv.jp`) are also accepted.
 
 <details>
   <summary><strong>Table of puzzles, datasets and solvers.</strong></summary>
@@ -215,6 +215,37 @@ For simplicity, the dataset is removed to [puzzlekit-dataset](https://github.com
 
 </details>
 
+<details>
+<summary><strong>Supported puzzle types for URL interchange</strong>
+</summary>
+
+> (canonical IR name, puzz.link token, aliases, Penpa genre tag)
+
+| Canonical (IR) | puzz.link token | puzz.link aliases               | Penpa genre tag       |
+| -------------- | --------------- | ------------------------------- | --------------------- |
+| `aqre`         | `aqre`          | aqre                            | `aqre`                |
+| `ayeheya`      | `ayeheya`       | ayeheya                         | `ayeheya (ekawayeh)`  |
+| `castle`       | `castle`        | castle                          | `castlewall`          |
+| `country`      | `country`       | country                         | `country road`        |
+| `hebi`         | `hebi`          | hebi, snakes                    | `hebi-ichigo`         |
+| `heyawake`     | `heyawake`      | heyawake, heyawacky, heyawack   | `heyawake`            |
+| `kurochute`    | `kurochute`     | kurochute, kuroshuto, kurochuto | `kurochute`           |
+| `kurodoko`     | `kurodoko`      | kurodoko                        | `kurodoko`            |
+| `kurotto`      | `kurotto`       | kurotto                         | `kurotto`             |
+| `masyu`        | `masyu`         | masyu, mashu, pearl             | `masyu`               |
+| `moonsun`      | `moonsun`       | moonsun                         | `moon or sun`         |
+| `nonogram`     | `nonogram`      | nonogram                        | `nonogram`            |
+| `nurikabe`     | `nurikabe`      | nurikabe                        | `nurikabe`            |
+| `nurimisaki`   | `nurimisaki`    | nurimisaki                      | `nurimisaki`          |
+| `shikaku`      | `shikaku`       | shikaku                         | `shikaku`             |
+| `shimaguni`    | `shimaguni`     | shimaguni                       | `shimaguni (islands)` |
+| `slitherlink`  | `slither`       | slitherlink                     | `slitherlink`         |
+| `stostone`     | `stostone`      | stostone                        | `stostone`            |
+| `yajilin`      | `yajilin`       | yajilin, yajirin                | `yajilin`             |
+
+</details>
+
+
 
 <details>
   <summary><strong>Gallery of some puzzles (not complete!)</strong></summary>
@@ -291,6 +322,33 @@ python scripts/benchmark.py -a
 
 Currently it will take ~30 min to solve all 30k+ instances available.
 
+---
+
+If you want to try the bi-directional conversion between penpa+ and puzz.link, follow the quick tour:
+
+
+```python
+import puzzlekit
+
+# 1st method
+ir = puzzlekit.decode("https://puzz.link/p?slither/10/10/g188227cl1dg367bdcg3ddgbhdgd1agbd760dg2cl633661d")
+penpa_url = puzzlekit.encode(ir, "penpa")
+print(penpa_url)
+# get:
+# https://swaroopg92.github.io/penpa-edit/#m=edit&p=7VdtT9swEP7Or0...
+
+
+# 2nd method (recommend)
+penpa_url = "YOUR_PENPA_URL" # both full URL or `m=edit&p=...` are okay
+puzzlink_url = puzzlekit.convert(penpa_url, "puzzlink")
+print(puzzlink_url)
+# get:
+# https://puzz.link/p?slither/10/10/b86ag68dg127bg62aldg8dad8bgdl26dg722cg68dg88b3
+```
+
+See also `scripts/quick_start.py` for a runnable sample.
+
+
 ## Roadmap
 
 - [x] 130+ Puzzle Solvers & 40k+ Dataset.

puzzlekit-0.3.2/src/puzzlekit.egg-info/PKG-INFO → puzzlekit-0.3.3/README.md

@@ -1,61 +1,10 @@
-Metadata-Version: 2.4
-Name: puzzlekit
-Version: 0.3.2
-Summary: A comprehensive logic puzzle solver (100+) based on Google OR-Tools. e.g., solvers for Nonogram, Slitherlink, Akari, Yajilin, Hitori and Sudoku-variants.
-Author-email: SmilingWayne <xiaoxiaowayne@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 SmilingWayne
-        
-        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.
-        
-Project-URL: Homepage, https://github.com/SmilingWayne/PuzzleSolver
-Project-URL: Repository, https://github.com/SmilingWayne/PuzzleSolver
-Project-URL: Issues, https://github.com/SmilingWayne/PuzzleSolver/issues
-Keywords: puzzle,solver,logic,cp-sat,efficient,python,nonogram,slitherlink,yajilin,hitori,sudoku,akari
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Games/Entertainment :: Puzzle Games
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy
-Requires-Dist: ortools>=9.6
-Requires-Dist: matplotlib
-Requires-Dist: typeguard
-Dynamic: license-file
-
 # Puzzle Kit
 
 This repository provides **100+ useful, efficient and problem‑specific solvers** for a variety of **logic puzzles**. The underlying solving engine is the open‑source Google [OR-Tools](https://developers.google.cn/optimization) CP-SAT solver. For more details of puzzles and their input format, you can refer to [docs of puzzlekit](https://smilingwayne.github.io/PuzzleSolver/).
 
 For simplicity, the dataset is removed to [puzzlekit-dataset](https://github.com/SmilingWayne/puzzlekit-dataset) repo. The structured dataset contains 41k+ instances covering 130+ specific and popular puzzle types (e.g. Nonogram, Slitherlink, Akari, Fillomino, Hitori, Kakuro, Kakuro), mostly from [Raetsel's Janko](https://www.janko.at/Raetsel/index.htm) and [puzz.link](https://puzz.link). The details are listed in the table below. 
 
-
+This repo also provides **bidirectional conversion between [puzz.link](https://puzz.link) and [Penpa+](https://swaroopg92.github.io/penpa-edit/) puzzle URLs** for supported genres (19 for now) via a shared intermediate representation. puzz.link-like links from common mirrors (e.g., `pzplus.tck.mn`, `pzv.jp`) are also accepted.
 
 <details>
   <summary><strong>Table of puzzles, datasets and solvers.</strong></summary>
@@ -215,6 +164,37 @@ For simplicity, the dataset is removed to [puzzlekit-dataset](https://github.com
 
 </details>
 
+<details>
+<summary><strong>Supported puzzle types for URL interchange</strong>
+</summary>
+
+> (canonical IR name, puzz.link token, aliases, Penpa genre tag)
+
+| Canonical (IR) | puzz.link token | puzz.link aliases               | Penpa genre tag       |
+| -------------- | --------------- | ------------------------------- | --------------------- |
+| `aqre`         | `aqre`          | aqre                            | `aqre`                |
+| `ayeheya`      | `ayeheya`       | ayeheya                         | `ayeheya (ekawayeh)`  |
+| `castle`       | `castle`        | castle                          | `castlewall`          |
+| `country`      | `country`       | country                         | `country road`        |
+| `hebi`         | `hebi`          | hebi, snakes                    | `hebi-ichigo`         |
+| `heyawake`     | `heyawake`      | heyawake, heyawacky, heyawack   | `heyawake`            |
+| `kurochute`    | `kurochute`     | kurochute, kuroshuto, kurochuto | `kurochute`           |
+| `kurodoko`     | `kurodoko`      | kurodoko                        | `kurodoko`            |
+| `kurotto`      | `kurotto`       | kurotto                         | `kurotto`             |
+| `masyu`        | `masyu`         | masyu, mashu, pearl             | `masyu`               |
+| `moonsun`      | `moonsun`       | moonsun                         | `moon or sun`         |
+| `nonogram`     | `nonogram`      | nonogram                        | `nonogram`            |
+| `nurikabe`     | `nurikabe`      | nurikabe                        | `nurikabe`            |
+| `nurimisaki`   | `nurimisaki`    | nurimisaki                      | `nurimisaki`          |
+| `shikaku`      | `shikaku`       | shikaku                         | `shikaku`             |
+| `shimaguni`    | `shimaguni`     | shimaguni                       | `shimaguni (islands)` |
+| `slitherlink`  | `slither`       | slitherlink                     | `slitherlink`         |
+| `stostone`     | `stostone`      | stostone                        | `stostone`            |
+| `yajilin`      | `yajilin`       | yajilin, yajirin                | `yajilin`             |
+
+</details>
+
+
 
 <details>
   <summary><strong>Gallery of some puzzles (not complete!)</strong></summary>
@@ -291,6 +271,33 @@ python scripts/benchmark.py -a
 
 Currently it will take ~30 min to solve all 30k+ instances available.
 
+---
+
+If you want to try the bi-directional conversion between penpa+ and puzz.link, follow the quick tour:
+
+
+```python
+import puzzlekit
+
+# 1st method
+ir = puzzlekit.decode("https://puzz.link/p?slither/10/10/g188227cl1dg367bdcg3ddgbhdgd1agbd760dg2cl633661d")
+penpa_url = puzzlekit.encode(ir, "penpa")
+print(penpa_url)
+# get:
+# https://swaroopg92.github.io/penpa-edit/#m=edit&p=7VdtT9swEP7Or0...
+
+
+# 2nd method (recommend)
+penpa_url = "YOUR_PENPA_URL" # both full URL or `m=edit&p=...` are okay
+puzzlink_url = puzzlekit.convert(penpa_url, "puzzlink")
+print(puzzlink_url)
+# get:
+# https://puzz.link/p?slither/10/10/b86ag68dg127bg62aldg8dad8bgdl26dg722cg68dg88b3
+```
+
+See also `scripts/quick_start.py` for a runnable sample.
+
+
 ## Roadmap
 
 - [x] 130+ Puzzle Solvers & 40k+ Dataset.

{puzzlekit-0.3.2 → puzzlekit-0.3.3}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "puzzlekit"
-version = "0.3.2"
-description = "A comprehensive logic puzzle solver (100+) based on Google OR-Tools. e.g., solvers for Nonogram, Slitherlink, Akari, Yajilin, Hitori and Sudoku-variants."
+version = "0.3.3"
+description = "100+ logic puzzle solvers on Google OR-Tools (e.g., yajilin, slitherlink, nonogram), with bidirectional conversion between puzz.link and Penpa+ URLs for supported genres (shared IR)."
 readme = "README.md"
 requires-python = ">=3.10"
 authors = [{name = "SmilingWayne", email = "xiaoxiaowayne@gmail.com"}]
 license = {file = "LICENSE"}
-keywords = ["puzzle", "solver", "logic", "cp-sat", "efficient", "python", "nonogram", "slitherlink", "yajilin", "hitori", "sudoku", "akari"]
+keywords = ["puzzle", "solver", "logic", "cp-sat", "python", "nonogram", "slitherlink", "yajilin", "sudoku", "puzzlink", "penpa", "url-conversion"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

puzzlekit-0.3.3/src/puzzlekit/__init__.py

@@ -0,0 +1,224 @@
+from typing import Dict, Any, Optional, Union
+from puzzlekit.solvers import get_solver_class
+from puzzlekit.parsers.registry import get_parser 
+from puzzlekit.formats.base import PuzzleInstance
+from puzzlekit.formats.puzzlink_converter import PuzzlinkConverter
+from puzzlekit.formats.penpa_converter import (
+    PenpaConverter,
+    PENPA_PREFIX,
+    PENPA_URLPREFIX,
+    PenpaDecodeError,
+)
+
+
+_FORMAT_ALIASES = {
+    "puzzlink": "puzzlink",
+    "pzl": "puzzlink",
+    "penpa": "penpa",
+    "ppa": "penpa",
+    "ir": "ir",
+    "instance": "ir",
+    "puzzleinstance": "ir",
+}
+
+
+def _normalize_format_name(name: str) -> str:
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("Format name must be a non-empty string.")
+    key = name.strip().lower()
+    if key not in _FORMAT_ALIASES:
+        raise ValueError(f"Unknown format '{name}'. Supported: puzzlink, penpa, ir.")
+    return _FORMAT_ALIASES[key]
+
+
+def _normalize_penpa_source(source: str) -> str:
+    s = source.strip()
+    if s.startswith("#"):
+        s = s[1:]
+    if s.startswith(PENPA_PREFIX):
+        return s
+    if s.startswith(PENPA_URLPREFIX):
+        frag = s.split("#", 1)[1] if "#" in s else ""
+        if frag.startswith("#"):
+            frag = frag[1:]
+        return frag if frag.startswith(PENPA_PREFIX) else f"{PENPA_PREFIX}{frag}"
+    return s
+
+
+def _detect_source_format(source: str) -> str:
+    s = source.strip()
+    if "puzz.link/p?" in s:
+        return "puzzlink"
+    if s.startswith(PENPA_PREFIX) or s.startswith("#" + PENPA_PREFIX) or PENPA_URLPREFIX in s:
+        return "penpa"
+    raise ValueError("Cannot detect source format. Please pass source_format explicitly.")
+
+
+def _build_converter(fmt: str, converter_config: Optional[Dict[str, Any]] = None):
+    if fmt == "puzzlink":
+        return PuzzlinkConverter(converter_config or {})
+    if fmt == "penpa":
+        return PenpaConverter(converter_config or {})
+    raise ValueError(f"Unsupported converter format '{fmt}'.")
+
+def solve(
+    source: Union[str, Dict[str, Any]], 
+    puzzle_type: str, 
+    **kwargs
+) -> Any:
+    """
+    Unified entry point for solving puzzles.
+    
+    Args:
+        source: 
+            - A string containing the raw puzzle data (with headers, e.g. "9 9\n...").
+            - A dictionary (pre-parsed data).
+        puzzle_type: The snake_case type name (e.g., 'akari', 'fuzuli').
+        show: Whether to visualize the result.
+        **kwargs: Overrides for solver parameters.
+    """
+    
+    # --- 1.  (Parsing) ---
+    init_params = {}
+    
+    if isinstance(source, dict):
+        init_params = source.copy()
+        
+    elif isinstance(source, str):
+        try:
+            target_parser = get_parser(puzzle_type) 
+            parsed_data = target_parser(source.strip())
+            
+            if parsed_data is None:
+                raise ValueError(f"Parser returned None for type '{puzzle_type}'")
+                
+            init_params.update(parsed_data)
+        except ValueError as e:
+            raise ValueError(f"Parsing failed for type '{puzzle_type}': {e}")
+            
+    else:
+        raise TypeError(f"Source must be dict or raw string, got {type(source)}")
+    
+    init_params.update(kwargs)
+
+    try:
+        SolverClass = get_solver_class(puzzle_type)
+    except ValueError as e:
+        raise ValueError(f"Unknown puzzle type '{puzzle_type}'.") from e
+
+
+    solver_instance = SolverClass(**init_params)
+    
+    result = solver_instance.solve()
+    
+    return result
+
+def solver(puzzle_type: str, data: Dict[str, Any] = None, **kwargs) -> Any:
+    # return solve(source=data, puzzle_type=puzzle_type, **kwargs)
+    init_params = {}
+    
+    if isinstance(data, dict):
+        init_params = data.copy()
+    else:
+        raise TypeError(f"Source must be dict or raw string, got {type(data)}")
+    
+    init_params.update(kwargs)
+
+    try:
+        SolverClass = get_solver_class(puzzle_type)
+    except ValueError as e:
+        raise ValueError(f"Unknown puzzle type '{puzzle_type}'.") from e
+    return SolverClass(**init_params)
+
+
+def decode(
+    source: str,
+    source_format: Optional[str] = None,
+    converter_config: Optional[Dict[str, Any]] = None,
+) -> PuzzleInstance:
+    """
+    Decode puzzle URL/text into PuzzleInstance (IR).
+
+    Args:
+        source: puzz.link URL, penpa URL, or penpa payload (`m=edit&p=...`).
+        source_format: Optional explicit source format ('puzzlink' or 'penpa').
+        converter_config: Optional converter config dict.
+    """
+    if not isinstance(source, str):
+        raise TypeError(f"source must be str, got {type(source)}")
+
+    fmt = _normalize_format_name(source_format) if source_format else _detect_source_format(source)
+    if fmt == "ir":
+        raise ValueError("decode(source_format='ir') is not valid.")
+
+    converter = _build_converter(fmt, converter_config)
+    normalized_source = _normalize_penpa_source(source) if fmt == "penpa" else source
+    return converter.decode(normalized_source)
+
+
+def encode(
+    instance: PuzzleInstance,
+    target_format: str,
+    converter_config: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Encode PuzzleInstance (IR) into target format URL/text.
+
+    Args:
+        instance: PuzzleInstance IR.
+        target_format: 'puzzlink' or 'penpa'.
+        converter_config: Optional converter config dict.
+    """
+    if not isinstance(instance, PuzzleInstance):
+        raise TypeError(f"instance must be PuzzleInstance, got {type(instance)}")
+
+    fmt = _normalize_format_name(target_format)
+    if fmt == "ir":
+        raise ValueError("encode(target_format='ir') is not valid.")
+
+    converter = _build_converter(fmt, converter_config)
+    return converter.encode(instance)
+
+
+def convert(
+    source: Union[str, PuzzleInstance],
+    target_format: str,
+    source_format: Optional[str] = None,
+    converter_config: Optional[Dict[str, Any]] = None,
+    decode_converter_config: Optional[Dict[str, Any]] = None,
+    encode_converter_config: Optional[Dict[str, Any]] = None,
+) -> Union[str, PuzzleInstance]:
+    """
+    Convert between puzzlink/penpa/IR.
+
+    Examples:
+        - URL -> IR: convert(url, "ir")
+        - puzzlink -> penpa: convert(url, "penpa")
+        - penpa -> puzzlink: convert(url, "puzzlink")
+        - IR -> puzzlink: convert(ir, "puzzlink")
+
+    Notes:
+        - `converter_config` is kept for backward compatibility and applies to both
+          decode/encode when side-specific configs are not provided.
+        - `decode_converter_config` and `encode_converter_config` let callers pass
+          different settings per stage in a two-step conversion.
+    """
+    dst = _normalize_format_name(target_format)
+    decode_cfg = decode_converter_config if decode_converter_config is not None else converter_config
+    encode_cfg = encode_converter_config if encode_converter_config is not None else converter_config
+
+    if isinstance(source, PuzzleInstance):
+        if dst == "ir":
+            return source
+        return encode(source, dst, converter_config=encode_cfg)
+
+    if not isinstance(source, str):
+        raise TypeError(f"source must be str or PuzzleInstance, got {type(source)}")
+
+    ir = decode(source, source_format=source_format, converter_config=decode_cfg)
+    if dst == "ir":
+        return ir
+    return encode(ir, dst, converter_config=encode_cfg)
+
+__all__ = ["solve", "solver", "decode", "encode", "convert", "PenpaDecodeError"]
+__version__ = '0.3.3'