valanga 0.1.1__tar.gz → 0.1.3__tar.gz

{valanga-0.1.1/src/valanga.egg-info → valanga-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valanga
-Version: 0.1.1
+Version: 0.1.3
 Summary: Shared types and utilities for evalaution
 Requires-Python: >=3.13
 License-File: LICENSE
@@ -8,6 +8,12 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.4.1; extra == "test"
 Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.14.10; extra == "lint"
+Requires-Dist: pylint>=4.0.4; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.19.1; extra == "typecheck"
+Requires-Dist: pyright[nodejs]>=1.1.408; extra == "typecheck"
 Provides-Extra: dev
 Requires-Dist: tox>=4.32.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.12.12; extra == "dev"
@@ -15,7 +21,7 @@ Requires-Dist: ruff>=0.14.10; extra == "dev"
 Requires-Dist: pylint>=4.0.4; extra == "dev"
 Requires-Dist: black>=25.12.0; extra == "dev"
 Requires-Dist: mypy>=1.19.1; extra == "dev"
-Requires-Dist: pyright>=1.1.407; extra == "dev"
+Requires-Dist: pyright[nodejs]>=1.1.408; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: sphinx; extra == "dev"

valanga-0.1.3/README.md

@@ -0,0 +1,43 @@
+# valanga
+
+![Python 3.13](https://img.shields.io/badge/python-3.13-blue?logo=python)
+[![Tests](https://github.com/victorgabillon/valanga/actions/workflows/ci.yaml/badge.svg?label=tests)](https://github.com/victorgabillon/valanga/actions/workflows/ci.yaml)
+[![License: GPL v3](https://img.shields.io/github/license/victorgabillon/valanga)](LICENSE)
+
+Shared Python types and lightweight utilities for describing turn-based games and their evaluations. The package exposes protocols for representing states, outcomes, and state representations that other libraries can build on.
+
+## Key concepts
+- **Game primitives**: `Color`, `BranchKey`, `State`, and related protocols describe whose turn it is, how to enumerate legal branches, and how to copy or advance a state. 【F:src/valanga/game.py†L14-L95】
+- **Evaluations**: `FloatyStateEvaluation` captures heuristic scores while `ForcedOutcome` records a definitive result plus the line of play that forces it. Both are grouped under `BoardEvaluation`. 【F:src/valanga/evaluations.py†L13-L43】
+- **Game termination**: `OverEvent` combines how a game ended with who won, backed by `HowOver` and `Winner` enums. Utility helpers like `is_over()` and `get_over_tag()` simplify downstream checks. 【F:src/valanga/over_event.py†L8-L115】
+- **State representations**: `ContentRepresentation` defines how to turn a `State` into evaluator input, and `RepresentationFactory` builds or updates those representations from states and modifications. 【F:src/valanga/represention_for_evaluation.py†L9-L22】【F:src/valanga/representation_factory.py†L7-L55】
+- **Progress reporting**: `PlayerProgressMessage` communicates per-player progress percentages during long-running work. 【F:src/valanga/progress_messsage.py†L9-L18】
+
+## Installation
+```bash
+pip install .
+```
+The project targets Python 3.13 and has no required runtime dependencies.
+
+## Quick start
+Below is a minimal example that marks a finished game and obtains an evaluation structure:
+```python
+from valanga import ForcedOutcome, OverEvent
+from valanga.over_event import HowOver, Winner
+
+# A checkmate where white wins.
+over_event = OverEvent(how_over=HowOver.WIN, who_is_winner=Winner.WHITE)
+
+# Record the forced outcome and the line of optimal moves that lead to it.
+forced = ForcedOutcome(outcome=over_event, line=["e2e4", "e7e5"])
+print(forced.outcome.get_over_tag())  # -> OverTags.TAG_WIN_WHITE
+```
+
+To wire in a custom state representation, supply callables to `RepresentationFactory` that know how to build representations from a `State` and its modifications.
+
+## Development
+Install the development dependencies and run the test suite:
+```bash
+pip install -e '.[dev]'
+pytest
+```

{valanga-0.1.1 → valanga-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "valanga"
-version = "0.1.1"
+version = "0.1.3"
 description = "Shared types and utilities for evalaution"
 requires-python = ">=3.13"
 dependencies = []
@@ -20,6 +20,16 @@ test = [
     "pytest-cov>=6.0.0"
 ]
 
+lint = [
+  "ruff>=0.14.10",
+  "pylint>=4.0.4",
+]
+
+typecheck = [
+  "mypy>=1.19.1",
+  "pyright[nodejs]>=1.1.408",
+]
+
 
 dev = [
     # Development dependencies (includes test)
@@ -33,7 +43,7 @@ dev = [
 
     # Type checking
     "mypy>=1.19.1",
-    "pyright>=1.1.407   ",
+    "pyright[nodejs]>=1.1.408   ",
 
     # Building & publishing
     "build",
@@ -150,4 +160,44 @@ reportMissingImports = true
 reportUnusedImport = true
 reportMissingTypeStubs = false
 reportUnknownMemberType = false
-reportPrivateImportUsage = false
+reportPrivateImportUsage = false
+
+
+#################### TOX ####################
+
+[tool.tox]
+min_version = "4.32.0"
+env_list = ["py313", "lint", "typecheck"]
+isolated_build = true
+
+[tool.tox.env_run_base]
+base_python = ["python3.13"]
+
+[tool.tox.env.py313]
+description = "Run tests"
+extras = ["test"]
+commands = [["pytest", "{posargs}"]]
+
+[tool.tox.env.lint]
+description = "ruff + pylint (fast, no package install)"
+package = "skip"
+deps = ["ruff>=0.14.10", "pylint>=4.0.4"]
+set_env = { PYTHONPATH = "{toxinidir}/src" }
+commands = [
+  ["python", "-m", "ruff", "check", "src", "tests"],
+  ["python", "-m", "ruff", "format", "--check", "src", "tests"],
+  ["python", "-m", "pylint", "src/valanga"],
+]
+
+[tool.tox.env.typecheck]
+description = "mypy + pyright (fast, no package install)"
+package = "skip"
+deps = ["mypy>=1.19.1", "pyright[nodejs]>=1.1.408"]
+set_env = { MYPYPATH = "{toxinidir}/src" }
+commands = [
+  ["python", "-m", "mypy", "--config-file", "pyproject.toml", "src/valanga"],
+  ["python", "-m", "pyright", "src/valanga"],
+]
+
+
+#################### END TOX ####################

{valanga-0.1.1 → valanga-0.1.3}/src/valanga/__init__.py

@@ -1,6 +1,6 @@
 """Common types and utilities shared by multiple libraries."""
 
-from .evaluations import BoardEvaluation, EvalItem, FloatyStateEvaluation, ForcedOutcome
+from .evaluations import EvalItem, FloatyStateEvaluation, ForcedOutcome, StateEvaluation
 from .game import (
     BLACK,
     WHITE,
@@ -22,7 +22,7 @@ from .represention_for_evaluation import ContentRepresentation
 __all__ = [
     "ForcedOutcome",
     "FloatyStateEvaluation",
-    "BoardEvaluation",
+    "StateEvaluation",
     "EvalItem",
     "OverEvent",
     "Color",

{valanga-0.1.1 → valanga-0.1.3}/src/valanga/evaluations.py

@@ -55,4 +55,4 @@ class FloatyStateEvaluation:
     value_white: float | None
 
 
-BoardEvaluation = FloatyStateEvaluation | ForcedOutcome
+StateEvaluation = FloatyStateEvaluation | ForcedOutcome

{valanga-0.1.1 → valanga-0.1.3}/src/valanga/game.py

@@ -6,6 +6,8 @@ from collections.abc import Hashable
 from enum import Enum
 from typing import Annotated, Iterator, Protocol, Self, Sequence, TypeVar
 
+type Seed = Annotated[int, "seed"]
+
 type StateTag = Annotated[Hashable, "A label or identifier for a state in a game"]
 
 type StateModifications = Annotated[
@@ -16,7 +18,7 @@ type StateModifications = Annotated[
 type BranchKey = Annotated[Hashable, "A label or identifier for a branch in a tree"]
 
 
-T_co = TypeVar("T_co", bound=BranchKey, covariant=True)
+T_co = TypeVar("T_co", bound=BranchKey, covariant=True, default=BranchKey)
 
 
 class BranchKeyGeneratorP(Protocol[T_co]):

valanga-0.1.3/src/valanga/policy.py

@@ -0,0 +1,42 @@
+"""
+Policy-related classes and protocols for branch selection in game trees.
+"""
+
+from dataclasses import dataclass
+from typing import Mapping, Protocol
+
+from valanga.evaluations import StateEvaluation
+from valanga.game import BranchKey, Seed, State
+
+
+@dataclass(frozen=True, slots=True)
+class BranchPolicy:
+    """
+    Represents a probability distribution over branches.
+    """
+
+    probs: Mapping[BranchKey, float]  # should sum to ~1.0
+
+
+@dataclass(frozen=True, slots=True)
+class Recommendation:
+    """A recommendation for a specific branch in a tree node."""
+
+    recommended_key: BranchKey
+    evaluation: StateEvaluation | None = None
+    policy: BranchPolicy | None = None
+    branch_evals: Mapping[BranchKey, StateEvaluation] | None = None
+
+
+class BranchSelector(Protocol):
+    """Protocol for a branch selector."""
+
+    def recommend(self, state: State, seed: Seed) -> Recommendation:
+        """Given a state and a seed, recommends a branch to take.
+        Args:
+            state (State): The current state of the game.
+            seed (Seed): A seed for any randomness involved in the selection.
+        Returns:
+            Recommendation: The recommended branch to take.
+        """
+        ...

{valanga-0.1.1 → valanga-0.1.3/src/valanga.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valanga
-Version: 0.1.1
+Version: 0.1.3
 Summary: Shared types and utilities for evalaution
 Requires-Python: >=3.13
 License-File: LICENSE
@@ -8,6 +8,12 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.4.1; extra == "test"
 Requires-Dist: coverage; extra == "test"
 Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.14.10; extra == "lint"
+Requires-Dist: pylint>=4.0.4; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.19.1; extra == "typecheck"
+Requires-Dist: pyright[nodejs]>=1.1.408; extra == "typecheck"
 Provides-Extra: dev
 Requires-Dist: tox>=4.32.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.12.12; extra == "dev"
@@ -15,7 +21,7 @@ Requires-Dist: ruff>=0.14.10; extra == "dev"
 Requires-Dist: pylint>=4.0.4; extra == "dev"
 Requires-Dist: black>=25.12.0; extra == "dev"
 Requires-Dist: mypy>=1.19.1; extra == "dev"
-Requires-Dist: pyright>=1.1.407; extra == "dev"
+Requires-Dist: pyright[nodejs]>=1.1.408; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: sphinx; extra == "dev"

{valanga-0.1.1 → valanga-0.1.3}/src/valanga.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/valanga/evaluations.py
 src/valanga/evaluator_types.py
 src/valanga/game.py
 src/valanga/over_event.py
+src/valanga/policy.py
 src/valanga/progress_messsage.py
 src/valanga/py.typed
 src/valanga/representation_factory.py
@@ -15,4 +16,6 @@ src/valanga.egg-info/SOURCES.txt
 src/valanga.egg-info/dependency_links.txt
 src/valanga.egg-info/requires.txt
 src/valanga.egg-info/top_level.txt
-tests/test_placeholder.py
+tests/test_over_event.py
+tests/test_placeholder.py
+tests/test_representation_factory.py

{valanga-0.1.1 → valanga-0.1.3}/src/valanga.egg-info/requires.txt

@@ -6,7 +6,7 @@ ruff>=0.14.10
 pylint>=4.0.4
 black>=25.12.0
 mypy>=1.19.1
-pyright>=1.1.407
+pyright[nodejs]>=1.1.408
 build
 twine
 sphinx
@@ -14,7 +14,15 @@ sphinx-rtd-theme
 sphinx-autodoc-typehints
 pre-commit
 
+[lint]
+ruff>=0.14.10
+pylint>=4.0.4
+
 [test]
 pytest>=8.4.1
 coverage
 pytest-cov>=6.0.0
+
+[typecheck]
+mypy>=1.19.1
+pyright[nodejs]>=1.1.408

valanga-0.1.3/tests/test_over_event.py

@@ -0,0 +1,106 @@
+import pytest
+
+from valanga.game import Color
+from valanga.over_event import HowOver, OverEvent, OverTags, Winner
+
+
+@pytest.mark.parametrize(
+    "who, expected",
+    [
+        (Winner.WHITE, OverTags.TAG_WIN_WHITE),
+        (Winner.BLACK, OverTags.TAG_WIN_BLACK),
+    ],
+)
+def test_get_over_tag_win_outcomes(who, expected):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=who)
+
+    assert event.get_over_tag() == expected
+    assert event.is_over() is True
+    assert event.is_win() is True
+    assert event.is_draw() is False
+
+
+@pytest.mark.parametrize("winner", [Winner.WHITE, Winner.BLACK])
+def test_is_winner_matches_color(winner):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=winner)
+
+    assert event.is_winner(Color.WHITE) is (winner == Winner.WHITE)
+    assert event.is_winner(Color.BLACK) is (winner == Winner.BLACK)
+
+
+@pytest.mark.parametrize(
+    "how_over, winner, expected",
+    [
+        (HowOver.DRAW, Winner.NO_KNOWN_WINNER, OverTags.TAG_DRAW),
+        (HowOver.DO_NOT_KNOW_OVER, Winner.NO_KNOWN_WINNER, OverTags.TAG_DO_NOT_KNOW),
+    ],
+)
+def test_get_over_tag_draw_and_unknown(how_over, winner, expected):
+    event = OverEvent(how_over=how_over, who_is_winner=winner)
+
+    assert event.get_over_tag() == expected
+    assert event.is_over() is (how_over == HowOver.DRAW)
+    assert event.is_win() is False
+    assert event.is_draw() is (how_over == HowOver.DRAW)
+
+
+@pytest.mark.parametrize(
+    "how_over, who_is_winner",
+    [
+        (HowOver.WIN, Winner.NO_KNOWN_WINNER),
+        (HowOver.DRAW, Winner.WHITE),
+    ],
+)
+def test_post_init_validates_winner_configuration(how_over, who_is_winner):
+    with pytest.raises(AssertionError):
+        OverEvent(how_over=how_over, who_is_winner=who_is_winner)
+
+
+@pytest.mark.parametrize("player", [Color.WHITE, Color.BLACK])
+def test_is_winner_requires_win(player):
+    event = OverEvent(how_over=HowOver.DRAW, who_is_winner=Winner.NO_KNOWN_WINNER)
+
+    assert event.is_winner(player) is False
+
+
+@pytest.mark.parametrize(
+    "how_over, expected_exception",
+    [
+        (HowOver.WIN, ValueError),
+        (None, ValueError),
+    ],
+)
+def test_get_over_tag_invalid_configurations(how_over, expected_exception):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=Winner.WHITE)
+    event.how_over = how_over  # mutate to bypass post-init validation
+    event.who_is_winner = Winner.NO_KNOWN_WINNER
+
+    with pytest.raises(expected_exception):
+        event.get_over_tag()
+
+
+@pytest.mark.parametrize(
+    "how_over, who_is_winner",
+    [
+        (HowOver.WIN, Winner.WHITE),
+        (HowOver.WIN, Winner.BLACK),
+    ],
+)
+def test_test_method_for_wins(how_over, who_is_winner):
+    event = OverEvent(how_over=how_over, who_is_winner=who_is_winner)
+
+    event.test()
+
+
+def test_test_method_invalid_draw_configuration():
+    event = OverEvent(how_over=HowOver.DRAW, who_is_winner=Winner.NO_KNOWN_WINNER)
+
+    with pytest.raises(AssertionError):
+        event.test()
+
+
+def test_bool_raises():
+    event = OverEvent()
+
+    with pytest.raises(ValueError):
+        bool(event)

valanga-0.1.3/tests/test_representation_factory.py

@@ -0,0 +1,70 @@
+from collections import Counter
+
+from valanga.representation_factory import RepresentationFactory
+
+
+class DummyRepresentation:
+    pass
+
+
+def test_create_from_transition_root_uses_full_creator():
+    calls = Counter()
+
+    def create_from_state(state):
+        calls["create_from_state"] += 1
+        return ("state", state)
+
+    factory = RepresentationFactory(
+        create_from_state=create_from_state, create_from_state_and_modifications=None
+    )
+
+    result = factory.create_from_transition(
+        state="root", previous_state_representation=None, modifications=None
+    )
+
+    assert result == ("state", "root")
+    assert calls["create_from_state"] == 1
+
+
+def test_create_from_transition_no_modifications_falls_back_to_state():
+    calls = Counter()
+
+    def create_from_state(state):
+        calls["create_from_state"] += 1
+        return ("state", state)
+
+    factory = RepresentationFactory(
+        create_from_state=create_from_state, create_from_state_and_modifications=None
+    )
+
+    result = factory.create_from_transition(
+        state="child",
+        previous_state_representation=DummyRepresentation(),
+        modifications=None,
+    )
+
+    assert result == ("state", "child")
+    assert calls["create_from_state"] == 1
+
+
+def test_create_from_transition_with_modifications():
+    calls = Counter()
+
+    def create_from_state_and_modifications(
+        state, state_modifications, previous_state_representation
+    ):
+        calls["create_from_state_and_modifications"] += 1
+        return (state, state_modifications, previous_state_representation)
+
+    factory = RepresentationFactory(
+        create_from_state=lambda state: ("unused", state),
+        create_from_state_and_modifications=create_from_state_and_modifications,
+    )
+
+    previous = DummyRepresentation()
+    result = factory.create_from_transition(
+        state="child", previous_state_representation=previous, modifications="delta"
+    )
+
+    assert result == ("child", "delta", previous)
+    assert calls["create_from_state_and_modifications"] == 1

valanga-0.1.1/README.md

@@ -1,2 +0,0 @@
-# valanga
-Common objects for evaluations