Import documentation: Shayan1/Prod/HOW.txt

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

Shayan1/Prod/HOW.txt

@@ -0,0 +1,64 @@
+Nash Equilibrium Solver & Simulator - Extended Usage Guide
+==========================================================
+
+This tool is a comprehensive command-line engine for solving, inspecting, and simulating normal-form (simultaneous-move) games like the Prisoner's Dilemma, Matching Pennies, or completely custom scenarios.
+
+0. Environment Setup
+--------------------
+Always run the tool using the local virtual environment to ensure dependencies (`numpy`, `matplotlib`, `anthropic`, etc.) are resolved correctly:
+
+    .venv/bin/python main.py [ARGS]
+
+1. Core Pipeline
+----------------
+- Data-Driven Games: Games are defined purely in JSON (players, strategies, payoff tensors). The underlying math generalizes to any number of players (N-player) automatically.
+- Theoretical Solvers:
+  * Pure Nash Equilibrium: Brute-force evaluates every profile to find states where no player can profitably deviate.
+  * Mixed Nash Equilibrium: Uses support enumeration to find probabilistic equilibria (2-player non-degenerate games only).
+
+2. Advanced Features & Dynamics
+-------------------------------
+- Matrix Reduction (IESDS): Use `--reduce`. It iteratively finds and deletes strictly dominated strategies (moves that are mathematically always worse than another option). This shrinks the game matrix to its "Rationalizable Core", drastically speeding up complex simulations and stripping away noise.
+- Inspection Mode: Use `--inspect` to bypass simulations. It prints a beautifully formatted, color-coded payoff matrix and automatically scans to identify if players have a dominant strategy.
+- Evolutionary Simulation: Use `--sim-type evolutionary`. Instead of modeling discrete individual choices, this tracks an infinite population using Replicator Dynamics. Strategies that score above the population average grow in frequency, creating smooth evolutionary trajectories plotted to a PNG.
+- Pluggable Agent Models: Use `--player <type>` to change how discrete agents play:
+  * `best_response` (default): Chooses the mathematically optimal move against the opponents' historical distribution (fictitious play).
+  * `q_learning`: Decentralized reinforcement learning agents that explore and exploit expected rewards over time.
+  * `regret_matching`: Hart & Mas-Colell algorithm where agents play proportionally to their cumulative regret (converges to Coarse Correlated Equilibrium).
+  * `softmax`: Probabilistic best response using Boltzmann exploration (adds "noise" or temperature to choices).
+  * `llm`: Queries Claude (Anthropic API) dynamically to reason about the game history and pick the next move.
+- Verbose Debugging: Add `--verbose` to any simulation to output the internal reasoning of agents (e.g., Q-values, expected payoffs, or LLM internal thoughts) round-by-round.
+
+3. Example Commands
+-------------------
+# Inspect a game's properties and dominant strategies (no simulation)
+.venv/bin/python main.py --game games/pricing.json --inspect
+
+# Shrink a game using IESDS, then inspect the reduced core
+.venv/bin/python main.py --game games/pricing.json --reduce --inspect
+
+# Standard Fictitious Play simulation for 30 rounds
+.venv/bin/python main.py --game games/pricing.json --rounds 30
+
+# Simulate Q-learning agents with verbose reasoning logs
+.venv/bin/python main.py --game games/rock_paper_scissors.json --player q_learning --rounds 100 --verbose
+
+# Run Evolutionary Replicator Dynamics and output a population chart
+.venv/bin/python main.py --game games/matching_pennies.json --sim-type evolutionary --rounds 50
+
+# Play using LLM agents (requires `export ANTHROPIC_API_KEY="sk-..."`)
+.venv/bin/python main.py --game games/pricing.json --player llm --rounds 5 --verbose
+
+4. Creating Your Own Games
+--------------------------
+Just create a new JSON file in `games/`. The engine handles the rest natively.
+Example shape:
+{
+  "players": ["P1", "P2"],
+  "strategies": [["Cooperate", "Defect"], ["Cooperate", "Defect"]],
+  "payoffs": [
+    [[3, 0], [5, 1]],  # P1's payoffs (rows=P1, cols=P2)
+    [[3, 5], [0, 1]]   # P2's payoffs
+  ]
+}
+No code changes are needed for 3+ players; just add another dimension to the payoff arrays to match the strategy counts!