gtlab 0.1.0__tar.gz

gtlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tamás Takács
+
+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.

gtlab-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: gtlab
+Version: 0.1.0
+Summary: Teaching toolkit for the ELTE Game Theory course: solvers, game library, and Jupyter-friendly visualizations.
+Author-email: Tamás Takács <tamastheactual@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tamastheactual/gtlab
+Project-URL: Repository, https://github.com/tamastheactual/gtlab
+Project-URL: Issues, https://github.com/tamastheactual/gtlab/issues
+Keywords: game-theory,nash-equilibrium,teaching,elte,education
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: matplotlib>=3.4
+Requires-Dist: pandas>=1.3
+Provides-Extra: nash
+Requires-Dist: nashpy>=0.0.35; extra == "nash"
+Provides-Extra: welfare
+Requires-Dist: pulp>=2.6; extra == "welfare"
+Provides-Extra: full
+Requires-Dist: nashpy>=0.0.35; extra == "full"
+Requires-Dist: pulp>=2.6; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# gtlab — Game Theory Lab
+
+A teaching toolkit for the ELTE Game Theory course. It consolidates the solvers,
+example games, and Jupyter visualizations that previously lived (duplicated) in
+six separate Colab notebooks into one installable, extensible package.
+
+## Install
+
+```bash
+pip install -e ".[full]"     # full = nashpy + pulp extras (recommended in Colab)
+pip install -e .             # core only (numpy / scipy / matplotlib / pandas)
+```
+
+## Quick start
+
+```python
+import gtlab
+gtlab.apply_rc()                         # shared matplotlib styling (call once)
+
+from gtlab.games import prisoners_dilemma
+prisoners_dilemma().solve()              # annotated bimatrix in a Jupyter cell
+```
+
+Build your own game:
+
+```python
+import numpy as np
+from gtlab import NormalFormGame
+
+g = NormalFormGame(
+    A=np.array([[3, 0], [5, 1]]),
+    B=np.array([[3, 5], [0, 1]]),
+    row_actions=["Cooperate", "Defect"],
+    col_actions=["Cooperate", "Defect"],
+    name="My Game",
+)
+g.explain()
+```
+
+## Architecture
+
+The design separates the three concerns that were tangled together in the
+notebooks:
+
+```
+gtlab/
+├── core/      game classes — hold data, expose a thin API
+│   ├── normal_form.py      NormalFormGame
+│   ├── zero_sum.py         ZeroSumGame
+│   ├── correlated.py       CorrelatedGame
+│   ├── stochastic.py       StochasticGame
+│   ├── extensive_form.py   ExtensiveFormGame
+│   └── bayesian.py         PostedPrice, FirstPriceAuction, SecondPriceAuction
+├── solvers/   pure algorithms — numpy in, numpy/dict out, no display
+│   ├── best_response.py    nash.py          dominance.py
+│   ├── pareto.py           linprog.py       value_iteration.py
+│   ├── welfare.py          learning.py      correlated.py
+├── viz/       display layer — ONE theme, formatters, HTML, plots
+│   ├── theme.py  format.py  html.py  plots.py
+└── games/     ready-made example games + REGISTRY
+```
+
+Rule of thumb: **math goes in `solvers/`, rendering goes in `viz/`, and the
+classes in `core/` just wire them together.** A theme tweak is one edit in
+`viz/theme.py`; a new algorithm is one file in `solvers/`; a new example is one
+factory in `games/`.
+
+## Extending
+
+| To add… | …do this |
+|---|---|
+| a new example game | write a factory in `games/`, add it to `REGISTRY` |
+| a new algorithm | add a pure function in `solvers/`, export it |
+| a new game type | add a class in `core/` that calls `solvers` + `viz` |
+| restyle output | edit `viz/theme.py` (colors / CSS / rcParams) |
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The solver layer has golden-value tests so refactors stay behavior-preserving.
+
+## Notebook migration
+
+Each lecture notebook drops its ~2,000-line engine class and imports from
+`gtlab` instead, keeping only narrative and example-specific calls. The methods
+the notebooks relied on (`.summary()`, `.solve()`, `.explain()`, `.plot_*()`)
+are preserved on the core classes.
+```python
+# old: 1,800 lines of NormalFormGame defined inline
+# new:
+from gtlab.games import prisoners_dilemma
+prisoners_dilemma().solve(show_br=True, show_ne=True)
+```

gtlab-0.1.0/README.md

@@ -0,0 +1,97 @@
+# gtlab — Game Theory Lab
+
+A teaching toolkit for the ELTE Game Theory course. It consolidates the solvers,
+example games, and Jupyter visualizations that previously lived (duplicated) in
+six separate Colab notebooks into one installable, extensible package.
+
+## Install
+
+```bash
+pip install -e ".[full]"     # full = nashpy + pulp extras (recommended in Colab)
+pip install -e .             # core only (numpy / scipy / matplotlib / pandas)
+```
+
+## Quick start
+
+```python
+import gtlab
+gtlab.apply_rc()                         # shared matplotlib styling (call once)
+
+from gtlab.games import prisoners_dilemma
+prisoners_dilemma().solve()              # annotated bimatrix in a Jupyter cell
+```
+
+Build your own game:
+
+```python
+import numpy as np
+from gtlab import NormalFormGame
+
+g = NormalFormGame(
+    A=np.array([[3, 0], [5, 1]]),
+    B=np.array([[3, 5], [0, 1]]),
+    row_actions=["Cooperate", "Defect"],
+    col_actions=["Cooperate", "Defect"],
+    name="My Game",
+)
+g.explain()
+```
+
+## Architecture
+
+The design separates the three concerns that were tangled together in the
+notebooks:
+
+```
+gtlab/
+├── core/      game classes — hold data, expose a thin API
+│   ├── normal_form.py      NormalFormGame
+│   ├── zero_sum.py         ZeroSumGame
+│   ├── correlated.py       CorrelatedGame
+│   ├── stochastic.py       StochasticGame
+│   ├── extensive_form.py   ExtensiveFormGame
+│   └── bayesian.py         PostedPrice, FirstPriceAuction, SecondPriceAuction
+├── solvers/   pure algorithms — numpy in, numpy/dict out, no display
+│   ├── best_response.py    nash.py          dominance.py
+│   ├── pareto.py           linprog.py       value_iteration.py
+│   ├── welfare.py          learning.py      correlated.py
+├── viz/       display layer — ONE theme, formatters, HTML, plots
+│   ├── theme.py  format.py  html.py  plots.py
+└── games/     ready-made example games + REGISTRY
+```
+
+Rule of thumb: **math goes in `solvers/`, rendering goes in `viz/`, and the
+classes in `core/` just wire them together.** A theme tweak is one edit in
+`viz/theme.py`; a new algorithm is one file in `solvers/`; a new example is one
+factory in `games/`.
+
+## Extending
+
+| To add… | …do this |
+|---|---|
+| a new example game | write a factory in `games/`, add it to `REGISTRY` |
+| a new algorithm | add a pure function in `solvers/`, export it |
+| a new game type | add a class in `core/` that calls `solvers` + `viz` |
+| restyle output | edit `viz/theme.py` (colors / CSS / rcParams) |
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The solver layer has golden-value tests so refactors stay behavior-preserving.
+
+## Notebook migration
+
+Each lecture notebook drops its ~2,000-line engine class and imports from
+`gtlab` instead, keeping only narrative and example-specific calls. The methods
+the notebooks relied on (`.summary()`, `.solve()`, `.explain()`, `.plot_*()`)
+are preserved on the core classes.
+```python
+# old: 1,800 lines of NormalFormGame defined inline
+# new:
+from gtlab.games import prisoners_dilemma
+prisoners_dilemma().solve(show_br=True, show_ne=True)
+```

gtlab-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gtlab"
+version = "0.1.0"
+description = "Teaching toolkit for the ELTE Game Theory course: solvers, game library, and Jupyter-friendly visualizations."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Tamás Takács", email = "tamastheactual@gmail.com" }]
+keywords = ["game-theory", "nash-equilibrium", "teaching", "elte", "education"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Education",
+]
+
+dependencies = [
+    "numpy>=1.21",
+    "scipy>=1.7",
+    "matplotlib>=3.4",
+    "pandas>=1.3",
+]
+
+[project.optional-dependencies]
+# Mixed-Nash via support enumeration in normal/extensive-form games.
+nash = ["nashpy>=0.0.35"]
+# Linear-programming welfare objectives (utilitarian / egalitarian).
+welfare = ["pulp>=2.6"]
+# Everything, for running the full notebook suite.
+full = ["nashpy>=0.0.35", "pulp>=2.6"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/tamastheactual/gtlab"
+Repository = "https://github.com/tamastheactual/gtlab"
+Issues = "https://github.com/tamastheactual/gtlab/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gtlab-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gtlab-0.1.0/src/gtlab/__init__.py

@@ -0,0 +1,39 @@
+"""gtlab — Game Theory Lab for the ELTE Game Theory course.
+
+Quick start::
+
+    import gtlab
+    gtlab.apply_rc()                       # consistent plot styling (once)
+
+    from gtlab.games import prisoners_dilemma
+    prisoners_dilemma().solve()            # annotated bimatrix in Jupyter
+
+Build your own::
+
+    from gtlab import NormalFormGame
+    import numpy as np
+    g = NormalFormGame(np.array([[3, 0], [5, 1]]), np.array([[3, 5], [0, 1]]))
+    g.explain()
+
+Layers:
+  * ``gtlab.core``    — game classes (data + thin API)
+  * ``gtlab.solvers`` — pure algorithms (best response, Nash, value iteration, …)
+  * ``gtlab.viz``     — formatting, HTML, plots, theme
+  * ``gtlab.games``   — ready-made example games
+"""
+from . import games, solvers, viz
+from .core import (CorrelatedGame, ExtensiveFormGame, FirstPriceAuction,
+                   Mechanism, NormalFormGame, PostedPrice, Procurement,
+                   PublicProject, SecondPriceAuction, SpenceSignaling,
+                   StochasticGame, VCGAssignment, ZeroSumGame)
+from .viz import apply_rc
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "NormalFormGame", "ZeroSumGame", "CorrelatedGame", "StochasticGame",
+    "ExtensiveFormGame", "Mechanism", "PostedPrice", "FirstPriceAuction",
+    "SecondPriceAuction", "SpenceSignaling", "VCGAssignment", "PublicProject",
+    "Procurement",
+    "solvers", "viz", "games", "apply_rc", "__version__",
+]

gtlab-0.1.0/src/gtlab/_memo.py

@@ -0,0 +1,31 @@
+"""A tiny per-instance memoization decorator for game-class analysis methods.
+
+Game classes are dataclasses wrapping numpy arrays, so they are unhashable and
+``functools.lru_cache`` does not apply. The payoff data is treated as immutable
+after construction, so caching results on the instance is safe and lets repeated
+display calls (and ``compare_via``) reuse expensive solves instead of redoing
+them. Mutating a payoff matrix in place after the first call is unsupported
+(call :func:`clear_cache` if you must).
+"""
+from __future__ import annotations
+
+import functools
+from typing import Callable
+
+
+def cached_method(func: Callable) -> Callable:
+    """Memoize a method's result on the instance, keyed by ``(name, args)``."""
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        cache = self.__dict__.setdefault("_cache", {})
+        key = (func.__name__, args, tuple(sorted(kwargs.items())))
+        if key not in cache:
+            cache[key] = func(self, *args, **kwargs)
+        return cache[key]
+
+    return wrapper
+
+
+def clear_cache(instance) -> None:
+    """Drop all memoized results on ``instance`` (use after mutating payoffs)."""
+    instance.__dict__.pop("_cache", None)

gtlab-0.1.0/src/gtlab/core/__init__.py

@@ -0,0 +1,17 @@
+"""Core game classes — each holds data and delegates math/display to the
+shared :mod:`gtlab.solvers` and :mod:`gtlab.viz` layers."""
+from .bayesian import (FirstPriceAuction, Mechanism, PostedPrice, Procurement,
+                       PublicProject, SecondPriceAuction, SpenceSignaling,
+                       VCGAssignment)
+from .correlated import CorrelatedGame
+from .extensive_form import ExtensiveFormGame
+from .normal_form import NormalFormGame
+from .stochastic import StochasticGame
+from .zero_sum import ZeroSumGame
+
+__all__ = [
+    "NormalFormGame", "ZeroSumGame", "CorrelatedGame", "StochasticGame",
+    "ExtensiveFormGame", "Mechanism", "PostedPrice", "FirstPriceAuction",
+    "SecondPriceAuction", "SpenceSignaling", "VCGAssignment", "PublicProject",
+    "Procurement",
+]