feat: implement NPC model switching and admin API for model management

config/game.llm.local.json

@@ -56,11 +56,11 @@
       "base_url": "https://georgij-sawin--world-simulator-qwen36-27b-h100-serve.modal.run/v1",
       "model": "qwen3.6-27b-h100-fp8",
       "timeout_seconds": 600,
-      "max_tokens": 1200,
+      "max_tokens": 256,
       "temperature": 0.6,
       "top_p": 0.95,
-      "tool_choice": "required",
-      "max_parallel_npc_calls": 6,
+      "tool_choice": "auto",
+      "max_parallel_npc_calls": 2,
       "fallback_to_deterministic": true,
       "extra_body": {
         "chat_template_kwargs": {

config/game.modal.local.json

@@ -60,11 +60,11 @@
       "base_url": "https://georgij-sawin--world-simulator-qwen36-27b-h100-serve.modal.run/v1",
       "model": "qwen3.6-27b-h100-fp8",
       "timeout_seconds": 600,
-      "max_tokens": 1200,
+      "max_tokens": 256,
       "temperature": 0.6,
       "top_p": 0.95,
-      "tool_choice": "required",
-      "max_parallel_npc_calls": 6,
+      "tool_choice": "auto",
+      "max_parallel_npc_calls": 2,
       "fallback_to_deterministic": true,
       "extra_body": {
         "chat_template_kwargs": {

frontend/src/App.tsx

@@ -45,7 +45,12 @@ export function App() {
         resource={simulation.selectedResource}
         house={simulation.selectedHouse}
         entities={simulation.snapshot?.entities ?? []}
+        modelProfiles={simulation.modelProfiles}
+        isModelSwitchPending={simulation.isModelSwitchPending}
         onSelectEntity={simulation.setSelectedId}
+        onSetNpcModel={(npcId, profileId) => {
+          void simulation.setNpcModel(npcId, profileId);
+        }}
       />
 
       <StatusToasts

frontend/src/api.ts

@@ -1,6 +1,7 @@
-import type { WorldSnapshot } from "./types";
+import type { AdminModelsSnapshot, WorldSnapshot } from "./types";
 
 const API_BASE = import.meta.env.VITE_WORLD_SIMULATOR_API ?? defaultApiBase();
+const ADMIN_TOKEN_STORAGE_KEY = "world-simulator-admin-token";
 
 function defaultApiBase(): string {
   if (window.location.hostname === "127.0.0.1" && window.location.port === "5173") {
@@ -41,3 +42,42 @@ export async function tickWorld(): Promise<void> {
     throw new ApiResponseError(`World tick failed: ${response.status}`, response.status);
   }
 }
+
+export async function fetchAdminModels(signal?: AbortSignal): Promise<AdminModelsSnapshot> {
+  const response = await fetch(`${API_BASE}/admin/models`, {
+    headers: adminHeaders(),
+    signal,
+  });
+  if (!response.ok) {
+    throw new ApiResponseError(`Model profiles failed: ${response.status}`, response.status);
+  }
+  return (await response.json()) as AdminModelsSnapshot;
+}
+
+export async function setNpcModelProfile(npcId: string, profileId: string): Promise<void> {
+  const response = await fetch(`${API_BASE}/admin/npcs/${encodeURIComponent(npcId)}/model`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...adminHeaders(),
+    },
+    body: JSON.stringify({ profile_id: profileId }),
+  });
+  if (!response.ok) {
+    throw new ApiResponseError(`NPC model switch failed: ${response.status}`, response.status);
+  }
+}
+
+function adminHeaders(): Record<string, string> {
+  return {
+    "X-Admin-Token": adminToken(),
+  };
+}
+
+function adminToken(): string {
+  return (
+    import.meta.env.VITE_WORLD_SIMULATOR_ADMIN_TOKEN ||
+    window.localStorage.getItem(ADMIN_TOKEN_STORAGE_KEY) ||
+    "dev-admin-token"
+  );
+}

frontend/src/components/AgentPanel.tsx

@@ -2,6 +2,7 @@ import type {
   BeastSnapshot,
   EntitySnapshot,
   HouseSnapshot,
+  ModelProfileSnapshot,
   ResourceNodeSnapshot,
 } from "../types";
 import { TooltipLabel } from "./TooltipLabel";
@@ -12,7 +13,10 @@ type AgentPanelProps = {
   resource?: ResourceNodeSnapshot | null;
   house?: HouseSnapshot | null;
   entities?: EntitySnapshot[];
+  modelProfiles?: ModelProfileSnapshot[];
+  isModelSwitchPending?: boolean;
   onSelectEntity?: (id: string) => void;
+  onSetNpcModel?: (npcId: string, profileId: string) => void;
 };
 
 export function AgentPanel({
@@ -21,7 +25,10 @@ export function AgentPanel({
   resource = null,
   house = null,
   entities = [],
+  modelProfiles = [],
+  isModelSwitchPending = false,
   onSelectEntity,
+  onSetNpcModel,
 }: AgentPanelProps) {
   if (beast) {
     return <BeastPanel beast={beast} />;
@@ -44,7 +51,16 @@ export function AgentPanel({
         <TooltipLabel className="panelTitle" value={selectedName} />
         <TooltipLabel className="panelRole" value={selectedRole} />
       </div>
-      {entity ? <AgentDetails entity={entity} /> : <EmptyAgentReadout />}
+      {entity ? (
+        <AgentDetails
+          entity={entity}
+          modelProfiles={modelProfiles}
+          isModelSwitchPending={isModelSwitchPending}
+          onSetNpcModel={onSetNpcModel}
+        />
+      ) : (
+        <EmptyAgentReadout />
+      )}
     </aside>
   );
 }
@@ -185,10 +201,28 @@ function HouseResidentList({ label, ids, emptyLabel, entities, onSelectEntity }:
   );
 }
 
-function AgentDetails({ entity }: { entity: EntitySnapshot }) {
+type AgentDetailsProps = {
+  entity: EntitySnapshot;
+  modelProfiles: ModelProfileSnapshot[];
+  isModelSwitchPending: boolean;
+  onSetNpcModel?: (npcId: string, profileId: string) => void;
+};
+
+function AgentDetails({
+  entity,
+  modelProfiles,
+  isModelSwitchPending,
+  onSetNpcModel,
+}: AgentDetailsProps) {
   return (
     <>
       <AgentReadout entity={entity} />
+      <ModelSwitcher
+        entity={entity}
+        profiles={modelProfiles}
+        isPending={isModelSwitchPending}
+        onSetNpcModel={onSetNpcModel}
+      />
       <SurvivalReadout entity={entity} />
       <RelationshipList entity={entity} />
       <MemoryList entity={entity} />
@@ -196,6 +230,39 @@ function AgentDetails({ entity }: { entity: EntitySnapshot }) {
   );
 }
 
+type ModelSwitcherProps = {
+  entity: EntitySnapshot;
+  profiles: ModelProfileSnapshot[];
+  isPending: boolean;
+  onSetNpcModel?: (npcId: string, profileId: string) => void;
+};
+
+function ModelSwitcher({ entity, profiles, isPending, onSetNpcModel }: ModelSwitcherProps) {
+  if (profiles.length === 0) {
+    return null;
+  }
+
+  const currentProfile = entity.model_profile_id ?? entity.connector_id ?? "default";
+
+  return (
+    <label className="modelControl">
+      <span>Model</span>
+      <select
+        value={currentProfile}
+        disabled={isPending || !onSetNpcModel}
+        onChange={(event) => onSetNpcModel?.(entity.id, event.currentTarget.value)}
+      >
+        {profiles.map((profile) => (
+          <option key={profile.id} value={profile.id}>
+            {profile.label || profile.id}
+            {profile.model ? ` - ${profile.model}` : ""}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+}
+
 function SurvivalReadout({ entity }: { entity: EntitySnapshot }) {
   const { hunger, fear, safety, age, max_age, importance, goal, inventory } = entity.state;
   if (

frontend/src/hooks/useWorldSimulation.ts

@@ -1,12 +1,20 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
-import { ApiResponseError, fetchWorldSnapshot, tickWorld } from "../api";
-import type { GameLogEventSnapshot, WorldSnapshot } from "../types";
+import {
+  ApiResponseError,
+  fetchAdminModels,
+  fetchWorldSnapshot,
+  setNpcModelProfile,
+  tickWorld,
+} from "../api";
+import type { GameLogEventSnapshot, ModelProfileSnapshot, WorldSnapshot } from "../types";
 
 export function useWorldSimulation() {
   const [snapshot, setSnapshot] = useState<WorldSnapshot | null>(null);
   const [isTickPending, setIsTickPending] = useState(false);
   const [isAutoTicking, setIsAutoTicking] = useState(false);
+  const [isModelSwitchPending, setIsModelSwitchPending] = useState(false);
+  const [modelProfiles, setModelProfiles] = useState<ModelProfileSnapshot[]>([]);
   const [error, setError] = useState<string | null>(null);
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const isTickingRef = useRef(false);
@@ -47,7 +55,30 @@ export function useWorldSimulation() {
     }
   }, [refresh, snapshot?.simulation.tick_in_progress]);
 
+  const refreshModelProfiles = useCallback(async () => {
+    const adminModels = await fetchAdminModels();
+    setModelProfiles(adminModels.profiles);
+  }, []);
+
+  const setNpcModel = useCallback(
+    async (npcId: string, profileId: string) => {
+      setIsModelSwitchPending(true);
+      setError(null);
+      try {
+        await setNpcModelProfile(npcId, profileId);
+        await refresh();
+        await refreshModelProfiles();
+      } catch (nextError) {
+        setError(nextError instanceof Error ? nextError.message : "NPC model switch failed");
+      } finally {
+        setIsModelSwitchPending(false);
+      }
+    },
+    [refresh, refreshModelProfiles],
+  );
+
   useInitialSnapshot(setSnapshot, setSelectedId, setError);
+  useInitialModelProfiles(setModelProfiles);
   useSelectedEntityFallback(snapshot, setSelectedId);
   useServerTickPolling(isServerTickPending, refresh, setError);
   useIdleSnapshotPolling({
@@ -90,20 +121,42 @@ export function useWorldSimulation() {
     error,
     eventHistory,
     isAutoTicking,
+    isModelSwitchPending,
     isWaitingForTick,
     isWorldCommandPending,
+    modelProfiles,
     selectedBeast,
     selectedEntity,
     selectedHouse,
     selectedResource,
     selectedId,
     setIsAutoTicking,
+    setNpcModel,
     setSelectedId,
     snapshot,
     step,
   };
 }
 
+function useInitialModelProfiles(
+  setModelProfiles: (profiles: ModelProfileSnapshot[]) => void,
+) {
+  useEffect(() => {
+    const abortController = new AbortController();
+    fetchAdminModels(abortController.signal)
+      .then((adminModels) => {
+        setModelProfiles(adminModels.profiles);
+      })
+      .catch(() => {
+        if (!abortController.signal.aborted) {
+          setModelProfiles([]);
+        }
+      });
+
+    return () => abortController.abort();
+  }, [setModelProfiles]);
+}
+
 function useEventHistory(snapshot: WorldSnapshot | null): GameLogEventSnapshot[] {
   const seenKeysRef = useRef<Set<string>>(new Set());
   const [history, setHistory] = useState<GameLogEventSnapshot[]>([]);

frontend/src/styles.css

@@ -538,6 +538,38 @@ button {
   font-weight: 750;
 }
 
+.modelControl {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-top: 1px solid rgb(255 255 255 / 10%);
+  background: rgb(255 255 255 / 5%);
+}
+
+.modelControl span {
+  color: #c7e6bd;
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+}
+
+.modelControl select {
+  min-width: 0;
+  height: 30px;
+  border: 1px solid rgb(255 255 255 / 18%);
+  border-radius: 6px;
+  background: rgb(18 28 23 / 88%);
+  color: #fffce9;
+  font-size: 11px;
+}
+
+.modelControl select:disabled {
+  opacity: 0.65;
+}
+
 .directiveBanner {
   display: grid;
   gap: 4px;

frontend/src/types.ts

@@ -32,6 +32,8 @@ export type EntitySnapshot = {
   role: string;
   country_id?: string | null;
   special_status?: string | null;
+  model_profile_id?: string | null;
+  connector_id?: string | null;
   position: Vec3;
   state: {
     intention: string;
@@ -216,3 +218,22 @@ export type ModelStatusSnapshot = {
   status: "unknown" | "checking" | "warmup" | "ready" | "error" | string;
   http_status: number | null;
 };
+
+export type ModelProfileSnapshot = {
+  id: string;
+  label: string;
+  connector_id?: string | null;
+  model?: string | null;
+  type?: string;
+};
+
+export type AdminModelsSnapshot = {
+  profiles: ModelProfileSnapshot[];
+  npcs: {
+    id: string;
+    name: string;
+    country_id: string | null;
+    model_profile_id: string | null;
+    connector_id: string | null;
+  }[];
+};

src/world_simulator/api/runtime.py

@@ -360,7 +360,7 @@ class GameRuntime:
                 raw = {}
             for item in raw.get("profiles", []) if isinstance(raw, dict) else []:
                 if isinstance(item, dict) and isinstance(item.get("id"), str):
-                    profiles[item["id"]] = dict(item)
+                    profiles[item["id"]] = {**profiles.get(item["id"], {}), **item}
         return list(profiles.values())
 
     def _override_player_directives(self, world: WorldState, plan: TickPlan) -> TickPlan:

src/world_simulator/api/server.py

@@ -3,8 +3,9 @@ from __future__ import annotations
 import json
 from http import HTTPStatus
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import os
 from typing import Any
-from urllib.parse import parse_qs, urlparse
+from urllib.parse import parse_qs, unquote, urlparse
 
 from world_simulator.api.runtime import (
     GameRuntime,
@@ -100,6 +101,11 @@ def build_handler(runtime: GameRuntime) -> type[BaseHTTPRequestHandler]:
                     runtime.scene_state(warmup=_truthy_query_value(query, "warmup"))
                 )
                 return
+            if path == "/admin/models":
+                if not self._require_admin():
+                    return
+                self._send_json(runtime.admin_models())
+                return
 
             self._send_json(
                 {"error": "not_found", "path": path},
@@ -107,13 +113,31 @@ def build_handler(runtime: GameRuntime) -> type[BaseHTTPRequestHandler]:
             )
 
         def do_POST(self) -> None:
-            if self.path == "/tick":
+            parsed_path = urlparse(self.path)
+            path = parsed_path.path
+
+            if path == "/tick":
                 status, payload = runtime.tick()
                 self._send_json(payload, status=status)
                 return
+            if path.startswith("/admin/npcs/") and path.endswith("/model"):
+                if not self._require_admin():
+                    return
+                npc_id = unquote(path.removeprefix("/admin/npcs/").removesuffix("/model"))
+                try:
+                    profile_id = self._read_json_field("profile_id")
+                except ValueError as exc:
+                    self._send_json(
+                        {"error": "bad_request", "message": str(exc)},
+                        status=HTTPStatus.BAD_REQUEST,
+                    )
+                    return
+                status, payload = runtime.admin_set_npc_model(npc_id, profile_id)
+                self._send_json(payload, status=status)
+                return
 
             self._send_json(
-                {"error": "not_found", "path": self.path},
+                {"error": "not_found", "path": path},
                 status=HTTPStatus.NOT_FOUND,
             )
 
@@ -140,7 +164,17 @@ def build_handler(runtime: GameRuntime) -> type[BaseHTTPRequestHandler]:
         def _send_cors_headers(self) -> None:
             self.send_header("Access-Control-Allow-Origin", "*")
             self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
-            self.send_header("Access-Control-Allow-Headers", "Content-Type")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, X-Admin-Token")
+
+        def _require_admin(self) -> bool:
+            expected = os.getenv("ADMIN_TOKEN", "dev-admin-token")
+            if self.headers.get("X-Admin-Token") == expected:
+                return True
+            self._send_json(
+                {"error": "admin_token_required"},
+                status=HTTPStatus.FORBIDDEN,
+            )
+            return False
 
         def _read_json_field(self, field: str) -> str:
             length_raw = self.headers.get("Content-Length")

src/world_simulator/rendering/scene_contract.py

@@ -51,6 +51,8 @@ def to_scene_snapshot(
                 "role": npc.role,
                 "country_id": npc.country_id,
                 "special_status": npc.special_status,
+                "model_profile_id": npc.model_profile_id,
+                "connector_id": npc.connector_id,
                 "position": {
                     "x": npc.position.x,
                     "y": npc.position.y,

src/world_simulator/simulation/connectors/openai_compatible.py

@@ -47,6 +47,7 @@ from world_simulator.simulation.survival import (
 from world_simulator.simulation.survival import select_goal as select_survival_goal
 
 ChatCompleter = Callable[[dict[str, Any]], dict[str, Any]]
+MODEL_CALL_ATTEMPTS = 3
 
 
 @dataclass(frozen=True, slots=True)
@@ -315,7 +316,7 @@ class OpenAICompatibleWorldSimulator:
         )
 
     def propose_tick(self, world: WorldState, next_tick: int) -> TickPlan:
-        fallback_plan = self._fallback.propose_tick(world, next_tick)
+        fallback_plan = self._owned_fallback_plan(world, next_tick)
 
         try:
             llm_plan = self._call_model(world, next_tick)
@@ -363,6 +364,32 @@ class OpenAICompatibleWorldSimulator:
             ledger_entries=[*llm_plan.ledger_entries, *fallback_entries],
         )
 
+    def _owned_fallback_plan(self, world: WorldState, next_tick: int) -> TickPlan:
+        fallback_plan = self._fallback.propose_tick(world, next_tick)
+        if self._connector_id_filter is _UNSET:
+            return fallback_plan
+
+        owned_npc_ids = {
+            npc.id
+            for npc in world.npcs
+            if is_alive(npc) and npc.connector_id == self._connector_id_filter
+        }
+        return TickPlan(
+            source=fallback_plan.source,
+            directives=[
+                directive
+                for directive in fallback_plan.directives
+                if directive.npc_id in owned_npc_ids
+            ],
+            overseer=fallback_plan.overseer,
+            ledger_entries=[
+                entry
+                for entry in fallback_plan.ledger_entries
+                if entry.get("npc_id") is None
+                or str(entry.get("npc_id")) in owned_npc_ids
+            ],
+        )
+
     def _call_model(self, world: WorldState, next_tick: int) -> TickPlan:
         assert self._config.model is not None
 
@@ -380,7 +407,18 @@ class OpenAICompatibleWorldSimulator:
             directives.extend(result.directives)
             ledger_entries.extend(result.ledger_entries)
 
-        missing_npcs = _missing_npcs(living_npcs, directives)
+        # Only retry NPCs the model never actually answered for (e.g. a batch
+        # call that omitted them). An NPC whose own call already failed/errored
+        # has an npc_response logged, so we must NOT call it again: re-hitting a
+        # dead/slow endpoint doubles every failure and freezes the tick.
+        attempted = {
+            str(entry.get("npc_id"))
+            for entry in ledger_entries
+            if entry.get("phase") == "npc_response"
+        }
+        missing_npcs = [
+            npc for npc in _missing_npcs(living_npcs, directives) if npc.id not in attempted
+        ]
         if missing_npcs:
             print(
                 f"Retrying {len(missing_npcs)} NPC(s) without LLM directives individually.",
@@ -425,6 +463,19 @@ class OpenAICompatibleWorldSimulator:
 
         return list(results)
 
+    def _complete_with_retries(self, request: dict[str, Any], npc_id: str) -> dict[str, Any]:
+        last_error: Exception | None = None
+        for attempt in range(1, MODEL_CALL_ATTEMPTS + 1):
+            try:
+                return self._chat_completer(request)
+            except Exception as exc:
+                last_error = exc
+                if attempt >= MODEL_CALL_ATTEMPTS:
+                    break
+                time.sleep(0.5 * attempt)
+        assert last_error is not None
+        raise last_error
+
     def _call_model_for_npc(
         self,
         world: WorldState,
@@ -442,7 +493,7 @@ class OpenAICompatibleWorldSimulator:
         )
         try:
             started = time.perf_counter()
-            response = self._chat_completer(request)
+            response = self._complete_with_retries(request, npc.id)
             latency_ms = round((time.perf_counter() - started) * 1000)
         except Exception as exc:
             print(

tests/test_api_server.py

@@ -13,7 +13,9 @@ from world_simulator.api.server import (
     _modal_health_urls,
     _ModalHealthTarget,
     _ModalHealthWarmer,
+    build_handler,
 )
+from world_simulator.api.runtime import GameRuntime
 from world_simulator.config import (
     ConnectorConfig,
     GameConfig,
@@ -181,6 +183,62 @@ def test_modal_health_urls_use_only_modal_openai_connectors() -> None:
     ]
 
 
+def test_http_server_admin_can_switch_npc_model(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ADMIN_TOKEN", "test-admin")
+    config = _config(
+        npc_count=2,
+        connector=ConnectorConfig(
+            type="openai_compatible",
+            base_url="https://workspace--npc-serve.modal.run/v1",
+            model="npc-model",
+        ),
+        secondary_connectors={
+            "qwen": ConnectorConfig(
+                type="openai_compatible",
+                base_url="https://workspace--qwen-serve.modal.run/v1",
+                model="qwen-model",
+            )
+        },
+    )
+    world = create_world(config)
+    runtime = GameRuntime(world=world, simulator=_SlowSimulator(), config=config)
+    server = ThreadingHTTPServer(("127.0.0.1", 0), build_handler(runtime))
+    port = int(server.server_address[1])
+    server_thread = Thread(target=server.serve_forever, daemon=True)
+
+    server_thread.start()
+    try:
+        status, payload = _request_json(
+            port,
+            "GET",
+            "/admin/models",
+            timeout=1,
+            headers={"X-Admin-Token": "test-admin"},
+        )
+        assert status == 200
+        assert {profile["id"] for profile in payload["profiles"]} >= {"default", "qwen"}
+        qwen_profile = next(profile for profile in payload["profiles"] if profile["id"] == "qwen")
+        assert qwen_profile["model"] == "qwen-model"
+
+        status, payload = _request_json(
+            port,
+            "POST",
+            "/admin/npcs/npc-001/model",
+            timeout=1,
+            headers={"X-Admin-Token": "test-admin"},
+            body={"profile_id": "qwen"},
+        )
+
+        assert status == 200
+        assert payload["profile"]["id"] == "qwen"
+        assert world.npcs[0].model_profile_id == "qwen"
+        assert world.npcs[0].connector_id == "qwen"
+    finally:
+        server.shutdown()
+        server.server_close()
+        server_thread.join(timeout=1)
+
+
 def test_forced_modal_warmup_does_not_duplicate_inflight_checks() -> None:
     opener = _BlockingOpener()
     warmer = _ModalHealthWarmer(
@@ -322,10 +380,16 @@ def _request_json(
     path: str,
     *,
     timeout: float,
+    headers: dict[str, str] | None = None,
+    body: dict[str, Any] | None = None,
 ) -> tuple[int, dict[str, Any]]:
     connection = HTTPConnection("127.0.0.1", port, timeout=timeout)
     try:
-        connection.request(method, path)
+        request_body = json.dumps(body).encode("utf-8") if body is not None else None
+        request_headers = dict(headers or {})
+        if request_body is not None:
+            request_headers.setdefault("Content-Type", "application/json")
+        connection.request(method, path, body=request_body, headers=request_headers)
         response = connection.getresponse()
         body = response.read().decode("utf-8")
     finally:

tests/test_country_systems.py

@@ -116,6 +116,8 @@ def test_routing_preserves_ledger_entries_with_model_per_npc() -> None:
     }
     # Every living NPC of both countries produced a logged request.
     assert {n.id for n in world.living_npcs()} <= set(requests)
+    assert "deterministic" not in plan.source
+    assert not [e for e in plan.ledger_entries if e.get("phase") == "npc_fallback"]
 
     nemo = requests["npc-001"]
     assert nemo["model"] == "nemotron-test"

tests/test_openai_connector.py

@@ -518,6 +518,58 @@ def test_openai_connector_malformed_json_output_falls_back_without_breaking_tick
     assert world.last_tick_source == "openai_compatible"
 
 
+def test_openai_connector_retries_transient_model_call_failure() -> None:
+    calls = 0
+
+    def flaky_chat_completer(request: dict[str, Any]) -> dict[str, Any]:
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            raise RuntimeError("temporary network failure")
+        payload = json.loads(request["messages"][1]["content"])
+        npc_id = payload["npc"]["id"]
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "tool_calls": [
+                            {
+                                "type": "function",
+                                "function": {
+                                    "name": "move",
+                                    "arguments": json.dumps(
+                                        {
+                                            "npc_id": npc_id,
+                                            "target_x": 5,
+                                            "target_z": 6,
+                                        }
+                                    ),
+                                },
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+
+    world = create_world(_game_config(npc_count=1))
+    simulator = OpenAICompatibleWorldSimulator(
+        ConnectorConfig(
+            type="openai_compatible",
+            base_url="http://llm.local/v1",
+            model="test-model",
+        ),
+        fallback=DeterministicWorldSimulator(),
+        chat_completer=flaky_chat_completer,
+    )
+
+    plan = simulator.propose_tick(world, 1)
+
+    assert calls == 2
+    assert len(plan.directives) == 1
+    assert not [entry for entry in plan.ledger_entries if entry.get("phase") == "npc_fallback"]
+
+
 def test_openai_connector_parses_optional_json_intent_and_confidence() -> None:
     world = create_world(_game_config(npc_count=1))
     response = {