src/apis/simulation_admin/settings.py (TOP_LEVEL_PARAMETER_MAPPINGS) and the SimulationSettings model in src/common/models.py. Clients send changes with UpdateSimulationSettingsRequest (partial updates, PATCH-style).
Audience: People configuring one organization. Platform-only or super-admin overrides are documented elsewhere unless your deployment routes them through the same surfaces.
Reading this catalog
- Each section groups related settings (schema, scenario, timing, chatter, and so on).
- Tables call out Purpose, Learner impact, and Operational impact where relevant.
- For nested
simulation_policy.*keys, see Simulation policy paths.
How settings take effect
| Aspect | Detail |
|---|---|
| Storage | MongoDB, keyed by organization_id. |
| Consumers | Background jobs (chatter, storyline, scheduler), agent orchestration, and API behavior read values at runtime. |
| Risk | High activity increases LLM cost, tokens, and channel noise; very low limits can make the simulation feel sparse or stalled. |
Basic vs Expert in the admin UI
The mapping contract labels each field Basic or Expert for the product UI. Treat Expert fields as requiring operators who understand downstream effects on learners and cost.Basic-only quick table
Use this table when you need a fast view of the parameters available in Basic mode. The detailed sections below remain the canonical reference.| Parameter | UI tab | What it controls | Platform impact |
|---|---|---|---|
chatter_enabled | Setup | Turns ambient channel chatter on/off | Disabling reduces background model calls and event churn. |
storyline_enabled | Setup | Turns storyline progression on/off | Disabling lowers periodic storyline processing and event generation. |
chatter_lambda | Setup | Average chatter cadence | Lower intervals increase model traffic and moderation load. |
min_chatter_interval | Setup | Hard minimum gap between chatter emits | Lower values increase burstiness and token spend. |
timezone | Calendar | Org-local simulation clock context | Drives schedule calculations and event timing consistency. |
business_days | Calendar | Which weekdays are treated as workdays | Changes pacing windows and scheduler behavior across the week. |
office_hours_start / office_hours_end | Calendar | Working-hour window | Affects when fast-response behavior is active and when off-hours messaging appears. |
dm_response_delay_max | Channels | Upper bound for DM response delay | Lower values raise concurrency and perceived responsiveness pressure. |
channel_response_delay_max | Channels | Upper bound for channel response delay | Lower values increase response throughput and model call frequency. |
task_first_assignment_delay_minutes | Tasks | Delay before first assigned task | Lower values increase early-task load and downstream workflow activity. |
enable_org_knowledge_rag | Memory | Enables retrieval-augmented org context | Increases retrieval calls and vector-store dependency at runtime. |
safety_enabled | Approvals | Legacy master switch for approvals path | Enabling can introduce gated actions and more operational review events. |
require_manager_approval_for | Approvals | Which action types require approval | Broader lists increase pending approvals and intervention overhead. |
simulation_policy (basic subset) | Setup / Channels / Memory / Approvals / Scenario Lab | High-level policy controls (realism/routing baseline) | Behavior shifts across routing, memory usage, and orchestration cost profile. |
Internal-only fields (not general org-admin toggles)
| Field | Notes |
|---|---|
enable_mem0_memory | May appear on update payloads for compatibility but is treated as internal / platform (SETTINGS_INTERNAL_ONLY_FIELDS). Do not treat it as a standard org-admin switch in customer documentation. |
1. Schema & metadata
settings_schema_version
| Type | integer |
| Default | 3 |
| UI | Expert · Scenario Lab |
| Purpose | Version tag for migrations and backward-compatible deserialization. |
| Learner impact | None directly. |
| Operational impact | Incorrect bumps can break compatibility with admin clients; change only with engineering guidance. |
2. Scenario, tasks, and character setup
active_task_ids
| Type | string[] or null (all tasks) |
| Default | null |
| UI | Expert · Tasks |
| Purpose | Restricts which task templates are eligible for assignment in this org. |
| Learner impact | High — limits which scenarios learners see; wrong IDs can hide required practice. |
| Operational impact | Requires valid task keys from your org’s task catalog; validate in staging. |
scenario_character_ids
| Type | dict (task/slot → character_id) or null |
| Default | null |
| UI | Expert · Setup |
| Purpose | Binds scenario slots (e.g. termination / hire targets) to concrete characters in the org. |
| Learner impact | High — changes who appears in narratives and DMs. |
| Operational impact | Must reference characters that exist for the org; inconsistent mappings confuse storylines. |
default_scenario_name
| Type | string or null |
| Default | null |
| UI | Expert · Setup |
| Purpose | Default scenario key for seeding and diagnostics (e.g. channel templates). |
| Learner impact | Medium — affects initial channel content and default narrative path. |
| Operational impact | Must match a scenario blueprint your org ships. |
primary_agent_ids
| Type | string[] or null |
| Default | null |
| UI | Expert · Setup |
| Purpose | Preferred agent/character IDs to ensure on login/signup when matching simulation characters exist. |
| Learner impact | Medium — influences who is available as primary responders early in the sim. |
| Operational impact | Agents are only created when simulation characters are configured; invalid IDs are ineffective. |
channel_template_character_mapping
| Type | dict (placeholder → org character_id) or null |
| Default | null |
| UI | Expert · Channel Seeding |
| Purpose | Maps template placeholders to org-specific characters for channel message seeding. |
| Learner impact | High — wrong mapping shows wrong names/story in channels. |
| Operational impact | Keep in sync with scenario_character_ids and actual character roster. |
3. Feature toggles (master switches)
chatter_enabled
| Type | boolean |
| Default | true |
| UI | Basic & Expert · Setup |
| Purpose | Master switch for ambient background chatter in channels. |
| Learner impact | High — off makes channels quiet; on increases realism and noise. |
| Operational impact | Off reduces LLM spend; on requires healthy rate limits below. |
storyline_enabled
| Type | boolean |
| Default | true |
| UI | Basic & Expert · Setup |
| Purpose | Enables storyline manager progression checks. |
| Learner impact | High — off freezes narrative progression features that depend on it. |
| Operational impact | Reduces periodic background work when off. |
auto_assign_tasks
| Type | boolean |
| Default | true |
| UI | Expert · Tasks |
| Purpose | Controls automatic task assignment flows (e.g. Head of HR automation). |
| Learner impact | High — off delays or prevents automatic task surfacing depending on product path. |
| Operational impact | May reduce scheduler/agent load when off. |
quick_help_call_enabled
| Type | boolean |
| Default | true |
| UI | Expert · Quick Help |
| Purpose | Master toggle for Quick Help LiveKit voice-call availability. |
| Learner impact | High — disables/enables entry to live voice coaching from chat. |
| Operational impact | Disabling prevents new voice sessions from being created for the org. |
quick_help_call_voice
| Type | string |
| Default | marin |
| UI | Expert · Quick Help |
| Purpose | Selects the OpenAI realtime voice used by the Quick Help worker. |
| Learner impact | Medium — changes assistant speaking style and tone perception. |
| Operational impact | Must be one of the backend-allowed voice IDs. |
quick_help_call_persona
| Type | string or null |
| Default | null |
| UI | Expert · Quick Help |
| Purpose | Organization-specific persona guidance injected into Quick Help instructions. |
| Learner impact | High — controls coaching voice, framing, and guidance style. |
| Operational impact | Keep concise and policy-safe; overly broad prompts can dilute response quality. |
4. Timing, calendar, and simulated clock
timezone
| Type | string (IANA name) |
| Default | UTC |
| UI | Basic & Expert · Calendar |
| Purpose | Timezone for business hours, schedules, and org-local “now” in simulation logic. |
| Learner impact | High — shifts when NPCs behave as “in office” vs off-hours messaging. |
| Operational impact | Must be valid IANA ID; invalid values fall back unpredictably in edge code paths. |
business_days
| Type | string[] (weekday names) |
| Default | Mon–Sun |
| UI | Basic & Expert · Calendar |
| Purpose | Defines working days for scheduling and ambient activity. |
| Learner impact | Medium — weekend vs weekday messaging and pacing. |
| Operational impact | Keep consistent with regional expectations for pilots. |
office_hours_start / office_hours_end
| Type | integer (0–23) |
| Default | 0 / 23 |
| UI | Basic & Expert · Calendar |
| Purpose | Window for business-hours behavior (response delays, instant-response probability, etc.). |
| Learner impact | High — defines when learners get “fast” vs delayed NPC behavior. |
| Operational impact | If start ≥ end, behavior is inconsistent; validate in UI/tests. |
outside_business_hours_message / weekend_message
| Type | string or null |
| Default | null (built-in fallbacks) |
| UI | Expert · Calendar |
| Purpose | Custom learner-facing guidance when outside office hours or on non-business days. |
| Learner impact | Medium — sets expectations for delay tone. |
| Operational impact | Keep concise; avoid leaking internal policy. |
simulation_speed
| Type | float |
| Default | 1.0 |
| UI | Expert · Scenario Lab |
| Purpose | Core pacing multiplier for simulation timing features (not wall-clock alone; interacts with engines). |
| Learner impact | High — faster speed compresses perceived cadence of simulation events. |
| Operational impact | Higher speeds increase background checks and agent invocations. |
storyline_check_interval
| Type | float (seconds — passed to asyncio.sleep between checks) |
| Default | 15.0 |
| UI | Expert · Scenario Lab |
| Purpose | How often the storyline manager evaluates progression per org loop. |
| Learner impact | Medium — lower values react faster to task/story state changes. |
| Operational impact | Lower values increase CPU/IO and storyline evaluation frequency. |
simulation_epoch_start
| Type | datetime or null |
| Default | null |
| UI | Expert · Calendar |
| Purpose | Reference epoch for deterministic time compression math. |
| Learner impact | High when compression used — anchors simulated timeline. |
| Operational impact | Should be stable for a cohort; changing mid-run confuses analytics. |
time_compression_factor
| Type | float |
| Default | 1.0 |
| UI | Expert · Calendar |
| Purpose | Scales simulated time vs wall-clock (get_simulation_time). |
| Learner impact | Very high — accelerates deadlines, story beats, and scheduled nudges. |
| Operational impact | Very high — raises LLM, scheduler, and DB load; test before pilots. |
5. Background chatter (ambient)
chatter_lambda
| Type | float |
| Default | 45.0 |
| UI | Basic & Expert · Setup |
| Purpose | Expected spacing / rate parameter for Poisson-style ambient chatter (product interpretation). |
| Learner impact | High — more chatter increases channel activity. |
| Operational impact | Primary driver of LLM cost alongside caps. |
min_chatter_interval
| Type | float |
| Default | 10.0 |
| UI | Basic & Expert · Setup |
| Purpose | Minimum gap between chatter emissions. |
| Learner impact | Prevents burst spam in channels. |
| Operational impact | Lower floor increases burstiness when combined with high lambda. |
chatter_max_global_per_hour
| Type | integer |
| Default | 10 |
| UI | Expert · Channels |
| Purpose | Org-wide hourly cap on ambient chatter. |
| Learner impact | High — hard ceiling on how “busy” channels feel. |
| Operational impact | Primary cost guardrail; raise only with budget. |
chatter_max_per_channel_per_hour
| Type | integer |
| Default | 5 |
| UI | Expert · Channels |
| Purpose | Per-channel hourly cap to avoid one channel dominating. |
| Learner impact | Medium — spreads activity across channels. |
| Operational impact | Tune with global cap. |
chatter_agent_cooldown_minutes
| Type | integer |
| Default | 15 |
| UI | Expert · Channels |
| Purpose | Cooldown before the same agent can post ambient chatter again. |
| Learner impact | Medium — reduces repetitive voices. |
| Operational impact | Helps diversify agent spend. |
chatter_daily_budget
| Type | integer |
| Default | 50 |
| UI | Expert · Channels |
| Purpose | Daily total cap on chatter messages for the org. |
| Learner impact | High — stops activity after budget exhaustion. |
| Operational impact | Strong fiscal control; pair with monitoring. |
chatter_context_messages
| Type | integer |
| Default | 8 |
| UI | Expert · Memory |
| Purpose | How many recent messages feed chatter generation context. |
| Learner impact | Medium — higher improves continuity; increases prompt size. |
| Operational impact | Higher values increase token usage per chatter call. |
chatter_include_org_context
| Type | boolean |
| Default | true |
| UI | Expert · Memory |
| Purpose | Whether to inject org-level context into chatter prompts. |
| Learner impact | Medium — improves relevance when on. |
| Operational impact | Slightly higher tokens when on. |
chatter_only_when_users_active
| Type | boolean |
| Default | true |
| UI | Expert · Channels |
| Purpose | Suppresses chatter when no users are active, reducing waste. |
| Learner impact | Low when learners absent; avoids dead-hour spam when on. |
| Operational impact | Saves cost during idle periods. |
chatter_max_chain_length
| Type | integer (optional; validated typically 1–5 in API) |
| Default | Persisted default often 2 when unset (repository/engine fallback). |
| UI | Expert · Channels |
| Purpose | Max depth of auto-reply chains in ambient threads. |
| Learner impact | Medium — higher chains feel more conversational but noisier. |
| Operational impact | Multiplies LLM calls per chain. |
chatter_chain_expiry_minutes
| Type | integer |
| Default | Often 30 when unset (engine fallback). |
| UI | Expert · Channels |
| Purpose | Window after which a chain expires and stops auto-continuing. |
| Learner impact | Medium — shorter windows truncate threads. |
| Operational impact | Shorter windows reduce follow-on LLM calls. |
6. NPC response delays and probability
instant_response_probability
| Type | float (0–1) |
| Default | 0.65 |
| UI | Expert · Channels |
| Purpose | Probability of near-immediate handling during business hours. |
| Learner impact | High — perceived responsiveness of NPCs. |
| Operational impact | Higher probability increases concurrent LLM work. |
dm_response_delay_max
| Type | float |
| Default | 25.0 |
| UI | Basic & Expert · Channels |
| Purpose | Upper bound for simulated DM delay (distribution engine). |
| Learner impact | High — DMs feel slower or faster. |
| Operational impact | Mostly UX; extreme values stress scheduling. |
channel_response_delay_max
| Type | float |
| Default | 15.0 |
| UI | Basic & Expert · Channels |
| Purpose | Upper bound for channel response delay. |
| Learner impact | High — public channel pacing. |
| Operational impact | Same as DM delay. |
office_hour_distribution
| Type | List of (start_min, end_min, probability) tuples |
| Default | Built-in multi-bucket distribution |
| UI | Expert · Calendar |
| Purpose | Shapes when within office hours responses concentrate (lunch dip, etc.). |
| Learner impact | Medium — realism of intra-day activity. |
| Operational impact | Invalid tuples can break normalization; validate sums and ranges. |
7. Tasks — onboarding pace
task_first_assignment_delay_minutes
| Type | float |
| Default | 5.0 |
| UI | Basic & Expert · Tasks |
| Purpose | Delay before first task is assigned to a new user (e.g. Head of HR flow). |
| Learner impact | High — first impression of workload timing. |
| Operational impact | Low; interacts with auto_assign_tasks. |
8. Memory & retrieval (org-scoped)
enable_org_knowledge_rag
| Type | boolean |
| Default | false |
| UI | Basic & Expert · Memory |
| Purpose | Enables retrieval-augmented org knowledge for agents (Qdrant-backed paths when configured). |
| Learner impact | High when on — answers can cite internal context; requires quality content. |
| Operational impact | High — vector queries, embedding costs, and latency; depends on Qdrant health. |
internal_agent_channels
| Type | string[] |
| Default | hr-internal, product-internal, engineering-internal |
| UI | Expert · Channels |
| Purpose | Channels used for agent coordination / internal routing (paired with policy orchestration). |
| Learner impact | Medium — misconfiguration routes wrong traffic to internal spaces. |
| Operational impact | Must exist or be created per org conventions. |
9. Safety and approvals (legacy mirrors + policy)
safety_enabled
| Type | boolean |
| Default | false |
| UI | Basic & Expert · Approvals |
| Purpose | Legacy safety toggle; mirrored into simulation_policy.approvals per product rules. |
| Learner impact | High when on — may require confirmations for sensitive flows. |
| Operational impact | Coordinate with require_manager_approval_for and policy approvals. |
require_manager_approval_for
| Type | string[] |
| Default | [] |
| UI | Basic & Expert · Approvals |
| Purpose | List of action keys requiring manager approval (e.g. sensitive DMs); mirrored into policy. |
| Learner impact | Very high — blocks or delays until approval. |
| Operational impact | Requires operational clarity on who approves in product workflows. |
10. Unified policy object
simulation_policy
| Type | object (nested JSON) |
| Default | Large structured default in SimulationSettings (version, realism_profile, routing, privacy, context, approvals, orchestration, assignment, memory, rollout, kpi_gates, propagation_sla, ambient, config_registry, tools, …) |
| UI | Basic & Expert across Setup, Channels, Memory, Approvals, Scenario Lab |
| Purpose | Single source of truth for realism, routing, privacy, orchestration limits, assignment profiles, memory behavior, rollout flags, KPI gates, propagation SLA, ambient nudges, and tool policy. |
| Learner impact | System-wide — small changes alter realism, safety, and task behavior. |
| Operational impact | High — prefer staged rollout; merge semantics are deep (partial updates merge into existing policy). |
11. Scheduled / random events
events
| Type | SimulationEvent[] |
| Default | [] |
| UI | Expert · Calendar |
| Purpose | Configures planned or random multi-channel events (participants, templates, probabilities). |
| Learner impact | High — drives coordinated bursts and storyline beats. |
| Operational impact | High — can spike traffic; test probabilities and cooldowns. |
12. Time-boxed simulation lifecycle
simulation_mode
| Type | string (continuous | time_boxed) |
| Default | continuous |
| UI | Expert · Scenario Lab |
| Purpose | Selects continuous vs time-boxed lifecycle (deadline-driven runs). |
| Learner impact | Very high in time-boxed mode — hard stops and pacing. |
| Operational impact | Time-boxed needs clear comms and monitoring for timeouts. |
simulation_duration_minutes
| Type | integer or null |
| Default | null |
| UI | Expert · Scenario Lab |
| Purpose | Duration for time-boxed sessions. |
| Learner impact | Very high — sets how long learners can work the sim. |
| Operational impact | Coordinate with lifecycle guards and analytics. |
simulation_completion_message
| Type | string or null |
| Default | null |
| UI | Expert · Scenario Lab |
| Purpose | Message shown when a lifecycle completes. |
| Learner impact | High — clarity of closure and next steps. |
| Operational impact | Low. |
milestones
| Type | object[] (milestone definitions) |
| Default | [] |
| UI | Expert · Scenario Lab |
| Purpose | Structured milestones (time/task/manual triggers) for progression tracking. |
| Learner impact | High — defines visible progression checkpoints. |
| Operational impact | Medium — incorrect triggers confuse analytics and UX. |
Appendix: Runtime lifecycle fields (not org-admin PATCH)
The persistedSimulationSettings document also stores lifecycle state updated by the engine, not by UpdateSimulationSettingsRequest. Do not treat these as org-admin “configuration” in the same sense as the fields above.
| Field | Role |
|---|---|
simulation_started_at | When a time-boxed or tracked run actually started. |
simulation_ends_at | Scheduled end instant when duration-based. |
simulation_status | e.g. not_started, active, completed, paused. |
simulation_paused_at | Timestamp when paused. |
simulation_remaining_minutes_at_pause | Carry-over remaining time when pausing. |
simulation_mode, simulation_duration_minutes, and milestones but are driven by runtime, APIs, or scheduler—not the same PATCH surface as tuning chatter or policy.
Related
- Simulation policy paths —
simulation_policy.*keys exposed in admin mapping. - Parameter documentation standard — template for bespoke deep dives.
- Memory decision table — MongoDB vs Qdrant vs mem0.