Add LLM probability slider: controls AI usage per call site

Adds a 0-100% slider (brain emoji, in the toolbar between speed and
zoom controls) that gates every LLM call in the simulation:
- Action decisions, conversation turns, reflections, social starts,
daily plan generation — each rolls random() < llm_call_probability.

Provider defaults (tuned for free-tier daily quotas):
Gemini → 45% (4 RPM + budget=1 → ~150 calls/h → ~10h at 1500 RPD)
Groq → 70% (conserves daily token budget)
HF → 45%
Ollama/Claude → 100% (no quota)

Also reduces Gemini's _max_llm_calls_this_tick from 4 → 1 so the
rate limiter (15s/call) naturally paces the simulation without
needing to burn all 4 budget slots every tick.

Override default via SOCI_LLM_PROB env var (0.0–1.0).
API: GET /api/controls → llm_call_probability field
POST /api/controls/llm_probability?value=0.45

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/soci/api/routes.py

@@ -693,8 +693,18 @@ async def get_events(limit: int = 50):
 @router.get("/controls")
 async def get_controls():
     """Get current simulation control state."""
-    from soci.api.server import _sim_paused, _sim_speed
-    return {"paused": _sim_paused, "speed": _sim_speed}
+    from soci.api.server import _sim_paused, _sim_speed, _llm_call_probability
+    return {"paused": _sim_paused, "speed": _sim_speed, "llm_call_probability": _llm_call_probability}
+
+
+@router.post("/controls/llm_probability")
+async def set_llm_probability(value: float = 1.0):
+    """Set LLM call probability (0.0–1.0). Controls how often agents use LLM vs. routine behaviour.
+    At 0.45 with Gemini free tier: ~150 calls/h → ~10h daily runtime."""
+    from soci.api.server import set_llm_call_probability
+    set_llm_call_probability(value)
+    from soci.api.server import _llm_call_probability
+    return {"llm_call_probability": _llm_call_probability}
 
 
 @router.post("/controls/pause")

src/soci/api/server.py

@@ -41,6 +41,7 @@ _sim_task: Optional[asyncio.Task] = None
 _sim_paused: bool = False
 _sim_speed: float = 1.0  # 1.0 = normal, 0.5 = fast, 2.0 = slow
 _llm_provider: str = ""  # Track which provider is active
+_llm_call_probability: float = 1.0  # 0.0–1.0; set per-provider on startup, adjustable via slider
 
 
 def get_simulation() -> Simulation:
@@ -57,6 +58,17 @@ def get_llm_provider() -> str:
     return _llm_provider
 
 
+def get_llm_call_probability() -> float:
+    return _llm_call_probability
+
+
+def set_llm_call_probability(value: float) -> None:
+    global _llm_call_probability, _simulation
+    _llm_call_probability = max(0.0, min(1.0, value))
+    if _simulation is not None:
+        _simulation.llm_call_probability = _llm_call_probability
+
+
 async def switch_llm_provider(provider: str, model: Optional[str] = None) -> None:
     """Hot-swap the LLM client on the running simulation."""
     global _llm_provider, _simulation
@@ -97,14 +109,18 @@ async def simulation_loop(sim: Simulation, db: Database, tick_delay: float = 2.0
             else:
                 sim._skip_llm_this_tick = False
                 if is_rate_limited:
-                    # Rate-limited providers (Groq 30 RPM, Gemini 15 RPM, HF) — budget 4 calls/tick
+                    # Rate-limited providers: tight budget — probability slider does the fine-tuning.
+                    # Gemini free tier: 4 RPM, ~1500 RPD → budget=1 + prob=0.45 ≈ 150 calls/h (10h).
                     sim._max_convos_this_tick = 1
-                    sim._max_llm_calls_this_tick = 4
+                    sim._max_llm_calls_this_tick = 1
                 else:
                     # Ollama / Claude: soft cap to keep ticks responsive
                     sim._max_convos_this_tick = 3
                     sim._max_llm_calls_this_tick = 10
 
+            # Apply the runtime probability slider every tick
+            sim.llm_call_probability = _llm_call_probability
+
             await sim.tick()
 
             # Auto-save every 24 ticks (~6 sim-hours)
@@ -306,6 +322,21 @@ async def lifespan(app: FastAPI):
     llm = create_llm_client(provider=_llm_provider)
     logger.info(f"LLM provider: {_llm_provider} ({llm.__class__.__name__})")
 
+    # Default LLM call probability — tuned per provider to stay within free-tier daily quotas.
+    # Gemini free tier: 4 RPM, ~1500 RPD → 0.45 ≈ 150 calls/h → ~10h runtime per day.
+    # Groq free tier: 30 RPM, limited daily tokens → 0.70 to conserve budget.
+    # Ollama / Claude: no quota → 1.0 (full fidelity).
+    # Override via SOCI_LLM_PROB env var (0.0–1.0).
+    _provider_default_prob = {
+        PROVIDER_GEMINI: 0.45,
+        PROVIDER_GROQ: 0.70,
+        PROVIDER_HF: 0.45,
+    }
+    _llm_call_probability = float(
+        os.environ.get("SOCI_LLM_PROB", str(_provider_default_prob.get(_llm_provider, 1.0)))
+    )
+    logger.info(f"LLM call probability: {_llm_call_probability:.0%}")
+
     db = Database()
     await db.connect()
     _database = db

src/soci/engine/simulation.py

@@ -64,6 +64,9 @@ class Simulation:
         self._max_convos_this_tick: int = 0  # 0 = no limit
         self._max_llm_calls_this_tick: int = 0  # 0 = no limit; global budget across all categories
         self._llm_calls_this_tick: int = 0  # counter, reset each tick
+        # LLM call probability: 0.0 = never use LLM (routine only), 1.0 = always (default).
+        # Applied per potential LLM call site. Tuned at 0.45 for ~10h Gemini free-tier runtime.
+        self.llm_call_probability: float = 1.0
         # Callback for real-time output
         self.on_event: Optional[Callable[[str], None]] = None
 
@@ -169,7 +172,7 @@ class Simulation:
                         plan_items[:8], self.clock.day,
                         self.clock.total_ticks, self.clock.time_str,
                     )
-                else:
+                elif random.random() < self.llm_call_probability:
                     plan_coros.append(self._generate_daily_plan(agent))
                     plan_agents.append(agent)
 
@@ -233,7 +236,7 @@ class Simulation:
                     continue
 
             # No routine slot — fallback to LLM (rare), skip in fast-forward
-            if not self._skip_llm_this_tick:
+            if not self._skip_llm_this_tick and random.random() < self.llm_call_probability:
                 action_coros.append(self._decide_action(agent))
                 action_agents.append(agent)
 
@@ -276,7 +279,7 @@ class Simulation:
                 if next_speaker_id:
                     responder = self.agents.get(next_speaker_id[0])
                     other = self.agents.get(last_speaker) if last_speaker else None
-                    if responder and other:
+                    if responder and other and random.random() < self.llm_call_probability:
                         conv_coros.append(
                             continue_conversation(conv, responder, other, self.llm, self.clock)
                         )
@@ -303,7 +306,8 @@ class Simulation:
         # 7. Social: maybe start new conversations (respect speed limits + budget)
         if not self._skip_llm_this_tick and self._llm_budget_remaining() > 0:
             if self._max_convos_this_tick == 0 or len(self.active_conversations) < self._max_convos_this_tick:
-                await self._handle_social_interactions(ordered_agents)
+                if random.random() < self.llm_call_probability:
+                    await self._handle_social_interactions(ordered_agents)
 
         # 8. Reflections for agents with enough accumulated importance
         if not self._skip_llm_this_tick and self._llm_budget_remaining() > 0:
@@ -311,8 +315,9 @@ class Simulation:
             reflect_agents = []
             for agent in ordered_agents:
                 if agent.memory.should_reflect() and not agent.is_player:
-                    reflect_coros.append(self._generate_reflection(agent))
-                    reflect_agents.append(agent)
+                    if random.random() < self.llm_call_probability:
+                        reflect_coros.append(self._generate_reflection(agent))
+                        reflect_agents.append(agent)
 
             # Limit by speed cap and global budget
             reflect_cap = min(

web/index.html

@@ -272,7 +272,13 @@
       <button class="ctrl-btn" id="btn-10x" onclick="setSpeed(0.1)" title="10x speed">10x</button>
       <button class="ctrl-btn" id="btn-50x" onclick="setSpeed(0.02)" title="50x speed">50x</button>
       <span class="speed-label" id="speed-label">1x</span>
-      <span style="color:#1a3a6e;margin:0 2px">│</span>
+      <span style="color:#1a3a6e;margin:0 4px">│</span>
+      <span style="font-size:10px;color:#666;white-space:nowrap" title="LLM call probability: controls how often agents use AI reasoning vs. routine behaviour. At 45% with Gemini free tier ≈ 10h daily runtime.">🧠</span>
+      <input type="range" id="llm-prob-slider" min="0" max="100" value="100" step="5"
+        style="width:64px;height:6px;accent-color:#4ecca3;cursor:pointer;vertical-align:middle;"
+        oninput="onLlmProbSlider(this.value)" title="LLM usage probability">
+      <span id="llm-prob-label" style="font-size:10px;color:#4ecca3;min-width:28px;text-align:right;">100%</span>
+      <span style="color:#1a3a6e;margin:0 4px">│</span>
       <button class="ctrl-btn" id="btn-rect-zoom" onclick="toggleRectZoom()" title="Draw a rectangle to zoom into that area (Shift+drag)">⬚</button>
       <button class="ctrl-btn" onclick="zoomBy(1.3)" title="Zoom In (scroll up)">＋</button>
       <button class="ctrl-btn" onclick="zoomBy(1/1.3)" title="Zoom Out (scroll down)">－</button>
@@ -3013,6 +3019,7 @@ async function fetchState() {
 // ============================================================
 let simPaused = false;
 let simSpeed = 1.0;
+let llmCallProbability = 1.0;
 
 async function togglePause() {
   try {
@@ -3069,6 +3076,24 @@ function updateControlsUI() {
   document.getElementById('speed-label').textContent = label;
 }
 
+async function onLlmProbSlider(val) {
+  const pct = parseInt(val);
+  document.getElementById('llm-prob-label').textContent = pct + '%';
+  llmCallProbability = pct / 100;
+  try {
+    await fetch(`${API_BASE}/controls/llm_probability?value=${llmCallProbability}`, { method: 'POST' });
+  } catch(e) {}
+}
+
+function updateLlmProbUI(prob) {
+  llmCallProbability = prob;
+  const pct = Math.round(prob * 100);
+  const slider = document.getElementById('llm-prob-slider');
+  const label = document.getElementById('llm-prob-label');
+  if (slider) slider.value = pct;
+  if (label) label.textContent = pct + '%';
+}
+
 async function fetchControls() {
   try {
     const res = await fetch(`${API_BASE}/controls`);
@@ -3076,6 +3101,7 @@ async function fetchControls() {
       const data = await res.json();
       simPaused = data.paused;
       simSpeed = data.speed;
+      if (data.llm_call_probability !== undefined) updateLlmProbUI(data.llm_call_probability);
       updateControlsUI();
     }
   } catch(e) {}