feat: Social Deduction Game demo (#36)

* feat: scaffold social deduction game — config, template, README

Add the supporting files for the Undercover/Spy Words social deduction
game demo: Ollama config, description-phase prompt template, and README
with hypothesis, game mechanics, and setup instructions.

* feat: social deduction game — core game logic and .nlogox model

Implement the full Undercover/Spy Words social deduction game with:
- Circle layout for N players (4-8), one randomly assigned as spy
- Description phase using llm:chat-with-template for word clues
- Voting phase using llm:choose for constrained spy identification
- Elimination with tie-breaking, win condition checks
- 15 word pairs across 3 difficulty tiers
- Cumulative stats tracking across games (detection rate, wins)
- Vote plot and detection rate plot
- Word leak protection and LLM error fallbacks

* fix: nlogox widget attributes and template variable format

- Add disableUntilTicks to buttons (required attribute)
- Add fontSize to monitors (required attribute)
- Fix plot attributes to camelCase (xMin/xMax/yMin/yMax/autoPlotX/autoPlotY)
- Fix llm:chat-with-template to use nested [key value] pairs
- Use llama3.2:3b model name in config

* feat: visual polish — noir theme, distinct colors, vote arrows, phase indicator

- Fix player visibility: radius 10, -90° offset (12 o'clock start), size 4.0
- Distinct player colors: 8-color palette with base-color variable
- Dark noir background: charcoal gradient + dark red circular table
- Vote arrows: directed links from voter to target in voter's color
- Center phase indicator: shows round, phase, elimination, and win state
- Spy reveal: size 5.0, bright red, all words shown on reveal
- Eliminated players: muted color (base-color - 4) instead of gray
- Correct link shape XML for NetLogo 7.0.3 format

* refactor: extract vote prompt to YAML template, use base-color in plot

- Add vote-template.yaml with system/template structure matching description template
- Replace inline vote prompt with llm:chat-with-template call
- Validate LLM response against alive player names, fallback to llm:choose
- Update Votes Per Round plot to use per-player base-color instead of red/sky
- Update info tab to reflect template-based voting

* fix: rewrite prompts for better gameplay — concrete clues, no self-votes

Description template:
- Demand distinguishing clues: "something TRUE about your word that would NOT be true for a similar word"
- Ban vague phrases and "I notice" narration style
- Add good vs bad clue examples for calibration
- Enforce one sentence under 20 words

Vote template:
- Add explicit self-vote prevention: "You CANNOT vote for {player_name}"
- Reinforce constraint in both system prompt and template
- Guide analytical comparison of clues

Voting code:
- Separate template vote and llm:choose fallback into independent carefully blocks
- Prevent cascading errors when template returns self-vote

* fix: enforce unique indirect clues, raise temperature for variety

- Rewrite description template: demand indirect associations, ban obvious properties
- Add good/bad clue examples for calibration
- Explicitly label transcript as "DO NOT repeat any of these"
- Ban common openings ("Best enjoyed", "Often enjoyed")
- Bump temperature to 0.8 in config for more diverse outputs

Author: JNK234

.gitignore

@@ -50,6 +50,7 @@ commands/
 config.txt
 config-*.txt
 !demos/provider-sensitivity/config-multi-provider.txt
+!demos/social-deduction-game/config.txt
 *.env
 *.env.*
 *.secrets*

demos/social-deduction-game/README.md

@@ -0,0 +1,57 @@
+# Social Deduction Game (Undercover / Spy Words)
+
+## Hypothesis
+
+LLM agents will correctly identify spies at below-chance accuracy because they struggle to integrate cross-round description patterns into coherent suspicion, while LLM spies will be caught faster than chance because they produce descriptions that are subtly misaligned with the majority word.
+
+## Source
+
+Inspired by LLMArena (ACL 2024) — social deduction games as an evaluation framework for LLM reasoning and theory of mind.
+
+## Game Mechanics
+
+1. **Setup**: N players arranged in a circle. One is randomly assigned the "spy word"; the rest share the "regular word". Words are similar but distinct (e.g., apple vs pear).
+2. **Description Phase**: Each alive player describes their word in 1-2 sentences without saying it.
+3. **Voting Phase**: Each alive player votes for who they think is the spy based on descriptions.
+4. **Elimination**: The player with the most votes is eliminated.
+5. **Win Condition**: Regulars win if the spy is eliminated. The spy wins if only 2 players remain or max rounds are reached.
+
+## Word Pairs (3 difficulty tiers)
+
+| Difficulty | Regular Word | Spy Word |
+|-----------|-------------|----------|
+| High (hard to detect) | apple/guitar/coffee/pillow/ocean | pear/ukulele/tea/cushion/lake |
+| Medium | bicycle/painting/castle/penguin/candle | motorcycle/photograph/mansion/duck/flashlight |
+| Low (easy to detect) | airplane/forest/piano/book/snowflake | submarine/desert/drums/television/raindrop |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `social-deduction-game.nlogox` | Main NetLogo model |
+| `config.txt` | LLM provider configuration (default: Ollama) |
+| `description-template.yaml` | Prompt template for description phase |
+| `README.md` | This file |
+
+## Setup
+
+1. Install the LLM extension (see main repo README)
+2. Configure `config.txt` with your preferred provider
+3. Open `social-deduction-game.nlogox` in NetLogo 7.0.3+
+4. Click **Setup** to initialize players
+5. Click **Go** to run the full game, or **Step** for one round at a time
+
+## Interface Controls
+
+- **num-players**: Number of players (4-8, default 6)
+- **max-rounds**: Maximum rounds before spy wins (3-10, default 6)
+- **difficulty-level**: Word pair similarity ("low"/"medium"/"high")
+- **show-descriptions?**: Display description speech bubbles
+- **show-votes?**: Display vote targets
+- **auto-reveal?**: Reveal spy identity when game ends
+
+## Expected Results
+
+- **Detection rate**: Expected below 1/N chance (where N = number of players)
+- **Spy survival**: Spy descriptions tend to be subtly "off", leading to faster-than-chance detection in some rounds, but overall detection accuracy remains low because regulars struggle to synthesize cross-round patterns
+- **Difficulty effect**: Higher difficulty (more similar words) should decrease detection rate

demos/social-deduction-game/config.txt

@@ -0,0 +1,5 @@
+provider=ollama
+model=llama3.2:3b
+temperature=0.4
+max_tokens=80
+timeout_seconds=30

demos/social-deduction-game/description-template.yaml

@@ -0,0 +1,29 @@
+system: |
+  You are {player_name} in a social deduction game called Undercover.
+  Several players each have a secret word. Most share the SAME word, but one player (the spy) has a DIFFERENT but similar word.
+  Each round you give a clue about your word. After clues, players vote to eliminate the suspected spy.
+
+  CRITICAL RULES:
+  - Your clue must be DIFFERENT from every clue already given. Read the previous clues carefully and say something NEW.
+  - Be INDIRECT — describe a memory, association, or situation involving your word, NOT its obvious properties
+  - Do NOT describe what it looks/tastes/smells like directly
+  - Do NOT say the word itself
+  - Write exactly ONE sentence, under 20 words
+  - Do NOT start with "Best enjoyed" or "Often enjoyed" or "My word"
+
+  GOOD CLUE EXAMPLES (indirect, subtle):
+  - "Some people collect fancy versions of these from around the world."
+  - "You might see one of these at a birthday party or during a power outage."
+
+  BAD CLUE EXAMPLES (too obvious, reveals the word):
+  - "It is brewed in a pot every morning" — too obvious
+  - "It has a warm glow and a wick" — basically says the word
+
+template: |
+  Your secret word is: {my_word}
+  Round {round_number}.
+
+  Previous clues from all players (DO NOT repeat any of these):
+  {transcript}
+
+  Think of a unique angle or personal association with your word that nobody has mentioned yet. Write ONE indirect, subtle clue under 20 words.