gtlab 0.1.0__py3-none-any.whl

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/_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/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",
+]

gtlab/core/bayesian.py

@@ -0,0 +1,335 @@
+"""Bayesian games and mechanism design.
+
+The original notebook dispatched ~8 mechanisms through one dataclass. Here each
+mechanism is a small focused class with the closed-form results from the
+lecture, sharing the display layer. Add a mechanism by subclassing
+:class:`Mechanism` and implementing ``solve``/``summary``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import product
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from ..viz import fmt, fmt_money, fmt_prob, html
+
+
+class Mechanism:
+    """Base class for a mechanism-design example."""
+
+    name: str = "Mechanism"
+
+    def solve(self) -> Dict[str, Any]:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def summary(self, title: Optional[str] = None) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+
+@dataclass
+class PostedPrice(Mechanism):
+    """Single seller posts a price; buyer's value is private (discrete types)."""
+
+    values: Sequence[float]
+    probs: Sequence[float]
+    name: str = "Posted price"
+
+    def __post_init__(self) -> None:
+        self.values = np.asarray(self.values, dtype=float)
+        self.probs = np.asarray(self.probs, dtype=float)
+        if not np.isclose(self.probs.sum(), 1.0):
+            raise ValueError("type probabilities must sum to 1")
+
+    def expected_revenue(self, price: float) -> float:
+        """E[revenue] = price · P(value ≥ price)."""
+        return float(price * self.probs[self.values >= price].sum())
+
+    def solve(self) -> Dict[str, Any]:
+        # Optimal posted price is one of the candidate type values.
+        revenues = {float(v): self.expected_revenue(v) for v in self.values}
+        best = max(revenues, key=revenues.get)
+        return {"revenues": revenues, "optimal_price": best,
+                "optimal_revenue": revenues[best]}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        rows = [[fmt_money(v), fmt_prob(p)] for v, p in zip(self.values, self.probs)]
+        tbl = html.table(["value", "probability"], rows)
+        sol = self.solve()
+        body = (tbl + f'<p><b>Optimal price</b> {fmt_money(sol["optimal_price"])} '
+                f'→ E[revenue] {fmt_money(sol["optimal_revenue"])}</p>')
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class FirstPriceAuction(Mechanism):
+    """Symmetric IPV first-price auction, values ~ Uniform[lo, hi]."""
+
+    n_bidders: int
+    lo: float = 0.0
+    hi: float = 1.0
+    name: str = "First-price auction"
+
+    def bid(self, value: float) -> float:
+        """BNE bid: shade toward lo by a factor (n-1)/n."""
+        n = self.n_bidders
+        return self.lo + (n - 1) / n * (value - self.lo)
+
+    def expected_revenue(self) -> float:
+        """E[revenue] = lo + (n-1)/(n+1) · (hi - lo) (= E[2nd-highest value])."""
+        n = self.n_bidders
+        return self.lo + (n - 1) / (n + 1) * (self.hi - self.lo)
+
+    def solve(self) -> Dict[str, Any]:
+        return {"expected_revenue": self.expected_revenue(),
+                "shading_factor": (self.n_bidders - 1) / self.n_bidders}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        sol = self.solve()
+        body = (f"<p>{self.n_bidders} bidders, values ~ U[{fmt(self.lo)}, {fmt(self.hi)}]</p>"
+                f"<p><b>BNE bid:</b> b(v) = {fmt(self.lo)} + "
+                f"{fmt(sol['shading_factor'])}·(v − {fmt(self.lo)})</p>"
+                f"<p><b>Expected revenue:</b> {fmt(sol['expected_revenue'])}</p>")
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class SecondPriceAuction(Mechanism):
+    """Vickrey auction: truthful bidding is weakly dominant; revenue-equivalent to FPA."""
+
+    n_bidders: int
+    lo: float = 0.0
+    hi: float = 1.0
+    name: str = "Second-price auction"
+
+    def expected_revenue(self) -> float:
+        n = self.n_bidders
+        return self.lo + (n - 1) / (n + 1) * (self.hi - self.lo)
+
+    def solve(self) -> Dict[str, Any]:
+        return {"expected_revenue": self.expected_revenue(), "dominant": "truthful"}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        sol = self.solve()
+        body = (f"<p>{self.n_bidders} bidders, values ~ U[{fmt(self.lo)}, {fmt(self.hi)}]</p>"
+                "<p><b>Weakly dominant strategy:</b> bid your true value.</p>"
+                f"<p><b>Expected revenue:</b> {fmt(sol['expected_revenue'])} "
+                "(equals the first-price auction — revenue equivalence).</p>")
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class SpenceSignaling(Mechanism):
+    """Spence job-market signaling: a worker's type is private; education is a
+    costly, productivity-free signal. Single-crossing (``c_high < c_low``)
+    yields a non-empty separating interval of education levels."""
+
+    w_low: float
+    w_high: float
+    c_low: float            # cost of education per unit for the LOW type
+    c_high: float           # cost per unit for the HIGH type (c_high < c_low)
+    name: str = "Spence signaling"
+
+    def __post_init__(self) -> None:
+        if not self.c_high < self.c_low:
+            raise ValueError("single-crossing requires c_high < c_low")
+
+    def solve(self) -> Dict[str, Any]:
+        d = self.w_high - self.w_low
+        e_min = d / self.c_low      # low-type indifference (IC for low type)
+        e_max = d / self.c_high     # high-type indifference (IC for high type)
+        e_star = 0.5 * (e_min + e_max)
+        return {
+            "e_min": e_min, "e_max": e_max, "e_star": e_star,
+            "u_high": self.w_high - self.c_high * e_star,
+            "u_low": self.w_low,
+        }
+
+    def summary(self, title: Optional[str] = None) -> None:
+        s = self.solve()
+        rows = [
+            ["e<sub>min</sub> (low-type IC)", "(w<sub>H</sub>−w<sub>L</sub>)/c<sub>L</sub>", fmt(s["e_min"])],
+            ["e<sub>max</sub> (high-type IC)", "(w<sub>H</sub>−w<sub>L</sub>)/c<sub>H</sub>", fmt(s["e_max"])],
+        ]
+        tbl = html.table(["bound", "formula", "value"], rows)
+        body = (tbl + f'<p>Any e* ∈ [{fmt(s["e_min"])}, {fmt(s["e_max"])}] supports a '
+                f'separating equilibrium; midpoint e* = <b>{fmt(s["e_star"])}</b>.</p>')
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class VCGAssignment(Mechanism):
+    """VCG (Vickrey–Clarke–Groves) assignment of indivisible items to bidders.
+
+    ``V[i, j]`` is bidder ``i``'s value for item ``j``. The efficient allocation
+    maximizes total welfare; each winner pays the externality it imposes on the
+    others. Truthful reporting is weakly dominant.
+    """
+
+    V: np.ndarray
+    bidders: Optional[Sequence[str]] = None
+    items: Optional[Sequence[str]] = None
+    name: str = "VCG assignment"
+
+    def __post_init__(self) -> None:
+        self.V = np.asarray(self.V, dtype=float)
+        n_b, n_it = self.V.shape
+        self.bidders = list(self.bidders) if self.bidders else [f"B{i+1}" for i in range(n_b)]
+        self.items = list(self.items) if self.items else [f"item{j+1}" for j in range(n_it)]
+
+    @staticmethod
+    def _enumerate(V: np.ndarray) -> List[Tuple[Tuple[int, ...], float]]:
+        """Every feasible assignment (item → bidder index, or −1) with welfare."""
+        n_b, n_it = V.shape
+        results: List[Tuple[Tuple[int, ...], float]] = []
+
+        def assign(pos: int, used: set, cur: List[int]) -> None:
+            if pos == n_it:
+                w = sum(V[cur[j], j] if cur[j] >= 0 else 0.0 for j in range(n_it))
+                results.append((tuple(cur), float(w)))
+                return
+            assign(pos + 1, used, cur + [-1])         # leave item unassigned
+            for i in range(n_b):
+                if i not in used:
+                    assign(pos + 1, used | {i}, cur + [i])
+
+        assign(0, set(), [])
+        return results
+
+    def _efficient(self, V: np.ndarray) -> Tuple[Tuple[int, ...], float]:
+        return max(self._enumerate(V), key=lambda x: x[1])
+
+    def solve(self) -> Dict[str, Any]:
+        V = self.V
+        n_b = V.shape[0]
+        a_star, w_star = self._efficient(V)
+        alloc = [-1] * n_b                # bidder → item
+        for j, i in enumerate(a_star):
+            if i >= 0:
+                alloc[i] = j
+        payments = np.zeros(n_b)
+        for i in range(n_b):
+            own = V[i, alloc[i]] if alloc[i] >= 0 else 0.0
+            others_with_i = w_star - own
+            _, w_without_i = self._efficient(np.delete(V, i, axis=0))
+            payments[i] = w_without_i - others_with_i
+        utilities = np.array([
+            (V[i, alloc[i]] if alloc[i] >= 0 else 0.0) - payments[i]
+            for i in range(n_b)
+        ])
+        return {"assignment": a_star, "welfare": w_star, "alloc": alloc,
+                "payments": payments, "utilities": utilities}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        s = self.solve()
+        rows = []
+        for i in range(self.V.shape[0]):
+            j = s["alloc"][i]
+            won = self.items[j] if j >= 0 else "—"
+            rows.append([won, fmt_money(s["payments"][i]), fmt_money(s["utilities"][i])])
+        tbl = html.table(["item won", "VCG payment", "utility"], rows,
+                         row_headers=self.bidders)
+        body = (tbl + f'<p><b>Efficient welfare:</b> {fmt(s["welfare"])}. '
+                "Each winner pays the externality it imposes; truthful bidding is "
+                "weakly dominant.</p>")
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class PublicProject(Mechanism):
+    """Clarke pivot mechanism for a binary public good.
+
+    Build iff the sum of reported values covers the cost. A *pivotal* citizen
+    (one whose presence flips the decision) pays the externality it imposes;
+    everyone else pays 0. Truthful, efficient, individually rational — but
+    generally runs a budget deficit (the impossibility trilemma).
+    """
+
+    values: Sequence[float]
+    cost: float
+    citizens: Optional[Sequence[str]] = None
+    name: str = "Public project (Clarke pivot)"
+
+    def __post_init__(self) -> None:
+        self.values = np.asarray(self.values, dtype=float)
+        self.citizens = list(self.citizens) if self.citizens else \
+            [f"C{i+1}" for i in range(len(self.values))]
+
+    def solve(self) -> Dict[str, Any]:
+        v = self.values
+        total = float(v.sum())
+        build = total >= self.cost
+        pay = np.zeros_like(v)
+        if build:
+            for i in range(len(v)):
+                others = total - v[i]
+                if others < self.cost:               # i is pivotal
+                    pay[i] = max(0.0, self.cost - others)
+        total_pay = float(pay.sum())
+        return {"build": build, "total_value": total, "payments": pay,
+                "total_payment": total_pay,
+                "deficit": float(self.cost - total_pay) if build else 0.0}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        s = self.solve()
+        rows = [[fmt(v), fmt_money(p)] for v, p in zip(self.values, s["payments"])]
+        tbl = html.table(["value", "pivot payment"], rows, row_headers=self.citizens)
+        verdict = "BUILD" if s["build"] else "DO NOT build"
+        body = (tbl + f'<p><b>Decision:</b> {verdict} '
+                f'(Σv = {fmt(s["total_value"])} vs cost {fmt_money(self.cost)}).</p>'
+                + (f'<p>Total collected {fmt_money(s["total_payment"])} → '
+                   f'budget deficit {fmt_money(s["deficit"])}.</p>' if s["build"] else ""))
+        html.show(html.card(title or self.name, body))
+
+
+@dataclass
+class Procurement(Mechanism):
+    """Reverse (Vickrey) procurement auction with discrete private costs.
+
+    The firm reporting the lowest cost wins and is paid the second-lowest
+    reported cost. Truthful reporting is weakly dominant; the expected payment
+    is the second-order statistic of ``n`` i.i.d. cost draws.
+    """
+
+    costs: Sequence[float]
+    probs: Sequence[float]
+    n: int = 2
+    name: str = "Procurement (reverse Vickrey)"
+
+    def __post_init__(self) -> None:
+        self.costs = np.asarray(self.costs, dtype=float)
+        self.probs = np.asarray(self.probs, dtype=float)
+        if not np.isclose(self.probs.sum(), 1.0):
+            raise ValueError("cost-type probabilities must sum to 1")
+        if self.n < 2:
+            raise ValueError("need at least 2 firms")
+
+    def solve(self, max_exact: int = 5000) -> Dict[str, Any]:
+        costs, probs, n = self.costs, self.probs, self.n
+        n_types = len(costs)
+        if n_types ** n <= max_exact:
+            e_pay = e_win = 0.0
+            for profile in product(range(n_types), repeat=n):
+                p = float(np.prod(probs[list(profile)]))
+                c_sorted = sorted(costs[list(profile)])
+                e_pay += p * c_sorted[1]
+                e_win += p * c_sorted[0]
+        else:
+            rng = np.random.default_rng(0)
+            draws = rng.choice(costs, size=(20_000, n), p=probs)
+            srt = np.sort(draws, axis=1)
+            e_pay = float(srt[:, 1].mean())
+            e_win = float(srt[:, 0].mean())
+        return {"expected_payment": e_pay, "expected_winner_cost": e_win,
+                "expected_rent": e_pay - e_win}
+
+    def summary(self, title: Optional[str] = None) -> None:
+        s = self.solve()
+        rows = [[fmt_money(c), fmt_prob(p)] for c, p in zip(self.costs, self.probs)]
+        tbl = html.table(["cost type", "probability"], rows)
+        body = (tbl + f"<p>{self.n} firms. <b>Expected payment</b> "
+                f"{fmt_money(s['expected_payment'])} (2nd-lowest cost); winner's "
+                f"expected cost {fmt_money(s['expected_winner_cost'])} → "
+                f"expected rent {fmt_money(s['expected_rent'])}.</p>")
+        html.show(html.card(title or self.name, body))

gtlab/core/correlated.py

@@ -0,0 +1,120 @@
+"""Correlated equilibrium, coarse correlated equilibrium, and no-regret learning."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Tuple
+
+import numpy as np
+
+from .. import solvers
+from .._memo import cached_method
+from ..viz import fmt, html, plots
+
+
+@dataclass
+class CorrelatedGame:
+    """Two-player general-sum game analyzed through the CE / CCE lens."""
+
+    A: np.ndarray
+    B: np.ndarray
+    row_actions: Optional[Sequence[str]] = None
+    col_actions: Optional[Sequence[str]] = None
+    name: str = "Game"
+
+    def __post_init__(self) -> None:
+        self.A = np.asarray(self.A, dtype=float)
+        self.B = np.asarray(self.B, dtype=float)
+        if self.A.shape != self.B.shape:
+            raise ValueError("A and B must have the same shape")
+        m, n = self.A.shape
+        self.row_actions = list(self.row_actions) if self.row_actions else [f"r{i}" for i in range(m)]
+        self.col_actions = list(self.col_actions) if self.col_actions else [f"c{j}" for j in range(n)]
+
+    @property
+    def shape(self) -> Tuple[int, int]:
+        return self.A.shape
+
+    # ── analysis (memoized; keyed by arguments) ──────────────────────────────
+    @cached_method
+    def find_ce(self, maximize: str = "welfare"):
+        return solvers.find_ce(self.A, self.B, maximize)
+
+    @cached_method
+    def find_cce(self, maximize: str = "welfare"):
+        return solvers.find_cce(self.A, self.B, maximize)
+
+    @cached_method
+    def nash(self):
+        return solvers.all_equilibria(self.A, self.B)
+
+    @cached_method
+    def hedge(self, T: int = 2000, seed: int = 0):
+        return solvers.hedge(self.A, self.B, T=T, seed=seed)
+
+    # ── display ──────────────────────────────────────────────────────────────
+    def _mu_table(self, mu: np.ndarray) -> str:
+        m, n = self.shape
+        rows = [[fmt(mu[i, j]) for j in range(n)] for i in range(m)]
+        return html.table(self.col_actions, rows, row_headers=self.row_actions)
+
+    def summary(self, title: Optional[str] = None) -> None:
+        ce = self.find_ce()
+        cce = self.find_cce()
+        body = ""
+        if ce:
+            body += "<b>CE (welfare-max)</b>" + self._mu_table(ce["mu"]) \
+                    + html.note(f"welfare = {fmt(ce['welfare'])}")
+        if cce:
+            body += "<b>CCE (welfare-max)</b>" + self._mu_table(cce["mu"]) \
+                    + html.note(f"welfare = {fmt(cce['welfare'])}")
+        html.show(html.card(title or self.name, body))
+
+    def compare_equilibria(self, title: Optional[str] = None) -> None:
+        """Compare NE, CE, and CCE welfare."""
+        ce = self.find_ce()
+        cce = self.find_cce()
+        rows = []
+        nash = self.nash()
+        if nash:
+            p, q = nash[0]
+            eu_r = float(p @ self.A @ q)
+            eu_c = float(p @ self.B @ q)
+            rows.append(["Nash", fmt(eu_r), fmt(eu_c), fmt(eu_r + eu_c)])
+        if ce:
+            rows.append(["CE", fmt(ce["eu_row"]), fmt(ce["eu_col"]), fmt(ce["welfare"])])
+        if cce:
+            rows.append(["CCE", fmt(cce["eu_row"]), fmt(cce["eu_col"]), fmt(cce["welfare"])])
+        tbl = html.table(["concept", "E[row]", "E[col]", "welfare"], rows)
+        body = tbl + html.note("welfare ordering: NE ≤ CE ≤ CCE (each relaxes the "
+                               "deviation constraints of the previous).")
+        html.show(html.card(title or f"{self.name} — equilibrium concepts", body))
+
+    def explain(self, title: Optional[str] = None) -> None:
+        """Walkthrough: NE ⊆ CE ⊆ CCE, plus the no-regret learning connection."""
+        items = [
+            "<b>Step 1 — Nash equilibrium.</b> Players randomize independently; "
+            "their product distribution must be a mutual best response.",
+            "<b>Step 2 — Correlated equilibrium (CE).</b> A trusted device draws a "
+            "joint action and privately recommends each player's part; obeying must "
+            "be optimal given the conditional belief it induces.",
+            "<b>Step 3 — Coarse correlated equilibrium (CCE).</b> Players commit "
+            "before seeing the recommendation; only ex-ante deviations are checked, "
+            "so CCE ⊇ CE ⊇ NE.",
+            "<b>Step 4 — Learning.</b> If both players run a no-regret algorithm "
+            "(see <code>plot_regret</code>), the empirical play converges to the CCE "
+            "set (Hannan's theorem).",
+        ]
+        html.show(html.card(title or f"{self.name} — equilibrium concepts",
+                            html.steps(items)))
+
+    def plot_regret(self, T: int = 2000, seed: int = 0, title: Optional[str] = None):
+        """Average regret of both players under Hedge → 0 (Hannan)."""
+        res = self.hedge(T=T, seed=seed)
+        return plots.convergence(
+            {"Row avg regret": res["avg_regret_row"],
+             "Col avg regret": res["avg_regret_col"]},
+            target=0.0, title=title or f"{self.name} — no-regret learning",
+            ylabel="average regret")
+
+    def __repr__(self) -> str:
+        return f"CorrelatedGame({self.name!r}, shape={self.shape})"

gtlab/core/extensive_form.py

@@ -0,0 +1,133 @@
+"""Extensive-form games: game trees, backward induction, welfare.
+
+The tree is a dict keyed by node id. Each node is either a decision node::
+
+    {"player": 0, "actions": {"L": "n1", "R": "n2"}}
+
+a chance node::
+
+    {"chance": {"L": (0.5, "n1"), "R": (0.5, "n2")}}
+
+or a terminal node::
+
+    {"payoff": (3.0, 1.0)}
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from .. import solvers
+from .._memo import cached_method
+from ..viz import fmt_vec, html
+
+
+@dataclass
+class ExtensiveFormGame:
+    """A finite extensive-form game over a tree of decision/chance/terminal nodes."""
+
+    tree: Dict[str, Dict[str, Any]]
+    root: str = "root"
+    players: Optional[List[str]] = None
+    name: str = "Extensive-form game"
+
+    def __post_init__(self) -> None:
+        if self.root not in self.tree:
+            raise ValueError(f"root node {self.root!r} not in tree")
+        n_players = self._infer_n_players()
+        self.players = list(self.players) if self.players else [f"P{i+1}" for i in range(n_players)]
+        self._validate()
+
+    def _infer_n_players(self) -> int:
+        n = 2
+        for node in self.tree.values():
+            if "payoff" in node:
+                n = max(n, len(node["payoff"]))
+        return n
+
+    def _validate(self) -> None:
+        for nid, node in self.tree.items():
+            kinds = sum(k in node for k in ("actions", "chance", "payoff"))
+            if kinds != 1:
+                raise ValueError(f"node {nid!r} must be exactly one of "
+                                 "decision/chance/terminal")
+            if "actions" in node:
+                for child in node["actions"].values():
+                    if child not in self.tree:
+                        raise ValueError(f"node {nid!r} → missing child {child!r}")
+
+    # ── backward induction ───────────────────────────────────────────────────
+    @cached_method
+    def backward_induction(self, tol: float = 1e-9) -> Dict[str, Any]:
+        """Compute the subgame-perfect equilibrium by backward induction.
+
+        Returns ``{"value": payoff_at_root, "strategy": {node: action}}``.
+        """
+        strategy: Dict[str, str] = {}
+
+        def value(nid: str) -> np.ndarray:
+            node = self.tree[nid]
+            if "payoff" in node:
+                return np.asarray(node["payoff"], dtype=float)
+            if "chance" in node:
+                out = np.zeros(len(self.players))
+                for prob, child in node["chance"].values():
+                    out += prob * value(child)
+                return out
+            player = node["player"]
+            best_action, best_val = None, None
+            for action, child in node["actions"].items():
+                v = value(child)
+                if best_val is None or v[player] > best_val[player] + tol:
+                    best_action, best_val = action, v
+            strategy[nid] = best_action
+            return best_val
+
+        root_value = value(self.root)
+        return {"value": root_value, "strategy": strategy}
+
+    def terminal_payoffs(self) -> np.ndarray:
+        """All terminal payoff vectors as an ``(N, players)`` array."""
+        return np.array([node["payoff"] for node in self.tree.values()
+                         if "payoff" in node], dtype=float)
+
+    def pareto_frontier(self) -> np.ndarray:
+        return solvers.pareto_frontier(self.terminal_payoffs())
+
+    def social_welfare(self, objective: str = "utilitarian") -> Tuple[np.ndarray, float]:
+        """Best terminal outcome and its welfare score for the given objective."""
+        outcomes = self.terminal_payoffs()
+        idx = solvers.best_outcome(outcomes, objective)
+        score = {"utilitarian": solvers.utilitarian,
+                 "egalitarian": solvers.egalitarian,
+                 "nash": solvers.nash_welfare}[objective](outcomes[idx])
+        return outcomes[idx], float(score)
+
+    # ── display ──────────────────────────────────────────────────────────────
+    def _solution_html(self) -> str:
+        res = self.backward_induction()
+        rows = [[nid, action] for nid, action in res["strategy"].items()]
+        tbl = html.table(["node", "chosen action"], rows)
+        return html.kv([("SPE payoff", fmt_vec(res["value"]))]) + tbl
+
+    def solve(self, title: Optional[str] = None) -> None:
+        html.show(html.card(title or f"{self.name} — backward induction",
+                            self._solution_html()))
+
+    def explain(self, title: Optional[str] = None) -> None:
+        res = self.backward_induction()
+        items = [
+            "<b>Step 1 — Start at the leaves.</b> Terminal nodes already carry payoffs.",
+            "<b>Step 2 — Fold the tree.</b> At each decision node the acting player "
+            "picks the action leading to the child with the highest payoff <i>for "
+            "them</i>; that child's payoff vector propagates up.",
+            f"<b>Step 3 — Read the root.</b> The resulting subgame-perfect equilibrium "
+            f"yields payoff {fmt_vec(res['value'])} (chosen actions tabulated above).",
+        ]
+        body = self._solution_html() + html.steps(items)
+        html.show(html.card(title or f"{self.name} — backward induction", body))
+
+    def __repr__(self) -> str:
+        return f"ExtensiveFormGame({self.name!r}, nodes={len(self.tree)})"