AI Players Configuration¶

All AI Player settings are configured via environment variables with the MAID_AI_PLAYERS__ prefix, or through a .env file. Settings are loaded by the AIPlayerSettings class using pydantic-settings.

Global Settings¶

Core¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__ENABLED`	`bool`	`false`	Master switch for the AI Player system. When disabled, no agents are spawned or ticked.
`MAID_AI_PLAYERS__MAX_AGENTS`	`int`	`10`	Maximum number of concurrent AI Players. Spawning beyond this limit raises `MaxAgentsExceededError`.
`MAID_AI_PLAYERS__AUTO_SPAWN_ON_START`	`bool`	`false`	Automatically spawn agents when the server starts.
`MAID_AI_PLAYERS__AUTO_SPAWN_COUNT`	`int`	`0`	Number of agents to auto-spawn on startup. Only used when `AUTO_SPAWN_ON_START` is `true`.

Models¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER`	`str`	`chatjimmy`	LLM provider for Layer 2 (executive) operations — perception, routine action selection, replanning.
`MAID_AI_PLAYERS__CHEAP_MODEL_NAME`	`str`	`llama3.1-8B`	Model name for cheap-tier operations.
`MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER`	`str`	`anthropic`	LLM provider for Layer 3 (deliberative) operations — goal generation, strategic reflection, memory consolidation.
`MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME`	`str`	`claude-sonnet-4`	Model name for expensive-tier operations.
`MAID_AI_PLAYERS__EMBEDDING_PROVIDER`	`str`	`anthropic`	Provider for embedding generation (memory retrieval).
`MAID_AI_PLAYERS__EMBEDDING_MODEL`	`str`	`text-embedding-3-small`	Embedding model name.
`MAID_AI_PLAYERS__EMBEDDING_DIMENSIONS`	`int`	`1536`	Embedding vector dimensions.
`MAID_AI_PLAYERS__EMBEDDING_FALLBACK`	`str`	`tfidf`	Fallback when embedding provider is unavailable. Options: `tfidf`.

Timing¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__COGNITIVE_TICK_INTERVAL`	`float`	`3.0`	Seconds between Layer 2 cognitive ticks.
`MAID_AI_PLAYERS__OBSERVATION_BATCH_INTERVAL`	`float`	`5.0`	Seconds to batch observations before processing. Reduces LLM calls by grouping rapid events.
`MAID_AI_PLAYERS__ACTION_MIN_DELAY`	`float`	`1.0`	Minimum seconds between actions. Prevents inhuman command spam.
`MAID_AI_PLAYERS__ACTION_MAX_DELAY`	`float`	`5.0`	Maximum seconds between actions. Adds human-like timing variance.
`MAID_AI_PLAYERS__IDLE_TICK_INTERVAL`	`float`	`10.0`	Seconds between ticks when the agent has no active plan. Reduces cost during idle periods.

Budget¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__GLOBAL_MAX_COST_PER_HOUR`	`float`	`1.0`	Maximum hourly spend (USD) across all agents combined.
`MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR`	`float`	`0.10`	Default sustained hourly cost limit per agent (USD).
`MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_BURST`	`float`	`0.20`	Elevated hourly limit during the first 10 minutes after spawn. Allows initial exploration burst.
`MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_SUSTAINED`	`float`	`0.12`	Hourly limit after the 10-minute warmup period.
`MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_DAY`	`float`	`2.50`	Daily cost cap per agent (USD).
`MAID_AI_PLAYERS__BUDGET_POLICY`	`str`	`enforce`	How to handle budget violations. See Budget Configuration below.

Memory¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__MAX_EPISODIC_MEMORIES`	`int`	`1000`	Maximum episodic memories (past events) per agent. Oldest are pruned.
`MAID_AI_PLAYERS__MAX_SEMANTIC_MEMORIES`	`int`	`500`	Maximum semantic memories (learned facts) per agent.
`MAID_AI_PLAYERS__MAX_PROCEDURAL_MEMORIES`	`int`	`200`	Maximum procedural memories (command sequences) per agent.
`MAID_AI_PLAYERS__MAX_REFLECTIVE_MEMORIES`	`int`	`100`	Maximum reflective memories (meta-insights) per agent.
`MAID_AI_PLAYERS__CONSOLIDATION_INTERVAL_TICKS`	`int`	`100`	Cognitive ticks between memory consolidation passes.
`MAID_AI_PLAYERS__MEMORY_DECAY_ENABLED`	`bool`	`true`	Enable time-based memory decay. When enabled, unreinforced memories lose salience over time.

Planning¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__SESSION_GOAL_COUNT`	`int`	`3`	Number of high-level goals generated per session.
`MAID_AI_PLAYERS__PHASE_PLAN_REVIEW_INTERVAL`	`float`	`1800.0`	Seconds between phase plan reviews (default: 30 minutes).
`MAID_AI_PLAYERS__TASK_PLAN_MAX_STEPS`	`int`	`20`	Maximum steps in a single task plan.

Reflection¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__REFLECTION_IMPORTANCE_THRESHOLD`	`float`	`150.0`	Cumulative importance score that triggers a reflection.
`MAID_AI_PLAYERS__REFLECTION_PERIODIC_INTERVAL`	`float`	`300.0`	Seconds between periodic reflections (default: 5 minutes).
`MAID_AI_PLAYERS__MAX_ABSTRACTION_DEPTH`	`int`	`3`	Maximum depth of reflective abstraction (reflections on reflections).

Safety¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__ACTION_RATE_LIMIT_PER_MINUTE`	`int`	`30`	Maximum commands an agent can issue per minute.
`MAID_AI_PLAYERS__ACTION_BLACKLIST`	`list[str]`	`[]`	Commands that AI Players are never allowed to execute.
`MAID_AI_PLAYERS__CONTENT_FILTERING_ENABLED`	`bool`	`true`	Enable content safety filtering on AI Player output.
`MAID_AI_PLAYERS__STUCK_DETECTION_THRESHOLD`	`int`	`10`	Number of repeated identical actions before triggering stuck recovery.

Scheduling¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__MAX_CONCURRENT_LLM_CALLS`	`int`	`5`	Maximum simultaneous LLM API calls across all agents.
`MAID_AI_PLAYERS__SCHEDULING_STRATEGY`	`str`	`adaptive`	How to distribute cognitive ticks. Options: `round_robin`, `priority`, `adaptive`.

Scheduling Strategies

round_robin — Each agent ticks in order. Simple and fair.
priority — Active agents tick before paused ones, ordered by least recently active.
adaptive (default) — Groups co-located agents (same room) to maximize shared perception cache hits, then orders by least recently active.

Shared Knowledge¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__SHARED_KNOWLEDGE_ENABLED`	`bool`	`true`	Allow agents to share discovered facts (map data, entity info).
`MAID_AI_PLAYERS__SHARED_PERCEPTION_ENABLED`	`bool`	`true`	Allow co-located agents to share perception results (saves LLM calls).
`MAID_AI_PLAYERS__SHARED_PERCEPTION_CACHE_TTL`	`float`	`30.0`	Seconds before shared perception cache entries expire.

Persistence¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__SAVE_INTERVAL_SECONDS`	`float`	`60.0`	Seconds between automatic state saves.
`MAID_AI_PLAYERS__PERSIST_ON_DESPAWN`	`bool`	`true`	Save agent state when despawning.
`MAID_AI_PLAYERS__RESTORE_ON_SPAWN`	`bool`	`true`	Restore saved state when spawning a previously persisted agent.

Observability¶

Variable	Type	Default	Description
`MAID_AI_PLAYERS__THOUGHT_TRACE_ENABLED`	`bool`	`true`	Log the agent's internal reasoning (thought traces).
`MAID_AI_PLAYERS__THOUGHT_TRACE_RETENTION_HOURS`	`int`	`24`	Hours to retain thought trace data before pruning.
`MAID_AI_PLAYERS__METRICS_ENABLED`	`bool`	`true`	Emit Prometheus-style metrics for AI Player operations.
`MAID_AI_PLAYERS__DECISION_LOG_ENABLED`	`bool`	`false`	Log every decision with full context. Verbose — use for debugging only.

Per-Agent Configuration¶

When spawning an AI Player programmatically, you can override global defaults on a per-agent basis using AIPlayerConfig:

Field	Type	Default	Description
`name`	`str`	(required)	Display name for the AI Player.
`ai_player_id`	`str \\| None`	`None`	Explicit ID. Auto-generated as `ai-<hex>` if omitted.
`personality_preset`	`str \\| None`	`None`	Use a named personality preset (e.g., `"explorer"`, `"warrior"`).
`personality`	`PersonalityDimensions \\| None`	`None`	Custom personality traits. Overrides `personality_preset` if both are set.
`initial_goals`	`list[str] \\| None`	`None`	Starting goals (e.g., `["explore the forest", "find a weapon"]`).
`goal_templates`	`list[str] \\| None`	`None`	Goal generation templates for the deliberative layer.
`cheap_model`	`str \\| None`	`None`	Override the cheap model name for this agent.
`expensive_model`	`str \\| None`	`None`	Override the expensive model name for this agent.
`action_delay_multiplier`	`float`	`1.0`	Scale action delays. Use `0.5` for faster actions, `2.0` for slower.
`max_cost_per_hour`	`float \\| None`	`None`	Override per-agent hourly cost limit.
`max_cost_per_day`	`float \\| None`	`None`	Override per-agent daily cost limit.
`auto_respawn`	`bool`	`true`	Automatically respawn if the agent dies or disconnects.
`respawn_delay_seconds`	`float`	`30.0`	Seconds to wait before auto-respawning.
`session_duration_hours`	`float \\| None`	`None`	Maximum session length. Agent despawns when exceeded. `None` = unlimited.

from maid_engine.ai_players.config import AIPlayerConfig

config = AIPlayerConfig(
    name="Aldric the Bold",
    personality_preset="warrior",
    initial_goals=["find the strongest weapon", "defeat the dungeon boss"],
    max_cost_per_hour=0.15,
    max_cost_per_day=3.00,
    action_delay_multiplier=0.8,  # Slightly faster than default
    session_duration_hours=8.0,
)

Model Configuration¶

AI Players use two model tiers to balance cost and capability:

Tier	Used For	Default Provider	Default Model
Cheap	Perception parsing, action selection, replanning	`chatjimmy`	`llama3.1-8B`
Expensive	Goal generation, strategic reflection, memory consolidation	`anthropic`	`claude-sonnet-4`

Chat Jimmy (Free)¶

No API key required. Best for development and testing:

MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.1-8B
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=llama3.1-8B

Warning

Using the same free model for both tiers works for testing but produces lower-quality strategic reasoning. Use a more capable model for the expensive tier in production.

Anthropic (Claude)¶

High-quality reasoning. Recommended for the expensive tier:

MAID_AI__ANTHROPIC_API_KEY=sk-ant-...
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=anthropic
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=claude-haiku-4
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=anthropic
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=claude-sonnet-4

OpenAI (GPT)¶

MAID_AI__OPENAI_API_KEY=sk-...
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=openai
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=gpt-4o-mini
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=openai
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=gpt-4o

Ollama (Local)¶

Run models locally with no API costs. Requires a running Ollama instance:

MAID_AI__OLLAMA_HOST=http://localhost:11434
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=ollama
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.2
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=ollama
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=llama3.1:70b

Budget Configuration¶

The cost management system enforces spending limits at two levels: global (all agents combined) and per-agent.

Budget Policies¶

Policy	Behavior
`enforce`	Hard limit — LLM calls are blocked when budget is exceeded. The agent falls back to template actions.
`warn`	Soft limit — a warning is logged but the call proceeds. Use for monitoring before enforcing.
`unlimited`	No budget enforcement. Use only for development/testing.

MAID_AI_PLAYERS__BUDGET_POLICY=enforce

Burst vs Sustained Limits¶

Each agent has two hourly cost limits:

Burst (PER_AGENT_MAX_COST_PER_HOUR_BURST): Elevated limit during the first 10 minutes after spawn. Allows the agent to rapidly orient — look around, read room descriptions, build an initial world model.
Sustained (PER_AGENT_MAX_COST_PER_HOUR_SUSTAINED): Lower limit applied after the 10-minute warmup. This is the steady-state operating cost.

The daily cap (PER_AGENT_MAX_COST_PER_DAY) provides an absolute ceiling regardless of hourly fluctuations.

Timeline:  |--- 10 min burst ---|------------ sustained ------------|
Limit:     $0.20/hr              $0.12/hr
Daily cap: ────────────────── $2.50/day ──────────────────────────────

Example Configurations¶

Development (Zero Cost)¶

Use Ollama or Chat Jimmy for both tiers. No API keys needed:

MAID_AI_PLAYERS__ENABLED=true
MAID_AI_PLAYERS__MAX_AGENTS=3
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.1-8B
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=llama3.1-8B
MAID_AI_PLAYERS__BUDGET_POLICY=unlimited
MAID_AI_PLAYERS__AUTO_SPAWN_ON_START=true
MAID_AI_PLAYERS__AUTO_SPAWN_COUNT=2
MAID_AI_PLAYERS__THOUGHT_TRACE_ENABLED=true
MAID_AI_PLAYERS__DECISION_LOG_ENABLED=true

Production — Small (10 Agents)¶

Chat Jimmy for routine operations, Anthropic for strategic reasoning:

MAID_AI_PLAYERS__ENABLED=true
MAID_AI_PLAYERS__MAX_AGENTS=10
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.1-8B
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=anthropic
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=claude-sonnet-4
MAID_AI_PLAYERS__GLOBAL_MAX_COST_PER_HOUR=1.0
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR=0.10
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_BURST=0.20
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_SUSTAINED=0.12
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_DAY=2.50
MAID_AI_PLAYERS__BUDGET_POLICY=enforce
MAID_AI_PLAYERS__MAX_CONCURRENT_LLM_CALLS=5
MAID_AI_PLAYERS__SCHEDULING_STRATEGY=adaptive

Production — Large (50+ Agents)¶

Aggressive budgets, shared knowledge enabled, adaptive scheduling:

MAID_AI_PLAYERS__ENABLED=true
MAID_AI_PLAYERS__MAX_AGENTS=50
MAID_AI_PLAYERS__CHEAP_MODEL_PROVIDER=chatjimmy
MAID_AI_PLAYERS__CHEAP_MODEL_NAME=llama3.1-8B
MAID_AI_PLAYERS__EXPENSIVE_MODEL_PROVIDER=anthropic
MAID_AI_PLAYERS__EXPENSIVE_MODEL_NAME=claude-sonnet-4
MAID_AI_PLAYERS__GLOBAL_MAX_COST_PER_HOUR=5.0
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR=0.08
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_BURST=0.15
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_HOUR_SUSTAINED=0.08
MAID_AI_PLAYERS__PER_AGENT_MAX_COST_PER_DAY=1.50
MAID_AI_PLAYERS__BUDGET_POLICY=enforce
MAID_AI_PLAYERS__MAX_CONCURRENT_LLM_CALLS=10
MAID_AI_PLAYERS__SCHEDULING_STRATEGY=adaptive
MAID_AI_PLAYERS__SHARED_KNOWLEDGE_ENABLED=true
MAID_AI_PLAYERS__SHARED_PERCEPTION_ENABLED=true
MAID_AI_PLAYERS__SHARED_PERCEPTION_CACHE_TTL=60.0
MAID_AI_PLAYERS__COGNITIVE_TICK_INTERVAL=5.0
MAID_AI_PLAYERS__IDLE_TICK_INTERVAL=15.0
MAID_AI_PLAYERS__OBSERVATION_BATCH_INTERVAL=10.0
MAID_AI_PLAYERS__CONSOLIDATION_INTERVAL_TICKS=200
MAID_AI_PLAYERS__REFLECTION_PERIODIC_INTERVAL=600.0
MAID_AI_PLAYERS__SAVE_INTERVAL_SECONDS=120.0
MAID_AI_PLAYERS__THOUGHT_TRACE_ENABLED=true
MAID_AI_PLAYERS__THOUGHT_TRACE_RETENTION_HOURS=12
MAID_AI_PLAYERS__DECISION_LOG_ENABLED=false

Cost Estimation

At steady state with the default budget settings, each agent costs approximately \(0.10/hour** or **\)2.40/day. For 50 agents, budget approximately \(5/hour** or **\)120/day. Actual costs depend on gameplay activity — idle agents cost less, combat-heavy agents cost more.