jansou 0.1.0__tar.gz

jansou-0.1.0/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

jansou-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/
+
+  coverage:
+    name: coverage
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests with coverage
+        run: uv run pytest tests/ --cov --cov-report=term-missing --cov-fail-under=100
+
+      - name: Update coverage badge
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format
+        run: uv run ruff format --check

jansou-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+Thumbs.db
+
+CLAUDE.local.md
+.claude/settings.local.json
+
+__pycache__/
+*.py[co]
+.venv/
+dist/
+
+.coverage
+site/
+
+dataset/*/data

jansou-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaemin Noh
+
+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.

jansou-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: jansou
+Version: 0.1.0
+Summary: Riichi Mahjong Environments and Utilities
+Project-URL: Homepage, https://github.com/Snack-X/jansou
+Project-URL: Repository, https://github.com/Snack-X/jansou
+Project-URL: Issues, https://github.com/Snack-X/jansou/issues
+Author-email: Jaemin Noh <korsnack@korsnack.kr>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mahjong,riichi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Games/Entertainment :: Board Games
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Jansou
+
+[![Coverage](https://raw.githubusercontent.com/your-org/jansou/python-coverage-comment-action-data/badge.svg)](https://github.com/your-org/jansou/tree/python-coverage-comment-action-data)
+
+Python library for Riichi Mahjong environments and ugittilities.
+
+- Conversion between multiple tile notations (MPSZ, MJAI, 136)
+- Hand analysis (shanten, wait, efficiency, yaku, fu/han, score)
+- Game environment for 3/4 player game with configurable rules
+- Game replay log in multiple formats (mjlog XML, mjai JSONL, Tenhou JSON)
+
+## Examples
+
+### Notation
+
+```python
+from jansou.core.notation import parse_mpsz, dump_mpsz, parse_mjai, dump_mjai, parse_136, dump_136
+
+tiles = parse_mpsz("667s 34668m 2357p 2z")
+
+dump_mpsz(tiles)  # 34668m2357p667s2z
+dump_mjai(tiles)  # 6s 6s 7s 3m 4m 6m 6m 8m 2p 3p 5p 7p S
+dump_136(tiles)   # [92, 93, 96, 8, 12, 20, 21, 28, 40, 44, 53, 60, 112]
+```
+
+### Hand
+
+```python
+from jansou.core.tiles import Tile, TileKind
+from jansou.core.notation import parse_mpsz
+from jansou.core.hand import Hand
+from jansou.analysis.efficiency import discard_evaluation
+from jansou.analysis.shanten import shanten, is_tenpai
+from jansou.analysis.waits import waits
+
+# (1) shanten advancement
+
+hand = Hand(parse_mpsz("279m 1569p 1168s 35z 2m"))
+
+shanten(hand)    # 3
+is_tenpai(hand)  # False
+
+options = discard_evaluation(hand)  # sorted by shanten advancement and wider acceptance
+                                    # in this case, 1p 9p 3z 5z are the best, with the same number of acceptance
+
+best = options[0]
+best.discard           # 1p
+best.shanten           # 3
+best.total_acceptance  # 20
+
+# (2) acceptance
+
+hand = Hand(parse_mpsz("567m 34567p 23489s 2z"))
+
+options = discard_evaluation(hand)  # there are multiple options for 1 shanten
+
+best = options[0]      # but the best option is 2z with the widest acceptance
+best.discard           # 2z
+best.shanten           # 1
+best.total_acceptance  # 33
+
+# (3) waits
+
+hand = Hand(parse_mpsz("1112345678999m"))
+
+waits(hand)  # 1m 2m 3m 4m 5m 6m 7m 8m 9m
+```
+
+### Score
+
+```python
+from jansou.core.tiles import Tile, TileKind, Wind
+from jansou.core.notation import parse_mpsz
+from jansou.core.rules import preset
+from jansou.core.hand import Hand, Meld, MeldType, CallSource
+from jansou.scoring.context import WinContext
+from jansou.scoring.score import score
+
+hand = Hand(
+    parse_mpsz("77m 34p 055s 5p"),
+    [
+        Meld(MeldType.PON, parse_mpsz("111m"), Tile(TileKind.M1), CallSource.TOIMEN),
+        Meld(MeldType.PON, parse_mpsz("777z"), Tile(TileKind.CHUN), CallSource.KAMICHA),
+    ]
+)
+
+context = WinContext(
+    rules=preset("m-league"),
+    seat_wind=Wind.WEST,
+    is_tsumo=False,
+    dora_indicators=[Tile(TileKind.CHUN)],
+)
+
+result = score(hand, Tile(TileKind.P5), context)
+
+result.yaku      # YAKUHAI_CHUN
+result.han       # 2
+result.fu.total  # 40 (20 + 4 + 4 + 4 = 32)
+
+result.payment.total  # 2600
+
+shanten(hand)    # 0
+is_tenpai(hand)  # True
+waits(hand)      # 2p, 5p
+```
+
+### Game environment, replay log
+
+```python
+from jansou.core.rules import preset
+from jansou.game.environment import Environment
+from jansou.game.agents import SmartEfficiencyAgent
+from jansou.io.from_game import paifu_from_game
+from jansou.io.tenhou_json import dump_tenhou_json_url
+
+env = Environment(preset("tenhou"))
+agents = [SmartEfficiencyAgent() for i in range(4)]
+
+result = env.run(agents)
+
+result.scores
+result.ranking
+
+paifu = paifu_from_game(env)
+dump_tenhou_json_url(paifu)   # https://tenhou.net/6/#json=...
+                              # can be viewed at https://mjv.snack.studio
+```
+
+## Development
+
+```sh
+uv sync
+
+uv run pytest
+uv run pytest --cov
+
+uv run ruff format
+uv run ruff check
+```

jansou-0.1.0/README.md

@@ -0,0 +1,139 @@
+# Jansou
+
+[![Coverage](https://raw.githubusercontent.com/your-org/jansou/python-coverage-comment-action-data/badge.svg)](https://github.com/your-org/jansou/tree/python-coverage-comment-action-data)
+
+Python library for Riichi Mahjong environments and ugittilities.
+
+- Conversion between multiple tile notations (MPSZ, MJAI, 136)
+- Hand analysis (shanten, wait, efficiency, yaku, fu/han, score)
+- Game environment for 3/4 player game with configurable rules
+- Game replay log in multiple formats (mjlog XML, mjai JSONL, Tenhou JSON)
+
+## Examples
+
+### Notation
+
+```python
+from jansou.core.notation import parse_mpsz, dump_mpsz, parse_mjai, dump_mjai, parse_136, dump_136
+
+tiles = parse_mpsz("667s 34668m 2357p 2z")
+
+dump_mpsz(tiles)  # 34668m2357p667s2z
+dump_mjai(tiles)  # 6s 6s 7s 3m 4m 6m 6m 8m 2p 3p 5p 7p S
+dump_136(tiles)   # [92, 93, 96, 8, 12, 20, 21, 28, 40, 44, 53, 60, 112]
+```
+
+### Hand
+
+```python
+from jansou.core.tiles import Tile, TileKind
+from jansou.core.notation import parse_mpsz
+from jansou.core.hand import Hand
+from jansou.analysis.efficiency import discard_evaluation
+from jansou.analysis.shanten import shanten, is_tenpai
+from jansou.analysis.waits import waits
+
+# (1) shanten advancement
+
+hand = Hand(parse_mpsz("279m 1569p 1168s 35z 2m"))
+
+shanten(hand)    # 3
+is_tenpai(hand)  # False
+
+options = discard_evaluation(hand)  # sorted by shanten advancement and wider acceptance
+                                    # in this case, 1p 9p 3z 5z are the best, with the same number of acceptance
+
+best = options[0]
+best.discard           # 1p
+best.shanten           # 3
+best.total_acceptance  # 20
+
+# (2) acceptance
+
+hand = Hand(parse_mpsz("567m 34567p 23489s 2z"))
+
+options = discard_evaluation(hand)  # there are multiple options for 1 shanten
+
+best = options[0]      # but the best option is 2z with the widest acceptance
+best.discard           # 2z
+best.shanten           # 1
+best.total_acceptance  # 33
+
+# (3) waits
+
+hand = Hand(parse_mpsz("1112345678999m"))
+
+waits(hand)  # 1m 2m 3m 4m 5m 6m 7m 8m 9m
+```
+
+### Score
+
+```python
+from jansou.core.tiles import Tile, TileKind, Wind
+from jansou.core.notation import parse_mpsz
+from jansou.core.rules import preset
+from jansou.core.hand import Hand, Meld, MeldType, CallSource
+from jansou.scoring.context import WinContext
+from jansou.scoring.score import score
+
+hand = Hand(
+    parse_mpsz("77m 34p 055s 5p"),
+    [
+        Meld(MeldType.PON, parse_mpsz("111m"), Tile(TileKind.M1), CallSource.TOIMEN),
+        Meld(MeldType.PON, parse_mpsz("777z"), Tile(TileKind.CHUN), CallSource.KAMICHA),
+    ]
+)
+
+context = WinContext(
+    rules=preset("m-league"),
+    seat_wind=Wind.WEST,
+    is_tsumo=False,
+    dora_indicators=[Tile(TileKind.CHUN)],
+)
+
+result = score(hand, Tile(TileKind.P5), context)
+
+result.yaku      # YAKUHAI_CHUN
+result.han       # 2
+result.fu.total  # 40 (20 + 4 + 4 + 4 = 32)
+
+result.payment.total  # 2600
+
+shanten(hand)    # 0
+is_tenpai(hand)  # True
+waits(hand)      # 2p, 5p
+```
+
+### Game environment, replay log
+
+```python
+from jansou.core.rules import preset
+from jansou.game.environment import Environment
+from jansou.game.agents import SmartEfficiencyAgent
+from jansou.io.from_game import paifu_from_game
+from jansou.io.tenhou_json import dump_tenhou_json_url
+
+env = Environment(preset("tenhou"))
+agents = [SmartEfficiencyAgent() for i in range(4)]
+
+result = env.run(agents)
+
+result.scores
+result.ranking
+
+paifu = paifu_from_game(env)
+dump_tenhou_json_url(paifu)   # https://tenhou.net/6/#json=...
+                              # can be viewed at https://mjv.snack.studio
+```
+
+## Development
+
+```sh
+uv sync
+
+uv run pytest
+uv run pytest --cov
+
+uv run ruff format
+uv run ruff check
+```

jansou-0.1.0/mise.toml

@@ -0,0 +1,11 @@
+[tools]
+python = "3.12"
+uv = "latest"
+
+[tasks.docs]
+description = "Generate the API documentation from docstrings into site/api"
+run = "uv run pdoc -d google jansou -o site/api"
+
+[tasks.docs-serve]
+description = "Serve the API documentation with live reload"
+run = "uv run pdoc -d google jansou"

jansou-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "jansou"
+version = "0.1.0"
+description = "Riichi Mahjong Environments and Utilities"
+authors = [
+    { name = "Jaemin Noh", email = "korsnack@korsnack.kr" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mahjong", "riichi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment :: Board Games",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Snack-X/jansou"
+Repository = "https://github.com/Snack-X/jansou"
+Issues = "https://github.com/Snack-X/jansou/issues"
+
+[project.scripts]
+jansou-validate = "jansou.validation.cli:main"
+
+[dependency-groups]
+dev = [
+    "pdoc>=15.0",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.15.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jansou"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/dataset",
+    "/docs",
+    "/.claude/",
+    "CLAUDE.md",
+]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "W191",   # tab-indentation
+    "E111",   # indentation-with-invalid-multiple
+    "E114",   # indentation-with-invalid-multiple-comment
+    "E117",   # over-indented
+    "D203",   # incorrect-blank-line-before-class
+    "D206",   # docstring-tab-indentation
+    "D300",   # triple-single-quotes
+    "Q000",   # bad-quotes-inline-string
+    "Q001",   # bad-quotes-multiline-string
+    "Q002",   # bad-quotes-docstring
+    "Q003",   # avoidable-escaped-quote
+    "Q004",   # unnecessary-escaped-quote
+    "COM812", # missing-trailing-comma
+    "COM819", # prohibited-trailing-comma
+    "ISC001", # single-line-implicit-string-concatenation
+
+    "EM", # flake8-errmsg
+
+    "PLR2004", # magic-value-comparison
+    "S311",    # suspicious-non-cryptographic-random-usage
+    "TRY003",  # raise-vanilla-args
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "D1",      # undocumented-*
+
+    "ANN001",  # missing-type-function-argument
+    "INP001",  # implicit-namespace-package
+    "PLR2004", # magic-value-comparison
+    "S101",    # assert
+    "S311",    # suspicious-non-cryptographic-random-usage
+    "SLF001",  # private-member-access
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pylint]
+max-args = 10
+max-branches = 15
+max-returns = 10
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["jansou"]
+branch = true
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "\\.\\.\\.",
+]

jansou-0.1.0/src/jansou/__init__.py

@@ -0,0 +1,11 @@
+"""Jansou: a Riichi Mahjong library.
+
+Functionality lives in topical subpackages:
+
+- jansou.core: tiles, notation, rules, and hands
+- jansou.analysis: decomposition, shanten, waits, and efficiency
+- jansou.scoring: win context, fu, yaku, and points
+- jansou.game: wall, state, events, actions, flow, agents, and environment
+- jansou.io: reading, writing, and replaying external records (mjlog, Tenhou JSON, MJAI), and exporting engine games
+- jansou.validation: checking parsed games against the scores their logs recorded
+"""

jansou-0.1.0/src/jansou/analysis/__init__.py

@@ -0,0 +1,7 @@
+"""Hand-shape analysis.
+
+- jansou.analysis.decompose: complete-hand decomposition and wait shapes
+- jansou.analysis.shanten: distance to ready
+- jansou.analysis.waits: the tiles that complete a ready hand
+- jansou.analysis.efficiency: acceptance, discard evaluation, improvement tiles
+"""