LLM Agent Architecture¶

BDPD supports two LLM integration paths: a Flask middleman that bridges the Node.js Platform to any language model, and a direct Python runner that connects LLMs to the card game simulator.

Integration Paths¶

Platform LLM Agent (`bdpd_agent.py`)¶

Platform (Node.js)  →  POST /decide  →  bdpd_agent.py (Flask)  →  LLM API
         ↑                                      ↓
         └──────── JSON response ───────────────┘

The agent joins the arena as an HTTP agent type. On each turn, the platform POSTs the observability-filtered game state to bdpd_agent.py at a configurable callback URL. The Flask server formats the state into a prompt, sends it to the LLM, parses the response, and returns {"harvest": <number>} within the timeout.

Card Game LLM Agent (`cards_ai_play.py`)¶

cards_ai_play.py  →  format game state as prompt  →  OpenAI-compatible API
        ↑                                                   ↓
        └────── parse response, apply harvest ──────────────┘

The card game simulator includes native LLM support. When run with --api-model, one or more archetype players are replaced by LLM agents. The full game state (hand, Forest Deck estimate, Health, opponent actions) is serialised into a structured prompt.

Architecture (`bdpd_agent.py`)¶

The Flask server (≥ v0.4.0) runs on a configurable port (default 5001) and exposes a single endpoint:

POST /decide
Content-Type: application/json

{
  "playerId": "alice",
  "observation": {
    "turn": 5,
    "commonsStock": 87.3,
    "myWealth": 34.1,
    "othersHarvest": [3.2, 4.1],
    "inbox": [...],
    "pacts": [...],
    "reputation": [...]
  }
}

→ Response: { "harvest": 12.5 }

The platform builds this payload in arena.js (_httpDecision). playerId identifies the agent instance; all game state is nested inside observation.

Key Features¶

Feature	Description
Conversation memory	Maintains turn history as a conversation log; older turns are summarised to stay within context limits
Archetype nudges	Injects strategy-specific instructions into the system prompt (`--nudge`)
Noisy observations	Passes through the platform's observability-filtered state (noise already applied)
Adaptive fallback	On timeout or parse error, returns \(0.2 \times \text{capacity}(w)\)
Multi-model support	Local llama-server or any OpenAI-compatible API
LLM trace logging	All prompts and responses are logged to JSONL for analysis

Modes¶

The LLM integration supports three operating modes, set via LLM_MODE environment variable:

local (llama-server)api (cloud)none (heuristic only)

LLM_MODE=local MODEL_PATH=/path/to/model.gguf ./scripts/run_arena.sh

Runs a local llama-server instance bound to localhost:10000. No API key required. See Local Models.

LLM_MODE=api BDPD_API_KEY=sk-... ./scripts/run_arena.sh

Connects to any OpenAI-compatible API (DeepSeek, OpenAI, etc.). See Cloud APIs.

LLM_MODE=none ./scripts/run_arena.sh

Runs 4 built-in agents only — useful for smoke tests and baseline comparisons.

Card Game LLM Configuration¶

When using cards_ai_play.py, LLM agents are configured via CLI:

python agents/cards_ai_play.py \
  --deck1 stranger --deck2 warrior \
  --cards cards/cards_v03.json \
  --games 5 \
  --api-model deepseek-v4-flash \
  --api-base-url https://api.deepseek.com \
  --forest-noise 0.05 \
  --nudge \
  --lock-defection \
  --history-window 5

Flag	Description
`--api-model`	Model name (e.g. `deepseek-v4-flash`)
`--api-base-url`	API endpoint
`--forest-noise FLOAT`	Gaussian noise on Forest Deck estimate (LLM agents only)
`--nudge`	Enable archetype-specific behavioural nudges
`--lock-defection`	Prevent voluntary Stranger-King defection (for parametric sweeps)
`--history-window N`	Number of past turns to include in prompt context

Comparison: Heuristic vs LLM Agents¶

Property	Heuristic Agents	LLM Agents
Determinism	Fully deterministic given same seed	Stochastic (temperature-dependent)
Cost	~0 (local CPU)	API credits or GPU compute
Speed	Microseconds per decision	Seconds per decision
Reasoning	Fixed formula	Chain-of-thought natural language
Strategic adaptation	Parameterised reactivity only	Can form novel strategies from prompt
Awareness	None	Can verbalise collapse risk
Restraint	Guaranteed by formula	Requires hard constraints (Collapse Brake)

Key finding: LLM agents exhibit awareness without restraint — they verbalise imminent collapse yet continue extracting. This pattern emerged spontaneously across single-model case studies and mirrors the heuristic results: institutional constraints (hard rules) outperform strategic intent (prompt guidance).

See Prompt Design for the engineering lessons derived from LLM case studies.