Upload folder using huggingface_hub

README.md

@@ -10,11 +10,13 @@ tags:
   - openenv
 ---
 
-# KantBench: 90+ Game Theory Environments for LLM Training
+# KantBench: 93 Game Theory Environments for LLM Training
 
 A comprehensive game theory environment for training and evaluating LLM strategic reasoning via OpenEnv. Supports GRPO/DPO training with the environment as a reward oracle.
 
-## Games (90+)
+## Games (93)
+
+### 2-Player Games (90)
 
 | Category | Examples | Count |
 |---|---|---|
@@ -25,22 +27,30 @@ A comprehensive game theory environment for training and evaluating LLM strategi
 | **Auctions & Contests** | First-Price, Vickrey, All-Pay, Colonel Blotto, Tullock Contest | 10+ |
 | **Sequential** | Ultimatum, Trust, Centipede, Stackelberg, Dictator | 6 |
 
+### N-Player Games (3)
+
+| Game | Players | Description |
+|---|---|---|
+| `nplayer_public_goods` | 5 | Each player contributes from an endowment; pot is multiplied and split equally |
+| `nplayer_volunteer_dilemma` | 5 | At least one must volunteer for everyone to benefit; volunteers pay a cost |
+| `nplayer_el_farol` | 5 | Attend a bar that's fun when uncrowded but unpleasant when full |
+
 ## Opponent Strategies (17)
 
 `random`, `always_cooperate`, `always_defect`, `tit_for_tat`, `tit_for_two_tats`, `grudger`, `pavlov`, `suspicious_tit_for_tat`, `generous_tit_for_tat`, `adaptive`, `mixed`, `ultimatum_fair`, `ultimatum_low`, `trust_fair`, `trust_generous`, `public_goods_fair`, `public_goods_free_rider`
 
 ## Quick Start
 
+### 2-Player Game
+
 ```python
 from KantBench import KantBenchAction, KantBenchEnv
 
 with KantBenchEnv(base_url="https://openenv-community-kantbench.hf.space") as env:
-    # Reset with a specific game and opponent strategy
     result = env.reset(game="prisoners_dilemma", strategy="tit_for_tat")
     print(f"Game: {result.observation.game_name}")
     print(f"Moves: {result.observation.available_moves}")
 
-    # Play rounds until done
     while not result.done:
         result = env.step(KantBenchAction(move="cooperate"))
         print(f"Round {result.observation.round_number}: "
@@ -51,12 +61,30 @@ with KantBenchEnv(base_url="https://openenv-community-kantbench.hf.space") as en
     print(f"Final score: {result.observation.cumulative_score}")
 ```
 
+### N-Player Game
+
+```python
+with KantBenchEnv(base_url="https://openenv-community-kantbench.hf.space") as env:
+    result = env.reset(game="nplayer_public_goods", strategy="random")
+    print(f"Players: {result.observation.num_players}")
+
+    while not result.done:
+        result = env.step(KantBenchAction(move="contribute_10"))
+        print(f"Round {result.observation.round_number}: "
+              f"all scores={result.observation.all_scores}")
+
+    print(f"Final scores: {result.observation.all_scores}")
+```
+
 ## Reset Parameters
 
 ```python
 # Specific game and strategy
 result = env.reset(game="stag_hunt", strategy="grudger")
 
+# N-player game (strategy applies to all opponents)
+result = env.reset(game="nplayer_volunteer_dilemma", strategy="random")
+
 # Random game and strategy (default)
 result = env.reset()
 ```
@@ -66,26 +94,29 @@ result = env.reset()
 - **Web Interface** at `/web` — Interactive UI for exploring the environment
 - **API Docs** at `/docs` — Full OpenAPI/Swagger interface
 - **Health Check** at `/health` — Container health monitoring
-- **WebSocket** at `/ws` — Persistent session endpoint
+- **WebSocket** at `/ws` — Persistent session endpoint (reset/step with state)
 
 ## Environment Details
 
 ### Action
 
 **KantBenchAction**: Single field
-- `move` (str) — Your move (e.g. `"cooperate"`, `"defect"`, `"hawk"`, `"produce_5"`)
+- `move` (str) — Your move (e.g. `"cooperate"`, `"defect"`, `"hawk"`, `"contribute_10"`)
 
 ### Observation
 
 **KantBenchObservation**: Full round result and episode state
 - `game_name`, `game_description` — Current game info
 - `available_moves` — Valid moves for this game
-- `your_move`, `opponent_move` — Moves played this round
-- `your_payoff`, `opponent_payoff` — Payoffs this round
+- `your_move`, `opponent_move` — Moves played this round (2-player)
+- `your_payoff`, `opponent_payoff` — Payoffs this round (2-player)
 - `cumulative_score` — Your total score
 - `round_number`, `max_rounds` — Episode progress
 - `opponent_strategy` — Opponent strategy name
 - `history` — Full round-by-round history
+- `num_players` — Number of players (N-player games only, `null` for 2-player)
+- `player_index` — Your player index (N-player games only)
+- `all_scores` — Scores for all players (N-player games only)
 
 ## Deployment
 

client.py

@@ -10,7 +10,7 @@ from .models import KantBenchAction, KantBenchObservation
 
 
 class KantBenchEnv(
-    EnvClient[KantBenchAction, KantBenchObservation]
+    EnvClient[KantBenchAction, KantBenchObservation, State]
 ):
     """
     Client for the KantBench game theory environment.

common/games_meta/game_tags.py

@@ -18,6 +18,9 @@ from constant_definitions.batch4.tag_constants import (
     MARKET_COMPETITION, EVOLUTIONARY, SECURITY, NETWORK,
     # Action space
     BINARY_CHOICE, SMALL_CHOICE, LARGE_CHOICE,
+    # Multiplayer dimensions
+    MULTIPLAYER, COALITION_FORMATION,
+    PENALTY_ENFORCEMENT, BINDING_ENFORCEMENT, META_GOVERNANCE,
     # Category grouping
     CATEGORIES,
 )
@@ -158,6 +161,20 @@ GAME_TAGS: dict[str, frozenset[str]] = {
     "risk_dominance": frozenset({NO_COMMUNICATION, COMPLETE_INFORMATION, SIMULTANEOUS, SINGLE_SHOT, COORDINATION, EVOLUTIONARY, BINARY_CHOICE}),
     "threshold_public_goods": frozenset({NO_COMMUNICATION, COMPLETE_INFORMATION, SIMULTANEOUS, SINGLE_SHOT, SYMMETRIC_PAYOFF, SOCIAL_DILEMMA, LARGE_CHOICE}),
     "evolutionary_pd": frozenset({NO_COMMUNICATION, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, EVOLUTIONARY, BINARY_CHOICE}),
+
+    # ── N-player games (common/games_meta/nplayer_games.py) ──
+    "nplayer_public_goods": frozenset({NO_COMMUNICATION, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, SOCIAL_DILEMMA, LARGE_CHOICE, MULTIPLAYER}),
+    "nplayer_volunteer_dilemma": frozenset({NO_COMMUNICATION, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, SOCIAL_DILEMMA, BINARY_CHOICE, MULTIPLAYER}),
+    "nplayer_el_farol": frozenset({NO_COMMUNICATION, INCOMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, ANTI_COORDINATION, SOCIAL_DILEMMA, BINARY_CHOICE, MULTIPLAYER}),
+
+    # ── Coalition games (common/games_meta/coalition_config.py) ──
+    "coalition_cartel": frozenset({CHEAP_TALK, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, MARKET_COMPETITION, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, PENALTY_ENFORCEMENT, META_GOVERNANCE}),
+    "coalition_alliance": frozenset({CHEAP_TALK, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, SOCIAL_DILEMMA, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, META_GOVERNANCE}),
+    "coalition_voting": frozenset({BINDING_COMMITMENT, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, VOTING, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, BINDING_ENFORCEMENT, META_GOVERNANCE}),
+    "coalition_ostracism": frozenset({CHEAP_TALK, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, ASYMMETRIC_PAYOFF, SOCIAL_DILEMMA, SMALL_CHOICE, MULTIPLAYER, COALITION_FORMATION, PENALTY_ENFORCEMENT, META_GOVERNANCE}),
+    "coalition_resource_trading": frozenset({CHEAP_TALK, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, MARKET_COMPETITION, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, META_GOVERNANCE}),
+    "coalition_rule_voting": frozenset({BINDING_COMMITMENT, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, VOTING, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, BINDING_ENFORCEMENT, META_GOVERNANCE}),
+    "coalition_commons": frozenset({CHEAP_TALK, COMPLETE_INFORMATION, SIMULTANEOUS, REPEATED, SYMMETRIC_PAYOFF, SOCIAL_DILEMMA, BINARY_CHOICE, MULTIPLAYER, COALITION_FORMATION, PENALTY_ENFORCEMENT, META_GOVERNANCE}),
 }
 
 

constant_definitions/batch4/tag_constants.py

@@ -40,6 +40,19 @@ BINARY_CHOICE = "binary_choice"
 SMALL_CHOICE = "small_choice"
 LARGE_CHOICE = "large_choice"
 
+# ── Player count ──
+MULTIPLAYER = "multiplayer"
+
+# ── Coalition ──
+COALITION_FORMATION = "coalition_formation"
+
+# ── Enforcement ──
+PENALTY_ENFORCEMENT = "penalty_enforcement"
+BINDING_ENFORCEMENT = "binding_enforcement"
+
+# ── Governance ──
+META_GOVERNANCE = "meta_governance"
+
 # ── Grouped by dimension (for programmatic enumeration) ──
 CATEGORIES: dict[str, list[str]] = {
     "communication": [
@@ -63,4 +76,8 @@ CATEGORIES: dict[str, list[str]] = {
     "action_space": [
         BINARY_CHOICE, SMALL_CHOICE, LARGE_CHOICE,
     ],
+    "player_count": [MULTIPLAYER],
+    "coalition": [COALITION_FORMATION],
+    "enforcement": [PENALTY_ENFORCEMENT, BINDING_ENFORCEMENT],
+    "governance": [META_GOVERNANCE],
 }