devcouncil 0.2.0 → 0.3.0

package/src/devcouncil/llm/provider.py

@@ -2,6 +2,7 @@ from abc import ABC, abstractmethod
 import copy
 from functools import lru_cache
 from importlib import resources
+import logging
 import os
 from typing import List, Dict, Any, Optional
 from pydantic import BaseModel, field_validator
@@ -10,6 +11,8 @@ import json
 from pathlib import Path
 import yaml
 
+logger = logging.getLogger(__name__)
+
 SUPPORTED_MODEL_PROVIDERS = ("openrouter", "vertexai", "doubleword", "ollama")
 PROVIDER_ALIASES = {
     "vertex-ai": "vertexai",
@@ -66,6 +69,7 @@ def raise_for_provider_status(response: "httpx.Response", provider: str) -> None
     message = f"{provider} API error {status}: {detail}."
     if body:
         message = f"{message} Response: {body}"
+    logger.error("Provider request failed: %s", message)
     raise ProviderRequestError(message, status_code=status)
 
 
@@ -99,6 +103,41 @@ class Provider(ABC):
     ) -> LLMResponse:
         pass
 
+    def _get_async_client(self, timeout: Any) -> "httpx.AsyncClient":
+        """Lazily create and reuse a single ``httpx.AsyncClient`` per provider instance.
+
+        Building an ``AsyncClient`` (connection pool + SSL context) is expensive and the
+        pool is meant to be reused across calls, so we keep one per instance rather than
+        constructing a fresh client on every ``complete()``. ``timeout`` is fixed per
+        provider instance (cloud providers use 180s; Ollama uses its resolved
+        ``self.timeout``), so binding it at construction time is equivalent to the previous
+        per-call client while still allowing the pool to be reused.
+
+        The client is bound to the event loop that created it. If the same provider
+        instance is ever driven from a *different* loop (e.g. a second ``asyncio.run``),
+        the old client's pool belongs to a now-closed loop and cannot be reused — we
+        detect that and rebind a fresh client to the current loop instead of failing. The
+        client lives for the provider's lifetime (one run / one cached router) and is
+        released on GC or via ``aclose()``; provider instances are bounded, so clients do
+        not accumulate."""
+        import asyncio
+
+        loop = asyncio.get_running_loop()
+        client = getattr(self, "_client", None)
+        if client is not None and not client.is_closed and getattr(self, "_client_loop", None) is loop:
+            return client
+        client = httpx.AsyncClient(timeout=timeout)
+        self._client: Optional[httpx.AsyncClient] = client
+        self._client_loop = loop
+        return client
+
+    async def aclose(self) -> None:
+        """Close the reused AsyncClient if one was created."""
+        client = getattr(self, "_client", None)
+        if client is not None:
+            self._client = None
+            await client.aclose()
+
     def cache_fingerprint(self) -> str:
         """Provider-specific options that change the model's output and therefore must
         be part of the LLM cache key. Empty for providers whose output depends only on
@@ -177,10 +216,37 @@ def build_role_model_config(
     return roles
 
 
-def create_provider(provider_name: str, api_key: str, project_root: Path = Path(".")) -> Provider:
+def openrouter_provider_payload(prefs: Any) -> Optional[Dict[str, Any]]:
+    """Translate DevCouncil's ``ProviderConfig`` (or a plain mapping) into OpenRouter's
+    ``provider`` routing object.
+
+    Returns ``None`` when no prefs are supplied so the request omits the field entirely
+    and OpenRouter applies its own defaults. Only the keys OpenRouter recognizes are
+    forwarded (``sort``, ``allow_fallbacks``, ``require_parameters``, ``data_collection``),
+    so adding unrelated fields to ``ProviderConfig`` never leaks into the API call.
+    """
+    if prefs is None:
+        return None
+    if hasattr(prefs, "model_dump"):
+        data = prefs.model_dump()
+    elif isinstance(prefs, dict):
+        data = prefs
+    else:
+        return None
+    allowed = ("sort", "allow_fallbacks", "require_parameters", "data_collection")
+    payload = {k: data[k] for k in allowed if data.get(k) is not None}
+    return payload or None
+
+
+def create_provider(
+    provider_name: str,
+    api_key: str,
+    project_root: Path = Path("."),
+    provider_prefs: Any = None,
+) -> Provider:
     normalized = validate_model_provider(provider_name)
     if normalized == "openrouter":
-        return OpenRouterProvider(api_key, project_root=project_root)
+        return OpenRouterProvider(api_key, project_root=project_root, provider_prefs=provider_prefs)
     if normalized == "doubleword":
         return DoublewordProvider(api_key, project_root=project_root)
     if normalized == "ollama":
@@ -239,10 +305,21 @@ def _log_model_call(
 
 
 class OpenRouterProvider(Provider):
-    def __init__(self, api_key: str, project_root: Path = Path(".")):
+    def __init__(self, api_key: str, project_root: Path = Path("."), provider_prefs: Any = None):
         self.api_key = api_key
         self.base_url = "https://openrouter.ai/api/v1"
         self.project_root = project_root
+        # OpenRouter routing preferences (sort/allow_fallbacks/require_parameters/
+        # data_collection) sent as the request's ``provider`` field. None → omit it.
+        self.provider_prefs = openrouter_provider_payload(provider_prefs)
+
+    def cache_fingerprint(self) -> str:
+        # Routing prefs change which upstream provider/model serves the request (and the
+        # data-collection policy), so they can change the output for an identical prompt
+        # and must invalidate the cache. Empty when unset so default runs share one key.
+        if not self.provider_prefs:
+            return ""
+        return "openrouter:provider=" + json.dumps(self.provider_prefs, sort_keys=True)
 
     async def complete(
         self, 
@@ -253,8 +330,9 @@ class OpenRouterProvider(Provider):
         task_id: Optional[str] = None,
         run_id: Optional[str] = None,
     ) -> LLMResponse:
-        # Deep-copy to avoid mutating the caller's messages list
-        msgs = copy.deepcopy(messages)
+        # Only deep-copy when json_mode mutates the last message; otherwise the
+        # caller's list is read but never modified, so we can use it directly.
+        msgs = copy.deepcopy(messages) if json_mode else messages
 
         headers = {
             "Authorization": f"Bearer {self.api_key}",
@@ -262,38 +340,41 @@ class OpenRouterProvider(Provider):
             "HTTP-Referer": "https://github.com/devcouncil/devcouncil", # Optional
             "X-Title": "DevCouncil", # Optional
         }
-        
+
         payload = {
             "model": model,
             "messages": msgs,
             "temperature": temperature,
         }
-        
+
         if json_mode:
             payload["response_format"] = {"type": "json_object"}
             # Ensure the user message mentions JSON
             if msgs[-1]["role"] == "user":
                 msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
 
-        async with httpx.AsyncClient(timeout=180.0) as client:
-            response = await client.post(
-                f"{self.base_url}/chat/completions",
-                headers=headers,
-                json=payload
-            )
-            raise_for_provider_status(response, "OpenRouter")
-            data = response.json()
-
-            resp = LLMResponse(
-                content=data["choices"][0]["message"]["content"],
-                model=data["model"],
-                usage=data.get("usage", {}),
-                raw_response=data
-            )
+        if self.provider_prefs:
+            payload["provider"] = self.provider_prefs
+
+        client = self._get_async_client(180.0)
+        response = await client.post(
+            f"{self.base_url}/chat/completions",
+            headers=headers,
+            json=payload,
+        )
+        raise_for_provider_status(response, "OpenRouter")
+        data = response.json()
+
+        resp = LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=data["model"],
+            usage=data.get("usage", {}),
+            raw_response=data
+        )
 
-            _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
+        _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
 
-            return resp
+        return resp
 
 
 class DoublewordProvider(Provider):
@@ -311,7 +392,9 @@ class DoublewordProvider(Provider):
         task_id: Optional[str] = None,
         run_id: Optional[str] = None,
     ) -> LLMResponse:
-        msgs = copy.deepcopy(messages)
+        # Only deep-copy when json_mode mutates the last message; otherwise the
+        # caller's list is read but never modified, so we can use it directly.
+        msgs = copy.deepcopy(messages) if json_mode else messages
         headers = {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
@@ -327,24 +410,24 @@ class DoublewordProvider(Provider):
             if msgs[-1]["role"] == "user":
                 msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
 
-        async with httpx.AsyncClient(timeout=180.0) as client:
-            response = await client.post(
-                f"{self.base_url}/chat/completions",
-                headers=headers,
-                json=payload
-            )
-            raise_for_provider_status(response, "Doubleword")
-            data = response.json()
-
-            resp = LLMResponse(
-                content=data["choices"][0]["message"]["content"],
-                model=data["model"],
-                usage=data.get("usage", {}),
-                raw_response=data
-            )
+        client = self._get_async_client(180.0)
+        response = await client.post(
+            f"{self.base_url}/chat/completions",
+            headers=headers,
+            json=payload,
+        )
+        raise_for_provider_status(response, "Doubleword")
+        data = response.json()
+
+        resp = LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=data["model"],
+            usage=data.get("usage", {}),
+            raw_response=data
+        )
 
-            _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
-            return resp
+        _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
+        return resp
 
 
 class OllamaProvider(Provider):
@@ -451,7 +534,9 @@ class OllamaProvider(Provider):
         task_id: Optional[str] = None,
         run_id: Optional[str] = None,
     ) -> LLMResponse:
-        msgs = copy.deepcopy(messages)
+        # Only deep-copy when json_mode mutates the last message; otherwise the
+        # caller's list is read but never modified, so we can use it directly.
+        msgs = copy.deepcopy(messages) if json_mode else messages
         headers = {
             "Content-Type": "application/json",
         }
@@ -480,36 +565,36 @@ class OllamaProvider(Provider):
             if msgs[-1]["role"] == "user":
                 msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
 
-        async with httpx.AsyncClient(timeout=self.timeout) as client:
-            response = await client.post(
-                self._chat_endpoint(),
-                headers=headers,
-                json=payload,
-            )
-            raise_for_provider_status(response, "Ollama")
-            data = response.json()
-
-            # Native response shape: {"message": {"content": ...}, "model": ...,
-            # "prompt_eval_count": N, "eval_count": M}. Map token counts to the
-            # OpenAI-style keys the cost ledger/tracker expect.
-            prompt_tokens = int(data.get("prompt_eval_count", 0) or 0)
-            completion_tokens = int(data.get("eval_count", 0) or 0)
-            usage = {
-                "prompt_tokens": prompt_tokens,
-                "completion_tokens": completion_tokens,
-                "total_tokens": prompt_tokens + completion_tokens,
-            }
-            resp = LLMResponse(
-                content=(data.get("message") or {}).get("content", ""),
-                # Ollama may omit ``model`` or return a local tag — fall back to
-                # the requested id rather than KeyError-ing.
-                model=data.get("model", model),
-                usage=usage,
-                raw_response=data,
-            )
+        client = self._get_async_client(self.timeout)
+        response = await client.post(
+            self._chat_endpoint(),
+            headers=headers,
+            json=payload,
+        )
+        raise_for_provider_status(response, "Ollama")
+        data = response.json()
+
+        # Native response shape: {"message": {"content": ...}, "model": ...,
+        # "prompt_eval_count": N, "eval_count": M}. Map token counts to the
+        # OpenAI-style keys the cost ledger/tracker expect.
+        prompt_tokens = int(data.get("prompt_eval_count", 0) or 0)
+        completion_tokens = int(data.get("eval_count", 0) or 0)
+        usage = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": prompt_tokens + completion_tokens,
+        }
+        resp = LLMResponse(
+            content=(data.get("message") or {}).get("content", ""),
+            # Ollama may omit ``model`` or return a local tag — fall back to
+            # the requested id rather than KeyError-ing.
+            model=data.get("model", model),
+            usage=usage,
+            raw_response=data,
+        )
 
-            _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id, provider="ollama")
-            return resp
+        _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id, provider="ollama")
+        return resp
 
 
 class VertexAIProvider(Provider):
@@ -556,7 +641,9 @@ class VertexAIProvider(Provider):
         task_id: Optional[str] = None,
         run_id: Optional[str] = None,
     ) -> LLMResponse:
-        msgs = copy.deepcopy(messages)
+        # Only deep-copy when json_mode mutates the last message; otherwise the
+        # caller's list is read but never modified, so we can use it directly.
+        msgs = copy.deepcopy(messages) if json_mode else messages
 
         payload = {
             "model": model,
@@ -569,30 +656,30 @@ class VertexAIProvider(Provider):
             if msgs[-1]["role"] == "user":
                 msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
 
-        async with httpx.AsyncClient(timeout=180.0) as client:
+        client = self._get_async_client(180.0)
+        response = await client.post(
+            f"{self.base_url}/chat/completions",
+            headers=self._headers(),
+            json=payload,
+        )
+        if response.status_code in {401, 403} and self._refresh_access_token_from_gcloud():
             response = await client.post(
                 f"{self.base_url}/chat/completions",
                 headers=self._headers(),
-                json=payload
-            )
-            if response.status_code in {401, 403} and self._refresh_access_token_from_gcloud():
-                response = await client.post(
-                    f"{self.base_url}/chat/completions",
-                    headers=self._headers(),
-                    json=payload
-                )
-            raise_for_provider_status(response, "Vertex AI")
-            data = response.json()
-
-            resp = LLMResponse(
-                content=data["choices"][0]["message"]["content"],
-                model=data["model"],
-                usage=data.get("usage", {}),
-                raw_response=data
+                json=payload,
             )
+        raise_for_provider_status(response, "Vertex AI")
+        data = response.json()
+
+        resp = LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=data["model"],
+            usage=data.get("usage", {}),
+            raw_response=data
+        )
 
-            _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
-            return resp
+        _log_model_call(payload, data, resp.usage, self.project_root, task_id=task_id, run_id=run_id)
+        return resp
 
 class MockProvider(Provider):
     """Mock provider for dry runs and testing."""

package/src/devcouncil/llm/router.py

@@ -1,8 +1,10 @@
 from typing import List, Dict, Any, Type, Optional, TypeVar
 import copy
+import functools
 import json
 import logging
 import asyncio
+import time
 from pathlib import Path
 
 from pydantic import BaseModel
@@ -15,6 +17,11 @@ logger = logging.getLogger(__name__)
 StructuredModel = TypeVar("StructuredModel", bound=BaseModel)
 
 
+@functools.lru_cache(maxsize=128)
+def _cached_schema_json(schema_class) -> str:
+    return json.dumps(schema_class.model_json_schema(), indent=2)
+
+
 class StructuredOutputError(RuntimeError):
     """A model could not produce valid structured output for a role, even after
     a healing retry. Carries the role/model so the CLI can give actionable advice
@@ -42,6 +49,51 @@ class ModelRouter:
         self.provider = provider
         self.role_config = role_config
         self.project_root = project_root
+        # LLMCache and TraceLogger do disk I/O (mkdir) in their constructors, so build
+        # them once here and reuse across calls. TelemetryTracker is deliberately *not*
+        # hoisted: it is constructed per-call so log_usage's reload-before-save stays
+        # concurrent-write safe.
+        self._cache = LLMCache(self.project_root)
+        self._traces = TraceLogger(self.project_root)
+        # Lazily-built providers for roles that override ``models.provider`` with
+        # their own ``provider:`` (e.g. live_reviewer on Ollama while planners run
+        # on OpenRouter). Keyed by normalized provider name; the default provider
+        # passed in above is reused for roles without an override.
+        self._role_providers: Dict[str, Provider] = {}
+
+    def _provider_for_role(self, role_config: Dict[str, Any]) -> Provider:
+        """Resolve the provider for a role, honoring a per-role ``provider`` override.
+
+        Roles without an override use the default provider supplied at construction.
+        Overriding roles get a provider built on demand (and cached) from the
+        configured credentials, so one router can fan a single run across multiple
+        providers."""
+        role_provider = role_config.get("provider")
+        if not role_provider:
+            return self.provider
+        # Local imports avoid a circular import at module load (provider/config
+        # both reference this package).
+        from devcouncil.llm.provider import create_provider, validate_model_provider
+        from devcouncil.app.config import get_api_key
+
+        normalized = validate_model_provider(role_provider)
+        if normalized not in self._role_providers:
+            api_key = get_api_key(normalized, self.project_root)
+            # An override to OpenRouter must still honor the project's provider-routing
+            # prefs (sort/allow_fallbacks/data_collection); other providers ignore them.
+            # Best-effort: a missing/invalid config just yields default routing.
+            prefs = None
+            if normalized == "openrouter":
+                try:
+                    from devcouncil.app.config import load_config
+
+                    prefs = load_config(self.project_root).provider
+                except Exception:
+                    prefs = None
+            self._role_providers[normalized] = create_provider(
+                normalized, api_key, project_root=self.project_root, provider_prefs=prefs
+            )
+        return self._role_providers[normalized]
 
     @staticmethod
     def _extract_json(content: str) -> str:
@@ -96,6 +148,23 @@ class ModelRouter:
                             break
         return text
 
+    @staticmethod
+    def _looks_like_schema_echo(text: str) -> bool:
+        """True when the model returned the JSON *schema* instead of an instance.
+
+        Weaker/local models sometimes parrot the schema document we showed them
+        (``{"$defs": ..., "properties": ..., "type": "object"}``). That parses as JSON
+        but never validates, so detecting it lets the healing retry give a pointed
+        correction instead of the generic "fix your JSON" nudge."""
+        try:
+            obj = json.loads(text)
+        except Exception:
+            return False
+        if not isinstance(obj, dict):
+            return False
+        markers = {"$schema", "$defs", "properties", "additionalProperties", "$ref"}
+        return bool(markers & set(obj.keys()))
+
     async def _complete_with_retry(
         self,
         *,
@@ -103,15 +172,18 @@ class ModelRouter:
         messages: List[Dict[str, str]],
         temperature: float,
         run_id: Optional[str],
+        provider: Optional[Provider] = None,
         attempts: int = 3,
     ) -> "LLMResponse":
         """Provider completion with bounded exponential-backoff retry. Used for BOTH the
         initial call and the healing call so a transient fault in either is retried (and,
         if still failing, surfaced to the caller's fallback logic) rather than aborting
-        the run."""
+        the run. ``provider`` defaults to the router's default provider but may be a
+        per-role provider for roles that override ``models.provider``."""
+        provider = provider or self.provider
         for attempt in range(attempts):
             try:
-                return await self.provider.complete(
+                return await provider.complete(
                     model=model,
                     messages=messages,
                     temperature=temperature,
@@ -141,16 +213,25 @@ class ModelRouter:
         config = self.role_config.get(role)
         if not config:
             raise ValueError(f"No config found for role: {role}")
-        
+
         model = config["model"]
         temp = temperature if temperature is not None else config.get("temperature", 0.0)
+        provider = self._provider_for_role(config)
         
         # Deep-copy to avoid mutating the caller's messages list
         msgs = copy.deepcopy(messages)
         
-        # Add schema instructions to system or user message
-        schema_json = json.dumps(schema.model_json_schema(), indent=2)
-        instruction = f"\n\nYou MUST output a JSON object matching this schema:\n{schema_json}"
+        # Add schema instructions to system or user message. Spell out "instance, not
+        # the schema" explicitly: weaker/local models otherwise sometimes echo the schema
+        # document back (``{"$defs": ..., "properties": ..., "type": "object"}``), which
+        # parses as JSON but fails validation and wastes a healing round.
+        schema_json = _cached_schema_json(schema)
+        instruction = (
+            "\n\nYou MUST output a single JSON object that is an INSTANCE of this schema — "
+            "real values for each field. Do NOT output the schema itself; never include "
+            'keys like "$defs", "$schema", "properties", or "type".\nSchema:\n'
+            f"{schema_json}"
+        )
         
         found_system = False
         for msg in msgs:
@@ -164,25 +245,27 @@ class ModelRouter:
 
         logger.info("LLM call: role=%s model=%s run_id=%s", role, model, run_id)
 
-        cache = LLMCache(self.project_root)
+        cache = self._cache
         tracker = TelemetryTracker(self.project_root)
-        traces = TraceLogger(self.project_root)
+        traces = self._traces
 
         # Provider knobs (e.g. Ollama num_ctx / base_url) that change the output for an
         # identical prompt must be part of the cache key, else raising OLLAMA_NUM_CTX
         # after a truncated answer would keep serving the stale response.
-        provider_fp = self.provider.cache_fingerprint()
+        provider_fp = provider.cache_fingerprint()
         # Zero local (Ollama) usage by provider so telemetry matches the cost ledger.
-        provider_local = self.provider.is_local_cost_free()
+        provider_local = provider.is_local_cost_free()
 
         # Check cache first
         response = cache.get(model, msgs, temp, True, provider_fp)
         cache_hit = response is not None
 
+        started = time.monotonic()
         if not response:
             response = await self._complete_with_retry(
-                model=model, messages=msgs, temperature=temp, run_id=run_id
+                model=model, messages=msgs, temperature=temp, run_id=run_id, provider=provider
             )
+        elapsed = time.monotonic() - started
 
         if response is None:
             raise RuntimeError(f"LLM request for role {role} did not return a response.")
@@ -190,9 +273,12 @@ class ModelRouter:
         if not cache_hit:
             tracker.log_usage(model, response.usage, local=provider_local)
 
+        # Include latency + cache status: on a slow (e.g. local) model this is what tells
+        # you *which* call dominated a multi-minute planning/verification stage.
         logger.info(
-            "LLM response: role=%s model=%s tokens=%s",
+            "LLM response: role=%s model=%s tokens=%s %s",
             role, response.model, response.usage,
+            "cache_hit" if cache_hit else f"{elapsed:.1f}s",
         )
         
         try:
@@ -218,13 +304,23 @@ class ModelRouter:
                 summary=f"Structured response parse failed for {role}; attempting repair.",
             )
             
-            # Healing attempt: Ask the model to fix its own JSON
+            # Healing attempt: Ask the model to fix its own JSON. If it echoed the schema
+            # back instead of an instance, say so explicitly — the generic "fix it" nudge
+            # otherwise tends to produce the schema again.
+            echo_hint = ""
+            if self._looks_like_schema_echo(self._extract_json(response.content)):
+                echo_hint = (
+                    "\nIMPORTANT: You returned the JSON *schema* (it contains keys like "
+                    '"$defs"/"properties"/"type"), not a value. Return a concrete INSTANCE: '
+                    "a JSON object whose keys are the schema's property names, each with a "
+                    "real value of the correct type."
+                )
             healing_prompt = f"""
 The following JSON was returned but failed to parse or validate against the schema.
 Error: {str(e)}
 Content:
 {response.content}
-
+{echo_hint}
 Please return the corrected JSON object only. No prose.
 """
             # The healing completion runs INSIDE this try (with the same retry/backoff as
@@ -239,6 +335,7 @@ Please return the corrected JSON object only. No prose.
                     messages=[{"role": "user", "content": healing_prompt}],
                     temperature=0.0,
                     run_id=run_id,
+                    provider=provider,
                 )
                 tracker.log_usage(healed_response.model, healed_response.usage, local=provider_local)
                 healed_content = self._extract_json(healed_response.content)
@@ -272,15 +369,17 @@ Please return the corrected JSON object only. No prose.
                         "(attempt %d/%d).",
                         role, _attempt + 2, self.STRUCTURED_ATTEMPTS,
                     )
-                    strict_messages = copy.deepcopy(messages)
-                    strict_messages.insert(0, {
-                        "role": "system",
-                        "content": (
-                            "Respond with a single valid JSON object only — no prose, no "
-                            "markdown fences, no trailing text. It must parse with a strict "
-                            "JSON parser and match the requested schema."
-                        ),
-                    })
+                    strict_messages = [
+                        {
+                            "role": "system",
+                            "content": (
+                                "Respond with a single valid JSON object only — no prose, no "
+                                "markdown fences, no trailing text. It must parse with a strict "
+                                "JSON parser and match the requested schema."
+                            ),
+                        },
+                        *messages,
+                    ]
                     return await self.complete_structured(
                         role,
                         strict_messages,