feat(gds-games): integrate Nashpy/pygambit for equilibrium computation

[rororowyourboat]

Summary

GDS-games specifies game structure (players, actions, payoffs, composition) but doesn't compute equilibria. The TerminalCondition metadata in the PD DSL example already declares outcomes (including "Mutual Defection" as Nash equilibrium) but this is hand-annotated, not computed. Adding Nashpy/pygambit integration would bridge the gap from structural specification to computational game theory — making GDS-games actionable.

Motivation

The existing PatternIR already contains the data needed for solver input:

• action_spaces → player action sets
• terminal_conditions → outcome annotations (currently manual)
• Game composition structure → information sets

With a solver backend, we could:

1. Compute Nash equilibria from the structural specification
2. Verify hand-annotated terminal conditions against computed results
3. Analyze dominance, Pareto optimality, and equilibrium characterization

Proposed Approach

Phase 1: Nashpy integration (2-player normal-form games)

• Add nashpy as optional dependency to gds-games or gds-examples
• Build payoff matrices from PatternIR metadata (action_spaces + terminal_conditions)
• Support enumeration algorithm for Nash equilibrium computation
• Cross-reference computed equilibria against declared TerminalConditions

Phase 2: pygambit integration (n-player extensive-form games)

• Add pygambit as optional dependency for richer game representations
• Map OGS composition trees to extensive-form game trees
• Support mixed-strategy equilibria and refinements
• Leverage HierarchyNodeIR for information set construction

Phase 3: Solver-backed verification

• New OGS verification check: "declared equilibria match computed equilibria"
• Automated Pareto optimality classification of terminal conditions
• Dominance analysis as a verification finding

Key Files

• ogs/dsl/pattern.py — TerminalCondition, ActionSpace models (solver inputs)
• ogs/ir/models.py — PatternIR with action_spaces and terminal_conditions
• packages/gds-examples/games/prisoners_dilemma_nash/ — Phase 1 proof-of-concept

Prior Art

• Nashpy — 2-player game solver (support enumeration, vertex enumeration, Lemke-Howson)
• pygambit — n-player game solver (extensive + strategic form)

Labels

enhancement, gds-games

[rororowyourboat]

Phase 1 implementation complete

The packages/gds-examples/games/prisoners_dilemma_nash/ directory implements Phase 1 as described in this issue:

Model (model.py):

• Builds PD from OGS primitives (DecisionGame, CovariantFunction, feedback composition)
• Extracts payoff matrices from PatternIR terminal conditions via regex parsing
• Computes Nash equilibria via Nashpy support enumeration
• Cross-references computed equilibria against declared TerminalConditions
• Full game analysis: dominance detection, Pareto optimality classification

Tests (test_model.py — 21 tests, all passing):

• TestPayoffMatrix — matrix shape, values, PD ordering constraints (T > R > P > S, 2R > T + S)
• TestNashEquilibria — exactly one pure-strategy NE at (Defect, Defect)
• TestEquilibriumVerification — computed NE matches declared "Mutual Defection" terminal condition
• TestDominance — Defect is strictly dominant for both players
• TestParetoOptimality — 3 Pareto optimal outcomes (all except DD), confirms the dilemma
• TestIntegration — full pipeline from OGS primitives → PatternIR → Nash → verify

Interactive notebook (guides/nash_equilibrium/notebook.py):

• Marimo notebook with tabbed OGS visualizations (structural, terminal conditions, by-domain)
• Live payoff matrix display, Nash equilibria computation, dominance and Pareto analysis

What's left for Phase 2+

• nashpy is currently only used in gds-examples — promoting to gds-games as an optional dep would require API design decisions (where does compute_nash_equilibria live?)
• pygambit integration for n-player extensive-form games
• Solver-backed OGS verification check ("declared equilibria match computed equilibria")