Deploy Labrats live Space (free-tier, remote embeddings)

app.py

@@ -633,13 +633,83 @@ with gr.Blocks(
 A small (\u226432B) LLM agent inside the DiscoveryWorld simulator, with a
 two-tier memory layer (private episodic + shared lab notebook).
 
-This Space replays recorded episodes. **Phase B** is a vanilla ReAct
-loop; **Phase C** adds the memory layer. The comparison tab shows the
-behavioural delta from adding memory on the same scenario and seed.
         """
     )
 
     with gr.Tabs():
+        with gr.Tab("Run live"):
+            _token_ok = has_hf_token()
+            _local_ok = has_local_model()
+            _default_backend = "local" if _local_ok else "hf"
+            _any_backend = _token_ok or _local_ok
+            _status_bits = []
+            _status_bits.append(
+                "`HF_TOKEN` detected" if _token_ok else "no `HF_TOKEN`"
+            )
+            _status_bits.append(
+                "local model configured" if _local_ok else "no local model"
+            )
+            gr.Markdown(
+                "Run a **live episode** — spin up N ReAct agents on a fresh "
+                "DiscoveryWorld scenario. Choose the **HF** backend (Hugging "
+                "Face Inference Providers, needs an `HF_TOKEN`) or the **local** "
+                "backend (in-process llama-cpp, needs the `LLAMA_*` env vars). "
+                "The run streams into a new trace that appears in the "
+                "**Episode replay** tab when it finishes.\n\n"
+                + (
+                    "**Status:** " + ", ".join(_status_bits) + "."
+                    if _any_backend
+                    else "**Status:** no backend is configured (no `HF_TOKEN` and "
+                    "no local model), so live runs are disabled. Recorded "
+                    "episodes still work in the other tabs."
+                )
+            )
+            with gr.Row():
+                live_backend = gr.Radio(
+                    choices=["local", "hf"],
+                    value=_default_backend,
+                    label="Backend",
+                    scale=2,
+                )
+                live_scenario = gr.Dropdown(
+                    choices=LIVE_SCENARIOS,
+                    value="Archaeology Dating",
+                    label="Scenario",
+                    allow_custom_value=True,
+                    scale=3,
+                )
+                live_difficulty = gr.Dropdown(
+                    choices=["Easy", "Normal", "Challenge"],
+                    value="Normal",
+                    label="Difficulty",
+                    scale=2,
+                )
+                live_seed = gr.Number(value=0, precision=0, label="Seed", scale=1)
+            with gr.Row():
+                live_agents = gr.Slider(
+                    minimum=1, maximum=LiveRunner.MAX_AGENTS_CAP, value=2, step=1,
+                    label="Agents", scale=2,
+                )
+                live_steps = gr.Slider(
+                    minimum=1, maximum=LiveRunner.MAX_STEPS_CAP, value=15, step=1,
+                    label="Max steps", scale=3,
+                )
+                live_memory = gr.Checkbox(value=True, label="Memory", scale=1)
+                live_dialogue = gr.Checkbox(value=True, label="Dialogue", scale=1)
+            live_start_btn = gr.Button(
+                "\u25b6 Start live episode", variant="primary", interactive=_any_backend
+            )
+            live_status_md = gr.Markdown(_live_status_md())
+            # Live viewport: the latest rendered frame, streamed in as the
+            # episode runs. Mirrors the playback view on the replay tab.
+            live_frame_caption = gr.Markdown("_(frames appear here once a run starts)_")
+            live_frame_view = gr.HTML(
+                "<div style='padding:1em;color:#888'>(no frames yet)</div>"
+            )
+            # Polls the background runner while an episode is in flight.
+            live_timer = gr.Timer(value=1.0, active=False)
+
+
         with gr.Tab("Episode replay"):
             with gr.Row():
                 ep_picker = gr.Dropdown(
@@ -802,77 +872,7 @@ behavioural delta from adding memory on the same scenario and seed.
                     title="Right score over time", height=260, y_lim=[0, 1],
                 )
 
-        with gr.Tab("Run live"):
-            _token_ok = has_hf_token()
-            _local_ok = has_local_model()
-            _default_backend = "local" if _local_ok else "hf"
-            _any_backend = _token_ok or _local_ok
-            _status_bits = []
-            _status_bits.append(
-                "`HF_TOKEN` detected" if _token_ok else "no `HF_TOKEN`"
-            )
-            _status_bits.append(
-                "local model configured" if _local_ok else "no local model"
-            )
-            gr.Markdown(
-                "Run a **live episode** — spin up N ReAct agents on a fresh "
-                "DiscoveryWorld scenario. Choose the **HF** backend (Hugging "
-                "Face Inference Providers, needs an `HF_TOKEN`) or the **local** "
-                "backend (in-process llama-cpp, needs the `LLAMA_*` env vars). "
-                "The run streams into a new trace that appears in the "
-                "**Episode replay** tab when it finishes.\n\n"
-                + (
-                    "**Status:** " + ", ".join(_status_bits) + "."
-                    if _any_backend
-                    else "**Status:** no backend is configured (no `HF_TOKEN` and "
-                    "no local model), so live runs are disabled. Recorded "
-                    "episodes still work in the other tabs."
-                )
-            )
-            with gr.Row():
-                live_backend = gr.Radio(
-                    choices=["local", "hf"],
-                    value=_default_backend,
-                    label="Backend",
-                    scale=2,
-                )
-                live_scenario = gr.Dropdown(
-                    choices=LIVE_SCENARIOS,
-                    value="Archaeology Dating",
-                    label="Scenario",
-                    allow_custom_value=True,
-                    scale=3,
-                )
-                live_difficulty = gr.Dropdown(
-                    choices=["Easy", "Normal", "Challenge"],
-                    value="Normal",
-                    label="Difficulty",
-                    scale=2,
-                )
-                live_seed = gr.Number(value=0, precision=0, label="Seed", scale=1)
-            with gr.Row():
-                live_agents = gr.Slider(
-                    minimum=1, maximum=LiveRunner.MAX_AGENTS_CAP, value=2, step=1,
-                    label="Agents", scale=2,
-                )
-                live_steps = gr.Slider(
-                    minimum=1, maximum=LiveRunner.MAX_STEPS_CAP, value=15, step=1,
-                    label="Max steps", scale=3,
-                )
-                live_memory = gr.Checkbox(value=True, label="Memory", scale=1)
-                live_dialogue = gr.Checkbox(value=True, label="Dialogue", scale=1)
-            live_start_btn = gr.Button(
-                "\u25b6 Start live episode", variant="primary", interactive=_any_backend
-            )
-            live_status_md = gr.Markdown(_live_status_md())
-            # Live viewport: the latest rendered frame, streamed in as the
-            # episode runs. Mirrors the playback view on the replay tab.
-            live_frame_caption = gr.Markdown("_(frames appear here once a run starts)_")
-            live_frame_view = gr.HTML(
-                "<div style='padding:1em;color:#888'>(no frames yet)</div>"
-            )
-            # Polls the background runner while an episode is in flight.
-            live_timer = gr.Timer(value=1.0, active=False)
+        
 
     # ---- wiring --------------------------------------------------
 

src/labrats/agents/react_agent.py

@@ -17,8 +17,10 @@ No memory retrieval yet — Stage 2 plugs it in via `StepContext.extras`.
 
 from __future__ import annotations
 
+import contextlib
 import json
 import re
+import time
 from collections import deque
 from collections.abc import Mapping
 from dataclasses import dataclass, field
@@ -212,6 +214,10 @@ class ReActAgent:
         self._pending: PreviousStep | None = None
         # Last retrieval result, exposed for trace/UI.
         self.last_retrieval: dict[str, list[MemoryHit]] = {}
+        # Per-step wall-time breakdown (perf diagnosis), exposed for trace.
+        self.last_timings: dict[str, float] = {}
+        # LLM wall time accumulated within the current step's `_decide`.
+        self._llm_seconds = 0.0
 
     def _build_system_prompt(self, peers: list[str]) -> str:
         base = _SYSTEM_TEMPLATE.format(
@@ -233,10 +239,16 @@ class ReActAgent:
     def step(
         self, observation: Mapping[str, Any], ctx: StepContext
     ) -> StepDecision:
+        step_t0 = time.perf_counter()
+        store = self._store
+        embed0 = getattr(store, "embed_seconds", 0.0)
+        vstore0 = getattr(store, "vstore_seconds", 0.0)
         view = compact(observation)
         # Flush memory writes for the previously-executed action — this
         # is the first turn we can see its `last_action_message`.
+        flush_t0 = time.perf_counter()
         self._flush_pending(view, ctx)
+        t_flush = time.perf_counter() - flush_t0
         # Anything currently accessible counts as "reached" for the
         # loop-break explorer so it stops steering us back to it.
         for obj in view.accessible:
@@ -244,10 +256,13 @@ class ReActAgent:
             if isinstance(uid, int):
                 self._visited.add(uid)
         # Retrieve memories before deciding.
+        retrieve_t0 = time.perf_counter()
         self.last_retrieval = self._retrieve(view, ctx)
+        t_retrieve = time.perf_counter() - retrieve_t0
         # Inbox + peer list from the scheduler (dialogue path).
         inbox: list[Any] = list(ctx.extras.get("inbox") or [])
         peers: list[str] = list(ctx.extras.get("peer_names") or self._static_peers)
+        self._llm_seconds = 0.0
         decision = self._decide(view, ctx, inbox=inbox, peers=peers)
         # Binding loop-break: if the chosen action is a verbatim repeat of a
         # recently-failed action, override it with a different move so the
@@ -275,6 +290,24 @@ class ReActAgent:
             errors=[],
             prev_view=view,
         )
+        # Record the per-step wall-time breakdown for the trace. embed/vstore
+        # are store-wide deltas (this agent's flush+retrieve), llm is the sum
+        # of provider calls inside `_decide`.
+        t_step = time.perf_counter() - step_t0
+        store_size = 0
+        if store is not None:
+            with contextlib.suppress(Exception):
+                store_size = store.count("private") + store.count("notebook")
+        self.last_timings = {
+            "t_step": round(t_step, 4),
+            "t_flush": round(t_flush, 4),
+            "t_retrieve": round(t_retrieve, 4),
+            "t_llm": round(self._llm_seconds, 4),
+            "t_embed": round(getattr(store, "embed_seconds", 0.0) - embed0, 4),
+            "t_vstore": round(getattr(store, "vstore_seconds", 0.0) - vstore0, 4),
+            "prompt_chars": len(decision.user_prompt or ""),
+            "store_size": store_size,
+        }
         return decision
 
     def on_action_result(
@@ -501,12 +534,14 @@ class ReActAgent:
 
         for attempt in range(2):
             try:
+                llm_t0 = time.perf_counter()
                 raw_text = self._client.complete(
                     messages,
                     response_format=response_format,
                     temperature=self._temperature,
                     max_tokens=self._max_tokens,
                 )
+                self._llm_seconds += time.perf_counter() - llm_t0
             except Exception as exc:
                 # Provider blew up: fall back to a safe MOVE rather than crash.
                 attempts.append(

src/labrats/env/actions.py

@@ -14,7 +14,7 @@ We mirror that schema here so we can:
 from __future__ import annotations
 
 from collections.abc import Mapping
-from typing import Any, Literal
+from typing import Any, Literal, get_args
 
 from pydantic import BaseModel, Field, ValidationError
 
@@ -34,6 +34,10 @@ ActionName = Literal[
     "DISCOVERY_FEED_GET_UPDATES", "DISCOVERY_FEED_GET_POST_BY_ID",
 ]
 
+# Case-insensitive lookup from any spelling the model emits to the canonical
+# enum value (e.g. "teleport_to_object" -> "TELEPORT_TO_OBJECT").
+_ACTION_NAME_LOOKUP = {name.lower(): name for name in get_args(ActionName)}
+
 DIRECTIONS = ("north", "east", "south", "west")
 
 UUID_1_ACTIONS = {
@@ -75,6 +79,68 @@ class ActionValidationError(Exception):
     """Raised when an action cannot be executed against the current obs."""
 
 
+def _unwrap_named_action(d: Mapping[str, Any]) -> dict[str, Any] | None:
+    """Normalize the action-name-as-key shapes the model emits without a grammar.
+
+    Grammar-free decoding lets Gemma invent encodings the JSON schema would
+    have forbidden, e.g.:
+        {"teleport_to_object": 47477}        -> arg1 = scalar
+        {"PUT": {"arg1": 1, "arg2": 2}}      -> nested arg dict
+        {"USE": [1, 2]}                      -> positional list
+    Returns the canonical `{"action": NAME, "arg1": .., "arg2": ..}` dict, or
+    None if exactly one action-name key isn't found (so canonical packets and
+    genuinely malformed ones fall through to Pydantic for a real error).
+    """
+    named = [
+        (key, _ACTION_NAME_LOOKUP[key.strip().lower()])
+        for key in d
+        if isinstance(key, str) and key.strip().lower() in _ACTION_NAME_LOOKUP
+    ]
+    if len(named) != 1:
+        return None
+    key, canon = named[0]
+    value = d[key]
+    out: dict[str, Any] = {"action": canon}
+    if isinstance(value, Mapping):
+        for slot in ("arg1", "arg2"):
+            if slot in value:
+                out[slot] = value[slot]
+    elif isinstance(value, (list, tuple)):
+        if len(value) >= 1:
+            out["arg1"] = value[0]
+        if len(value) >= 2:
+            out["arg2"] = value[1]
+    elif value is not None:
+        out["arg1"] = value
+    # Carry over any arg1/arg2 the model placed beside the named key.
+    for slot in ("arg1", "arg2"):
+        if slot in d and slot not in out:
+            out[slot] = d[slot]
+    return out
+
+
+def _coerce_action_shape(raw: Mapping[str, Any]) -> dict[str, Any]:
+    """Map common model deviations onto the canonical ActionPacket shape."""
+    data = dict(raw)
+    action = data.get("action")
+    # Canonical-ish: a string action name (normalize casing only).
+    if isinstance(action, str):
+        canon = _ACTION_NAME_LOOKUP.get(action.strip().lower())
+        if canon:
+            data["action"] = canon
+        return data
+    # {"action": {"PUT": {...}}} / {"action": {"teleport_to_object": id}}
+    if isinstance(action, Mapping):
+        unwrapped = _unwrap_named_action(action)
+        if unwrapped is not None:
+            return unwrapped
+    # Action name used directly as the top-level key, no "action" field.
+    unwrapped = _unwrap_named_action(data)
+    if unwrapped is not None:
+        return unwrapped
+    return data
+
+
 def parse(raw: Any) -> ActionPacket:
     """Coerce raw model output into an `ActionPacket`. Raises on failure."""
     if isinstance(raw, ActionPacket):
@@ -84,7 +150,7 @@ def parse(raw: Any) -> ActionPacket:
             f"action must be a JSON object, got {type(raw).__name__}"
         )
     try:
-        return ActionPacket.model_validate(dict(raw))
+        return ActionPacket.model_validate(_coerce_action_shape(raw))
     except ValidationError as e:
         raise ActionValidationError(str(e)) from e
 
@@ -381,6 +447,11 @@ def schema_summary_for_prompt() -> str:
         "\"action\".\n"
         "Action shape (the value of \"action\"): {\"action\": NAME, \"arg1\": "
         "..., \"arg2\": ...}\n"
+        "NAME is a string in the \"action\" field. Never use the action name "
+        "as a key or nest arguments — write {\"action\": \"PUT\", \"arg1\": 1, "
+        "\"arg2\": 2}, NOT {\"PUT\": {...}} or {\"action\": {\"put\": ...}}.\n"
+        "Example: {\"reason\": \"Pick up the shovel to start digging.\", "
+        "\"action\": {\"action\": \"PICKUP\", \"arg1\": 47477}}\n"
         "Argument rules (omit arg2 when not listed):\n"
         "  PICKUP/DROP/OPEN/CLOSE/ACTIVATE/DEACTIVATE/EAT/READ/TALK/"
         "TELEPORT_TO_OBJECT: arg1 = visible UUID (integer)\n"

src/labrats/live.py

@@ -73,6 +73,13 @@ def has_local_model() -> bool:
         or (os.environ.get("LLAMA_REPO_ID") and os.environ.get("LLAMA_FILENAME"))
     )
 
+def max_agents_cap() -> int:
+    """The max agents cap for live episodes."""
+    return int(os.environ.get("LIVE_MAX_AGENTS_CAP", 4))
+
+def max_steps_cap() -> int:
+    """The max steps cap for live episodes."""
+    return int(os.environ.get("LIVE_MAX_STEPS_CAP", 40))
 
 def backend_available(backend: str) -> bool:
     """Whether the given backend has its prerequisites configured."""
@@ -114,10 +121,10 @@ class LiveRunner:
 
     #: Hard ceiling on steps regardless of what the UI requests, to bound the
     #: cost of any single run against the shared token.
-    MAX_STEPS_CAP = 40
+    MAX_STEPS_CAP = max_steps_cap()
     #: Hard ceiling on agents for the same reason (each agent is an LLM call
     #: per tick).
-    MAX_AGENTS_CAP = 4
+    MAX_AGENTS_CAP = max_agents_cap()
 
     def __init__(
         self,

src/labrats/memory/embedder.py

@@ -6,6 +6,7 @@ without pulling sentence-transformers / downloading bge-small.
 
 from __future__ import annotations
 
+import contextlib
 import hashlib
 import time
 from typing import Protocol
@@ -35,12 +36,18 @@ class BGEEmbedder:
     def __init__(self, device: str | None = None) -> None:
         self._device = device
         self._model = None  # type: ignore[assignment]
+        # Filled in on first embed; exposed for the perf trace.
+        self.resolved_device: str | None = None
 
     def _ensure_model(self):
         if self._model is None:
             from sentence_transformers import SentenceTransformer
 
             self._model = SentenceTransformer(self.model_name, device=self._device)
+            # Surface the device actually chosen (CUDA vs CPU) — a CPU-bound
+            # BGE is a prime suspect for the local memory-step slowdown.
+            with contextlib.suppress(Exception):
+                self.resolved_device = str(self._model.device)
         return self._model
 
     def embed(self, texts: list[str]) -> np.ndarray:

src/labrats/memory/store.py

@@ -28,6 +28,7 @@ Chroma backend choices:
 from __future__ import annotations
 
 import contextlib
+import time
 from collections.abc import Iterable
 from pathlib import Path
 from typing import Any, Protocol
@@ -82,6 +83,14 @@ class ChromaMemoryStore:
         import chromadb
 
         self._embedder = embedder
+        # Cumulative perf counters (diagnosing memory-driven slowdown). All
+        # embedding goes through this store, so deltas around an agent step
+        # attribute time to embed vs vector-store (HNSW) cleanly. Agents run
+        # sequentially per tick, so monotonic counters split correctly.
+        self.embed_seconds = 0.0
+        self.embed_calls = 0
+        self.vstore_seconds = 0.0
+        self.vstore_calls = 0
         self._decay = decay
         self._weights = weights
         self._dedup = {
@@ -139,20 +148,30 @@ class ChromaMemoryStore:
 
     # ---- write -------------------------------------------------------
 
+    def _timed_embed(self, texts: list[str]) -> np.ndarray:
+        t0 = time.perf_counter()
+        out = self._embedder.embed(texts)
+        self.embed_seconds += time.perf_counter() - t0
+        self.embed_calls += 1
+        return out
+
     def write(self, record: MemoryRecord) -> bool:
         """Embed + insert. Returns False if dedup suppressed the write."""
         coll = self._collections[record.tier]
-        vec = self._embedder.embed([record.content])[0]
+        vec = self._timed_embed([record.content])[0]
 
         # Dedup: query same tier (author-scoped on private; cross-author on
         # notebook), require same type, and require cosine ≥ threshold.
         where = self._dedup_where(record)
+        t0 = time.perf_counter()
         existing = coll.query(
             query_embeddings=[vec.tolist()],
             n_results=1,
             where=where,
             include=["metadatas", "distances", "documents"],
         )
+        self.vstore_seconds += time.perf_counter() - t0
+        self.vstore_calls += 1
         ids = (existing.get("ids") or [[]])[0]
         if ids:
             dist = (existing.get("distances") or [[1.0]])[0][0]
@@ -161,12 +180,15 @@ class ChromaMemoryStore:
             if sim >= self._dedup[record.tier]:
                 return False
 
+        t0 = time.perf_counter()
         coll.add(
             ids=[record.id],
             documents=[record.content],
             embeddings=[vec.tolist()],
             metadatas=[_to_chroma_metadata(record)],
         )
+        self.vstore_seconds += time.perf_counter() - t0
+        self.vstore_calls += 1
         return True
 
     def _dedup_where(self, record: MemoryRecord) -> dict[str, Any]:
@@ -193,7 +215,7 @@ class ChromaMemoryStore:
         coll = self._collections[tier]
         if coll.count() == 0:
             return []
-        q_vec = self._embedder.embed([query_text])[0]
+        q_vec = self._timed_embed([query_text])[0]
         where = _build_where(tier=tier, author=author, type_filter=type_filter)
         kwargs: dict[str, Any] = {
             "query_embeddings": [q_vec.tolist()],
@@ -202,7 +224,10 @@ class ChromaMemoryStore:
         }
         if where is not None:
             kwargs["where"] = where
+        t0 = time.perf_counter()
         res = coll.query(**kwargs)
+        self.vstore_seconds += time.perf_counter() - t0
+        self.vstore_calls += 1
         ids = (res.get("ids") or [[]])[0]
         if not ids:
             return []

src/labrats/models/hf_provider.py

@@ -47,6 +47,7 @@ class HFProviderClient:
         provider: str | None = None,
         token: str | None = None,
         timeout: float = 60.0,
+        grammar: bool | None = None,
     ) -> None:
         self.model = model or os.environ.get("HF_MODEL", DEFAULT_MODEL)
         self.provider = provider or os.environ.get("HF_INFERENCE_PROVIDER", DEFAULT_PROVIDER)
@@ -61,6 +62,12 @@ class HFProviderClient:
             token=self._token,
             timeout=timeout,
         )
+        # `response_format` (json_schema grammar) is 8-31x slower on HF: with
+        # `provider="auto"` it routes to grammar-capable but slow providers
+        # (measured 8-31s/call vs ~0.7-1.3s free). We rely on the prompt + the
+        # agent's JSON extractor/coercion/validator/retry instead. Default OFF;
+        # set grammar=True (or HF_GRAMMAR=1) to re-enable constrained decoding.
+        self._grammar_enabled = _bool_env("HF_GRAMMAR", grammar, default=False)
         # Flips to False on the first 422 grammar rejection so we stop
         # paying the round-trip cost on every subsequent call.
         self._response_format_supported = True
@@ -74,7 +81,11 @@ class HFProviderClient:
         max_tokens: int = 512,
     ) -> str:
         payload = [m.to_dict() for m in messages]
-        rf = response_format if self._response_format_supported else None
+        rf = (
+            response_format
+            if self._grammar_enabled and self._response_format_supported
+            else None
+        )
         last_exc: Exception | None = None
         for attempt in range(2):
             try:
@@ -111,6 +122,19 @@ def _is_transient(exc: BaseException) -> bool:
     return any(h in msg for h in _TRANSIENT_HINTS)
 
 
+def _bool_env(name: str, override: bool | None, *, default: bool) -> bool:
+    """Resolve a tri-state bool: explicit override > env var > default.
+
+    Accepts 1/0, true/false, yes/no, on/off (case-insensitive) for the env.
+    """
+    if override is not None:
+        return override
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
 def _is_response_format_rejection(exc: BaseException) -> bool:
     msg = str(exc).lower()
     # Providers signal "I can't honor this response_format" with different

src/labrats/models/local_provider.py

@@ -46,6 +46,7 @@ class LocalLlamaClient:
         n_threads: int | None = None,
         seed: int | None = None,
         chat_format: str | None = None,
+        grammar: bool | None = None,
         verbose: bool = False,
         **llama_kwargs: Any,
     ) -> None:
@@ -104,6 +105,15 @@ class LocalLlamaClient:
             self.model = Path(path).name
             self._llama = Llama(model_path=path, **common_kwargs)
 
+        # Grammar-constrained decoding (JSON schema/object) is ~8-10x slower
+        # on large-vocab models like Gemma-4 (262k vocab): llama-cpp filters
+        # the grammar against candidate tokens every step. When disabled we
+        # drop `response_format` and rely on the prompt + the agent's JSON
+        # extractor/validator/retry instead. Default OFF (a controlled A/B
+        # showed identical task score at ~3.8x the speed); set grammar=True
+        # (or LLAMA_GRAMMAR=1) to re-enable constrained decoding.
+        self._grammar_enabled = _bool_env("LLAMA_GRAMMAR", grammar, default=False)
+
         # Flips to False on the first grammar compile failure so we stop
         # paying the round-trip cost on every subsequent call.
         self._response_format_supported = True
@@ -117,7 +127,11 @@ class LocalLlamaClient:
         max_tokens: int = 512,
     ) -> str:
         payload = [m.to_dict() for m in messages]
-        rf = _normalize_response_format(response_format) if self._response_format_supported else None
+        rf = (
+            _normalize_response_format(response_format)
+            if self._grammar_enabled and self._response_format_supported
+            else None
+        )
         try:
             resp = self._llama.create_chat_completion(
                 messages=payload,
@@ -170,6 +184,19 @@ def _int_env_optional(name: str, override: int | None) -> int | None:
     return int(raw) if raw is not None and raw != "" else None
 
 
+def _bool_env(name: str, override: bool | None, *, default: bool) -> bool:
+    """Resolve a tri-state bool: explicit override > env var > default.
+
+    Accepts 1/0, true/false, yes/no, on/off (case-insensitive) for the env.
+    """
+    if override is not None:
+        return override
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
 def _is_grammar_rejection(exc: BaseException) -> bool:
     msg = str(exc).lower()
     return any(h in msg for h in _GRAMMAR_REJECT_HINTS)

src/labrats/orchestrator/episode.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import contextlib
 import hashlib
+import time
 from collections.abc import Iterator, Mapping
 from pathlib import Path
 from typing import Any
@@ -12,6 +13,7 @@ from ..agents.base import Agent
 from ..env.world import DiscoveryWorldEnv
 from ..memory.store import MemoryStore
 from ..telemetry.agents_log import AgentsLogWriter, _fmt_action
+from ..telemetry.perf import PerfMonitor
 from ..telemetry.trace import TraceWriter
 from .bus import MessageBus
 from .scheduler import SimultaneousScheduler, TickOutcome
@@ -114,7 +116,18 @@ def run_episode(
             )
 
     try:
-        for outcome in _iter_ticks(scheduler, max_steps):
+        monitor = PerfMonitor(enabled=progress)
+        tick_iter = _iter_ticks(scheduler, max_steps)
+        while True:
+            tick_t0 = time.perf_counter()
+            try:
+                outcome = next(tick_iter)
+            except StopIteration:
+                break
+            tick_wall = time.perf_counter() - tick_t0
+            monitor.start_tick()
+            for idx in outcome.decisions:
+                monitor.record_step(getattr(agents[idx], "last_timings", None))
             if trace is not None:
                 for idx, decision in outcome.decisions.items():
                     res = outcome.results[idx]
@@ -139,6 +152,9 @@ def run_episode(
                         "memory": memory_summary,
                         "utterance": _utterance_summary(decision),
                     }
+                    timings = getattr(agent, "last_timings", None)
+                    if timings:
+                        step_fields["timings"] = timings
                     if verbose_agents:
                         cur_sp = getattr(agent, "_last_system_prompt", "")
                         sp_hash = _sys_hash(cur_sp) if cur_sp else ""
@@ -213,9 +229,17 @@ def run_episode(
                         f"successes={successes}/{len(outcome.results)} "
                         f"progress={_progress_summary(env.scorecard())}"
                     )
+            perf_line = monitor.end_tick(
+                outcome.tick, outcome.step_counter, tick_wall
+            )
+            if perf_line:
+                print(perf_line)
             if outcome.tasks_complete:
                 break
 
+        perf_summary = monitor.summary()
+        if perf_summary:
+            print(perf_summary)
         final_scorecard = env.scorecard()
         summary = {
             "tasks_complete": env.tasks_complete(),

src/labrats/telemetry/perf.py

@@ -0,0 +1,106 @@
+"""Live performance monitor for episode runs.
+
+Aggregates the per-step `timings` block each agent exposes (see
+`ReActAgent.last_timings`) and turns it into a compact per-tick line plus an
+end-of-episode breakdown. This makes the "where does the 30s/tick go?" answer
+visible *during* a run instead of only post-hoc from the trace.
+
+Buckets tracked per step (seconds): t_llm, t_embed, t_vstore, t_flush,
+t_retrieve, plus t_step (measured agent-step wall) and the raw tick wall time.
+All buckets are summed across the agents that acted in a tick, because the
+scheduler runs them sequentially — so their times add up to the tick wall.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+# Buckets we attribute, in print order. t_llm first because it dominates.
+BUCKETS = ("t_llm", "t_embed", "t_vstore", "t_flush", "t_retrieve")
+_SHORT = {
+    "t_llm": "llm",
+    "t_embed": "embed",
+    "t_vstore": "vstore",
+    "t_flush": "flush",
+    "t_retrieve": "retr",
+}
+
+
+@dataclass
+class PerfMonitor:
+    """Accumulates per-step timings and prints per-tick + summary lines.
+
+    `enabled=False` makes every method a cheap no-op so callers can wire it
+    in unconditionally.
+    """
+
+    enabled: bool = True
+    _totals: dict[str, float] = field(default_factory=lambda: defaultdict(float))
+    _tick_buf: dict[str, float] = field(default_factory=lambda: defaultdict(float))
+    _tick_agents: int = 0
+    _tick_max_store: int = 0
+    _n_ticks: int = 0
+    _n_steps: int = 0
+    _wall_total: float = 0.0
+
+    def start_tick(self) -> None:
+        """Reset the per-tick accumulators (call before agents act)."""
+        if not self.enabled:
+            return
+        self._tick_buf = defaultdict(float)
+        self._tick_agents = 0
+        self._tick_max_store = 0
+
+    def record_step(self, timings: dict[str, float] | None) -> None:
+        """Fold one agent's `last_timings` into the current tick + totals."""
+        if not self.enabled or not timings:
+            return
+        self._n_steps += 1
+        self._tick_agents += 1
+        for key in (*BUCKETS, "t_step"):
+            val = float(timings.get(key, 0.0))
+            self._tick_buf[key] += val
+            self._totals[key] += val
+        store = int(timings.get("store_size", 0))
+        self._tick_max_store = max(self._tick_max_store, store)
+
+    def end_tick(self, tick: int, step: int, wall: float) -> str | None:
+        """Close the tick, update wall totals, and return a one-line summary."""
+        if not self.enabled:
+            return None
+        self._wall_total += wall
+        self._n_ticks += 1
+        accounted = sum(self._tick_buf.get(b, 0.0) for b in BUCKETS)
+        parts = " ".join(
+            f"{_SHORT[b]}={self._tick_buf.get(b, 0.0):.2f}" for b in BUCKETS
+        )
+        other = max(0.0, wall - accounted)
+        return (
+            f"  [perf] tick={tick:03d} wall={wall:5.2f}s  {parts} "
+            f"other={other:.2f}  store={self._tick_max_store}"
+        )
+
+    def summary(self) -> str | None:
+        """Episode-level attribution: per-bucket totals, share, per-tick mean."""
+        if not self.enabled or self._n_ticks == 0:
+            return None
+        accounted = sum(self._totals.get(b, 0.0) for b in BUCKETS)
+        denom = max(self._wall_total, accounted) or 1.0
+        lines = [
+            "  [perf] episode summary "
+            f"(ticks={self._n_ticks} steps={self._n_steps} "
+            f"wall={self._wall_total:.1f}s):"
+        ]
+        for b in BUCKETS:
+            tot = self._totals.get(b, 0.0)
+            lines.append(
+                f"    {_SHORT[b]:>7}: {tot:7.2f}s  ({100 * tot / denom:5.1f}%)  "
+                f"{tot / self._n_ticks:.2f}s/tick"
+            )
+        other = max(0.0, self._wall_total - accounted)
+        lines.append(
+            f"    {'other':>7}: {other:7.2f}s  ({100 * other / denom:5.1f}%)  "
+            f"{other / self._n_ticks:.2f}s/tick"
+        )
+        return "\n".join(lines)