Metadata-Version: 2.4
Name: gtlab
Version: 0.2.6
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
Requires-Dist: networkx>=2.6
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

[![CI](https://github.com/tamastheactual/gtlab/actions/workflows/ci.yml/badge.svg)](https://github.com/tamastheactual/gtlab/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/gtlab.svg)](https://pypi.org/project/gtlab/)
[![Python](https://img.shields.io/pypi/pyversions/gtlab.svg)](https://pypi.org/project/gtlab/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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:

```text
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. As of
**0.2.0** the package covers the full notebook surface: every solver, plot
(`plot_tree`, `plot_mixed`, `plot_frontier`, ...), parameter sweep, styled
walkthrough (`explain`, `iesds_explain`, `*_detail`, `verify_*`), Monte-Carlo
`simulate`, and the `GeneralSumSG` / `CheapTalkGame` models. 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)
```
