rpr-cli 0.3.3__tar.gz → 0.3.4__tar.gz

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rpr-cli
-Version: 0.3.3
+Version: 0.3.4
 Summary: RPR CLI -- React Python Rust monorepo scaffolding orchestrator
 License-Expression: MIT
 License-File: LICENSE

rpr_cli-0.3.4/src/rpr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.4"

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/commands/init.py

@@ -727,8 +727,8 @@ uv.lock
     ctx.write_file(ctx.project_dir / ".gitignore", content)
 
 
-def _write_env_example(ctx: RunContext) -> None:
-    content = """# Database
+def _write_env_example(ctx: RunContext, name_underscore: str) -> None:
+    content = f"""# Database
 DATABASE_URL=
 
 # Auth
@@ -742,13 +742,10 @@ FERNET_KEY=
 API_BASE_URL=http://localhost:8000
 
 # vLLM
-VLLM_BASE_URL=http://localhost:8000/v1
 VLLM_API_KEY=EMPTY
-VLLM_MODEL_ID=google/gemma-4-12B-it-qat-q4_0-gguf
-# Optional multi-server catalog. Each reasoning-capable profile must match its
-# server's reasoning parser. Omitted providerProperties.mode defaults to online.
-# VLLM_MODEL_CATALOG=[{"id":"gemma","label":"Gemma","modelId":"google/gemma","baseUrl":"http://localhost:8000/v1","reasoningParser":"gemma4","supportsThinking":true}]
-# VLLM_DEFAULT_MODEL_PROFILE_ID=gemma
+# Model profiles, the default profile, restoration policy, and awake-model
+# capacity are maintained in
+# packages/python/{name_underscore}_domain/src/{name_underscore}_domain/services/agents/model_catalog.py.
 VLLM_THINKING_EFFORT=high
 """
     ctx.write_file(ctx.project_dir / ".env.example", content)
@@ -893,7 +890,7 @@ def init(
     _write_dependency_cruiser_config(ctx)
     _write_pre_commit_config(ctx)
     _write_gitignore(ctx)
-    _write_env_example(ctx)
+    _write_env_example(ctx, variables["name_underscore"])
 
     # ------------------------------------------------------------------
     # Step 5 – AI instruction files

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/domain/settings.md

@@ -9,54 +9,10 @@ The first Python block is the generated file used by `rpr generate domain` and `
 ```python
 from __future__ import annotations
 
-from pydantic import AliasChoices, BaseModel, Field, JsonValue, model_validator
+from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
-class VllmModelProfileSettings(BaseModel):
-    """One vLLM deployment available to the chat application."""
-
-    id: str = Field(description="Stable public model-profile identifier.")
-    label: str = Field(description="User-facing model label.")
-    model_id: str = Field(
-        validation_alias=AliasChoices("modelId", "model_id"),
-        description="Model identifier sent to the vLLM Responses API.",
-    )
-    base_url: str = Field(
-        validation_alias=AliasChoices("baseUrl", "base_url"),
-        description="OpenAI-compatible vLLM endpoint for this profile.",
-    )
-    reasoning_parser: str | None = Field(
-        default=None,
-        validation_alias=AliasChoices("reasoningParser", "reasoning_parser"),
-        description="Documented vLLM parser required by this deployment.",
-    )
-    supports_thinking: bool = Field(
-        default=False,
-        validation_alias=AliasChoices("supportsThinking", "supports_thinking"),
-        description="Whether this deployment emits native reasoning output.",
-    )
-    description: str | None = Field(
-        default=None, description="Optional user-facing model description."
-    )
-
-    provider_properties: dict[str, JsonValue] = Field(
-        default_factory=dict,
-        validation_alias=AliasChoices("providerProperties", "provider_properties"),
-        description="vLLM-specific deployment properties not exposed by the chat API.",
-    )
-
-    @model_validator(mode="after")
-    def validate_execution_mode(self) -> VllmModelProfileSettings:
-        """Validate the optional vLLM execution mode stored in provider properties."""
-        mode = self.provider_properties.get("mode", "online")
-        if not isinstance(mode, str) or mode not in {"online", "offline"}:
-            raise ValueError(
-                "VLLM providerProperties.mode must be either 'online' or 'offline'."
-            )
-        return self
-
-
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -96,28 +52,10 @@ class Settings(BaseSettings):
         default=20,
         description="Maximum keepalive HTTP connections",
     )
-    vllm_base_url: str = Field(
-        default="http://localhost:8000/v1",
-        description="OpenAI-compatible vLLM server base URL",
-    )
     vllm_api_key: str = Field(
         default="EMPTY",
         description="API key sent to vLLM model servers",
     )
-    vllm_model_id: str = Field(
-        default="google/gemma-4-12B-it-qat-q4_0-gguf",
-        description="Legacy default vLLM model when no catalog is configured",
-    )
-    vllm_model_catalog: list[VllmModelProfileSettings] = Field(
-        default_factory=list,
-        validation_alias="VLLM_MODEL_CATALOG",
-        description="Configured public model profiles and their vLLM endpoints.",
-    )
-    vllm_default_model_profile_id: str | None = Field(
-        default=None,
-        validation_alias="VLLM_DEFAULT_MODEL_PROFILE_ID",
-        description="Public ID of the default catalog profile.",
-    )
     vllm_thinking_effort: str = Field(
         default="high",
         description="vLLM thinking effort for reasoning-capable profiles",

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/js_special_files/chat/BACKEND_FLOW.md

@@ -99,21 +99,25 @@ flowchart LR
 
   runtimePort("ConversationRuntimeProtocol\nprovider-neutral execution contract")
   runtime("runtimes/agents_sdk.py\nAgentsSdkConversationRuntime")
-  factoryPort("VllmAgentFactoryProtocol\ncreate an Agents SDK Agent")
+  factoryPort("VllmAgentFactoryProtocol\nacquire an Agents SDK Agent")
   factory("agents/vllm_agent_factory.py\nVllmAgentFactory")
+  coordinator("agents/vllm_inference_coordinator.py\nVllmInferenceCoordinator")
   catalog("agents/model_catalog.py\nVllmModelCatalog")
   vllm("OpenAI-compatible vLLM\nResponses API")
   offline("Offline executor\nnot registered yet")
 
   runtimePort -. "implemented by" .-> runtime
-  runtime -->|"create selected agent"| factoryPort
+  runtime -->|"reserve selected model for stream"| factoryPort
   factoryPort -. "implemented by" .-> factory
-  factory -->|"resolve public profile"| catalog
+  factory -->|"resolve and create cached agent"| catalog
+  factory -->|"reserve profile"| coordinator
+  coordinator -->|"capacity and priority policy"| catalog
+  coordinator -->|"sleep-state control"| vllm
   factory -->|"online profile: Agent + AsyncOpenAI"| vllm
-  factory -. "offline profile: raises\nVllmOfflineModeNotImplementedError" .-> offline
+  coordinator -. "offline profile: raises\nVllmOfflineModeNotImplementedError" .-> offline
 
   class runtimePort,factoryPort protocol;
-  class runtime,factory,catalog,vllm concrete;
+  class runtime,factory,coordinator,catalog,vllm concrete;
   class offline future;
 ```
 
@@ -122,7 +126,9 @@ flowchart LR
 If it still uses the Agents SDK but needs a different model vendor, replace or
 extend `VllmAgentFactory` behind `VllmAgentFactoryProtocol` and update
 `Container.vllm_agent_factory`. The current offline branch stops in
-`VllmAgentFactory.create()` before any agent is constructed.
+`VllmAgentFactory.acquire()` before inference starts. Keep the acquisition
+context open for the complete response stream so a deployment cannot be slept
+while it is still generating.
 
 ### 4. History and agent-session storage
 
@@ -159,9 +165,9 @@ flowchart LR
 runtime, also replace the session factory dependency used by
 `AgentsSdkConversationRuntime`.
 
-### 5. Model catalog: configuration to picker
+### 5. Model catalog: Python profiles to picker
 
-**Purpose:** the catalog is the allow-list between local configuration, the
+**Purpose:** the catalog is the allow-list between Python-owned configuration, the
 browser picker, and agent creation. It keeps base URLs, parser configuration, and
 provider-only properties on the server.
 
@@ -173,30 +179,38 @@ flowchart LR
   classDef api fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-width:2px;
   classDef ui fill:#dbeafe,stroke:#2563eb,color:#172554,stroke-width:2px;
 
-  env(".env\nVLLM_MODEL_CATALOG\nVLLM_DEFAULT_MODEL_PROFILE_ID")
-  settings("config/settings.py\nSettings / VllmModelProfileSettings")
+  profiles("agents/model_catalog.py\nPython catalog DTO + policy")
+  dto("models/dtos/vllm_model_dtos.py\nVllmModelCatalogDto / VllmModelProfileDto")
   container("config/container.py\nContainer.vllm_model_catalog")
   catalog("agents/model_catalog.py\nVllmModelCatalog")
   route("chat_routes.py\nGET /api/chat/models")
   loader("services/chatModels.ts\nloadChatModels()")
   picker("MainPage.tsx / ChatExperience\nmodels + initialModelId")
 
-  env --> settings
-  settings --> container
+  profiles --> catalog
+  dto -->|"validates internal profiles"| catalog
   container --> catalog
   catalog -->|"public_profiles(): safe metadata"| route
   route --> loader
   loader --> picker
 
-  class env,settings config;
-  class container,catalog domain;
+  class profiles config;
+  class dto,container,catalog domain;
   class route api;
   class loader,picker ui;
 ```
 
-To add a selectable model, update local `.env` and the documented non-secret
-shape in `.env.example`; then verify the catalog profile resolves and
-`GET /api/chat/models` returns the safe metadata used by `MainPage.tsx`.
+To add a selectable model, update `VLLM_MODEL_CATALOG` in
+`agents/model_catalog.py`. Set exactly one profile's `is_default=True` and give
+each profile a one-based `priority` (`1` is highest). Set `max_awake_models` to
+the number of deployments the host can retain in memory; then verify the catalog
+profile resolves and `GET /api/chat/models` returns the safe metadata used by
+`MainPage.tsx`.
+
+Every online profile must point to a vLLM server started with
+`VLLM_SERVER_DEV_MODE=1` and `--enable-sleep-mode`. The coordinator uses
+`/is_sleeping`, `/sleep`, and `/wake_up`; keep these development-only endpoints
+local or otherwise private.
 
 ### 6. Protocol-to-concrete registration map
 
@@ -253,6 +267,7 @@ sequenceDiagram
   participant Store as PostgresConversationHistoryStore
   participant Runtime as AgentsSdkConversationRuntime
   participant Factory as VllmAgentFactory
+  participant Coordinator as VllmInferenceCoordinator
   participant Session as PostgresAgentSessionFactory
   participant VLLM as vLLM Responses API
 
@@ -269,9 +284,13 @@ sequenceDiagram
   Store-->>Service: turn_id
   Service->>Runtime: stream(ConversationExecution)
   activate Runtime
-  Runtime->>Factory: create(model_id, thinking_effort)
+  Runtime->>Factory: acquire(model_id, thinking_effort)
   Factory->>Catalog: resolve(model_id)
   alt profile mode is online
+    Factory->>Coordinator: reserve_profile(profile_id)
+    Coordinator->>Catalog: profiles + max_awake_models
+    Coordinator->>VLLM: inspect, sleep lower-priority deployment, wake target
+    Coordinator-->>Factory: reserved profile
     Factory-->>Runtime: cached/new Agent and AsyncOpenAI client
     Runtime->>Session: create(execution)
     Session-->>Runtime: persisted Agents SDK session
@@ -283,6 +302,8 @@ sequenceDiagram
       Route-->>UI: SSE thinking event or data frame
     end
     Runtime-->>Service: ConversationThinkingCompleted + ConversationCompleted
+    Runtime->>Factory: release acquisition
+    Factory->>Coordinator: restore default when configured
     Service->>Store: finish(..., complete)
     Store-->>Service: persisted transcript and session ledger
   else profile mode is offline

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/py_special_files/chat/domain/services/in_memory_history_store.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 from {name_underscore}_domain.services.protocols.llm_provider import ChatConversationTurn
@@ -16,7 +16,7 @@ class InMemoryConversationHistoryStore:
         self._locks: dict[str, asyncio.Lock] = {}
 
     @asynccontextmanager
-    async def serialized(self, thread_id: str) -> AsyncIterator[None]:
+    async def serialized(self, thread_id: str) -> AsyncGenerator[None, None]:
         lock = self._locks.setdefault(thread_id, asyncio.Lock())
         async with lock:
             yield

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/py_special_files/chat/domain/services/postgres_history_store.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 from sqlalchemy import text
@@ -34,7 +34,7 @@ class PostgresConversationHistoryStore:
         configure_encrypted_columns(encryption_key)
 
     @asynccontextmanager
-    async def serialized(self, thread_id: str) -> AsyncIterator[None]:
+    async def serialized(self, thread_id: str) -> AsyncGenerator[None, None]:
         connection = await self._engine.connect()
         acquired = False
         try:

rpr_cli-0.3.4/src/rpr/scaffolds/py_special_files/vllm_provider/domain/models/dtos/__init__.py

@@ -0,0 +1,3 @@
+from .vllm_model_dtos import VllmModelCatalogDto, VllmModelProfileDto
+
+__all__ = ["VllmModelCatalogDto", "VllmModelProfileDto"]

rpr_cli-0.3.4/src/rpr/scaffolds/py_special_files/vllm_provider/domain/models/dtos/vllm_model_dtos.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Literal, Self, cast
+
+from pydantic import Field, JsonValue, model_validator
+
+from {name_underscore}_domain.models.dtos.chat_dtos import ChatModelProfileDto
+from {name_underscore}_domain.utils.camel_case_model import CamelCaseModel
+
+
+class VllmModelProfileDto(CamelCaseModel):
+    """Internal configuration for one vLLM model deployment."""
+
+    id: str = Field(description="Stable public model-profile identifier.")
+    label: str = Field(description="User-facing model label.")
+    model_id: str = Field(
+        description="Model identifier sent to the vLLM Responses API."
+    )
+    base_url: str = Field(
+        description="OpenAI-compatible vLLM endpoint for this profile."
+    )
+    reasoning_parser: str | None = Field(
+        default=None,
+        description="Documented vLLM parser required by this deployment.",
+    )
+    supports_thinking: bool = Field(
+        default=False,
+        description="Whether this deployment emits native reasoning output.",
+    )
+    supports_chat: bool = Field(
+        default=True,
+        description="Whether this deployment can be selected by the chat runtime.",
+    )
+    supports_ocr: bool = Field(
+        default=False,
+        description="Whether this deployment is available to an OCR service.",
+    )
+    is_default: bool = Field(
+        default=False,
+        description="Whether this is the default chat model profile.",
+    )
+    priority: int = Field(
+        default=1,
+        ge=1,
+        description="Awake-model retention priority; 1 is the highest priority.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional user-facing model description.",
+    )
+    provider_properties: dict[str, JsonValue] = Field(
+        default_factory=dict,
+        description="vLLM-specific deployment properties kept inside the domain.",
+    )
+
+    @model_validator(mode="after")
+    def validate_execution_mode(self) -> Self:
+        """Validate the optional execution mode stored in provider properties."""
+        mode = self.provider_properties.get("mode", "online")
+        if not isinstance(mode, str) or mode not in {"online", "offline"}:
+            raise ValueError(
+                "VLLM providerProperties.mode must be either 'online' or 'offline'."
+            )
+        return self
+
+    @property
+    def execution_mode(self) -> Literal["online", "offline"]:
+        """Return the configured execution mode, defaulting to online."""
+        return cast(
+            Literal["online", "offline"],
+            self.provider_properties.get("mode", "online"),
+        )
+
+    def to_chat_model_profile_dto(self, *, is_default: bool) -> ChatModelProfileDto:
+        """Map internal deployment data to safe model-picker metadata."""
+        return ChatModelProfileDto(
+            id=self.id,
+            label=self.label,
+            description=self.description,
+            is_default=is_default,
+            supports_thinking=self.supports_thinking,
+        )
+
+
+class VllmModelCatalogDto(CamelCaseModel):
+    """Internal policy and profile data for all configured vLLM deployments."""
+
+    profiles: list[VllmModelProfileDto] = Field(
+        min_length=1,
+        description="Configured vLLM model profiles.",
+    )
+    max_awake_models: int = Field(
+        default=1,
+        ge=1,
+        description="Maximum number of distinct online vLLM deployments kept awake.",
+    )
+    restore_default_after_request: bool = Field(
+        default=True,
+        description="Whether to reactivate the default profile after another request.",
+    )
+
+    @model_validator(mode="after")
+    def validate_default_profile(self) -> Self:
+        """Require one chat model profile to be designated as the default."""
+        if sum(profile.is_default for profile in self.profiles) != 1:
+            raise ValueError(
+                "The VLLM catalog must contain exactly one default profile."
+            )
+        if not next(
+            profile for profile in self.profiles if profile.is_default
+        ).supports_chat:
+            raise ValueError("The default VLLM profile must support chat.")
+        return self

rpr_cli-0.3.4/src/rpr/scaffolds/py_special_files/vllm_provider/domain/services/agents/VLLM_SETUP.md

@@ -0,0 +1,31 @@
+# vLLM model catalog and sleep coordination
+
+Model profiles, the default profile, awake-model capacity, and restoration policy
+are defined in `model_catalog.py`. Do not put model IDs or base URLs in `.env`.
+
+Start every online catalog deployment with vLLM development mode and sleep mode
+enabled. For the generated Gemma profile:
+
+```sh
+VLLM_WSL2_ENABLE_PIN_MEMORY=1 \
+VLLM_SERVER_DEV_MODE=1 \
+vllm serve google/gemma-4-12B-it-qat-w4a16-ct \
+  --max-model-len 8192 \
+  --gpu-memory-utilization 0.70 \
+  --max-num-seqs 1 \
+  --enable-auto-tool-choice \
+  --tool-call-parser gemma4 \
+  --reasoning-parser gemma4 \
+  --enable-sleep-mode \
+  --port 8000
+```
+
+The coordinator calls `/is_sleeping`, `/sleep`, and `/wake_up` on each online
+deployment to enforce `max_awake_models`. Keep these development-only endpoints
+local or otherwise private. Lower numeric `priority` values are retained first;
+`1` is the highest priority. When `restore_default_after_request` is enabled, a
+temporary profile is released and the default profile is restored after the
+complete response stream.
+
+Each reasoning-capable profile must match its server's `--reasoning-parser`
+setting. The generated runtime sends `reasoning.effort` per request.

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/py_special_files/vllm_provider/domain/services/agents/__init__.py

@@ -1,15 +1,18 @@
-from .model_catalog import UnknownModelProfileError, VllmModelCatalog, VllmModelProfile
+from .model_catalog import UnknownModelProfileError, VllmModelCatalog
 from .vllm_agent_factory import (
     VllmAgentFactory,
+    VllmModelSwitchError,
     VllmOfflineModeNotImplementedError,
 )
 from .vllm_agent_factory_protocol import VllmAgentFactoryProtocol
+from .vllm_inference_coordinator import VllmInferenceCoordinator
 
 __all__ = [
     "UnknownModelProfileError",
     "VllmAgentFactory",
     "VllmAgentFactoryProtocol",
     "VllmModelCatalog",
-    "VllmModelProfile",
+    "VllmInferenceCoordinator",
+    "VllmModelSwitchError",
     "VllmOfflineModeNotImplementedError",
 ]

rpr_cli-0.3.4/src/rpr/scaffolds/py_special_files/vllm_provider/domain/services/agents/model_catalog.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from {name_underscore}_domain.models.dtos.chat_dtos import ChatModelProfileDto
+from {name_underscore}_domain.models.dtos.vllm_model_dtos import (
+    VllmModelCatalogDto,
+    VllmModelProfileDto,
+)
+
+VLLM_MODEL_CATALOG = VllmModelCatalogDto(
+    max_awake_models=1,
+    restore_default_after_request=True,
+    profiles=[
+        VllmModelProfileDto(
+            id="gemma",
+            label="Gemma 4 12B",
+            model_id="google/gemma-4-12B-it-qat-w4a16-ct",
+            base_url="http://localhost:8000/v1",
+            reasoning_parser="gemma4",
+            supports_thinking=True,
+            is_default=True,
+            priority=1,
+        ),
+    ],
+)
+
+
+class UnknownModelProfileError(ValueError):
+    """Raised when a request refers to a model profile unavailable to this app."""
+
+
+class VllmModelCatalog:
+    """Returns and resolves the Python-owned vLLM deployment catalog."""
+
+    def __init__(
+        self,
+        catalog: VllmModelCatalogDto | None = None,
+    ) -> None:
+        self._catalog = (catalog or VLLM_MODEL_CATALOG).model_copy(deep=True)
+        configured_profiles = tuple(self._catalog.profiles)
+
+        profile_ids = [profile.id for profile in configured_profiles]
+        if len(set(profile_ids)) != len(profile_ids):
+            raise ValueError("VLLM model profile IDs must be unique.")
+
+        self._profiles = {profile.id: profile for profile in configured_profiles}
+        self._default_profile_id = next(
+            profile.id for profile in configured_profiles if profile.is_default
+        )
+
+    @property
+    def default_profile_id(self) -> str:
+        return self._default_profile_id
+
+    @property
+    def catalog(self) -> VllmModelCatalogDto:
+        """Return a copied catalog configuration and model profile list."""
+        return self._catalog.model_copy(deep=True)
+
+    @property
+    def max_awake_models(self) -> int:
+        return self._catalog.max_awake_models
+
+    @property
+    def restore_default_after_request(self) -> bool:
+        return self._catalog.restore_default_after_request
+
+    @property
+    def profiles(self) -> tuple[VllmModelProfileDto, ...]:
+        """Return configured profiles for internal deployment coordination."""
+        return tuple(self._profiles.values())
+
+    def resolve(self, model_id: str | None) -> VllmModelProfileDto:
+        profile_id = model_id or self._default_profile_id
+        try:
+            return self._profiles[profile_id]
+        except KeyError as error:
+            raise UnknownModelProfileError(profile_id) from error
+
+    def public_profiles(self) -> list[ChatModelProfileDto]:
+        return [
+            profile.to_chat_model_profile_dto(is_default=profile.is_default)
+            for profile in self._profiles.values()
+            if profile.supports_chat
+        ]

{rpr_cli-0.3.3 → rpr_cli-0.3.4}/src/rpr/scaffolds/py_special_files/vllm_provider/domain/services/agents/vllm_agent_factory.py

@@ -1,21 +1,32 @@
 from __future__ import annotations
 
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+import httpx
 from agents import Agent, ModelSettings, OpenAIResponsesModel, set_tracing_disabled
 from openai import AsyncOpenAI
 
+from {name_underscore}_domain.models.dtos.vllm_model_dtos import VllmModelProfileDto
 from {name_underscore}_domain.services.agents.model_catalog import VllmModelCatalog
+from {name_underscore}_domain.services.agents.vllm_inference_coordinator import (
+    VllmInferenceCoordinator,
+    VllmModelSwitchError,
+    VllmOfflineModeNotImplementedError,
+)
 from {name_underscore}_domain.utils.logging import get_logger
 
 set_tracing_disabled(True)
 
-
 _FINAL_OUTPUT_INSTRUCTIONS = """You are an AI assistant. Keep your responses concise and helpful. Keep your thoughts to a minimum try not to generate code when thinking."""
 
 _logger = get_logger("VllmAgentFactory")
 
-
-class VllmOfflineModeNotImplementedError(NotImplementedError):
-    """Raised when an offline vLLM profile has no registered executor yet."""
+__all__ = [
+    "VllmAgentFactory",
+    "VllmModelSwitchError",
+    "VllmOfflineModeNotImplementedError",
+]
 
 
 class VllmAgentFactory:
@@ -27,25 +38,48 @@ class VllmAgentFactory:
         api_key: str,
         http_timeout: float,
         thinking_effort: str | None,
+        coordinator: VllmInferenceCoordinator | None = None,
+        control_client: httpx.AsyncClient | None = None,
     ) -> None:
         self._catalog = catalog
         self._api_key = api_key
         self._http_timeout = http_timeout
         self._thinking_effort = thinking_effort
+        if coordinator is None:
+            if control_client is None:
+                raise TypeError("VllmAgentFactory requires a vLLM coordinator.")
+            coordinator = VllmInferenceCoordinator(
+                catalog=catalog,
+                api_key=api_key,
+                control_client=control_client,
+            )
+        self._coordinator = coordinator
         self._clients: dict[str, AsyncOpenAI] = {}
         self._agents: dict[tuple[str, str | None], Agent[None]] = {}
 
-    def resolve_profile(self, model_id: str | None):
-        return self._catalog.resolve(model_id)
+    @property
+    def active_profile_id(self) -> str | None:
+        """Return the profile most recently activated for an inference stream."""
+        return self._coordinator.active_profile_id
+
+    def resolve_profile(self, model_id: str | None) -> VllmModelProfileDto:
+        return self._coordinator.resolve_profile(model_id)
+
+    @asynccontextmanager
+    async def acquire(
+        self, model_id: str | None = None, thinking_effort: str | None = None
+    ) -> AsyncGenerator[Agent[None], None]:
+        """Exclusively activate a model for the lifetime of one inference stream."""
+        profile = self._require_chat_profile(model_id)
+        agent = self.create(profile.id, thinking_effort)
+        async with self._coordinator.reserve_profile(profile.id):
+            yield agent
 
     def create(
         self, model_id: str | None = None, thinking_effort: str | None = None
     ) -> Agent[None]:
-        profile = self._catalog.resolve(model_id)
-        if profile.execution_mode == "offline":
-            raise VllmOfflineModeNotImplementedError(
-                f"Offline vLLM model profile '{profile.id}' is not implemented."
-            )
+        """Create or reuse an agent without managing its deployment lifecycle."""
+        profile = self._require_chat_profile(model_id)
         effective_effort = (
             thinking_effort or self._thinking_effort
             if profile.supports_thinking
@@ -81,3 +115,15 @@ class VllmAgentFactory:
         )
         self._agents[key] = agent
         return agent
+
+    def _require_chat_profile(self, model_id: str | None) -> VllmModelProfileDto:
+        profile = self._coordinator.resolve_profile(model_id)
+        if not profile.supports_chat:
+            raise ValueError(
+                f"VLLM model profile '{profile.id}' does not support chat."
+            )
+        return profile
+
+    @staticmethod
+    def _build_url(base_url: str, replace_path: str = "") -> str:
+        return VllmInferenceCoordinator._build_url(base_url, replace_path)