Import documentation: Shayan1/Prod/docs/superpowers/specs/2026-07-07-advanced-game-theory-design.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.

Shayan1/Prod/docs/superpowers/specs/2026-07-07-advanced-game-theory-design.md

@@ -0,0 +1,49 @@
+# Advanced Game Theory Upgrades Design Document
+
+## Objective
+Implement Iterated Elimination of Strictly Dominated Strategies (IESDS), an LLM-driven player model, and a full Evolutionary Game Theory (Replicator Dynamics) simulation mode, maintaining the project's dependency constraints and N-player support.
+
+## 1. Iterated Elimination (IESDS)
+### Architecture (`nash/solver.py`)
+- **`reduce_game(game) -> tuple[Game, list[str]]`**:
+  - Iteratively searches for strictly dominated strategies for all players.
+  - When found, it slices the `numpy` payoff tensors (using `np.delete`) to remove the strategy.
+  - Returns a new, reduced `Game` object and a list of string logs describing the eliminations (e.g., `"Player 'Company A' eliminated dominated strategy 'High'"`).
+  - Stops when a full pass over all players yields no new eliminations (the "Rationalizable Core").
+
+### CLI Integration (`main.py`)
+- Add `--reduce` flag.
+- If `--reduce` is passed, `main.py` replaces the loaded game with the reduced game *before* solving or simulating.
+- If used with `--inspect`, the CLI prints the step-by-step elimination logs, followed by the final reduced payoff matrix.
+
+## 2. LLM-Driven Player
+### Architecture (`nash/players.py`)
+- **`LLMPlayer(BasePlayer)`**:
+  - Requires the `anthropic` client (already a project dependency).
+  - In `choose(history)`, constructs a prompt containing: the game matrix, the player's specific role, and the formatted history of previous rounds.
+  - Requests JSON output containing a `reasoning` string and an integer `strategy_index`.
+  - Parses the index to make the move.
+  - Calls `self.debug_logger` (if provided via `--verbose`) to print the LLM's `reasoning` live to the terminal.
+- **CLI**: Exposed via `--player llm`.
+
+## 3. Evolutionary Dynamics (Replicator Dynamics)
+### Architecture (`nash/simulation.py`)
+- **`EvolutionarySimulation`**:
+  - A new class parallel to `Simulation`.
+  - State is tracked as a list of population vectors (one probability distribution per player).
+  - Initializes with uniform distribution or slightly randomized weights.
+  - **Math**: Uses discrete-time replicator equations. Let $x_i$ be the proportion playing strategy $i$, $u_i$ the expected payoff of strategy $i$, and $\bar{u}$ the average payoff of the population. The update is: $x_i(t+1) = x_i(t) \times \frac{u_i}{\bar{u}}$ (with appropriate scaling to avoid negative division if payoffs are negative, e.g., by shifting payoffs positively).
+- **Visualization (`nash/visualize.py`)**:
+  - Add `plot_evolutionary_trajectories(game, evo_sim, save_path)`.
+  - Plots continuous floating-point proportions over rounds, rather than rolling averages of discrete events.
+
+### CLI Integration
+- Add `--sim-type {agents, evolutionary}` to `main.py` (default: `agents`).
+- If `evolutionary`, bypass standard player instantiation, run `EvolutionarySimulation`, and use the new trajectory plotter.
+
+## Data Flow
+1. Load game -> Apply IESDS reduction if `--reduce`.
+2. Inspect -> Print reduction logs, final matrix, exit.
+3. Sim Mode -> Switch on `--sim-type`.
+   - `agents`: Runs existing `Simulation`. If `--player llm`, uses Anthropic API to decide moves.
+   - `evolutionary`: Runs `EvolutionarySimulation` with replicator math.